# AI Agent Memory AI Agent Memory is the mechanism by which [[AI Agents]] retain and accumulate knowledge across sessions. Most AI agent frameworks implement memory as opaque vector databases or key-value stores. A vault-native approach stores memory as plain Markdown files: you can open one, see what the agent knows, and fix it when it's wrong. In November 2026, [[Anthropic]] published a research post on the topic, "The components of agent memory", with experiments across six Claude models, a Pokémon game and two wiki-building tasks. A good part of this note comes from it and from the Hacker News discussion that followed. ## What counts as memory Anthropic's definition: agent memory is "knowledge that Claude gains from experience—including interactions with users and tasks it's been assigned—and that it retains between sessions, saved as context it can read later." Three things are NOT memory under that definition: - Changes to the model's weights - In-context learning inside a single conversation - Compaction (summarizing a long session so that it fits in the context window) The analogy they use is the [[Hippocampus]]. It encodes experiences quickly, and only part of that gets consolidated into long-term knowledge, mostly offline, during sleep. Agents get the same division of labour: write quickly while working, consolidate later. Two ideas from the post frame everything else. **Salience is the hard part.** You rarely know what matters before you know what comes next. That's why choosing what to write down is much harder than writing it. **Memory is a prediction.** In Anthropic's words, "memory is, occasionally, a prediction." A rule predicts that a pattern will recur. A verified fact predicts that you can rely on it without checking again. When the prediction is wrong, or when the world changes, the memory becomes a liability. This is why memory needs maintenance: predictions expire. ## The memory hierarchy Anthropic splits agent memory into four layers, from bottom to top: transcripts (a searchable event log of the work), memory notes (salient observations the agent writes down), memory representations (structures like wikis that link knowledge) and injected context (loaded into every session). Dreaming, an offline pass, moves knowledge up and between the layers. It fixes notes that are wrong, and it moves what matters toward the top (it can also add or reorganize pages). Details in [[Agent Memory Hierarchy]]. ## Two Levels **Shared memory** (cross-agent): Knowledge that all agents should have access to. Includes stable facts about the user, non-negotiable rules, cross-agent preferences, and lessons learned from past mistakes. **Agent-scoped memory**: Knowledge specific to one agent's domain. Each agent maintains a curated MEMORY.md (append-only, dated entries, outdated entries struck through) and daily operational logs. ## Vault-Native Advantages Storing memory as Markdown in the knowledge base provides several advantages over database-backed approaches: - **Human-readable**: Open any memory file and see exactly what the AI "knows" - **Editable**: Correct mistakes, remove outdated entries, add missing context directly - **Transparent**: Nothing hides in embeddings, so you can always trace why the AI made a decision - **Compounding**: Each session adds to the knowledge base. The system gets better over time - **Portable**: No vendor lock-in. Memory files work with any tool that reads Markdown ## Limitations Vault-native memory is not a perfect solution. Retrieval depends on the agent's ability to read and reason over text, not on semantic similarity search. Memory files can grow large and require periodic curation. There is no automatic deduplication or conflict resolution. These trade-offs are worth it for the transparency and control they provide, but it's important to acknowledge them. ## The open problem: what to forget By late 2026, storing memories is the easy part. The hard part is deciding what to keep. Harrison Chase (LangChain) lists memory as one of the unsolved problems for always-on agents: they either remember nothing useful or every tiny detail. Drew Breunig, after six months with a [[Hermes Agent]], saw memories and self-written skills pile up into contradictions. Precise memories age badly. See [[Strategic Forgetting]] for the approaches being tried. The strike-through convention above is one of them: old entries stay visible but marked outdated. ## What Anthropic's experiments found (November 2026) ### Stronger models use memory better On CL-Bench 1.0, a database task, every question ran in a fresh session. The only state carried between questions was a memory directory, and Claude got a reward after answering. Mean reward: | Model | Without memory | With memory | |---|---|---| | [[Claude Opus 5.5]] | 0.655 | 0.838 | | [[Claude Sonnet 5.5]] | 0.644 | 0.833 | | [[Claude Opus 5]] | 0.564 | 0.828 | | [[Claude Opus 4.7]] | 0.383 | 0.700 | | [[Claude Sonnet 5]] | 0.306 | 0.610 | | Claude Sonnet 4.6 | 0.330 | 0.364 | The memory folders show why. Sonnet 4.6 wrote untested theories into scattered files. Opus 4.7 consolidated everything into one reference document and marked what was verified and what wasn't. Sonnet 5 marked answers as confirmed after grading and wrote corrections. Opus 5 was the first to "close the loop": rules, provenance, prior answers and warnings about traps. Opus 5.5 and Sonnet 5.5 do the same, and the top three end up within 0.01 of each other. ### Less memory, better memory Anthropic compared memory folders about 10,000 steps into Pokémon Red: - Claude Sonnet 3.7 had 413 files in 225 folders (977,930 characters), with archives of every battle, item and NPC. It had 1 badge. Around step 10,000, it spent 17 steps creating 6 files and deleting 9, without a single game action - [[Claude Fable 5]] had 10 files (43,406 characters): a `global.md` dashboard plus `locations/` and `gameplay/` folders. It had 4 badges. It stored what the screen can't show: strategy, plans and tested rules (e.g. vary the timing after three failed Poké Ball throws) - Opus 5.5 kept a small folder with the current goal and the next steps, rewrote it as it played, and beat the game Sonnet 3.7's folder was 22 times larger than Fable 5's, for a quarter of the badges. ### Tell the model what memory is for A fixed rule ("record only failures") reduced the memory gain, and it hurt stronger models more: Opus 5 lost 0.234, Opus 4.7 0.150, Sonnet 4.6 0.020. Older models still need help. With refined instructions (read memory before answering, test theories explicitly), Sonnet 4.6 went from 0.364 to 0.641. Sonnet 5 read its memory before answering 9 times out of 10 without being asked; Sonnet 4.6 did it less than half the time. Anthropic's default guidance for frontier models: create notes when asked, or when something is clearly worth remembering, and leave the judgement to Claude. ### Dreaming fixes wrong notes At Mt. Moon, Claude wrote the PokéCenter landmark down on the wrong side and declared "Mt Moon DONE". It then fell off a one-way ledge three times, wrote "I'm going to stop rather than keep looping", got pushed on by the auto-reply, and ended up in Pewter City. A dreaming pass checked the note against the transcript, found the error and rewrote it. The corrected run reached Cerulean City at action 1,935. The run with the uncorrected note and the run without memory never got past the mountain. ### Wikis help on top of search Opus 5 agents explored about 350,000 internal Stainless files (~420M tokens) over 128 sessions. They wrote and linked wiki pages, merged duplicates and checked claims against the sources, with a shared log. On 25 eval questions (share of graded criteria met): | Setup | Result | |---|---| | Wiki only | 13% → 48% as the wiki grew | | Wiki + search | 54% → 61% | | Search only | 53%, flat | Wiki plus search also saved about 20,000 tokens per question. The wiki went from 103 pages and 766 links after 2 sessions to 222 pages and 12,893 links after 128 (Anthropic compares that to a new employee versus a seasoned one). On Harvey's LAB merger questions (24 questions that need several documents), the wiki scored 87% against 73% for search. When the criteria sat in a single document, the wiki added nothing. More in [[LLM Wiki]]. ### Bloat, parallel writes and gaps - One wiki weighed 203 KB, built from a 115 KB corpus (1.77 times the source), with 68 pages, 255 links and some orphan pages. Anthropic calls it Borges' map: the map that grows as large as the territory - Parallel agents writing to one shared `provisions.md` overwrote each other: 41 of 57 facts (72%) survived. A goal-focused dreaming loop (reflect, propose, rebuild) rewrote the wiki instructions (one page per contract, quote terms verbatim) and kept 57 of 57 - Sessions created links to pages that didn't exist. A second pass repointed nine of them (e.g. `escrow-agreement` to `buyer-form-escrow-agreement`) and added three pages: 38 entries and 225 links became 41 and 278 ## Design lessons What I take away from the post: 1. Let strong models decide what's worth remembering. Keep fixed rules to a minimum 2. Prompt older models to read their memory before acting and to test their theories 3. Keep the transcripts and make them searchable. Search over transcripts is a strong base on its own 4. Add a wiki on top of search, never instead of it, and only when questions need several sources 5. Keep the injected layer small. Push the details down and leave links behind 6. Run a dreaming pass to repair, structure and promote memory. It costs compute, so tune how often it runs 7. Don't let parallel agents write to the same file. Give each one its own page ## Failure modes Anthropic's list of what goes wrong: - Notes that are wrong from the start and get trusted later - Drift as the environment changes - Over-logging that steals attention - Parallel overwrites - Wiki bloat - Dangling links - Giving up after repeated failures - Not reading memory unprompted (older models) - The token cost of injected context ### Memory that makes agents timid Anthropic's prompting guide for [[Claude Fable 5.2]] adds one more: cautions that pile up. Memory files, notes, instruction files and messages between agents collect "be careful" lines over time, and a model that follows instructions closely ends up asking for approvals it doesn't need and holding back routine work (mostly in multi-agent setups). One stale "never retry" note among a dozen cut retries after a busy tool to about 4 in 10 tries, against nearly all without it. Naming the steps that need no approval works; a general "act more freely" changes nothing. Writing the exception into the rule itself works about 9 times out of 10, against about 1 in 10 without it. The guide's hygiene advice before moving to a new model: 1. Delete cautions whose reason no longer holds 2. Rewrite absolute rules with their scope and their reason 3. Restart stuck systems with trimmed memory, and keep a copy of the old one ## The criticism The Hacker News thread (187 points, 103 comments) was split. Some found the post validated what they were building. Many pushed back: - troupo called it "such a bullshit article": Claude rarely "remembers", these are Markdown files injected into a small context, and Claude Code says "I'll make a note of it" and then writes a note it has already written dozens of times. ashishact sees the same duplicates in Claude Code - anonymous908213 called the word "dreaming" for "writing notes into an .md file to be re-injected into context later" anthropomorphic marketing; xtiansimon and MASNeo objected to it too. 2001zhaozhao defended it as an analogy for post-hoc conflict resolution, and antonvs replied that dreaming is thought to be a side effect of memory consolidation, not the process itself - yfontana turns off automatic memory in every harness and deletes about 95% of what Claude Code creates anyway, because those memories only matter for the task at hand. sunaurus says turning memory off is one of the best ways to reduce "WTF per minute". stingraycharles periodically asks Claude to curate its memory and to ask him questions while doing it, because he finds that dreaming leads to bloat and outdated entries. hridyaagrawal keeps an AGENTS.md and a progress.md in the repo instead: visible in a diff, and they work in both Claude Code and Codex - prtmnth runs a memory-prune skill that decides where each automatic memory belongs: a code comment, a rule, the project's AGENTS.md, the global AGENTS.md/CLAUDE.md, or nowhere. Deletion is the most common verdict - yfontana's other advice: transcripts are under-used. Load your own transcripts into [[DuckDB]] (Claude Code builds the pipeline in about 10 minutes) and analyse them, starting with tool call failures. nedt says old session transcripts are the most useful memory he has, across projects and agents; he had to extend Claude Code's 30-day transcript retention - aszen argued that the post sidesteps the real problem: models can't learn continuously by updating their weights. nullc pointed out an advantage of files: a wrong conclusion in a file can be found and deleted, which isn't possible once it's buried in weights - benfortuna noted that most memory systems overwrite memories instead of keeping the source of each resolution (see [[Context Provenance]]) ## How this maps to my own setup I run this kind of system in my vault, with plain Markdown files instead of a memory store (see [[AI Assistant Architecture]]). Mapped onto Anthropic's hierarchy: | Layer | In my vault | |---|---| | Transcripts | Claude Code session transcripts, plus backups that a PreCompact hook copies into the vault before compaction | | Memory notes | Daily logs per agent, a curated `MEMORY.md` per agent, and the shared `MEMORY.md` and `Lessons Learned.md` files | | Memory representations | LLM wikis (the [[LLM Wiki]] pattern), each with an index and a log file | | Injected context | `AGENTS.md` in every session; `Hard Rules.md` and `Facts.md` at every agent activation | Several findings confirm choices I made: - Durable memory lives in the vault, not in Claude Code's auto memory folder. That's a hard rule since August 2026, when the auto memories were migrated into the shared files. The auto memory index now only points to the vault - My hard rules forbid writing to shared memory files from parallel sessions, because concurrent writes are last-writer-wins. The `provisions.md` result (72% of the facts surviving) is exactly what that rule prevents - Every agent reads its `MEMORY.md` when it activates. That's the "read memory before answering" behaviour that older models had to be prompted for, built into the activation steps - Memory entries are dated and append-only, and outdated ones get struck through instead of deleted. That's a basic form of provenance: you can see when a memory was written and what replaced it - A session-harvest skill mines my Claude Code sessions for rules and patterns during the weekly review. That's a manual dreaming pass over the transcripts Others challenge it: - Bloat. Append-only without consolidation grows forever. In November 2026, my ghostwriter agent's `MEMORY.md` is 422 lines and about 159 KB, and the shared `Lessons Learned.md` is about 68 KB. Claude Code caps its own index at 200 lines or 25 KB for a reason. Those files need what dreaming does: merge the duplicates, move the details into topic notes, and keep a short index on top - Mandatory write-back. Every agent activation must log what was asked, done and learned, even for a read-only lookup. For the daily logs, that's fine: they're closer to transcripts. The curated `MEMORY.md` files should follow the post's advice instead, and only get what is clearly worth remembering - Piled-up cautions. `Hard Rules.md` holds 38 numbered rules, and many of them are cautions. The Fable 5.2 advice applies directly: give each one its scope and its reason, and delete the ones whose reason is gone - Wikis versus search. According to the Stainless and Harvey results, an LLM wiki only pays off for questions that span several sources. For single-document lookups, search over the vault does the job I strongly believe that file-based memory is the right base, and this research supports it: every experiment in the post works with files the agent reads and writes, and the Mt. Moon fix only worked because the transcript was still there to check the note against. The critics are right about the word "dreaming", and right that most automatic memories are clutter. But clutter is a curation problem, and PKM practitioners have dealt with it for decades: capture freely at the bottom, curate hard at the top, and review regularly. That's [[Strategic Forgetting]] and [[Periodic reviews]] applied to machines. ## Open questions The ones Anthropic leaves open: - When should an agent write memory? - How do you keep memory current without checking everything again? Their suggestion: focus on volatile information, and tune the dreaming cadence to how often a memory is accessed - When do wikis beat search? - How much should be loaded upfront? - What does dreaming cost, and when is it worth it? Their own conclusion: "we still have a lot to learn about designing Claude's memory systems." ## The Compound Effect When memory is persistent and accumulative, the AI system exhibits a compound effect. Early sessions establish basic preferences. Later sessions build on those, adding nuance and context. Over months, the system develops a rich understanding of the user that would be impossible to provide in a single prompt. This compounding only works if feedback is captured consistently. Without recording corrections and confirmations, the system stays static. ## References - Anthropic, "The components of agent memory" (research post, 2026-11-06): https://www.anthropic.com/research/components-of-agent-memory - Hacker News discussion of the post (187 points, 103 comments): https://news.ycombinator.com/item?id=50402212 - Anthropic, "Prompting Claude Fable 5.2", section "Keep caution from piling up": https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#keep-caution-from-piling-up - Claude Code auto memory documentation: https://code.claude.com/docs/en/memory - Claude Managed Agents memory stores documentation: https://platform.claude.com/docs/en/managed-agents/memory - Claude Managed Agents dreams documentation: https://platform.claude.com/docs/en/managed-agents/dreams ## Related - [[AI Agents]] - [[Agent Memory Hierarchy]] - [[AI Agent Identity]] - [[AI Agent Panels]] - [[AI Assistant Architecture]] - [[AI Organizational Memory]] - [[Claude Code Memory]] - [[Claude Managed Agents Memory Stores]] - [[Claude Managed Agents Dreams]] - [[LLM Wiki]] - [[Cog Memory]] - [[OpenClaw Memory System]] - [[Mastra Memory]] - [[Honcho]] - [[Context Engineering]] - [[Context Provenance]] - [[Compound Effect]] - [[Kaizen]] - [[Loop Engineering]] - [[Strategic Forgetting]] - [[Periodic reviews]]