Stop Installing Memory Plugins: A Polemic Says They're All Wrong — Documentation Is the Answer

On October 3, 2026, engineer Kevin Liao published a polemic on his personal blog liao.gg with the thesis as its title: "Agents Don't Need Memory. They Need Documentation." The essay hit the Hacker News front page the same day, collecting 300+ points and a long argument thread underneath.

Its target is a red-hot category: agent memory plugins. Over the past year, every coding-agent ecosystem has sprouted "memory" products with near-identical pitches — "let your agent remember everything." Liao's diagnosis is merciless: the category is solving the wrong problem.

Anatomy of a memory plugin: all the same architecture

Liao tore down the memory plugins on the market and found nearly all of them share one architecture under different packaging:

• Scrape your old session transcripts;
• Chop them into ~1,000 disconnected "memory" snippets;
• Embed everything and stuff it into a vector database;
• On every prompt, retrieve the 5 most similar snippets and inject them into context;
• Agent still confused? Give it a search tool to rummage through its own memory.

That's the whole thing. Some products add multi-tier memory classification, overnight "dreamer" consolidation daemons, rerankers — Liao says these are patches on a structurally flawed architecture, burning ever more tokens without fundamentally improving reliability.

The core charge: similarity retrieval is a lottery machine

Why is the architecture wrong? The retrieval mechanism. Vector search returns whatever looks like the query — a note that went stale last week can look just as close as today's correct fact in embedding space. Your codebase changes daily, yet the agent can confidently "recall" a fact that stopped being true last week.

Liao's phrasing is cutting: what you get isn't memory, it's "a lottery over RAG snippets," hoping the right ones float up with every prompt. Worse, even when the lottery hits, the agent still doesn't understand your project — it's just stitched-together chat logs.

What you actually want was never an agent that "remembers what we talked about." It's an agent that understands your project: where a feature lives, why it was built that way, what you agreed on, what you care about.

The prescription: a documentation workspace, not a memory store

Liao's alternative is disarmingly simple: give the agent a readable, writable Markdown documentation workspace — instructions, project specs, decision logs, indexes, research notes. The work loop flips from "prompt → build → forget" to "prompt → consult → build → update."

Before starting a task, the agent reads the relevant docs; when it finishes, it updates what's outdated and writes down new conclusions. No vector database, no embeddings, no 24/7 background daemons. Every document in the workspace is something you can read directly, edit directly, commit directly, and share with your team.

He has used this pattern himself for over a year and shipped it as an open-source plugin, Operator Memory: one npm command to install, supporting Claude Code, Codex, OpenCode, and more. Knowledge splits into three layers: .operator/ for private project knowledge, .operator-shared/ for shared knowledge committed alongside your code, and ~/.operator/user/ for personal rules that follow you across projects.

The other side is strong too: two objections you can't dodge

The top HN objections deserve serious treatment. First: agents write sloppy docs. Let an agent maintain documentation and in three months you'll own a pile of Markdown nobody dares delete and nobody dares trust. Liao's implicit premise is "humans will review" — but many people install memory plugins precisely because they're lazy. Expecting the same people to review docs may be wishful thinking.

Second: "evals or it didn't happen." This is an opinion polemic, not a controlled experiment. It doesn't quantify how many fewer mistakes the documentation approach makes versus memory plugins. In engineering decisions, a beautifully written essay is not evidence.

Both objections stand. But they don't kill the argument; they add operating instructions: the documentation approach isn't "install and it works" — it's "it works if someone maintains it."

Why vibe coders should read this seriously

Because many of you already use the prototype: CLAUDE.md, AGENTS.md, MEMORY.md in the project root. Liao's essay is the theoretical backing for that habit — upgrade it from "an instruction file" to "a documentation workspace."

Documentation has three structural advantages over memory plugins. First, auditability. Why did the agent do that? Check the docs' git history — obvious at a glance. Try that with 1,000 snippets in a vector store. Second, it survives model swaps. Docs are model-agnostic: switch from Claude to GPT tomorrow and the knowledge stays; a memory plugin's embeddings are deeply coupled to its model and vector store. Third, teams can share it. Docs go into git; memory stores don't.

My verdict: memory plugins won't disappear, but they'll retreat to what they're actually good at — cross-session personal preferences, fuzzy "vibes." Project knowledge, the stuff that's either right or wrong, belongs in documents, managed with git.

