AI agents need documentation, not retrieval-based memory

Documentation over recall

Memory plugins generally process session transcripts into isolated snippets, store them in a vector database and retrieve the five most similar items for each prompt. Agents can also search the archive, but similarity alone cannot establish whether a snippet is correct, current or complete. Context, motivations, lessons and environmental details may be lost when conversations are reduced to snippets.

The source says this creates an opaque store. It cites examples such as hundreds of snippets about authentication becoming outdated as code changes, and embeddings in SQLite that may be stale, unused or incorrect. An agent cannot reliably search for unknown gaps because it does not know what it does not know. The argument is that teams document constraints and decisions rather than reconstructing them from old meetings, so agents should consult maintained records instead of relying on recall.

A structured workspace for agents

AGENTS.md files already give agents project-level guidance, but the source says one file is rarely enough. It recommends a broader workspace containing instructions, specifications, decisions, research and indexes. Agents should read relevant documents before work and update outdated or missing material afterward. This changes the workflow from prompt, build and forget to prompt, consult, build and update, while making context readable, editable and shareable.

The model is presented as document-based memory: a persistent knowledge base rather than a database of retrieved conversation fragments. The aim is to give an agent a fuller picture of why features exist, what was agreed and how the project works, while allowing people to inspect and maintain the underlying records.

Operator Memory puts the model into Markdown

Operator Memory is the source author's open source implementation of this approach. It provides agents with a Markdown workspace for instructions, specifications, research and indexes. Agents consult relevant documents before working and update the workspace afterward by revisiting stale material and adding missing documents.

The system does not use vector databases, embeddings, summarizers, curators, updaters, background daemons or black-box retrieval, according to the source. Its records remain plain Markdown files that can be read, updated, committed and shared with a team. The author says they have used the system across their projects for more than a year and that the software is free and open source.