Memory plugins vs documentation-first: unpacking the agent architecture fight behind claude-mem's 96k stars
大模型之路 · wechat · 2026-10-14
Two signals collided this week: claude-mem, a persistent-memory plugin for coding agents, hit 96k GitHub stars, while an HN essay "Agents Don't Need Memory, They Need Documentation" (368 points) argued vector-memory is fundamentally flawed.
Four failure modes of RAG-style memory (Kevin Liao):
- Similarity answers "what's nearby," not "what's correct now" — stale architecture snippets get recalled after a refactor;
- Past context gets treated as present truth;
- Agents don't know what they don't know — retrieval only triggers when they think to query;
- The whole store is unauditable, so repeated mistakes can't be traced.
Documentation-first: maintain a structured Markdown brain (Instructions/Specs/Research/Indexes), read before tasks, update explicitly after, commit to Git. Shipped as the open-source OperatorMemory, no vector DB or embeddings. AGENTS.md is now used by 60k+ open-source projects and recognized by Codex CLI, Claude Code, Cursor and more.
The verdict is layering, not either/or: stable architecture/interfaces/invariants go in docs under review; only truly dynamic state (user preferences, this week's environment quirks) belongs in local, zero-token, auditable memory. Data backs trimming: full conversation history inflates p95 latency 91% and token cost 90%+, while a curated context file cuts median runtime 29% and output tokens 17%.
Practical advice: write a one-page ops manual per role and validate on ten real tasks; only add memory for "breaks if not recorded" facts. Pitfalls: docs rot and need owners; and LLM-generated context files actually hurt (3% worse, 20%+ costlier) — human-written, concise docs are what work.
More from coding & agent
- Claude Code Pushes Urgent Security Update Across All Installations — umeshonai · 2026-10-23
- Claude cut a 2.6-hour video export to 20 minutes — but only after being told to rebuild the server — byhewar · 2026-10-23
- 3 flight-booking rules my AI agent checks that I'd never do by hand — Efistoffeles · 2026-10-23
- OpenJet claims Qwen3.8-27B coding runs 1.9x faster than llama.cpp on one RTX 3090 — JeremyCMorgan · 2026-10-23
- Building an autonomous SEO agent in Hermes with three skills: programmatic pages, Keywords Everywhere, DataForSEO — EXM7777 · 2026-10-23
- Building a sports betting AI agent with onchain execution and human approval by default: architecture and lessons — Dry-Comfortable-2678 · 2026-10-23