memory — Project Memory

Lightweight session memory using markdown files. Captures what code can't tell you: decisions, intent, gotchas, and handoff state.

Memory Files

File	Purpose	Budget	Loading
`HANDOFF.md`	Current state, next steps, session gotchas	80 lines	Auto — every session
`SCOPE.md`	Project identity, boundaries, conventions	80 lines	Auto — every session
`SYSTEM.md`	Architecture, components, constraints, gotchas	80 lines	On demand
`DECISIONS.md`	Decision log with reasoning, prepend-only	120 lines	On demand

Command	What it does
`init [description]`	Create `.memory/` with populated files
`update`	Refresh HANDOFF, append new decisions
`status`	Quick health check on memory freshness
`compact`	Suggest compressions, user approves each
`purge`	Delete `.memory/` and clean agent config

Inline (no separate spec needed):

Don't store what's derivable. If git log, grep, or reading code answers it — skip it.
HANDOFF.md is ephemeral. Rewrite it fully each update — it's a snapshot, not a log.
DECISIONS.md is prepend-only. Newest first. Never edit past entries.
SCOPE.md is stable. Update only when project direction genuinely changes.
Keep it tiny. Prune aggressively. If a file is near budget, run compact.

Parse the user's message for a command keyword: init, update, status, compact, purge, search, diff.
If no command recognized, show the commands table and ask.
For search: run grep -ri "<query>" .memory/ directly. No spec file needed.
For diff: run git diff -- .memory/ directly. No spec file needed.
For all other commands: verify .memory/ exists (except init). If missing, say "No memory found. Run init."
Read and execute the corresponding spec:
- init → references/cmd-init.md
- update → references/cmd-update.md
- status → references/cmd-status.md
- compact → references/cmd-compact.md
- purge → references/cmd-purge.md