What my agents are allowed to remember

Every agent platform ships memory now. Persistence across sessions went from a trick to a checkbox sometime this year, and I expected that to settle the question. It didn't. My agents remembered plenty. They just never remembered anything useful, and the first time I audited the store I found out why: the memory was filed like a library and read like a headline.

Here is the mechanism that bit me. A memory store has two layers, an index file that loads into every session, and a body file per memory that loads only if something sends the agent to read it.

memory/
├── MEMORY.md            the index: one line per memory, loaded
│                        into every session
├── deploy-cache.md      a body: opened only when its index line
├── editor-profile.md    sends the agent there, which is rarely
└── ...

I had written the index as titles. "Deploy notes". "Editor profile gotcha". The facts those titles pointed at lived in the bodies, and the bodies never got opened, because nothing in a title tells an agent mid-task that the body matters. The index was the only layer reliably read, and I had filled it with pointers to the layer that wasn't. Memories that cost real incidents to learn sat there, correctly filed, dead.

The routing rule that fixed it fits in one line: the actionable atom goes into the index line itself, and the body holds only what is worth a deliberate fetch, the why, the full runbook. A dead line and a live one:

- Deploy notes
+ Deploys need the cache cleared first, or the old bundle serves an hour

The body can explain the hour.

- Write every index line as if it is all the agent will ever see, because usually it is.

That fixed retrieval. The bigger problem was admission, because an agent that can write memory will write memory about everything. So a memory earns its slot by passing three tests, and fails on any miss:

1. Not derivable. If the repo, its history or its docs already record it, the memory is a copy, and copies drift. One home per fact.
2. Durable. True beyond this conversation. "We are editing the parser today" is context, not memory.
3. Behavior-changing. A future session acts differently for having it. Trivia fails; preferences, gotchas and standing rulings pass.

Shape decides where a survivor goes. A rule that fires on the shape of a task, "never stage with add-all", gets a one-line pin in the instructions that load every time. A plain fact gets a self-contained index line. A fact about one project lives in that project's store and nowhere else; the global store is for the machine and the person.

Then there is decay, which is the part nobody warns you about. A stored claim is a claim about the past. Repos merge, flags flip, another session fixes the thing, and the memory sits there unchanged and confident. I lost a day to this once, duplicating a feature my night shift had already built, on the strength of a queue entry I had read the day before and carried in my head. Two rules now handle it. Re-verify on repeat, or drop: any stored claim about to be repeated or acted on gets checked against the primary source, the file over the summary, the machine over the memory, or it gets deleted. And the tell for when to check is the feeling of already knowing. Every stale assertion I have audited in my own sessions had that same signature, a fact held confidently enough that checking felt redundant. That feeling is the trigger, not the excuse. The belief you are about to act on is exactly the one worth the ten-second look.

Which leaves bloat. Agents inflate everything they write and memory is no exception, so the counterweight is machinery, never advice. My index lines carry a hard character budget and a commit hook rejects the commit that exceeds it; the fix is demoting detail into the body, not arguing with the hook. Wrong memories get deleted, not annotated. A store with archaeology layers is a second archive, not a working surface.

If you want one thing to do today:

1. Open your store and grade every entry against the three tests.
2. Delete the derivable, the transient and the inert.
3. Lift every surviving body's atom into its index line.
4. Count.

If more than half died, you did it right. The store was carrying the noise floor of everything you ever half-thought, and your agents were paying the reading tax every single session.