Agents don't need memory, they need documentation

The piece argues that current “memory” plugins for agents are fundamentally misdesigned because they turn conversation histories into thousands of vectorized snippets and rely on similarity-based retrieval (RAG) to feed context back into prompts. That architecture produces a lottery of fragments: retrieved items lack full context, can be stale or incorrect, and are unauditable; similarity does not guarantee relevance or truth; agents won’t know to search for gaps; and elaborate add-ons (dreamers, rerankers, compressors) only consume tokens without fixing the core issue. The critique summarizes the common pipeline (transcript → snippets → vector DB → top-k injection) and lists concrete failure modes that make recall-based memory unreliable for capturing project intent, decisions, and constraints.

Instead of recall, the recommendation is document-based memory: a readable, versioned “brain” of structured Markdown documents - specs, decisions, indexes, instructions - that agents consult before work and update afterwards, converting PROMPT → BUILD → FORGET into PROMPT → CONSULT → BUILD → UPDATE. The author implemented this approach as Operator Memory, a simple plugin that stores plain Markdown files (no embeddings, vector DBs, or background daemons), enforces read/update behavior, and remains auditable, shareable, and commit-friendly. The system has been used for over a year and is available open source for teams that want a maintainable, context-rich agent workspace.