Dreaming: what Anthropic found about AI agent memory (and what it changes in your harness)

AI agent memory is the knowledge an agent builds up from experience and carries from one session to the next, outside the model weights. And its problem isn't just forgetting. It's remembering too much. And remembering wrong.

In an Anthropic experiment, Sonnet 3.7 playing Pokémon Red ended up with 413 memory files spread across 225 folders, almost a million characters of notes. Result: one badge. In one 17-step stretch it created six files, deleted nine, and didn't press a single game button.

The article The components of agent memory, published by Anthropic on November 6, 2026, is the most complete study I've seen on the subject. It splits memory into layers, measures what works with benchmarks, and introduces dreaming: the agent "sleeps," rereads what it did, and fixes its own memory.

In this post you'll learn the four layers, what the numbers say about how to instruct the agent, when a wiki beats search, and how to apply this today, in the API and in Claude Code.

TL;DR

• What it is: a 4-layer model of agent memory (transcript, notes, representations, injected context) plus an offline reflection step called dreaming.
• Stack/Models: Claude Managed Agents (Memory Stores + Dreams), Claude Code (auto memory). Tested from Sonnet 3.7 to Opus 5.5.
• Cost/Access: Memory Stores in beta. Dreams in research preview, billed at the standard token rate of the model you pick. Neither is ZDR/HIPAA eligible.
• Useful link: original article and Dreams docs.

The 4 layers of AI agent memory

First, what is not memory in this model. Anthropic leaves out three things: changes to model weights, learning within a single conversation (in-context), and compaction, the summary that replaces older turns.

Memory, here, is knowledge the agent gains from experience that survives across sessions as context it can read later.

The inspiration is the brain. The hippocampus records experiences fast and, during rest, replays and consolidates what matters into long-term memory. The agent does the equivalent: it writes logs while working and, offline, turns those logs into organized knowledge.

The article's diagram, bottom to top:

┌──────────────────────────────────────────────┐
│ 4. Injected context   → loaded into EVERY     │  ▲
│    session (e.g. CLAUDE.md, MEMORY.md)        │  │
├──────────────────────────────────────────────┤  │
│ 3. Representations    → wiki with pages       │  │  DREAMING
│    per subject and links between them         │  │  corrects, creates,
├──────────────────────────────────────────────┤  │  promotes and
│ 2. Memory notes       → salient observations  │  │  demotes
│    written by the agent during the session    │  │
├──────────────────────────────────────────────┤  │
│ 1. Transcripts        → searchable event      │──┘
│    log (the source of truth)                  │
└──────────────────────────────────────────────┘

Each layer up is cheaper to query and more expensive to keep correct. The transcript is raw truth, but nobody rereads 400k lines of logs. Injected context is read for free in every session, but if it's wrong, the error travels to all of them.

And here's the line that reframes everything: "Memory is, occasionally, a prediction." Every note the agent writes is a bet that the information will be relevant and reliable later. Bets can lose.

What the numbers say about instructing memory

Anthropic ran CL-Bench 1.0 on a database scenario: 30 questions, a fresh session per question, and a persistent memory directory as the only shared state. Mean reward, without memory vs with memory:

Look at Sonnet 4.6. Memory barely helped. The reason: it read its own memory before answering less than half the time. Sonnet 5 read it 9 out of 10 times, without being told.

When they added an explicit instruction to read memory and test hypotheses, Sonnet 4.6 went from 0.364 to 0.641. Nearly double.

Now the counterintuitive part. A fixed rule like "record only failures" reduced the memory gain on the strong models: −0.234 on Opus 5, −0.150 on Opus 4.7. On Sonnet 4.6, practically nothing (−0.020).

Anthropic's conclusion fits in one line: tell the agent what memory is for, not how to use it. Older models need a firm hand. Newer models choke on too many rules. Same pattern we already covered in minimal harnesses for new models.

Calibrating this is an architecture decision, and it changes with every model generation. That's the kind of tuning we test every week, live, in the Clã Beer and Code: harnesses running, memory breaking, people comparing results instead of opinions.

What's worth keeping: salience

Back to Pokémon. Sonnet 3.7 logged money and map position, things the screen already shows. In a game where state changes constantly, that's noise that goes stale in seconds.

Claude Fable 5, at the same ~10k-step mark, had 10 files and 43k characters. And four badges. It stored strategy, plans, and rules: things that only exist if the agent works them out. After seven failed Poké Balls on a Magikarp, it wrote a rule to vary timing after three failures in a row. The next catch worked. Opus 5.5 kept a small folder with its goal and next steps, and beat the game.

Rule of thumb: good memory stores what's expensive to rediscover, not what's easy to look at.

