MEMORIES.md

An open, standardized format for documenting work-in-progress context around project tasks and features.

What is MEMORIES.md?

MEMORIES.md is a Markdown file that travels with your work, enabling seamless handoffs between agents, machines, or team members. It captures decisions, learnings, blockers, and progress in a structured, agent-readable format.

Think of it as a "session notebook" that helps the next agent (or human) understand:

• What we're trying to accomplish
• What we've already tried (and why it worked or failed)
• Where we are now
• What's blocking us
• Where to look in the codebase

Why MEMORIES.md?

The Problem: When an agent finishes work and another agent (or human) picks it up on a different machine or session, critical context is lost. The new agent has to:

• Re-read the issue/ticket
• Re-explore the codebase
• Re-run tests to understand what's working
• Potentially re-try approaches that already failed

The Solution: MEMORIES.md captures this context in a structured, standardized format that any agent can read and update.

Key Features

• Agent-Agnostic: Designed to work with any AI coding agent or tool
• Human-Readable: Plain markdown, easy to read and edit manually
• Bidirectional: Agents both read from and write to the file
• Actionable: Contains information and context that helps agents continue work outside of internal threads and memory systems
• Optional Sections: Include only what's relevant to your task

Quick Start

1. Create a MEMORIES.md file at the root of your repository
2. Fill in the sections relevant to your work
3. Update it as you make progress
4. When handing off to another agent, ensure it's up-to-date

Example

## Work Item

**Title**: Fix login button not responding on mobile
**Issue/Ticket**: https://github.com/example/repo/issues/1234
**Branch**: fix/mobile-login-button

## Objectives

- Identify why login button is unresponsive on mobile devices
- Fix the issue without breaking desktop functionality

## Current Status

Bug identified and fix implemented. Unit tests passing. Need integration tests.

## Task List

- [x] Reproduce the issue on mobile
- [x] Identify root cause
- [x] Implement fix
- [ ] Run integration tests
- [ ] Manual testing

## Key Decisions

- **Decision 1**: Add touch event handler alongside click handler
  - Reasoning: Maintains backward compatibility

## Approaches Attempted

**Approach 1: Replace click with pointer events** - ❌ Failed

- Why: Broke click handling on desktop in some edge cases

**Approach 2: Add touch event listener alongside click** - ✅ Succeeded

- Why: Explicit event handlers for both input types, no conflicts

## Relevant Code Locations

- `src/components/LoginButton.tsx` - Main button component
- `tests/auth.test.ts` - Authentication tests

## Test Results

**Unit Tests**: ✅ Passing (24/24)
**Integration Tests**: ⏳ Not yet run

See examples/MEMORIES-example-*.md for more realistic examples.

Sections

MEMORIES.md includes these optional sections:

• Work Item: What we're working on and where it lives
• Objectives: Clear goals for this work
• Current Status: One-line snapshot of progress
• Task List: What's done and what remains
• Key Decisions: Important choices and their reasoning
• Approaches Attempted: What worked, what didn't, and why
• Relevant Code Locations: Quick reference to key files
• Blockers: What's preventing progress
• Test Results: What's been validated
• Session Log: Optional chronological record of work sessions

See docs/SPECIFICATION.md for detailed documentation of each section.

Guidelines

What to Include

• Decisions and their reasoning
• Approaches that failed and why
• Concrete code locations and file paths
• Test results and validation status
• Blockers and constraints
• Relevant error messages or log excerpts (when they illuminate an issue)
• Links to related documentation or issues

What to Exclude

• Full code diffs (link to PR or commit instead)
• Full log outputs (include relevant excerpts only)
• Verbose debugging output
• Unrelated project information (use AGENTS.md for that)

Updating MEMORIES.md

• Update whenever significant progress is made
• Update when blockers are encountered
• Update when approaches fail or succeed
• Update before handing off to another agent
• Treat merge conflicts like any other file conflict

Integration Workflow

1. Start - Find and read MEMORIES.md
2. Understand - Parse sections and review context
3. Work - Perform the task
4. Update - Record progress, mark tasks, add notes
5. Save - Write updated file to disk
6. Commit - Commit changes with code updates

Agentic Adoption

MEMORIES.md is designed to be adopted by any AI coding agent or tool. If you're building an agent, consider:

1. Checking for MEMORIES.md at the start of a task
2. Reading and understanding the current context
3. Updating MEMORIES.md as work progresses
4. Ensuring MEMORIES.md is up-to-date before handing off work

Inspiration

MEMORIES.md is inspired by AGENTS.md, which provides a standardized format for project-level guidance. While AGENTS.md is static (project conventions and setup), MEMORIES.md is dynamic (work-in-progress context).

License

MIT

Contributing

This is an open format. Contributions, feedback, and adoption are welcome. Please open issues or PRs to suggest improvements.

Examples

See the examples/ directory for realistic MEMORIES.md files:

• examples/MEMORIES-example-1-simple-bug-fix.md - Simple bug fix with single session
• examples/MEMORIES-example-2-feature-development.md - Feature development with multiple sessions and handoff
• examples/MEMORIES-example-3-debugging-complex-issue.md - Complex debugging scenario with detailed error context