Agent Memory vs Documentation: Which Does Your Agent Need?

Use both, for different jobs. Documentation is curated knowledge a human wrote and reviews: requirements, decisions, constraints. Agent memory is an automatic record of what happened across sessions, including the failures nobody would ever write down. Docs answer “what should this be?”; memory answers “what did we already try?”

What the agent memory vs documentation debate is about

In October 2026 a post titled “Agents don’t need memory, they need documentation” by Kevin Liao reached 392 points on Hacker News. It argued that memory plugins all share one shape (generate snippets from transcripts, store them in a vector database, inject the top matches) and that this shape is broken for coding work.

The post names five problems:

1. Similarity-based recall. Memories surface by vector similarity, so the agent learns nothing about whether a hit is still relevant or what it is missing.
2. Missing context. A snippet loses the motivation and the environment that made it true.
3. Stale truth. “The past is treated as truth,” while the codebase changes daily.
4. Unknown unknowns. An agent cannot search for what it does not know it is missing.
5. Opacity. An unauditable store can shape behavior with a wrong memory nobody can see.

Its answer is Operator Memory (BSD-3-Clause, 461 stars at the time of writing): markdown documents in the repo, a lean catalog injected at session start saying which document to open and when, written by the working agent while it still has full context, with a “no appending” rule so facts get rewritten instead of accumulating. It installs per harness (operator-helper install <harness>) for Claude Code, Codex, OpenCode V2, Pi and the DeepSeek harness.

What is agent memory?

Agent memory is a store that an agent writes to and reads from automatically across sessions. It captures episodes (what happened, when, in what order), facts extracted from those episodes, and in some systems consolidated beliefs built from repeated evidence. The agent decides what to keep; retrieval happens at query time, not by a human opening a file. See how AI memory works for the mechanics.

Documentation, by contrast, is written once and read deliberately. A human owns it, a human reviews it in a pull request, and it is only as current as the last person who touched it.

What each one actually fixes

The two failure modes are different, which is the clearest sign they are not substitutes. Documentation fails from neglect. Memory fails from accumulation.

Where the documentation-only argument holds

For a single repo with a small team and slow-changing architecture, curated markdown is usually enough and costs nothing to run. You get:

• Review. Memory that lands in a pull request can be rejected.
• No infrastructure. No database, no embedding calls, no daemon.
• Git history. You can see when a fact changed and why.
• Portability. The same files work in Claude Code, Codex and anything else that reads a project file.

Liao is honest about the limits: he still intervenes by hand to create, rewrite and trim documents, agents avoid splitting or merging files on their own, and documentation bloats without tuned instructions. The HN thread adds a sharper objection, that the markdown approach still has the discovery and staleness problems it criticizes, plus a security one: auto-injecting markdown from a cloned repo lets hostile content steer the agent.

Where documentation alone is not enough

Three things never make it into docs, because no human would write them down:

• Negative results. The library version that breaks the build, the flag that silently does nothing, the test that is flaky on CI only. These are the highest-value facts an agent can hold and the least likely to be documented.
• Per-session episodic detail. What the agent tried last Tuesday, in what order, and what the error was. This is episodic memory in AI agents, and it is high-volume by nature.
• Cross-project patterns. A user’s preferences and a team’s habits, which belong to no single repo’s docs.

A documentation-only setup also gives you nothing outside coding agents. Support bots, personal assistants and long-running agents have no repo to put markdown in, and their useful history is conversational, not architectural.

Where Hindsight fits

Most of the five objections in the post are aimed at the snippet-plus-vector-database design. Hindsight (MIT, full server open source) answers several of them directly, which makes it a useful reference point for what a memory system can do beyond similarity search:

• Not similarity-only. recall runs four strategies in parallel (semantic, BM25 keyword, graph over entity, temporal and causal links, and temporal range), merges them by reciprocal rank fusion, reranks with a cross-encoder, then trims to a token budget you set.
• Evidence instead of snippets. Its observations are consolidated beliefs backed by quotes and a proof count, refined as new evidence arrives rather than overwritten, which is the closest thing in a memory system to the “no appending” rule.
• Standing answers. Mental models are kept current in the background; reading one is a database read with no retrieval and no LLM call, so it behaves like a document that maintains itself.
• Reasoning, not just lookup. reflect reasons over stored memories to answer a question rather than returning the nearest matches.
• Auditability. A UI on port 9999 ships with the server, so stored memory is inspectable rather than opaque.

On vendor-reported numbers from its own benchmarks site, it scores LongMemEval S 94.6 and LoCoMo 92. The gap that matters for long project histories shows up on BEAM: 73.9 at 1M tokens and 64.1 at 10M, against 64.1 and 48.6 for Mem0 on Mem0’s own comparison page. Treat all of these as vendor-reported; research collaborators at Virginia Tech and The Washington Post reproduced results per its README, which is reproduction, not an independent audit.

The honest costs: Hindsight returns roughly 4x more context per retrieval than Mem0 by default on Mem0’s measurement (23.9K tokens on LongMemEval, 43.6K on BEAM 1M), so set max_tokens lower if your budget is tight. Writes call an LLM twice, for retain and for consolidation. Its README says it may be overkill for simple workflows, and a documentation-only setup for one small repo is exactly that case. It has native plugins for Claude Code, Codex, Cursor and Copilot plus an MCP server, so it sits alongside markdown rather than replacing it. See Hindsight agent memory and Mem0 vs Hindsight for detail.

How to choose

1. One repo, stable design, small team. Curated markdown only. Add AGENTS.md or CLAUDE.md, a short architecture note, and a catalog of what to open when.
2. Agent repeats the same mistakes across sessions. Add memory. Repeated failures are exactly what docs miss.
3. History is long. Past a few hundred thousand tokens of project history, file-reading stops scaling and retrieval wins. See context window limitations and solutions.
4. Multiple projects or non-coding agents. Memory, because there is no shared repo to hold the files.
5. You need review and audit above all. Docs for anything that must be approved; memory scoped to the episodic layer underneath.

The practical setup for most teams is both: markdown for intent, a memory system for experience, and a rule that anything the team must agree on gets promoted out of memory and into a reviewed file. AI coding agent memory covers the harness-specific pieces, and RAG vs agent memory covers the other comparison people confuse this with.

What to watch

Operator Memory has no published benchmark results, so the documentation-first claim rests on reported experience rather than measurement. Memory systems publish numbers but mostly on conversational benchmarks (LongMemEval, LoCoMo, BEAM), not on coding tasks. Neither side has the evidence that would settle the argument, and memory decay (keeping old facts from outranking current ones) is the open problem in both designs.