A memory system that only ever appends becomes a diary nobody rereads. One fact per file, an index that loads every session, and aggressive deletion of what turned out wrong is what keeps it worth reading.
The failure mode I kept hitting with agent memory was not that it forgot things — it was that it remembered everything, indiscriminately, and the useful facts got buried under a sediment of session notes nobody was ever going to reread. A memory system that just appends is a diary, and a diary is exactly the wrong shape for something that has to be scanned in full at the start of every session.
What works instead is closer to a card index than a journal. One fact per file — a preference, a piece of standing project context, a correction with its reason — each one small enough to be read in isolation, with a short description attached that says what it is for. The description matters more than it looks like it should, because it decides whether the fact gets surfaced the next time it is relevant, and a fact that never gets surfaced again is functionally the same as a fact that was never saved.
On top of the individual files sits one index — a single document that loads every session, one line per fact, pointing at where the full version lives. That index is the thing that actually gets read cheaply and often; the individual files get read on demand, when something in the index suggests they matter to what is happening right now.
The part people skip, because it feels like throwing away work, is deletion. A fact that turned out to be wrong — a workaround for a bug that got properly fixed, an assumption about a system that changed underneath it — does not get an amendment appended next to it. It gets deleted, cleanly, so nothing reading the index later has to work out which of two contradictory entries is current. A memory system that only ever grows accumulates exactly the kind of stale, contradictory advice that makes an agent confidently wrong.
The instinct to keep everything just in case is understandable, and it is also how you end up back at the diary problem from a different direction — a memory store so large that scanning it costs more than the value of anything it might contain. Aggressive deletion is not the memory system failing to be thorough. It is the maintenance that keeps a memory system worth reading at all.
The other half of keeping it small is being strict about what never goes in. Anything the codebase already records — the shape of the modules, what a function does, why a commit was made — does not belong in a memory store, because the code and the history are the source of truth for those, and a remembered copy exists only to go stale against them and then contradict them confidently. The same goes for anything true only inside the current session: what I am part-way through right now is context, not a fact, and writing it down as one produces an entry that reads as standing knowledge six weeks later when what it actually describes is an afternoon that ended long ago. What earns a place is the thing that is durable, not derivable from anything else, and would otherwise have to be explained from scratch every time — a preference, a constraint that came from outside the code, a correction and the reason behind it. Everything else is sediment that has not settled yet.
The test for whether a memory system is working is not how much it holds. It is whether the fact you actually needed this session was easy to find, current, and not sitting behind forty other entries nobody has looked at in months.