cd /news/ai-agents/how-claudes-agent-memory-works · home › topics › ai-agents › article
[ARTICLE · art-173699] src=dev.to ↗ pub= topic=ai-agents verified=true sentiment=↑ positive

How Claude’s Agent Memory Works

Anthropic published a technical brief on November 6 detailing a four-tier native memory architecture for Claude Agents, paired with an asynchronous background process called "dreaming" that refines raw conversation logs into notes, a knowledge wiki, and a small resident context loaded each session. The design treats every stored memory note as a predictive claim about future utility and keeps original logs immutable so revisions produce new copies, giving the system a built-in undo. In a controlled Pokémon test, an agent that wrote 413 memory files earned 1 in-game badge while one maintaining 9 curated files earned 4.

recommendation

Curate agent memory as predictive claims about future utility rather than accumulating logs; in Anthropic's Pokémon test, 9 curated files outperformed 413 raw ones.

more in playbook: Designing agent systems
by read9 min views7 publishedNov 21, 2026

On November 6, Anthropic published a technical brief outlining its native memory architecture for Claude Agents. The design splits long-term memory into four distinct tiers, paired with an asynchronous background process called dreaming. Rather than focusing purely on maximizing information retention, the system is optimized to decide what information to discard, validate, and prioritize. A well-known Pokémon experiment included in the document illustrates this core principle: a model that wrote 413 separate memory files only collected 1 in-game badge, while another model that maintained just 9 carefully curated files earned 4 badges. This article breaks down the layered memory stack, the mechanics of dreaming, supporting experimental metrics, unresolved limitations, and practical implications for agent developers.

Anthropic organizes agent memory along two axes: persistence and information density. The four layers form a sequential processing pipeline, where raw conversation data flows upward through extraction, synthesis, and promotion. Higher layers contain sparser, higher-value records that load rapidly at the start of a new session.

Layer Content Origin
Layer 1: Raw Conversation Logs Full, unmodified record of dialogue, observations, actions and tool returns Captured live during agent execution, no transformation
Layer 2: Memory Notes Extracted observations, recurring patterns, constraints, behavioural rules and verified facts Derived from raw logs during active interaction and offline dreaming
Layer 3: Knowledge Wiki Cross-session synthesized knowledge, structured as interconnected wiki-style entries Aggregated and merged from validated memory notes
Layer 4: Resident Context High-priority wiki entries and notes automatically injected at the start of each new conversation Selected from the knowledge wiki based on access frequency and relevance

The stack operates as a one-way refinement workflow. Raw logs act as immutable source material. Notes are intermediate artifacts. The wiki represents consolidated knowledge. Resident context is the small, fast subset loaded automatically for every new turn.

A critical architectural rule governs the whole system: original conversation logs are never altered. All edits, corrections and revisions produce new copies of notes and wiki entries. Outdated records can simply be discarded. This immutability gives the memory system a built-in undo capability. The design draws academic inspiration from sleep-time compute research from Letta and UC Berkeley, framing offline processing as a mechanism for grounding learned facts against historical interaction traces.

Memory notes are often misread as simple conversation summaries. Anthropic frames them differently: every stored note is a predictive claim about future utility. Writing a rule means predicting that this pattern will reappear in later tasks. Saving a verified fact means predicting that the agent will rely on it repeatedly without re-deriving the conclusion. This predictive nature introduces inherent risk. If the prediction is wrong, the stored note becomes stale and may mislead subsequent sessions.

This framing yields a clear principle: memory quality is not measured by how much information it stores, but by how accurately it anticipates future requirements. A note stating “the user prefers concise answers” is a high-value prediction. A note recording “there are three enemies visible on screen right now” is low-value, because the environment state will be available directly in the next turn.

Anthropic explicitly scopes this memory system. It does not cover attention weighting, single-turn in-context learning, or run-time context compression. It exclusively refers to persistent, cross-session records stored as readable text artifacts.

Anthropic tested memory selection behaviour using a controlled Pokémon environment. Each agent received a writable memory directory and decided independently what to persist. The contrast between the two test configurations demonstrates the core thesis of the memory design.

global.md index. It collected four badges. Fable’s strategy ignored transient, observable state such as gold count, position and current health. Those values could be read directly from the interface at any time. Instead, it stored latent knowledge: strategy notes, validated rules, and lessons learned from failed attempts. The global file tracked high-level objectives; location files stored route plans; gameplay files recorded refined tactics from repeated failures. The experiment’s conclusion is foundational: memory capacity is defined by filtering decisions, not storage volume. Retention is valuable only when it captures information that cannot be reliably observed at the moment of need.

Many engineering teams building memory systems begin with rigid filter rules such as “only record failures” or “only store user preferences”. Anthropic’s internal tests show this approach works inconsistently, and performance varies sharply by model capability tier.

When Opus 5 and Opus 4.7 were given a hard rule to record only failures, their overall memory utility declined. Stronger models can already distinguish useful signals from noise. Overly restrictive rules strip away valid insights the model would otherwise identify. The recommended pattern is to tell the model the purpose of memory, rather than dictating exactly what to write.

