Agent Memory vs Documentation: What the HN Debate Gets Wrong

A Hacker News post titled "Agents don't need memory, they need documentation" collected 368 points and 272 comments in two days. The article behind it, by Kevin Liao, argues that every memory plugin is the same architecture: parse session transcripts into snippets, push them into a vector database, and inject the top matches into every prompt. Liao calls the result a "lottery over RAG snippets." His conclusion is that agents need documentation instead.

The thread is half right. Documentation is the substrate most agents are missing. But the conclusion, that memory plugins are the wrong shape entirely, does not follow. Documentation and memory solve different problems, and the teams that ship agents daily end up needing both.

What the article gets right

The strongest part of Liao's argument is the failure mode. "Memories are surfaced by similarity," he writes. "You don't know which is correct, current, or what's missing." That is a real criticism. A similarity search ranks how close two snippets sit in embedding space. It says nothing about whether a snippet survived the latest refactor.

His second point lands harder. "The past is treated as truth." Memory systems that replay old context as current fact will feed an agent yesterday's architecture on today's task. He is also right that "agents can't search for what they don't know." A retrieval tool only fires when the agent realizes it should fire. That is a genuine gap, and any memory system that ignores it will leak.

We build a memory engine. We still think every word of that section is correct. The honest reading of this debate is not "docs versus memory." It is which facts belong in which layer.

Where documentation fails

Documentation has a failure mode of its own: it goes stale the day it is written, and nothing forces the update. The auth flow changes, the doc keeps describing the old one, and now the codebase lies to every reader, human or agent. Docs are also written after the fact, by people who already know the outcome. The paths a team tried and abandoned never make it into the README. One commenter pointed at Peter Naur's essay Programming as Theory Building, which argued in 1985 that documentation cannot carry the full theory behind a program. Another builds ADRs from session history because the "why" behind decisions never survives in prose alone.

There is a third gap that rarely gets named. A project accumulates operational state that never becomes documentation, because writing a document per fact is too expensive. Deploy quirks. Environment details. Preferences that emerged mid-project. Coordination between agents on the same codebase. In our own fleet, that state lives in tens of thousands of recalled memories, and none of it would survive as a hand-written page.

The honest case for memory

If memories are surfaced by similarity and treated as truth, the fix is not deleting memory. It is fixing those two properties. Search by meaning instead of by keyword alone, so the agent finds "how auth sessions expire" when it asks about a 401 loop. Keep it cheap enough to run on every relevant prompt. A local index answers in about 45 ms warm, sends zero tokens per query, and runs fully offline on CPU. Recall at that price can fire on every relevant turn instead of waiting for the agent to guess that it needs it.

Cost was the other half of the complaint. Plugins that burn tokens on every prompt deserve the criticism. A local engine that adds zero tokens per query is a different cost class. The reply "grep is free" only holds if grep finds the fact, and grep cannot match a paraphrase.

Where documentation still wins

Documentation remains the right layer for curated truth. Anything a new teammate must read on day one belongs in docs: architecture, setup, interfaces, invariants. Docs get reviewed before they merge. Memory should never be the system of record for that material. If a fact is stable and onboarding-critical, write it down. A memory layer is a supplement to a maintained docs directory, never a replacement for one.

The division of labor

The workable split, from running agents daily across many projects:

• Into docs: architecture, setup steps, interfaces, anything a new teammate must read on day one.
• Into memory: current operational state, preferences, environment quirks, and the history of approaches that were tried and rejected, the stuff that is true this week but might not be true next month.
• Into neither: anything that fails both tests. Delete it or leave it in the transcript.

One commenter replaced memories with versioned principles that agents must quote in commits. That works for rules. It does not work for state. The docs debate and the memory debate are arguing past each other because they are optimizing different halves of the same problem.

The next time a thread declares memory dead, check what the proposal removes. If it removes similarity-ranked snippets injected as truth, it is fixing memory, not burying it. Documentation for the truth you curated. Memory for the history you lived. Most agent projects are short on both.

Try Uteke

Uteke is an open source local-first semantic memory engine: one SQLite file, semantic recall in about 45 ms warm, zero LLM tokens per query, fully offline. LongMemEval-S recall@5 is 98.2 percent.

uteke init --agent your-agent

Install docs: codecora.dev/uteke

Further reading: the hybrid memory architecture, memory as a local file, why a local LLM feels amnesic.