Anthropic Unveils Claude's Agent Memory: Four Layers, Dreaming, and Why Less Is More
Anthropic discloses Claude's four-layer memory architecture—transcripts, notes, wiki, and injected context—plus an offline Dreaming process that corrects errors, showing through Pokemon and code experiments that effective agent memory requires selective retention of implicit rules over volatile facts, not maximal storage.
Developers building long-running agents often encounter a recurring problem: an agent solves an issue in one session, but in a new session it repeats the same investigation from scratch. For example, a code agent might diagnose a timeout as a gateway retry issue in the morning, then in a fresh session waste time adjusting database connection pools—re-testing already-eliminated hypotheses.
The intuitive fix is to give the agent memory: stuff historical conversations back into context, or dump logs and execution records into a vector store for retrieval. But as records accumulate, transient state, stale conclusions, and genuinely valuable experience blend together, making the critical hint harder to find next time.
Anthropic recently published The components of agent memory , detailing how Claude handles long-term memory. This architecture is already used in Claude Code and comprises four memory layers plus an offline consolidation process called Dreaming .
What Counts as Agent Memory
The article first distinguishes three things often conflated with "memory":
Training knowledge – facts baked into model weights (e.g., Python syntax). These don't update when the agent fixes a bug today.
In-context learning – information from the current conversation (e.g., project directory location). It disappears when the session ends.
Compaction – summarizing the current task when context fills up, so work can continue. This serves the ongoing task, not cross-session reuse.
Anthropic defines long-term memory more narrowly: knowledge and rules distilled from real tasks, saved across sessions, and actively readable later. Raw logs (thousands of lines of test errors) are not memory; the distilled rule "this project's tests require a specific env var first" is.
Why Recording Everything Backfires: The Pokémon Experiment
Anthropic let Claude play Pokémon Red to measure memory strategies. Early model Sonnet 3.7 recorded every battle, item, and NPC line in separate files. By ~10,000 steps it had created 413 files across 225 folders (977,930 characters) and earned only 1 badge.
A more mature agent, Fable 5, kept just 10 files in 2 folders plus a global.md (43,406 characters) and earned 4 badges. Around step 10,000, Sonnet 3.7 started a fourth root memory directory; over the next 17 steps it created 6 files and deleted 9, yet game progress stalled—mirroring real-world agents that spend most tool calls organizing notes instead of acting.
Memory has costs: write, read, and maintenance operations consume tokens and latency. Fast-changing facts (coordinates, item counts) quickly stale, forcing the agent to verify which record is current. The key metric is not file count but whether retained information reduces exploration cost on the next task .
What to Keep: Volatile Facts vs. Implicit Rules
Anthropic proposes a practical split:
Volatile facts – current state (NPC position, remaining potions, live DOM). These are re-queryable and change rapidly; yesterday's coordinate is no more reliable than looking at the map now.
Implicit rules – hard-won patterns: "exiting this cave, the right staircase is a one-way drop," "this API requires a lock before concurrent calls," "this test failure often means a missing env var." These emerge only after repeated trial and verification.
In a code agent: "service runs on port 8080" is verifiable on the spot; "every deploy must run DB migration or health checks fail" is a rule worth passing to the next session. Rules can expire, so recording is only step one—verification mechanisms are essential.
Memory Helps, But Rigid Rules Can Hurt: CL-Bench 1.0 Results
On CL-Bench 1.0 (database QA with fresh sessions each question), cross-session memory consistently improved scores:
Opus 5.5: No Memory 0.655 → With Memory 0.838
Sonnet 5.5: No Memory 0.644 → With Memory 0.833
Opus 5: No Memory 0.564 → With Memory 0.828
Opus 4.7: No Memory 0.383 → With Memory 0.700
Sonnet 5: No Memory 0.306 → With Memory 0.610
Sonnet 4.6: No Memory 0.330 → With Memory 0.364
However, constraining the model to "record only failures" reduced gains: Opus 5 lost 0.234, Opus 4.7 lost 0.150, Sonnet 4.6 lost 0.020. Successful patterns (a stable API call sequence, a correct SQL form) are equally valuable; discarding them wastes signal.
For weaker models, explicit guidance helps. Sonnet 4.6 scored 0.330 without memory, 0.364 with memory, and 0.641 when prompted to "read memory first, then verify hypotheses." Sonnet 5 proactively read memory in 9 of 10 runs. Practical takeaway: strong models need only know memory's purpose and can judge what to keep; weaker models benefit from prescribed read-verify steps.
Four-Layer Architecture: From Raw Stream to Startup Index
Anthropic organizes memory into four layers, each refining the one below:
Layer 1: Transcripts – Full conversations, tool calls, results, environment feedback. Role: Single lossless source of truth; searchable.
Layer 2: Memory notes – Notable observations written during a session. Role: Capture local experience from a single task.
Layer 3: Memory representations – Structured, cross-linked knowledge (e.g., Wiki). Role: Synthesize fragmented notes into a knowledge map.
Layer 4: Injected context – Small payload auto-loaded at session start. Role: Acts as a table of contents, not a data dump.
Analogy for a code agent: Layer 1 preserves a complete debugging session (files viewed, commands run, exact error logs). Layer 2 holds the agent's contemporaneous hunches ("looks like a gateway config issue"). Layer 3 merges verified findings across tasks (module dependencies, common error patterns, required operation order) with cross-links. Layer 4 is a concise index telling a new session where each knowledge piece lives—so the agent fetches only what's relevant.
This design keeps raw evidence intact for later audit while preventing context bloat at startup.
Correcting Errors After the Fact: Dreaming
A critical risk: notes written mid-task may be unverified guesses. Later sessions treat them as confirmed facts. In the Pokémon Mt. Moon task, Claude noted "Pokémon Center is east of the cave." Acting on this, it exited the cave, jumped right off a one-way ledge, and fell back to start. The navigation tool couldn't detect elevation change, so Claude even reinforced the error in its notes. Three subsequent fresh sessions blindly trusted the record and repeated the same fall, until the agent wrote "I'd rather stop than loop again" and retreated to Cerulean City.
This mirrors a code agent inheriting a bad heuristic: "all timeouts mean increase DB pool," causing the real gateway bug to stay hidden.
Dreaming is an offline phase that revisits Layer 1 transcripts and cross-checks higher-layer notes against actual tool feedback. In the Mt. Moon case, the transcript showed the character walking east out the door, falling, and resetting—contradicting the note. Dreaming rewrote the note: "After Mt. Moon, do not jump right off the ledge; return inside and go north." The corrected run reached Cerulean City at cumulative action 1,935; the uncorrected and no-memory baselines never cleared Mt. Moon.
Lesson for agent engineers: we often check if the agent answered correctly this time, but rarely audit the conclusions it prepares for next time. Long-term memory must be traceable to raw evidence and allow correction. Dreaming runs offline, so it costs extra compute and its fixes aren't instant for the current session.
From File Pile to Wiki: Gains and Limits
Dreaming also consolidates scattered notes into a cross-linked Wiki. On Anthropic's internal Stainless codebase (~350k files, 420M tokens, 25 eval questions), Opus 5 iteratively wrote, merged, pruned, and linked Wiki pages over 128 sessions. Wiki-only accuracy rose from 13% to 48%; Wiki + search from 54% to 61%, while search alone plateaued at 53%. Wiki + search also saved ~20,000 tokens per question. The Wiki grew from 103 pages / 766 links to 222 pages / 12,893 links.
The Wiki acts as a knowledge map: search finds specific artifacts; the Wiki pre-structures relationships across modules, concepts, and docs, helping the agent decide where to look first for cross-file problems.
But a heavy Wiki isn't always justified. On Harvey LAB legal tasks, Wiki scored 87% vs. search's 73% when answers required synthesizing multiple documents; when answers lived in a single document, Wiki's edge vanished. In one run the Wiki ballooned to 203 KB—1.77× the 115 KB raw corpus—making retrieval and maintenance more expensive. Decision guide: if the task demands frequent multi-document synthesis, invest in a Wiki; if a good search endpoint suffices, stop there.
Production Pattern: Lightweight Index on Top, Searchable Store Below
Claude Code's auto memory illustrates the deployed pattern. On session start it loads only the first 200 lines or 25 KB of MEMORY.md —a concise index pointing to project conventions, testing gotchas, and per-module troubleshooting notes. The agent reads the relevant section (e.g., payments module) on demand; next session it pulls the build-script section. This avoids stuffing unrelated history into context and limits blast radius if the index contains a stale rule.
Multi-agent collaboration introduces another hazard: concurrent writes to a shared memory. In Harvey LAB, multiple agents maintaining a single clause table overwrote each other—57 key facts dropped to 41 (72% retention). Switching to one agent per contract, verbatim clause capture, then cross-document linking retained all 57 facts and achieved 100% briefing eval satisfaction. The same principle applies to code agents: let each agent own its source-specific notes, then merge and link afterward—easier to trace and debug.
A second Dreaming pass also fixed 9 broken links, added 3 pages, and grew the Wiki from 38 entries / 225 links to 41 entries / 278 links. Such housekeeping—repairing dead links, deduplicating, preserving provenance, preventing write conflicts—is tedious but essential; otherwise the agent can't even locate the right page when it needs the knowledge.
Three Trade-offs to Resolve Before Building
If you're adopting this architecture, settle three questions upfront—you don't need all four layers at once.
What gets recorded online vs. deferred to offline Dreaming? A failed deploy's exact command and error can be noted immediately with a source link. Post-task, Dreaming checks consistency with prior records and promotes to a durable rule. Online recording is timely but consumes current-session tools and context; Dreaming batches merging, validation, and correction but needs extra compute and can't help the running task. Split based on task length and whether a bad heuristic would immediately derail the next step.
Which memories expire easily? An API that once required a separate auth call may later embed auth in the SDK. Stale notes cause repeated redundant calls. Tag memories with source and applicability conditions; prioritize re-verification for frequently used, fast-changing, or weakly evidenced entries. Full re-validation every time is too costly—start with the highest-risk subset.
Do you really need a full Wiki? For a handful of key documents, a short Markdown index plus search may suffice. Invest in incremental Wiki building only when you hit hundreds of thousands of files, many modules, and repeated cross-session knowledge synthesis. Anthropic's compromise: top-level lightweight index, bottom-level searchable detail. The real measure is exploration savings minus write/query/maintenance overhead.
Three Starter Practices for a First Version
Keep auditable raw transcripts. Notes, summaries, and Wikis can hallucinate. Full execution logs and tool outputs let you re-ground when conclusions conflict.
Inject a table of contents at startup; fetch details on demand. Put only what the new session must know immediately in the injected context. Module specifics, historical incidents, and complex rules stay in lower layers, retrieved when relevant—avoiding the "whole history in context" trap.
Let the model judge experience value, but give it verification and revision loops. Strong models need fewer rigid templates; weaker ones get explicit read-verify steps. Either way, memory must be revisable and retractable.
For a v1 code agent: retain execution streams, write brief notes for critical tasks, maintain a concise index. When real usage reveals repeated re-work, error propagation, or rising retrieval cost, gradually add scheduled consolidation and a structured Wiki. The goal is simple: next time a similar problem appears, the agent takes fewer wrong turns; if past experience was wrong, it can find the evidence and correct it.
Signed-in readers can open the original source through BestHub's protected redirect.
This article has been distilled and summarized from source material, then republished for learning and reference. If you believe it infringes your rights, please contactand we will review it promptly.
How this landed with the community
Was this worth your time?
0 Comments
Thoughtful readers leave field notes, pushback, and hard-won operational detail here.
