The Disintegration of the Persistence of MEMORY.md
Show up for your first day at any functioning organization and the same five things (should) happen, in roughly the same order.
- You arrive remembering what your job is here and what you were doing yesterday.
- Someone hands you the binder: hereâs how we do things around here.
- You get a ticket: hereâs your task, here are its files.
- When you finish, it gets filed, so that when someone later asks âwhat did we do for the X widget?â, the answer doesnât depend on whoâs still employed.
- And when something looks wrong - âwait, how did it get like this?â - thereâs a record for when it changed and footage for how and why.
That ladder is the memory apparatus of an institution - and cognitive science already has a name for each rung:
- Autobiographical memory - what I do here, what I was doing yesterday: recent episodes fused with self-knowledge, weighted toward the present, fading as it goes.
- Procedural memory - how we do things here. In a person this knowledge is implicit - you can ride the bike but not recite how - which is exactly why the binder exists: procedure forced into words so it can be handed to someone whose hands donât know it yet.
- Prospective memory - remembering to do: buy the milk, send the report. Psychologists split it into remembering that something needs doing and what it is - and the institution splits it the same way: the ticket holds the what, and the directive to âwork your queueâ supplies the that.
- Semantic memory - facts detached from the experience of learning them. The archive answers âwhat did we do for the X widget?â without needing anyone who was there.
- Episodic memory - re-living a specific event in order: when it changed, how, and why. Audit logs and security camera footage.
No rung is the memory class it serves. The binder holds procedure as explicit words precisely because hands canât be photocopied; the queue holds intentions outside any head so they reload reliably into whichever head takes the ticket. Each rung is a serialization format: a memory class offloaded from one human, stored durably, and deserialized back into the native faculty of another.
Notice one class is absent: working memory, the scratch paper you think on. No institution keeps a scratch-paper archive, and that absence matters later.
Before I name a single tool, place your own agent setup on the ladder. Which rungs do your agents have in the institution youâve built around using them? Which are missing? The missing ones matter unequally: exactly one of them cannot wait.
Six Stores, Five Rungs#
Hereâs my stack, rung for rung:
-
Autobiographical: OptMem-Split.
- While working, the agent records what it judges worth remembering, and at the start of every session its recent memories are pushed into context - what I do here, what I was doing yesterday.
-
Procedural: Nikoâs memory bank forms rungs 2 through 4, starting with the persistent files as the binder.
- Product context, system patterns, tech stack. âWhat this repo is and how we do things here.â
-
Prospective: the ephemeral memory-bank files in
memory-bank/activeare the ticket.- The current task, the plan for how to tackle it, and progress so far.
-
Semantic: the archives in
memory-bank/archive.- One completion record per task, finer-grained than an ADR.
- Episodic, split in two:
I didnât pick these tools specifically to fulfill this taxonomy, by the way - I assembled the stack empirically and noticed the isomorphism afterward.
Exactly one store is pushed: OptMemâs memories arrive unbidden at session start, under a hard cap. Everything else is pulled - the active ticket by a nudge (thatâs the that half of prospective memory, supplied by the Niko entrypoint skills), the archive, the git history, and the footage only when the agent goes digging. That ratio is a staffing decision, not an implementation detail: push more than one rung and youâve reinvented context stuffing with extra steps.
The Notepad Isnât on the Org Chart#
The ambient advice for âgive your agent memoryâ is a markdown file the model appends to. MEMORY.md, a notes section at the bottom of AGENTS.md, or a directory full of such files - the shape is the same: a shared, unordered notepad. Where does it sit on the ladder? Nowhere. Every rung has some rules about how to use it:
- Write Rule: what gets recorded, by whom, when
- Read Trigger: what causes an entry to resurface
- Retention Policy: what ages out, compresses, or gets promoted
The notepad has none of the three. Anything may be appended at any time, nothing determines when an entry is seen again, and nothing ever leaves. At least not predictably. Someone will tell me their MEMORY.md is very tidy; tidiness doesnât supply a write rule.
The generous reading is that the notepad persists the context window. But the context window is working memory - scratch paper. You scribble on it while solving the problem; then you solve the problem, record the solution somewhere governed - the ticket, a commit, the archive - and throw the scribbles away. They should not be preserved - at least, the institution should not be designed to rely on their preservation. If anyone later needs to know how you arrived at the solution, the napkin wonât tell them; the recording of the meeting will, and thatâs rung 5âs job. A MEMORY.md is a photograph of the whiteboard at the end of the meeting: the messy end-result of a live context, now stripped of the liveness that made it and less-intelligible for it. A screenshot of a Zoom call.
The Rung Nobody Needed to Build#
Institutions did not arrive at the ladder by theorizing. They arrived at it by failing, and the binder rung has the best-documented failure of all.
During the Second World War, bombs were going off inside British munitions factories.1 The governmentâs remedy was the binder, enforced: to be a supplier you wrote down your procedures, your workers were inspected against what you wrote, and a state inspector audited the whole method. The bombs stopped going off in the factories. That seed grew through military procurement standards - the US MIL-Q-9858 in 1959, the UKâs Def Stan 05-21 - into the British Standard BS 5750 in 1979, which in 1987 became the ISO 9000 series. Its flagship, ISO 9001, now counts over one million certified organizations across essentially every industry on Earth. âHereâs how we do things hereâ got standardized planet-wide because the failure mode that preceded it left craters.
The other rungs have similar origin stories: ticketing, record-keeping, and audit trails all got formalized after failures made them non-optional. But notice whatâs missing. No institution ever built rung 1. There is no ISO standard for autobiographical memory, no document control number for âremember what you were doing yesterday.â Nobody wrote one, nobody productized it, no vendor category exists - because every hire arrives with it pre-installed. Humans come with yesterdayâs salience for free. The one memory that never needed institutionalizing got a name anyway: we call it experience, and we price it in salary bands.
The four rungs institutions built are also exactly the four you can construct from records - which is what made them institutionalizable in the first place. A binder can be written from what practitioners already know. An archive can be assembled from what the tickets say. An audit trail accretes from artifacts that exist anyway. Whatever required a live judgment in the moment could never be turned into a document control standard, so it stayed in peopleâs heads. Salience never got a serialization format.
Machine agents show up with rung 1 empty. The one rung with no institutional precedent to copy is the one your agents are missing - and itâs also the only one you cannot start late.
Adopt It Six Months Late#
The test: for each rung, suppose you become a believer six months from now instead of today. What have you permanently lost?
| Store | Loss if adopted six months late |
|---|---|
| git history | Zero. It has been recording whether or not you believed in it. |
| The binder | Zero. Arguably better written later, with more system to describe. |
| The ticket | Zero. Point an agent at whatever tracking you already have, whenever. |
| The archive | Near zero. The facts survive in tickets and commits; some texture fades. |
| The footage | Real, but mechanical. See below. |
| Autobiographical (rung 1) | Total. See below. |
Four zeros. Most of agent memory is safe to procrastinate on, and anyone who tells you otherwise is selling something.
A recorder you werenât running canât be re-run, so the footage loss is real - but itâs mechanical, and mechanical loss is the fixable kind, because the raw material usually still exists. Your harnesses have been writing conversation logs to disk all along; thatâs why Stockroom, once I built it, backfilled my entire agent history from those files, including formats the harnesses had already abandoned. In Just Try the Thing I described that as the tool paying backwards. Come around to the importance of reviewing footage in six months and youâll backfill in an afternoon and be nearly whole - because the cameras were running all along.
Rung 1âs loss is total, and âyouâll have zero memories on day oneâ understates it: no process, at any budget, can manufacture what would have been there.
Salience Is a fold, Not a map
#
Suppose you have perfect transcripts - âfootageâ of every session for the past six months. Suppose the exact model that ran those sessions is still being served, so the judge is the same. Suppose token cost is no object. Replay the whole six months through the API, and at each juncture ask the model: what here is worth remembering? Write its answers into your store, timestamped into the past. You now hold six months of memories.
Do you, though?
The five backfillable stores are maps over history: each record is a function of the events it describes, so you can compute any record, in any order, at any distance from the events. Thatâs the mathematical reason the audit table has four zeros in it, and itâs the property the replay is betting on.
Rung 1 is a fold (also known as reduce). Each salience judgment took two inputs: the moment being judged, and the accumulator: every memory recorded so far, pushed into the very context doing the judging. The agent that evaluated week ten had been shaped, at the start of every session, by what it wrote in weeks one through nine. So run the replay and watch it invalidate itself: the first memory it writes changes the context in which the second judgment should have been made, and the transcript youâre replaying was recorded in a world where that memory didnât exist. Rewrite commit three and every SHA downstream changes. There is no fixed set of memories waiting to be recovered, because the memories, had they existed, would have changed everything downstream of them - including which memories came next. The replay doesnât reconstruct your history; it manufactures a history that never happened.
And even granting the manufactured set, itâs missing the thing that made the originals memories: none of it ever influenced anything. A real rung-1 memory earned its place by steering the decisions that came after it. The replayed entries are receipts for judgments that never occurred - downstream of nothing, upstream of nothing.
So the artifact was never the memory. The judgment was - the live, in-context act of deciding this matters, in time for it to matter. The store is a receipt. Rungs 2 through 5 backfill because their contents are records of events, and events leave evidence. Rung 1 doesnât, because its contents are records of judgments, and the judgment is the perishable part.
The Shape, Not the Tool#
I use OptMem for rung 1. You donât need OptMem. You need something, anything, in its shape:
- An agent judges salience in medias res - during the work, while the judgment can still steer it.
- Judgments are written to a temporally-aware store.
- Recent entries get priority.
- Older entries get compressed.
- Whatâs pushed into context is hard-capped.
- Older memories can be resurfaced - progressively disclosed - when judged relevant.
Nothing in that list names a vendor, a file format, or a harness; five people could implement it five different ways, which is how you know it describes a class of memory and not a product. Itâs also the sieve Iâd hold up to the firehose of memory tools that seem to never stop shipping. Anything that satisfies it is a rung-1 candidate, and warrants urgent attention if you donât already have one in play. Anything else can wait (but maybe shouldnât).
Open Positions#
I may have overfit: own five pets and you will discover there are exactly five kinds of animal. So, a redaction test. Cover each storeâs name tag and describe it by three properties alone - the question it answers, what triggers a write, what triggers a read. If a stranger could build a different tool from that description, it names a class and mine is just an instance; if the description only fits my tool, thatâs a pet, not a species. All six stores survive. But covering the name tags of pets you own will never reveal that fish exist: the test checks the rungs I have, and is blind to any I never built.
One gap is visible already: nothing in my stack recalls associatively. The archive, the git history, the footage - all of it gets read when someone already knows to look. Human recall is involuntary; you donât decide to remember the X widget, the X widget surfaces on its own when something rhymes with it. My agentsâ recall is deliberate all the way down. Thatâs an open position on the org chart, and I havenât interviewed a credible candidate yet.
The Only Rung with a Start Date#
Everything else on the ladder will wait for you. Write the binder when youâre ready; it improves with age. Point an agent at your tickets whenever. The cameras are running even if nobodyâs checking the footage yet; backfill whenever youâre ready, from the logs your tools were keeping anyway. Four zeros and one afternoon of catch-up: thatâs the honest cost of procrastinating on five-sixths of agent memory.
Rung 1âs clock only runs forward. Adopt it in six months and youâll hold zero memories on day one, six months of judgments behind - and those judgments werenât recorded-and-lost; they never happened at all.
So find something rung-1-shaped and just try the thing. Starting the clock costs pennies and minutes. Nothing you can pay later will start it retroactively.
-
Seddon, John. âA Brief History of ISO 9000.â In The Case Against ISO 9000. Oak Tree Press, 2000. https://beyondcommandandcontrol.com/wp-content/uploads/2015/09/a-brief-history-of-iso-9000.pdf â©