Current AI agent memory plugins operate on a flawed premise, according to a software developer who has spent over a year working with the technology. These tools typically function by analyzing conversation transcripts, generating isolated snippets, inserting them into vector databases, and then retrieving the most similar snippets for each new prompt. While this approach mimics how humans recall information, it fails to provide agents with the kind of understanding they actually need.
The core issue, the author argues, is that similarity-based retrieval—the foundation of all major memory plugins—has inherent limitations. Memories surfaced this way are ranked only by embedding proximity, offering no guarantee they are correct, current, or complete. Context, motivations, and environmental details are lost when information is compressed into RAG snippets. Additionally, the codebase changes constantly, making historical snippets potentially inaccurate references. Even when agents can search the memory database directly, they lack the awareness to know what information they’re missing.
Instead of relying on recall systems, the author proposes document-based memory: a structured workspace where agents write and maintain plain-text documentation before and after each task. This mirrors how human teams actually manage knowledge—through written records rather than by rewatching past meetings.
The approach involves creating a dedicated folder where agents store instructions, specifications, decisions, research notes, and indexes. Before working on a task, the agent reads relevant documents for context. After completing work, the agent updates outdated information and creates new documents while the full picture remains in memory. This transforms the workflow from “prompt → build → forget” to “prompt → consult → build → update.”
The author developed a plugin called Operator Memory based on this principle over a year of personal use. It provides agents with a Markdown-based “brain” without vector databases, embeddings, or background daemons. All information remains in plain-text format that team members can read, update, version control, and share. The plugin is available as free and open-source software.
According to the author, documentation-based approaches already exist in practice—many developers create AGENTS.md files to onboard AI agents into codebases—but these single files are insufficient. A complete documentation system requires organized, persistent records maintained throughout the agent’s interaction cycle.
Key facts
- Current memory plugins use RAG-based retrieval ranked only by embedding similarity, offering no guarantee of accuracy or completeness
- Vector database approaches lose context, motivations, and environmental details when compressing conversations into snippets
- Agents cannot effectively search for information they don’t know exists, limiting the utility of search tools
- Documentation-based memory systems require agents to read relevant files before working and update them afterward
- The author’s Operator Memory plugin uses plain Markdown documents instead of embeddings or vector databases