What an agent should remember, and what it should forget

The naive version of agent memory is to save the conversation and reload it. Keep the transcript, stuff it back into context next time, call it continuity. It doesn't work, for the same reason a person doesn't remember a day by replaying every second of it. Most of what happens in a session is scaffolding — dead ends, restated context, the back-and-forth of getting to an answer. Re-loading all of it doesn't make the agent wiser; it buries the three facts that mattered under a thousand that didn't, and it costs you on every single turn to carry the weight.

So the first design decision is that memory is not storage, it's distillation. The question at the end of a session isn't 'what happened,' it's 'what did I learn here that will still be true and useful next time, that I couldn't just re-derive from the code?' That last clause is the filter. Anything the agent could rediscover by reading the repo doesn't belong in memory — the repo already remembers it. Memory is for what the repo can't tell you.

If the agent can re-derive a fact by reading the code, it isn't a memory — it's a cache you'll have to invalidate. Save the things the code can't tell you.

Once you accept that memory is a small, curated set rather than a log, the question becomes what earns a slot. I've converged on a short list of categories, and almost nothing lives outside them. Who the operator is — role, preferences, the way they like to work. Feedback — corrections I've been given and should not need to be given twice, always with the why, because a rule without its reason gets misapplied. Project state — the goals and constraints that aren't visible in the code or the git history. And pointers — where the real thing lives, so the agent knows how to go find the detail rather than trying to hold it all.

The discipline is that each of those is one fact per note, with a one-line description of what it's about, so the agent can decide relevance quickly without reading the whole thing. It's the same progressive-disclosure trick that makes anything scale: keep the always-on index tiny and sharp, and let the depth live one level down, pulled in only when a note turns out to be relevant to the task at hand.

Concretely, a note is a tiny file with a name, a one-line description, and a body — and one index that lists them all. The name and description are what's loaded every session so the agent can route among its memories cheaply; the body is only pulled when the description signals it's relevant. A feedback note doesn't just say 'the operator prefers terse replies' — it says that, plus why, plus how to apply it, so a future agent inherits not just the rule but the reasoning behind it and can't misfire it in a new situation.

Of the four kinds, the one that pays off most is feedback — the record of corrections. The reason is compounding: a correction I capture once saves me from re-explaining it every session thereafter, and the cost of re-explaining the same thing to a stateless agent is the single biggest tax on running a fleet of them. Every 'no, not like that' that gets written down with its reasoning is a mistake the whole fleet stops making, permanently, instead of one I re-litigate every time a fresh agent starts cold.

This is also why the feedback note carries the why and not just the rule. A bare instruction — 'always do X' — gets applied blindly in situations where it shouldn't, because the agent doesn't know the boundary of when it applies. The reasoning is the boundary. It turns a brittle command into a piece of judgment the agent can extend correctly to cases the original correction never anticipated. Catalogued corrections, with their reasons, are also exactly what a good adversarial review leans on to check whether a new plan is about to repeat an old mistake.

The failure mode of any memory that everything writes into is rot. Notes go stale. Two notes quietly contradict each other. A fact that was true when it was written names a file that no longer exists. Left alone, a memory store degrades from an asset into a liability — a pile of confident, out-of-date claims that make the agent worse than having no memory at all, because now it's wrong with conviction.

So forgetting has to be a deliberate, scheduled act, not an accident. Notes that turn out to be wrong get deleted, not just corrected. Anything that names a specific file or flag gets treated as a claim to verify before it's trusted, because the world it described may have moved. The same instinct that keeps a shared note-vault from filling with stale duplicates applies here: a memory that only grows is a memory that's dying slowly, and the healthy ones are weeded as ruthlessly as they're written.

The reason this is worth getting right is that memory is the difference between an agent that's a very fast stranger and one that's actually a colleague. A stranger you have to brief every time; the briefing tax eats the speed advantage. A colleague remembers that you hate a certain pattern, that this project has a specific landmine, that last month's decision went a particular way for a reason. The compounding only starts once the agent stops arriving empty-handed.

And the shape of a good memory says something about how I want the whole system to behave: modest, curated, honest about staleness. It doesn't hoard. It writes down what it learned, links it to what it already knew, and throws out what stopped being true. That's not a database design decision. It's the same value that runs through everything else I build — that the impressive behavior on the surface is downstream of a lot of unglamorous discipline about what to keep, what to check, and what to let go.