Twenty-six. That was the point count on the Hacker News thread for Kevin Liao’s post, “Agents don’t need memory, they need documentation,” when I opened it. A modest number for an argument that quietly undercuts an entire category of tooling I’ve been bolting onto my own bots for the better part of two years.
I build agents for a living. I have written memory layers. I have shipped vector stores stuffed with conversation transcripts. And after reading Liao’s piece alongside the essay from explainx.ai dated October 3, 2026, I had the uncomfortable realization that most of what I called memory was just a very expensive way of avoiding writing things down.
The claim, stated plainly
The explainx.ai essay puts it in a line worth repeating: you do not want an agent that remembers your conversations, you want an agent that understands your project. Those are not the same goal, and they do not have the same solution.
Remembering conversations is a retrieval problem. Understanding a project is a structure problem. When I ask an agent to add a feature, I don’t need it to recall that I was grumpy about the auth refactor last Tuesday. I need it to know where the auth boundary lives, which decisions are already locked, and what the tests expect. None of that belongs in a chat log. All of it belongs in a file.
One file won’t cut it
Liao’s framing is the part that actually changed how I work. His argument is that a single file is not enough. The agent needs an entire brain, a structured workspace where it can record instructions, specs, decisions, research, indexes, anything, without being asked.
That last clause is the one I keep coming back to. Without being asked. Most of us treat documentation as a thing the human writes and the agent reads. Flip it. Give the agent write access to its own context directory and let it maintain the thing it depends on. The agent that just spent forty minutes figuring out why your build breaks on Node 20 is the agent best positioned to write that down.
In practice, the layout I’ve settled on looks something like this:
- Instructions — how to behave in this repo, what’s off limits, which commands to run before claiming something works
- Specs — what we’re building, in enough detail that a fresh session can pick it up cold
- Decisions — the choices already made and why, so nobody relitigates the database schema every Monday
- Research — findings from investigation, including dead ends, which are the most valuable and least recorded artifact in software
- Indexes — pointers into the codebase so the agent isn’t re-deriving the map every time
The nice property here is that it’s all plain text in version control. It diffs. It reviews. It survives you switching model providers. Try saying that about a proprietary memory plugin.
The counterargument deserves a hearing
I’d be doing you a disservice if I pretended this was settled. Oracle’s recent writeup on AI agent memory makes a straightforward case in the other direction: many agents need to remember more than the latest user message. They need preferences, decisions, task state, policy guidance, tool outputs, and prior conversation context. Their newer work adds custom extraction, hybrid search, and more control over what gets retained.
Eric Roby draws a similar boundary in his piece on the 2026 agent stack. A single-session chatbot doesn’t need memory. But an agent working across multiple sessions, tracking user preferences over time and gathering project context over weeks, is a different animal.
Read those lists carefully, though. Decisions. Task state. Policy guidance. Those are documentation artifacts wearing a memory costume. The genuinely memory-shaped items are the personal ones: preferences that accumulate about you specifically, across projects, over months. That’s real, and docs in a repo don’t cover it.
Where I’ve landed
The sources don’t hand you a verdict, and I won’t fake one. What they do give you is a useful split. Project knowledge is documentation, and it should live as structured, writable files inside the thing being built. Personal continuity across sessions is memory, and it’s a much smaller surface than the tooling market implies.
If you’re deciding where to spend your next build weekend, I’d skip the embedding pipeline. Spend it designing the workspace your agent writes into. You’ll get a system that’s debuggable, reviewable, and portable, and you’ll stop paying retrieval costs for information that could have been a markdown file.
🕒 Published: