Operator Memory author: agents need documentation, not RAG memory

The post, titled "Agents Don’t Need Memory. They Need Documentation.", opens with a description of how a typical agent memory plugin works. It analyzes your conversations, generates 1,000 isolated snippets and inserts them into a vector database. With each prompt it attaches the five most similar snippets, and if the agent is confused, the agent searches manually for more. The author calls this a lottery over RAG snippets: you want the agent to understand your project (where a feature is, why it was built, what was agreed), but you get injected fragments and hope the right ones float up. His thesis is that the whole memory plugin ecosystem is solving the wrong problem.

He says every memory plugin on the market works the same way: go through session transcripts, generate snippets of memories, insert them into a RAG database, retrieve the top 5 on every prompt and inject them, and optionally give the agent a tool to search the database. Fancier tools let the agent search past transcripts word for word, add multi-tier memory that separates short and long term, run background daemons that review, merge or deduplicate memories, or use "dreamers" that rewrite memories overnight, continuous context compression and rerankers. In his words, each plugin adds token-burning features to the same flawed architecture, which is why none of them reliably work.

He lists five problems with recall. First, memories are surfaced by similarity, which only ranks how close two snippets are in embedding space, so you cannot tell which is correct, current or what is missing. Second, snippets are stored without context: motivations, lessons and environment are lost. Third, the past is treated as truth, yet the codebase changes every day, so he asks how accurate each of 500 snippets about authentication would be. Fourth, agents cannot search for what they do not know, so even with a search tool they will not know when to use it. Fifth, the store is unauditable: with 10,000 embeddings in SQLite, you cannot easily tell which memories exist, which are stale, which were never retrieved, or which are wrong and quietly shaping the agent's behavior. All of this, he says, follows from one assumption: agents forget, so the fix is to remember better.

His counter-argument is an analogy. Nobody rewatches a team meeting from 3 years ago to recall the constraints around a feature; people write things down and use those records. So the answer is not a search tool over 10 million tokens of past conversations. It is document-based memory. He adds that people now use AI to produce products and features at great speed without reading the code, so documentation becomes an afterthought just when it matters most.

He notes that AGENTS.md files were invented so agents do not enter a codebase blind, and that this works, but often that single file is the only documentation a project has. A single file is not enough. The agent needs a "brain": a structured workspace where it records instructions (such as how code review works), specs of what was discussed with the user, reusable research on a foreign library or API, and indexes, without being asked. Before working, the agent reads the relevant files. After working, it updates what is outdated and adds new documents while the full picture is still in context. The loop changes from prompt, build, forget to prompt, consult, build, update. Memory becomes a workspace you can read, update and share, not a RAG database bolted onto the agent.

In the section "Putting It to the Test", the author says he recognized the problem over a year ago when he started programming with AI. He created an internal/ folder where the agent wrote specs, plans and indexes, and told it to read the right documents and the index before work and update them afterwards. These rudimentary instructions grew into a formal system and then into a plugin called Operator Memory, which he has used regularly across all his projects for over a year. It gives the agent a Markdown brain for instructions, specs, research and indexes. It uses no vector databases, no embeddings, no summarizers, curators, updaters, dreamers or other background daemons, and no black-box retrieval. Everything is a plain Markdown document that can be read, updated, committed and shared with a team. The plugin is free and open source, at github.com/aerovato/operator-memory.

Key facts

• The author says all memory plugins share one RAG architecture: mine transcripts, generate snippets, store them in a vector database, inject the top 5 on every prompt, and optionally add a search tool.
• He lists five problems: similarity ranking says nothing about correctness, snippets lose context, the past is treated as truth while code changes daily, agents cannot search for what they do not know, and the store is unauditable.
• His alternative is a structured Markdown workspace (a "brain") that the agent consults before work and updates after, changing the loop to prompt, consult, build, update.
• He built the plugin Operator Memory from this idea; it has no vector databases, embeddings, summarizers or background daemons, and is free and open source.
• His evidence is a personal account of using the system for over a year; the post reports no benchmark or comparison.

Why it matters

Agent memory is a crowded plugin category, and this post questions its basic design. The author's claim is that retrieving similar snippets is the wrong way to give an agent project knowledge, because knowledge people actually rely on is written down, organized and kept current. He ties this to a current habit: AI is used to ship features quickly without reading the code, so documentation gets neglected. The practical idea is simple. Treat the agent as a team member who reads and maintains project docs, rather than as a system that needs a retrieval layer.

Who it affects

People who code with AI agents and have tried or are considering memory plugins, especially those whose only project documentation is a single AGENTS.md file. It also touches teams, because the author stresses that a Markdown workspace can be committed and shared, while a vector store cannot be read the same way. Builders of memory plugins are the target of the criticism, although the post names no specific plugin.

How to use it

The author's recipe has two parts. Give the agent a structured workspace of Markdown documents (instructions, specs, decisions, research, indexes) and instruct it to read the relevant documents and the index before every task and to update stale ones and add missing ones afterwards. He started this way by hand with an internal/ folder. Or install his plugin Operator Memory, which packages the approach and is free and open source at github.com/aerovato/operator-memory. The text does not say which agents or models the plugin supports.

How solid is it

This is an opinion piece by the plugin's own author, who is promoting his own tool. The support is an analogy (nobody rewatches a three-year-old meeting) and his personal account of using the system for over a year across his projects. No benchmark, measurement or comparison against memory plugins is reported, and the figures of 1,000 snippets, 10,000 embeddings and 500 authentication snippets are illustrative examples, not measurements. No specific memory plugin is named or tested; the criticism is of the whole category. No user numbers, adoption data or independent reviews of Operator Memory are given.

Risks and caveats

The claim that none of the memory plugins reliably work is the author's assertion and is not tested in the post. The approach also depends on the agent consistently reading and updating the documents, and the post does not measure how well that happens. The author says that the document brain is read before work and updated after, but gives no token-cost figures for either approach, so the claim that plugins burn tokens while documents do not remains unquantified. Treat it as a design argument and a tool worth trying, not as a proven result.

“Agents don’t need memory. They need documentation.”

— From the blog post "Agents Don’t Need Memory. They Need Documentation."