Project memory

docs/memory/README.md is the routing index for hard-won knowledge. The actual entries live beside it in focused files under docs/memory/. docs/PROJECT_MEMORY.md is only a compatibility pointer for older clients. This catalog is shared by every developer, agent and reviewer and replaces agent-private memory stores.

Consult it first

Read docs/memory/README.md, then only the topic files covering the area you will touch. Do not load every topic by default. A meaningful share of "new" bugs in this repo are documented recurrences.

What belongs here

Something non-obvious, durable, and written in English: a foot-gun that cost real debugging time, an invariant that is not visible from the code, a decision whose rationale would otherwise evaporate, an intentional asymmetry that looks like a bug.

What does not belong: anything the repo already records — code structure, the content of a fix (that is the commit), git history, or universal rules already written in AGENTS.md. Do not restate; link instead.

Entry format

Add the entry to the narrowest existing topic file.

### slug-with-dashes

One concise paragraph naming the mechanism and the action future work must take.

Use dash-separated slug headings. Keep entries short enough to scan and link directly to code/tests when that is more useful than restating them.

Writing well

• Be concrete. "Guard the map access" is useless; name the file, the key, the failure mode, and what the symptom looked like.
• Convert relative dates to absolute. "Last week" is meaningless in six months.
• Record the symptom, not just the cause — that is the string a future reader searches for when they hit it again.
• Check for an existing entry first and extend it rather than adding a near duplicate. Delete entries that turn out to be wrong.
• Delete stale history. Completed audit transcripts, branch narratives, commit summaries, temporary measurements, and TODO snapshots belong in Git, not project memory.
• Verify before trusting. Entries reflect what was true when written. If one names a file, function or flag, confirm it still exists before acting on it — and correct it if not.

Cadence

Add or update entries proactively at the end of a task, without being asked. Prune obsolete material at the same time. Put measured rejected ideas in docs/memory/rejected_proposals.md, not among implementation invariants. Then commit without pushing, per the commit-and-push skill.