Dreaming: why the agent needs to "sleep"

A wrong note doesn't sit quietly. It becomes a trap.

In the Mt. Moon test, Claude wrote down that the Pokémon Center was on the east side of the mountain. It was wrong. After falling off a one-way ledge, it read its own note, concluded it had "overshot far west," and went back the wrong way. Three times. It never reached Cerulean City.

With memory corrected by dreaming, the same run reached Cerulean at action 1,935. The run with no memory at all didn't make it either. In other words: wrong memory was as bad as no memory.

Dreaming is the offline step that fixes this. The agent rereads transcripts (the source of truth) and:

• corrects notes the log contradicts;
• creates notes that should have been written;
• builds representations, like a wiki;
• promotes heavily used items to injected context, and demotes detail to lower layers, leaving a link.

The upside is moving memory organization out of the middle of the task. Note-taking in real time competes for attention with the main work. Sleeping solves that, at the cost of new memory not being available right away. Same idea as sleep-time compute from Letta and Berkeley, now as a product.

Wiki vs search: when a representation pays off

The third layer is the most expensive. Anthropic tested whether it's worth it.

On a Stainless corpus of about 350k files (~420 million tokens), Opus 5 agents built a wiki over 128 dreaming sessions. On 25 questions:

• Wiki only: from 13% to 48% of criteria met, growing with more dreaming. The wiki went from 103 pages and 766 links to 222 pages and 12,893 links.
• Search only: 53%.
• Wiki + search: 61%, using ~20k fewer tokens per question.

On Harvey LAB, across 24 merger questions that require combining several documents, judgment, or arithmetic, the wiki scored 87% vs 73% for search.

But it's no silver bullet. On a task where almost every criterion could be found with text search in a single document, the wiki brought no clear gain. And on a small corpus (10 documents, 115 KB), the wiki ended up 1.77 times larger than the corpus itself.

The most useful case for builders is the contracts one. Four agents writing at the same time into a shared table: only 41 of 57 facts survived (72%), because they overwrote each other. Switching to one page per contract, quoting the terms verbatim: 57 of 57.

The architecture lesson is an old one for any backend dev: shared state with concurrent writes means race conditions. One owner per entity fixes it.

Anthropic's recommendation: transcript search as the foundation, representations on top when the question requires synthesis.

Hands-on: memory and dreaming in practice

Prerequisites

• [ ] Anthropic API key with access to Claude Managed Agents
• [ ] For Dreams: research preview access (request via the official form)
• [ ] Up-to-date Anthropic Python SDK
• [ ] For step 3: Claude Code installed

Step 1: create a memory store and attach it to the session

A Memory Store is a collection of text documents mounted as a directory in the sandbox. The agent reads and writes it with its normal file tools, and every change creates an immutable version.

from anthropic import Anthropic

client = Anthropic()

store = client.beta.memory_stores.create(
    name="User Preferences",
    description="Per-user preferences and project context.",
)

client.beta.memory_stores.memories.create(
    store.id,
    path="/formatting_standards.md",
    content="All reports use GAAP formatting. Dates are ISO-8601...",
)

session = client.beta.sessions.create(
    agent=agent.id,
    environment_id=environment.id,
    resources=[
        {
            "type": "memory_store",
            "memory_store_id": store.id,
            "access": "read_write",
            "instructions": "User preferences and project context. Check before starting any task.",
        }
    ],
)

Note the instructions field: it says what the memory is for, not how to use it. Exactly what the benchmark recommends.

Two caveats from the docs. A store can only be attached at session creation, with at most 8 per session. And if the agent reads untrusted content (web, email, customer tickets), a read_write store becomes a door for persistent prompt injection: the next session trusts whatever was written. For reference material, use "access": "read_only".

In cURL calls, the headers differ: memory store endpoints use anthropic-beta: agent-memory-2026-07-22, and sessions use managed-agents-2026-04-01. Sending both on a memory store call returns 400.

Step 2: run a dream over your sessions

A dream is an async job. It takes a memory store and 1 to 100 past sessions, and returns a new store, reorganized. The original is never modified, so you can compare before and after.

import time

dream = client.beta.dreams.create(
    inputs=[
        {"type": "memory_store", "memory_store_id": store_id},
        {"type": "sessions", "session_ids": [session_a, session_b]},
    ],
    model="claude-opus-5-5",
    instructions="Focus on coding-style preferences; ignore one-off debugging notes.",
)

while dream.status in ("pending", "running"):
    time.sleep(10)
    dream = client.beta.dreams.retrieve(dream.id)
    print(f"status={dream.status} input_tokens={dream.usage.input_tokens}")

output_store_id = next(
    output.memory_store_id for output in dream.outputs if output.type == "memory_store"
)

