memory-structure

Persistent memory for Claude Code. Survives context compaction and session boundaries.

When to Bootstrap

• No memory/ directory exists in the auto memory path (shown in system prompt)
• User asks to set up memory or save context
• Context is growing long and key information risks being lost

Directory Layout

memory/
├── MEMORY.md          # Index — auto-loaded, kept under 200 lines
├── architecture.md    # Module layout, data flow, key types
├── decisions.md       # Design decisions with one-line rationale
├── debugging.md       # Past bugs: symptom → root cause → fix
└── patterns.md        # Code conventions, fixture templates

Start with MEMORY.md only. Add topic files as the project grows.

MEMORY.md Template

# Project Name — Memory

## Project State
- Current phase/status in one line
- Key metrics (test count, lint status)

## Key Gotchas
- Hard-won lessons that prevent repeat mistakes
- One line each, specific and actionable

## Architecture Rules
- Invariants that must never be violated

## Build
` ` `bash
# exact commands to build/test/lint
` ` `

## Deep References
- [architecture.md](architecture.md) — module layout, data flow
- [decisions.md](decisions.md) — design decisions and rationale
- [debugging.md](debugging.md) — past bugs, root causes, fixes
- [patterns.md](patterns.md) — code patterns, conventions

Topic File Formats

architecture.md — Module tree, data flow (ascii), key types table, public API, test map. Update when modules change.

decisions.md — One entry per decision. Title + one-line rationale:

## Decision Title
Brief rationale explaining why this choice was made.

debugging.md — One entry per bug. Three fields:

## Bug Title
**Symptom:** What you observed.
**Root cause:** Why it happened.
**Fix:** What resolved it.

patterns.md — Recurring code patterns with minimal examples. Function signatures, registration patterns, test fixture templates, data model conventions.

Maintenance Rules

1. MEMORY.md must stay under 200 lines — it's auto-loaded into every prompt
2. Topic files: no hard limit, but prefer concise over exhaustive
3. Update after completing significant work — don't let memory go stale
4. Delete or correct entries that turn out to be wrong
5. Organize by topic, not chronologically
6. These files are private to Claude Code — never check into git
7. Information useful to humans or other agents belongs in docs/, not here