The minimal practice you can do tonight

No plugin needed. Eighty percent of the value comes from three things:

• Create a docs/ folder with three documents: ARCHITECTURE.md (architecture and key decisions), DECISIONS.md (decision log: date + conclusion + reason), CONVENTIONS.md (code conventions);
• Add two lines to CLAUDE.md / AGENTS.md: "before starting, read the relevant docs under docs/; after finishing, update outdated docs";
• Spend 10 minutes each week reviewing docs/ yourself, deleting the parts the agent wrote sloppily — your 10 minutes as "editor-in-chief" are worth more than any plugin.

Fun fact from the essay's comment section: Liao admits the method's biggest enemy isn't technology but that "writing docs is boring" — so his plugin makes "update the docs" a default step of the agent workflow rather than relying on human discipline. That's exactly the detail vibe coders should copy: bake good habits into the process instead of testing human nature.

The memory camp fires back: docs go stale too — why would you be different

To be fair, the memory-plugin camp has its replies, and they're not baseless. First, docs go stale too — an agent forgetting to update docs and a stale snippet rotting in a memory store are two symptoms of the same "humans are lazy" disease. Moving knowledge from a vector store to Markdown doesn't automatically solve "who maintains it"; it just moves the maintenance from an invisible background process to a visible file.

Second, what memory plugins are actually good at isn't project knowledge but episodic knowledge: you prefer pnpm over bun, you hate a certain code style, you once said "run the tests first next time." These fragments aren't worth formal documents, but they're perfect for fuzzy recall from a vector store. Liao attacks "using memory plugins for project knowledge," but what the vendors actually sell is "remembering you."

So the more honest conclusion may be a division of labor: docs for facts, memory for preferences. Architecture, decisions, conventions — into docs, into git. Personal habits, fuzzy preferences — to the memory plugin. Using a memory plugin to memorize architecture docs is the wrong tool; demanding docs remember your offhand preferences is the wrong tool too.

Move the three-layer structure into your vibe project

Operator Memory's three-layer directory design can be copied without installing anything:

• Project layer (.operator/ or docs/): this project's architecture, decisions, conventions. Travels with the project across machines and agents. The most important layer — build it tonight.
• Shared layer (.operator-shared/): the part that goes into git — for collaborators (or future you). Most vibe projects are solo, so this can merge with the project layer; but if you plan to open-source or hand off, a separate layer stays cleaner.
• Personal layer (~/.operator/user/): cross-project personal rules — "I use pnpm in all projects," "commit messages in Chinese," "no class components for me." Lives in your home directory, follows you around.

Once split into three layers, the question that plagues everyone disappears: "where do these rules actually go?" Project stuff goes in the project, personal habits in the personal layer, public stuff in the shared layer. No more mush.

One honest closing note: whichever camp you pick, the worst choice is picking neither — no memory plugin, no docs, just re-explaining requirements from scratch every time. That's the status quo of most vibe projects, and the root cause of agents repeating the same mistakes. Liao's polemic at least forces you to choose: either give your agent documentation it can consult, or admit you enjoy starting over every time.

An October convergence: the explicit is beating the implicit

Read Liao's polemic against the backdrop of the first week of October 2026 and a convergence appears: the same week, the HN front page was simultaneously debating "default hard budget caps for metered services" (money spent needs an explicit wall), "agents don't need memory, they need documentation" (knowledge needs explicit documents), and the "cloud agent harness" trend (execution needs explicit scaffolding).

Three stories, one sentence: in the agent era, the implicit, the black-box, the "trust me" is failing; the explicit, the auditable, the written-down is appreciating. Bills must be explicit, knowledge must be explicit, execution boundaries must be explicit. Liao's documentation workspace is just this larger trend projected onto the specific problem of "memory."

For vibe coders, the trend has a minimal action version: for everything your agent needs to know, ask — is it written down? Requirements written down, architecture written down, decisions written down, budget caps set. Only then is your agent a predictable agent. Otherwise what you own isn't an assistant but a brilliant, hardworking intern who works entirely on guesswork.

This debate won't settle soon — memory vendors won't concede, and the docs camp has no decisive evals. But the direction is clear: agent knowledge management is moving from "black-box recall" to "white-box documentation." Whoever builds the documentation workspace a year early will be a step ahead at every model generation change, because knowledge never lived in the model — it lives where you wrote it down.