Agents don't need memory, they need documentation

TL;DR Highlight

Swap RAG memory plugins for Markdown docs the agent reads before and updates after each task.

Who Should Read

Developers whose coding agents forget project context each session and who are weighing memory plugins.

Core Mechanics

Every memory plugin is just RAG
- They extract snippets from session transcripts and store them in a RAG (retrieval) database.
- They inject the top 5 on each prompt and offer a search tool for more.
Recall has five problems
- Similarity ranking cannot tell what is correct or current.
- Snippets lose context, treat the past as truth, cannot search unknowns, and are hard to audit.
The fix is a structured doc 'brain'
- A workspace of instructions, specs, research and mappings that the agent reads before work and updates after.
- The author grew an internal/ folder into the Operator Memory plugin.
Document only what code cannot say
- Record requirements, decisions, constraints, mappings, reusable research and standards.
- Otherwise each session burns about 80k tokens of exploration reverse-engineering intent.
A catalog opens only needed docs

Community Reactions

Docs go stale too
- One commenter kept many decision docs that went stale and now confuse the LLM.
- Reconciliation sessions did not stop the confusion.
Same weakness applies to docs
- Some argued the 'can't search what you don't know' critique also hits index-based docs.
- Another said the GitHub repo's catalogs and read_if conditions are better designed than the article suggests.
Token cost and lifecycle concerns
- One person who built something similar said token cost balloons for small tasks as docs grow.
- Others noted time-limited facts, preference vs. fact, and server-side agents are not covered.
Alternative setups
- One uses a docs folder with an archive for stale plans and says it works well.
- Others suggested per-folder README.md files or lint rules whose error messages explain the fix.
No evidence offered

How to Apply

Create a docs index file
- Today, write docs/INDEX.md with a one-line description and 'when to open' for each doc.
- Tell AGENTS.md to read only this index at session start.
Add a post-task doc update rule
- In AGENTS.md, require rewriting changed facts in place, not appending.
- State that anything derivable from code must not be documented.
Include doc changes in PR review
- Review agent-written doc diffs alongside code.
- Ask directly to split or merge docs that have bloated.
Move stale docs to an archive
- Move finished plans and handoff docs into an archive folder.
- Tell the agent to ignore the archive.

Try It

copy & run

# Paste into a Claude Code or other coding agent session (simplified version of the article's method)

You maintain this repo's documentation 'brain'. Rules:
1. Before work, read docs/INDEX.md and open only docs whose description and read_if match.
2. Do not write what code already shows. Record only requirements, decisions and reasons, constraints, and reusable research.
3. After work, while you still have full context, update the relevant docs. When a fact changes, rewrite it instead of appending.
4. Split or consolidate docs that grow long or drift out of scope.
5. Keep in INDEX.md one line per doc: what it covers and 'read_if: when to open it'.

Task now: {{task description}}

First, create docs/INDEX.md if missing, and propose candidate decisions and constraints that the code alone cannot tell.

Next to try: after the task, review the docs with git diff docs/ as if it were code

Terminology

RAGRetrieving snippets similar to the query and inserting them into the prompt. Like a librarian putting a few similar books on your desk.

AGENTS.mdA guidance file agents read before entering a codebase. Like a one-page onboarding note for a new hire.

HarnessThe runtime like Claude Code or Codex that wraps a model with tools and a loop.

Operator MemoryThe author's open-source plugin. It makes consulting docs before work and updating them after structural steps of the agent loop.

ADRArchitecture Decision Record. Like meeting minutes capturing why a choice was made.