session = client.beta.sessions.create(
    agent=agent_id,
    environment_id=environment_id,
    resources=[
        {"type": "memory_store", "memory_store_id": output_store_id},
    ],
)

A tip straight from the docs: instructions steers the synthesis as a whole ("focus on X, ignore Y"). Surgical orders like "change sentence X to Y" generally do nothing. For targeted edits, use the memories API directly on the output store.

Common errors: archiving the store or deleting an input session while the dream runs kills the job (input_memory_store_unavailable, input_session_unavailable). A failed or canceled dream leaves the output store with partial contents, so don't promote that store to production without checking it. And run time ranges from minutes to a few hours.

Step 3: apply the layers in Claude Code today

You don't need Managed Agents to use these ideas. Claude Code already has the layers:

• Injected context: CLAUDE.md (you write it) and the auto memory MEMORY.md (Claude writes it), in ~/.claude/projects/<project>/memory/.
• Notes: one file per memory in that folder, read on demand.
• Transcripts: the session history.

The detail that changes everything: only the first 200 lines or 25 KB of MEMORY.md are loaded at session start. It's an index, not a dumping ground. One line per memory, pointing to the file with the details. That's a small layer 4 and a large layer 2, exactly what the article recommends.

There's no automatic dreaming in Claude Code. But the idea works manually. This is my own prompt, not Anthropic's, which I run every so often in a dedicated session:

Revise a pasta de memória deste projeto como uma etapa de "dreaming".

1. Para cada memória, verifique no código e no git log se ainda é verdade.
   Corrija ou apague o que estiver desatualizado.
2. Junte memórias duplicadas ou que falam do mesmo assunto.
3. Mantenha o MEMORY.md como índice: uma linha por memória, bem abaixo de 200 linhas.
   Detalhe vai para o arquivo da memória, não para o índice.
4. Não invente memória nova sem evidência no código ou no histórico.

No fim, liste o que mudou e por quê.

(The prompt is in Portuguese; in English: review the project memory folder as a "dreaming" step, verify each memory against the code and git log, merge duplicates, keep MEMORY.md as an index well under 200 lines, don't invent memories without evidence, and list what changed and why.)

Item 1 is the one that matters. It's the equivalent of checking the note against the transcript: the truth lives in the code and the history, not in what the agent thought a month ago.

Limitations and gotchas

• Wrong memory contaminates everything. An incorrect note in injected context goes into every session. Mt. Moon showed it can be worse than having no memory.
• Dreaming costs tokens. Cost grows roughly linearly with the number and length of sessions. Anthropic itself admits that checking every memory all the time "might not be practical" and suggests focusing on what changes most or is accessed most.
• Wikis hallucinate too. A representation needs compute to stay correct. Without maintenance, it piles up errors that look like official documentation.
• Loading isn't obeying. Injected memory costs tokens and doesn't guarantee the model acts on it. Long instruction files reduce adherence.
• Partly anecdotal evidence. The Pokémon comparisons are one run per model. CL-Bench and Harvey are specific tasks. Don't generalize the percentages to your domain without measuring.
• Privacy. Memory Stores and Dreams are not ZDR or HIPAA eligible. Sensitive customer data doesn't go there without a deliberate decision.

FAQ

Is dreaming fine-tuning?

No. No model weights change. Dreaming is Claude itself reading transcripts and rewriting memory files. The output is text that goes into the context of future sessions, auditable and versioned. If it goes wrong, you go back to the previous store, which the dream never touches.

Does it work outside Managed Agents?

The Dreams API belongs to Managed Agents. But the pattern is portable: any harness that keeps transcripts and a notes folder can run a periodic job that rereads the logs and fixes the notes. For the file-based notes part, see the file system as agent memory.

How much does a dream cost?

The standard token rate of the model you choose, with no separate price. The resource's usage field reports exact input, output, and cache token totals. Start with a few sessions and a smaller model to measure before scaling.

Do I need a vector database for agent memory?

Not necessarily. The whole article works with files, transcript search, and a linked wiki. Vectors help with semantic search of facts across conversations, but they don't fix wrong memory or bloated memory. For when they do make sense, see pgvector as your agent's memory.

Conclusion

Anthropic's article swaps the question "how do I give my agent memory" for a better one: how do I keep that memory small and correct over time.

The answer has three parts. Layers, with a lean top and the transcript as truth. Instructions about purpose, not procedure. And an offline step that rereads, corrects, and reorganizes.

The next step for this tech is obvious: dreaming with adaptive cadence, running more where memory changes more. Until then, start with the basics: understand why your agent forgets everything and treat your MEMORY.md as an index, not a diary.