Memory
Memory is not storage. Memory is the foundation for evolution.
Philosophy
Why Memory?
Without memory, every session starts from zero.
Session 1: Makes mistake A
Session 2: Makes mistake A again
Session 3: Makes mistake A again
...foreverWith memory, patterns emerge:
Session 1: Makes mistake A, records it
Session 2: Reads record, avoids A, discovers B
Session 3: Reads both, avoids A and B, finds better path
...progressMemory isn't for the current session—memory is a gift to future sessions.
The Deeper Purpose
Memory transforms isolated events into accumulated wisdom.
Individual record: "We tried X, it failed because Y"
Pattern after 5 records: "Approaches like X tend to fail when Y"
Wisdom after 20 records: "Before attempting X-like solutions, check for Y"This is how learning works. Not through rules handed down, but through patterns that emerge from recorded experience.
What to Remember
Not everything deserves memory. Record what would hurt if forgotten:
| Remember | Don't Remember |
|---|---|
| Decisions and their rationale | Implementation details (use code) |
| Mistakes and lessons | Obvious facts (use docs) |
| Context that explains "why" | Temporary debugging notes |
| Patterns that emerged | Things Git already tracks |
The test: "Would a future agent benefit from knowing this?"
Structure
.memory/
├── context.md → Current state, active concerns (read first)
├── notes/ → Learnings, observations
├── decisions/ → ADRs: what was decided and why
├── todos/ → Tasks that span sessions
└── sessions/ → Session summaries (handoff to next)context.md
The handoff document. When a new session starts, this tells them:
- What's currently in progress
- What concerns are active
- What needs attention
Keep it current. A stale context.md is worse than none.
Naming Convention
YYYY-MM-DD-kebab-slug.mdNatural sort order. Grep-friendly. Self-documenting.
Core Operations
| Intent | Action |
|---|---|
| "Remember this" | Create note in .memory/notes/ |
| "We decided X because Y" | Create ADR in .memory/decisions/ |
| "What did we learn about Z?" | Search .memory/, summarize with citations |
| "Session ending" | Create session summary, update context.md |
Record Format
---
type: note | decision | todo | session
status: active | completed | archived
tags: [relevant, keywords]
created: YYYY-MM-DD
---
# Title
Content that future agents will thank you for.Integration
Memory provides context to other skills:
memory
│
├─► orientation reads context.md at session start
├─► dive uses past notes to inform investigation
├─► engineering reads decisions before proposing new ones
└─► refining includes relevant history in PR descriptionsUnderstanding, Not Rules
| Tension | Resolution |
|---|---|
| Completeness vs Noise | Record signal, not noise. Ask: "Would this help a future agent?" |
| Structure vs Flexibility | Use consistent format, but content matters more than form |
| Writing vs Doing | Recording takes seconds; re-learning takes hours |
The Anti-Pattern
The worst failure isn't forgetting to record—it's recording without understanding.
Bad: "Fixed bug in auth"
Good: "Auth was failing silently when token expired mid-request.
Root cause: async race condition.
Fix: Added token refresh before sensitive operations.
Lesson: Any auth code should handle mid-operation expiry."The second takes 30 seconds longer. It saves the next agent hours.
Reference
See reference/ for:
- templates/ - Record templates
- remote-sync.md - GitHub/GitLab Issues sync
- setup.md - Initialization options