Memory

Memory is not storage. Memory is the foundation for evolution.

Philosophy

Why Memory?

Without memory, every session starts from zero.

code

Session 1: Makes mistake A
Session 2: Makes mistake A again
Session 3: Makes mistake A again
...forever

With memory, patterns emerge:

code

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
...progress

Memory isn't for the current session—memory is a gift to future sessions.

The Deeper Purpose

Memory transforms isolated events into accumulated wisdom.

code

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

code

.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

code

YYYY-MM-DD-kebab-slug.md

Natural 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

markdown

---
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:

code

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 descriptions

Understanding, 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.

code

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