It’s 11:40 on a Tuesday night. You’re three hours into a refactor with a coding agent, and it finally gets the architecture. It knows why the auth module is split the way it is. It knows the migration you abandoned in March and why. It knows you prefer explicit error types over swallowed exceptions. Then you close the terminal, reopen it in the morning, and the thing greets you like a stranger at a bus stop. So you start installing memory plugins.
That reflex is the subject of a debate that got loud this fall. A widely shared essay published October 3, 2026 on explainx.ai makes a claim that sounds almost too simple to be interesting: this is the wrong problem to solve. You don’t want an agent that remembers your conversations. You want an agent that understands your project. Kevin Liao’s post on the same theme hit Hacker News and argues the same direction, and he goes further on what the fix looks like — a single file isn’t enough. The agent needs an entire brain, a structured workspace where it can record instructions, specs, decisions, research, indexes, anything, without being asked.
I’ve spent enough time instrumenting agent loops to find this framing more useful than most of what gets written about memory. Here’s why.
Memory is a storage answer to a representation problem
When we say an agent “forgot,” we usually mean something more specific: the information it needed was not in context at the moment it made a decision. Memory systems treat that as a retrieval failure and respond by making retrieval better — embeddings, hybrid search, extraction pipelines, recency weighting. Oracle’s recent writeup on AI agent memory lays out the shape of this work honestly. Many agents need to remember more than the latest user message. They need preferences, decisions, task state, policy guidance, tool outputs, prior conversation context. Without memory, the agent starts cold.
All true. But notice what that list is doing. Preferences, decisions, task state, policy guidance — those aren’t memories in any meaningful sense. They’re artifacts. They have authors, versions, and reasons. Storing them as recalled fragments of conversation is a lossy encoding of something that was structured to begin with.
This is where the documentation argument earns its keep. A decision record is not a memory of a decision. It’s the decision, written down, reviewable, diffable, and correctable by a human who disagrees. When your agent’s understanding of the project lives in a prose file in the repo, three properties come along for free that memory systems fight hard to approximate:
- Inspectability. You can read what the agent believes. You cannot read a vector.
- Editability. When the belief is wrong, you fix a line. You don’t negotiate with a retrieval ranker.
- Shared ground truth. The next agent, the next model version, and your new teammate all read the same file.
Where the memory camp is right
I don’t think this resolves cleanly in favor of docs, and the honest reading of these sources is that they disagree rather than that one side won. Eric Roby’s sketch of the 2026 agent stack puts the boundary in a sensible place. A single-session chatbot doesn’t need memory. But an agent covering multiple sessions needs to track user preferences over time, and gather project context over weeks.
That’s the real split. Documentation handles what the project is. Memory handles what happened — the observational residue of working alongside you that nobody would ever think to write a spec about. You interrupt long-running tasks. You hate being asked to confirm twice. You always want the test run before the commit. That’s behavioral, accumulated, and genuinely memory-shaped.
The failure mode in practice is using one for the other’s job. Teams stuff architectural truth into memory stores and then wonder why the agent cites a design it saw discussed and discarded. Or they write beautiful specs and still watch the agent make the same workflow mistake forty times, because nothing is accumulating observations.
What I’d build instead
Treat the repo as the agent’s source of truth and treat memory as a cache of behavioral signal with a short half-life. Give writes to the documentation layer first-class status — if the agent learns something durable about the system, that learning should land as a file change, not a memory row. Make everything the agent believes about the project reachable by a human with a text editor.
The appealing part of the documentation argument isn’t that memory is useless. It’s that writing things down is a discipline we already know how to do, with tooling we already trust. Agents that work well over weeks look less like minds with good recall and more like careful colleagues who keep notes.
đź•’ Published: