Agent Memory Can’t Rely on Storage Alone: How Claude Dreaming Uses 4 Layers of Memory to Correct Errors, Organize, and Build a Knowledge Base Between Sessions

Author’s note: This article breaks down the Claude Dreaming mechanism disclosed on Anthropic’s engineering blog. It covers the 4-layer memory structure, the CL-Bench and Wiki experiment data, an error-correction case study, and the engineering risks. It also explains how developers can borrow the “organize memory between sessions” idea to build their own agent memory system.

On November 6, 2026, Anthropic published The components of agent memory on its engineering blog. It’s the first systematic explanation of how Claude Dreaming corrects errors, organizes memory, and builds a knowledge base between sessions. The official X account shared the post at the same time, and the Claude Managed Agents docs now include a research-preview API for Dreams.

This isn’t just another “bolt a vector store onto your agent” idea. Anthropic ran several experiments to show that a long-running agent needs more than saved history. It also has to keep verifying, correcting, consolidating, and organizing its memory before old information can actually help with the next task.

Core value: By the end of this article, you’ll know the 4-layer memory structure behind Claude Dreaming and the key experiment data. You’ll also know when it helps, when it hurts, and how to borrow from it in your own agent.

Claude Dreaming at a Glance

Before we get into Dreaming, let’s pin down a few terms. A Transcript is the full record of a session, including user input, agent output, tool calls, and their results. A Memory Note is a persistent fact, rule, or lesson distilled from past experience. A Memory Store is persistent storage that keeps memory files across sessions. Dreaming works much like Sleep-time Compute: it uses idle compute outside the main interaction to process context you already have.

Why Agent Memory Can’t Just Be Stored Chat History

When teams start building agent memory, their first instinct is usually to save every conversation and retrieve from it later. The trouble is that raw logs, session summaries, and searchable knowledge are three different things. Logs are just a pile of raw events. Summaries can drop key details. Only knowledge that has been verified and organized reliably helps with the next task.

Saving every conversation as-is creates three kinds of problems: duplicated information, outdated state, and accumulating errors. A single wrong record gets read again and again by later sessions, and the error gets treated as fact and acted on. Anthropic’s conclusion is blunt: more memory isn’t better memory. Memory needs to be selected, verified, and organized.

The Pokémon Red experiment makes the difference clear. At around 10,000 steps, Sonnet 3.7 had created 413 files and 225 folders, and had earned just 1 badge. Fable 5 had created only 9 ordinary memory files, 2 folders, and a single global.md, yet it earned 4 badges.

The gap comes down to what gets remembered. Sonnet 3.7 saved a lot of constantly changing game state, and those records went stale quickly. Fable 5 focused on strategies, verified rules, and action plans. That points to a design principle: long-term memory should prioritize knowledge that’s hard to get back from the current environment. Live state that can be read directly every time doesn’t need to be remembered.

The 4 Layers of Claude’s Memory System

Anthropic splits Agent memory into 4 layers. Each layer differs in its responsibility, how often it’s written to, and how expensive it is to read.

Moving through these 4 layers is a process of going from “raw” to “refined.” Transcripts hold the most complete information, but they’re bulky and noisy. Injected context is the most refined, but every entry takes up space in the new session’s context window, so it’s reserved for the information with the highest salience.

Dreaming’s role is maintenance across layers. It goes back into Transcripts to correct old records, merges duplicate information in Memory notes, builds wikis and indexes, and decides what’s worth injecting up front when a new session begins (Context Injection).

How Claude Dreaming Corrects Errors, Organizes Memory, and Builds Knowledge Bases

Dreaming Error Correction: The Mt. Moon Navigation Case

Anthropic documented a navigation error. An agent misremembered the direction of the Pokémon Center near Mt. Moon, and every later session kept retrying the same wrong route.

After Dreaming re-examined the historical transcripts, it found the original faulty entry and corrected the memory file. The agent using the corrected memory reached Cerulean City on action 1,935. The version without correction failed repeatedly and never completed the goal.

This case shows that Dreaming does more than summarize. It can go back to the raw experience and check whether a memory still holds up. That gives saved transcripts a new purpose: they become an evidence base you can re-verify again and again.

Claude Memory Performance: CL-Bench Experiment Data

Anthropic tested memory effectiveness using the database tasks in CL-Bench 1.0. The table below shows the mean reward reported officially.

Keep in mind that this data only covers this specific task. It isn’t a general score for agent memory capability. What’s more interesting is a pattern: the stronger the model, the more it tends to record verified rules, the causes of errors, and pitfalls it might hit in the future, rather than copying past conversations verbatim. Sonnet 4.6 improved only slightly, which suggests that how well a memory system works depends heavily on the model’s own “note-taking quality.”

How Well Dreaming Builds a Wiki Knowledge Base

The largest experiment used roughly 350,000 internal documents, about 420M tokens in total. Anthropic ran 128 Dreaming sessions to gradually build a knowledge wiki, then evaluated it with a question-answering task.

📊 About the chart: All the data above comes from public experiments on Anthropic’s engineering blog. If you’d like to run a similar small-scale test on your own corpus, you can call Claude models through APIYI (apiyi.com) and compare two setups, plain retrieval versus retrieval plus a curated wiki, on both quality and token cost.

Structured memory delivers value in two main ways. First, it builds links and indexes, so information spread across many files can be synthesized. Second, it cuts down the amount of source text that has to be re-read on each retrieval, which lowers token costs.

Impact Analysis: Why Claude Dreaming Memory Consolidation Sometimes Helps and Sometimes Hurts

Anthropic doesn’t pitch Dreaming as a cure-all. The article includes several counterexamples, and for engineering practice, these may be more useful than the positive numbers.

5 Engineering Risks of Memory Consolidation

• Over-recording: Like Sonnet 3.7, a model may save a lot of volatile state. The memory bloats quickly, and it goes stale just as fast.
• Stale information: The environment changes, but the memory is stuck on an old version. Without source verification, it keeps misleading the Agent.
• Shared-write overwrites: In a contract consolidation experiment, multiple Agents wrote to the same summary sheet at once, and only 41 of the 57 key facts survived (about 72%). After switching to one page per contract, written by a single Agent with the original clauses preserved, all 57 facts were retained.
• Wiki bloat: In one test, the raw files totaled only 115 KB, yet the generated Wiki grew to 203 KB. Consolidation actually made the information larger.
• No gain on simple tasks: For questions where the answer can be retrieved directly from a single file, the Wiki brought no noticeable improvement and only added maintenance cost.

What This Means for Developers

• Memory needs layers: Keep raw logs, learned rules, structured knowledge, and pre-injected context separate, each with its own write and read strategy.
• Sources must be traceable: Every memory should link back to its original Transcript. That’s the prerequisite for fixing mistakes.
• Serialize or partition writes: Don’t let multiple Agents write to the same file concurrently. Prefer a “one entity, one page” structure.
• Clean up regularly: Wikis and Memory notes also need deduplication, merging, and retirement. Otherwise they only get bigger.

What This Means for the Industry

• Agent memory research is shifting its focus from “retrieving accurately” to “whether the memory itself is correct and being maintained.”
• Sleep-time Compute may become a standard architecture, moving consolidation costs into idle periods and easing the context burden during live interactions.
• Structured memory fits tasks that span multiple files, multiple turns, and long-term accumulation. For one-off simple Q&A, plain retrieval is still the more economical choice.

How Developers Can Apply the Claude Dreaming Approach to Their Own Agents

Requirements for the Official Dreams Research Preview

According to Anthropic’s current documentation, Dreams is a feature of Claude Managed Agents. It’s in Research Preview, so you’ll need to request access. Calls must include two beta headers: managed-agents-2026-04-01 and dreaming-2026-04-21.

The input is an existing Memory Store plus 1 to 100 past Sessions, and the output is a new Memory Store. The original Store is never modified. The job runs asynchronously and usually takes anywhere from a few minutes to a few hours. You’re billed at the standard token price of the model you choose. Supported models are mainly Opus 5.5 and Sonnet 5.5. Also, it currently isn’t eligible for Zero Data Retention or HIPAA, so you’ll need to assess the risk before processing any sensitive data.

Dynamic Workflow Design in the Cookbook

The official Cookbook lays out a multi-agent workflow you can build yourself. By default, a Lead Agent orchestrates the process, each Analyzer Agent handles one transcript, and an Organizer Agent takes care of deduplication, fixing links, and maintaining the index. The cleaned-up Memory Store is then mounted to the next Session, usually as read-only. You can also run it on a schedule with Cron, for example consolidating the past day’s Sessions every night.

The Cookbook also includes a cost example. 11 sample transcripts totaling 283 KB ran in about 2.5 minutes and cost roughly $0.36. 50 long transcripts totaling about 12 MB cost around $8 with cost-optimized settings and took about 10 minutes. These are results from specific experiments, not fixed pricing.

Building Your Own Cross-Session Memory Consolidation Pipeline with Claude

One thing to clear up first: APIYI gives you access to the Claude family of models through its API. That’s not the same as offering Managed Agents, Memory Stores, or the Dreams API. But the core idea behind Dreaming (read transcripts in the background, extract verified rules, and hand them to a single writer to consolidate) is easy to build yourself with ordinary model invocation. Here’s a minimal example that has Claude analyze a session transcript and output candidate memories.

import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"  # APIYI OpenAI-compatible endpoint
)

transcript = open("session_001.txt", encoding="utf-8").read()
resp = client.chat.completions.create(
    model="YOUR_CLAUDE_MODEL",  # Replace with a Claude model available in the model list
    messages=[
        {"role": "system", "content": "只提炼经过验证的规则、错误原因和未来陷阱，忽略易变状态，每条注明来源行号。"},
        {"role": "user", "content": transcript},
    ],
)
print(resp.choices[0].message.content)

import json
import pathlib
import openai

client = openai.OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.apiyi.com/v1"
)
MODEL = "YOUR_CLAUDE_MODEL"
MEMORY_DIR = pathlib.Path("memory_store")
MEMORY_DIR.mkdir(exist_ok=True)

ANALYZER_PROMPT = """你是记忆分析器。阅读会话记录，输出 JSON 数组，每项包含:
topic(实体或主题名), rule(经过验证的规则/错误原因/陷阱), evidence(原文出处)。
不要记录每次都能直接从环境读取的实时状态。"""

ORGANIZER_PROMPT = """你是记忆整理器。给定某个主题的旧记忆页面和新候选条目:
1. 与旧记录冲突时，以 evidence 更可靠者为准，并注明修正原因;
2. 合并重复条目;
3. 保留原始证据引用;
输出更新后的 Markdown 页面全文。"""

def analyze(transcript: str) -> list:
    resp = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": ANALYZER_PROMPT},
            {"role": "user", "content": transcript},
        ],
    )
    try:
        return json.loads(resp.choices[0].message.content)
    except json.JSONDecodeError:
        return []

def organize(topic: str, items: list) -> None:
    # One page per topic, written serially by a single process to avoid concurrent overwrites
    page = MEMORY_DIR / f"{topic}.md"
    old = page.read_text(encoding="utf-8") if page.exists() else ""
    resp = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": ORGANIZER_PROMPT},
            {"role": "user", "content": f"旧页面:\n{old}\n\n新条目:\n{json.dumps(items, ensure_ascii=False)}"},
        ],
    )
    page.write_text(resp.choices[0].message.content, encoding="utf-8")

def nightly_dream(transcript_files: list) -> None:
    grouped = {}
    for f in transcript_files:
        for item in analyze(pathlib.Path(f).read_text(encoding="utf-8")):
            grouped.setdefault(item.get("topic", "misc"), []).append(item)
    for topic, items in grouped.items():
        organize(topic, items)

# Can be triggered by Cron every night; the next session loads only the index pages in memory_store, read-only
nightly_dream(["session_001.txt", "session_002.txt"])

🚀 Quick-start tip: When you’re building a prototype, you can use a single API key from APIYI (apiyi.com) to test different Claude models as the Analyzer and the Organizer. Compare which combination extracts more accurate rules at lower token cost, then decide on your production setup.

Here’s a table summarizing the differences between the two approaches:

Claude Dreaming FAQ

Claude Dreaming Key Takeaways

• Memory isn’t just storage: Saving every conversation piles up duplicates, outdated info, and mistakes, so memory needs to be verified and organized.
• 4-layer memory structure: Transcripts, Memory notes, Memory representations, and Injected context each have their own job.
• Corrections depend on raw records: Dreaming goes back to the Transcript to double-check, and it fixed a wrong direction that had been causing repeated failures.
• Wikis excel at cross-document tasks: On an M&A task, the Wiki scored 87% versus 73% for pure retrieval, saving about 20,000 tokens per question on average.
• Consolidation has side effects too: Concurrent writes can lose facts, Wikis can bloat, and simple tasks don’t need one.
• You can build it yourself: By calling Claude models through APIYI (apiyi.com), you can implement a simplified version of cross-session memory consolidation.

Summary

Claude Dreaming offers three main lessons:

1. Long-term memory is all about maintenance: Only memory that’s been verified, deduplicated, and organized can reliably help with the next task.
2. What you remember matters more than how much you remember: Prioritize rules, error causes, and pitfalls that are hard to rediscover from the environment, and don’t record volatile state.
3. Structured memory depends on the scenario: Tasks that span multiple files, multiple rounds, and long-term accumulation are worth a Wiki, while simple retrieval tasks don’t need the extra maintenance overhead.

If your Agent already runs across multiple sessions, start with the smallest working loop: “keep the Transcripts, consolidate serially once a night, and mount the index page as read-only.” We recommend calling Claude models through APIYI (apiyi.com) to quickly validate this workflow. The platform offers an OpenAI-compatible interface and free trial credits for new users.

📚 References

1. The components of agent memory: The original Anthropic engineering blog post, covering the 4-layer memory structure and the Dreaming experiments
2. Link: anthropic.com/research/components-of-agent-memory

3. Notes: The original source for the experiment data from CL-Bench, Pokémon, Wiki, and contract organization

4. Dreaming with a dynamic workflow: The official Claude Cookbook

5. Link: platform.claude.com/cookbook/managed-agents-cma-dreaming-with-a-dynamic-workflow

6. Notes: A sample multi-agent workflow with Lead, Analyzer, and Organizer agents, plus cost references

7. Anthropic’s official X announcement: The release note for the Dreaming engineering blog post

8. Link: x.com/AnthropicAI/status/2118814753154064501
9. Notes: Confirms the release date and the official positioning

Author: The APIYI Technical Team
Technical discussion: Reach out to us on the APIYI homepage. For more resources, visit the docs.apiyi.com documentation center.