The opposite behaviour appears on weaker models. Sonnet 4.6 rarely consults its own memory or validates prior mistakes without explicit prompting. Adding a simple steering instruction to read memory and test hypotheses before responding nearly doubled its benchmark scores. Sonnet 5, by contrast, performs this validation autonomously in most cases.

This creates a practical product pattern: the same memory stack acts as an amplifier for capable models, while it functions primarily as a noise collector for weaker ones. Complex memory pipelines cannot compensate for limited native reasoning ability.

Dreaming is the official term for the asynchronous offline batch job that runs when the agent is not actively handling user requests. It is not a generative hallucination step. Every dreaming run executes three fixed operations:

Several engineering constraints shape dreaming execution. A single job can process between 1 and 100 conversation histories. Runtime ranges from minutes to hours, scaling with the volume of source logs. The input log corpus remains untouched; the output is a fresh set of notes and wiki artifacts. Developers can use high-level instructions to guide dreaming behaviour, but the process operates at the aggregate synthesis level and does not support fine-grained line-by-line editing of memory records.

The Pokémon example of a navigation loop illustrates dreaming’s grounding function. One agent repeatedly failed to navigate out of a cave. During active runs, it consistently misrecorded the exit direction. When dreaming triggered, the model cross-referenced its notes against immutable raw conversation logs. It detected the mismatch between written memory and actual action traces, revised the flawed note, and successfully navigated the route in subsequent attempts. This shows raw logs serve as the ground truth anchor for memory correction. Without the immutable log layer, dreaming can only reproduce the model’s prior misconceptions.

Anthropic published long-term wiki benchmark results using a corpus of roughly 35,000 documents and 4.2 billion tokens of technical documentation. The test set required cross-document synthesis.

The 48% figure marks a nearly fourfold improvement over the baseline, confirming that offline consolidation accumulates usable knowledge. At the same time, it highlights the hard upper bound: 52% of the evaluation questions still failed even after 128 consolidation passes.

This gap reveals a key behavioural trait of dreaming. It corrects mistakes that leave clear feedback traces. It is far less effective for domains with delayed or ambiguous outcomes. In coding, testing and gaming, failure signals appear immediately. In business judgement or market forecasting, bad decisions may only become visible much later, if at all. Those latent errors can persist in the wiki indefinitely.

Separate benchmark gains were observed on CL-Bench. Opus 5.5 improved from 0.655 to 0.838, and Sonnet 4.6 moved from 0.330 to 0.364 after the introduction of the dreaming consolidation workflow.

Anthropic’s documentation lists four major limitations, ordered by impact severity.

First, restricted availability. Dreaming is currently limited to Claude Managed Agents research preview. It requires a dedicated beta HTTP header. Teams working with standard API integrations or third-party agent frameworks cannot access this native offline pipeline today.

Second, saturation of returns. 48% represents the measured endpoint after 128 cycles. Further repeated dreaming brings diminishing marginal gains. Higher reliability requires cleaner source traces rather than additional consolidation passes.

Third, non-determinism. Memory updates are non-deterministic. Identical queries may receive different answers at different times, as the set of active notes and wiki entries evolves. This creates compliance challenges for workloads requiring stable, repeatable outputs.

Fourth, rising audit overhead. The immutability guarantee means every dreaming pass generates new storage artifacts. Frequent dreaming creates a growing version history of memory snapshots. Saved token cost is partially traded for increased human review labour.

The technical summary consolidates three foundational judgements for memory system design.

These rules shift the implementation focus away from unlimited storage and toward filtering, grounding, and capability matching.

For teams building production agents, this architecture delivers three actionable design principles. First, implement layered storage. Do not merge all records into a single flat memory table. Separate immutable logs, volatile notes, synthesized wiki knowledge, and hot resident context. Tiered storage reduces search overhead and isolates risk. Unified routing and observability become simpler when memory, tool calls and model inference are managed through a consistent control plane, and 4sapi delivers this gateway abstraction for mixed-model agent stacks.

Second, prioritize forgetting strategies before retention strategies. For every candidate memory record, evaluate whether the information can be read directly from the environment or the current prompt on the next turn. If it is observable on demand, persistent storage is usually unnecessary.

Third, prefer steering instructions over rigid filter scripts. Early-stage guardrails can guide behaviour, but hard filters such as “only record failures” degrade performance on capable models. Let the model judge what to keep, while clearly stating the purpose of memory.

Developers should also budget for cost growth. Offline dreaming pipelines scale cost with conversation history length and processing frequency. It is economical to validate consolidation workflows on small traffic segments before rolling out frequent background jobs broadly. The same applies to audit processes; every generation of memory artifacts adds to review workloads.

Anthropic’s four-layer memory stack and dreaming process represent a distinct departure from simple vector database retrieval designs. The system treats memory as a predictive asset, validated periodically against immutable interaction logs. The Pokémon experiment and long-term wiki benchmarks prove that selective forgetting is as important as remembering for agent performance. Even so, the workflow carries practical constraints: limited preview access, diminishing returns, non-determinism and audit burden must all be weighed before adoption. The pattern is most suitable for capable foundation models that can interpret steering guidance and self-filter useful knowledge.

── more in #ai-agents 4 stories · sorted by recency
── more on @anthropic 3 stories trending now
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/how-claudes-agent-me…] indexed:0 read:9min 2026-11-21 · —