AI agents today often rely on 'memory' plugins that attempt to give them persistent context across sessions. However, these systems are fundamentally flawed. Rather than helping agents understand projects, these memory plugins create a lottery where agents retrieve snippets of past conversations hoping the relevant ones float to the top. The problem lies in the architecture of these memory systems. Nearly all commercial memory plugins work identically: they analyze session transcripts, generate memory snippets, store them in a vector database (RAG), and on every prompt retrieve the top 5 most similar snippets to inject into the agent's context. This approach suffers from several critical limitations. First, memories are surfaced purely by similarity in embedding space, with no mechanism to determine which snippet is correct, current, or complete. Second, storing only snippets loses crucial context—motivations, lessons learned, environmental factors, and reasoning behind decisions. Third, these systems treat the past as truth, ignoring that codebases evolve daily, making snippets about features like authentication quickly outdated. Fourth, even when agents are given search tools over their memory, they cannot know what to search for because they don't know what they don't know. Finally, the memory store becomes unauditable—thousands of embeddings in SQLite with no way to verify which memories exist, which are stale, or which might be incorrectly influencing agent behavior. The core insight is that agents don't need better recall mechanisms; they need documentation. As the author observes, 'No one rewatches a team meeting from 3 years ago to remember constraints around a feature. People write things down and use those records instead.' This realization led to the development of document-based memory systems. Instead of capturing fleeting conversation snippets, these systems give agents a structured workspace of Markdown files where they can persist important knowledge: specifications, decisions, research findings, indexes, and guidelines. The agentic loop transforms from 'prompt → build → forget' to 'prompt → consult → build → update'—before starting work, the agent consults relevant documents from its brain; after completing work, it updates the brain by revising outdated information and adding new documents where needed. One implementation of this approach is Operator Memory, which provides agents with a Markdown-based brain organized into three partitions: private project knowledge (.operator/), project knowledge shared with the repository (.operator-shared/), and personal rules usable across projects (~/.operator/user/). The system features automatic documentation of specs and decisions, transparent memory stored as readable Markdown files, shareable knowledge through Git version control, and zero infrastructure requirements—no background agents, embeddings, or vector databases. Similar principles appear in alternative systems like Encephalon, which stores durable agent knowledge as Git-mergeable JSON records indexed by SQLite for fast search. Both approaches share the key characteristic of treating agent memory as documentation that can be read, updated, committed, and shared—rather than as an opaque recall mechanism. This shift represents a fundamental change in how we think about agent state: moving from brittle, context-free snippets to maintainable, auditable documentation that grows with the project and team.
The image supports the article’s core argument that agents should consult documentation (the brain) before building and update it after work, rather than relying on unreliable memory snippets.