Memory Consolidation

Agents forget everything between sessions (lesson 2), and the remedy is a memory file: notes written at the end of work — decisions made, approaches that failed, current state — and reloaded at the start of the next session. CLAUDE.md holds the permanent knowledge (lesson 8); a memory file holds the evolving kind: where a multi-day effort actually stands, and why. Memory consolidation is the unglamorous discipline that keeps such files useful instead of letting them rot into a junk drawer — a small practice with one genuinely deep trap. This lesson: the retention policy that is the whole game, the trap, and the brutal little test that tells you whether your memory actually works.

The retention policy is the whole game

A memory file without admission rules grows without bound, and a 5,000-line memory is functionally amnesia: the load-bearing note is buried in transcript sludge, the whole thing rides your context budget (lesson 2), and the model's attention over it degrades exactly like any long context. Decide what earns a line before the session — mid-session, everything feels important, which is why files curated in the moment converge on "everything." A filter that works:

Decisions, with their reasons. "Chose polling over webhooks — provider's webhooks drop events under load." The reason is the valuable half: it's what prevents next month's session from re-litigating the choice with less information than you had.

Dead ends. "Migrating auth first fails — session table has an FK into users; do users first." Failed paths are premium content — the notes that stop an agent from confidently repeating last week's four-hour mistake. (Notice these are exactly what a fresh session cannot infer from the code: the code shows what you did, never what you tried and abandoned.)

Corrections issued twice — the standing bugs in the agent's mental model of this effort. When one turns out to be permanent, it graduates to CLAUDE.md (lesson 8's correction-harvesting, one layer down).

Current state, tersely. Done / in progress / next. A few lines, dated.

And the expiry rule that makes state notes safe: they rot fast, and the model cannot tell stale from current — it follows a three-week-old "next steps" with exactly the confidence it follows yesterday's (lesson 4's staleness trap, sharpened: this file changes weekly by design, so rot is structural, not accidental). Date entries. Sweep on task completion. When an effort ends, distill its durable lessons into CLAUDE.md and delete its memory — an archived memory file is a trap you've set for a future session.

The consolidation trap

Periodically you'll compress the file — summarize, prune, tighten. Necessary, and here's the trap: consolidation is lossy, and its loss is silent. The summary keeps what seemed important at compression time; what got dropped is gone from the only place it lived — unlike code, there's no git history of your reasoning unless you make one. Worse, the loss compounds: summarize a summary a few times and you're reading a fourth-hand account. Each pass looked reasonable; the sum has quietly shed the specific details — that FK constraint, that provider quirk — which were the file's entire value. Generic advice survives compression; specifics die in it; and specifics were the point.

Two mitigations, both cheap:

1. Consolidate by rewrite, not re-summarization. Go back to the sources — the actual decisions, the current code, the open PRs — and write fresh notes, rather than compressing the previous compression. First-hand every time, however many times.
2. Log what you drop. One line — "pruned: webhook investigation (superseded by polling decision)" — turns a silent loss into an auditable one. And it generates a signal: if the same topic keeps getting pruned and re-added, the file is telling you that topic belongs in permanent memory instead.

The test that actually matters

Everything above is technique; this is the measurement. Cold-start a fresh session with only the memory file and ask it to continue the work. If it makes a mistake the previous session already learned from — re-proposes the abandoned approach, re-breaks the known constraint — the memory failed, whatever it felt like it contained. Run this for real occasionally, not as a thought experiment: it measures the only thing memory is for, which is whether the next session is genuinely smarter than the last.

And when you want the claim to be rigorous — does this memory file actually improve outcomes, or is it 2,000 tokens of comfort ballast? — that's a lesson 21 question with a lesson 21 answer: score sessions with the file against sessions without it, same suite, same yardstick. Memory that doesn't move the score is rent paid on every turn (lesson 20) for nothing. Memory that does is the cheapest capability upgrade in this course: a text file, some discipline about what it admits, and the humility to test whether it's working.