Step-by-Step Teaching

Step 1: The Core Problem — Why Agents Need Memory

Start with the fundamental challenge.

The bind: AI agents must act forward in time, but useful memory requires understanding backward — you only know what mattered after the fact.

Human analogy to anchor your understanding:

Key distinction: Agent memory specifically means knowledge gained from experience and retained between sessions. It does not include:

• Weight changes from training
• In-context learning within one conversation
• Compaction summaries

---

Step 2: The Memory Hierarchy — Four Layers

Think of memory as a pyramid with four levels, bottom to top:

┌─────────────────────────────┐
│     INJECTED CONTEXT        │  ← Loaded automatically every session
├─────────────────────────────┤
│   MEMORY REPRESENTATIONS    │  ← Wikis, structured knowledge maps
├─────────────────────────────┤
│      MEMORY NOTES           │  ← Claude's written observations
├─────────────────────────────┤
│       TRANSCRIPTS           │  ← Raw searchable event logs
└─────────────────────────────┘

Dreaming is the process that moves information upward through these layers during idle time between sessions.

---

Step 3: Memory Notes — The First Active Layer

The core insight: Writing a memory note is actually a prediction.

When Claude writes down a rule, it is predicting: "A future version of me will need this."

How this works in practice — the CL-Bench example:

A benchmark asked Claude to answer database questions across sessions. After each answer, Claude learned whether it was right or wrong. The learning loop looked like this:

Get question wrong
       ↓
Record the failure
       ↓
Generate theories about why
       ↓
Test those theories
       ↓
Write a validated rule to memory
       ↓
Apply rule to future questions

Model progression showed increasing sophistication:

Takeaway: The ability to close a learning loop is a capability that improves with model sophistication.

---

Step 4: Salience Judgment — What's Worth Remembering?

This is where memory quality diverges dramatically between approaches.

The Pokémon experiment revealed two opposing strategies:

Sonnet 3.7 — Record Everything

• 413 files across 225 folders
• Separate file for every battle, item, NPC encounter
• Problem: Game state changes constantly → memory goes stale instantly
• Result: Spent more time managing memory than playing; earned 1 badge

Fable 5 — Record What Only Claude Can Know

• 10 files in 2 folders + one global.md
• Earned 4 badges

The key principle Fable 5 applied:

Don't store what you can read off the screen. Store what disappears unless you write it down.

Fable 5's global.md acted as a dashboard — current goal, gym plan, and Claude's own rules for using memory.

---

Step 5: Steering Memory — How Much Guidance Helps?

Finding: Tell Claude what memory is for, not how to use it.

Evidence from CL-Bench:

When researchers gave Opus 5 and Opus 4.7 a specific rule — "record only failures" — performance actually dropped:

• Opus 5: −0.234 performance loss
• Opus 4.7: −0.150 performance loss

Stronger models perform better with freedom to judge salience themselves.

However, weaker models benefit from explicit guidance:

• Sonnet 4.6 rarely read its memory files unprompted
• Adding instructions to read memory before answering and explicitly test theories nearly doubled its benchmark score
• Sonnet 5 reads memory before answering 9/10 times without being told to

Practical rule:

Frontier models → Simple guidance, trust their judgment
Older/weaker models → Explicit step-by-step instructions help significantly

---

Step 6: Dreaming — Four Functions

Dreaming is offline processing that improves memory between sessions. It has four distinct jobs:

Function 1: Correct Wrong Notes

The Mt. Moon example:

Claude incorrectly recorded that the PokéCenter was on the east side of the mountain. This caused it to:

1. Walk the wrong direction
2. Fall off a one-way ledge
3. Conclude it had "overshot west" (wrong interpretation)
4. Repeat the mistake three times

With dreaming: Claude checked the note against the original transcript (ground truth), caught the error, rewrote it, and successfully navigated through.

Key mechanism: Transcripts serve as ground truth. Dreaming validates notes against transcripts.

---

Function 2: Build Memory Representations (Wikis)

For large knowledge bases, flat notes aren't enough. Dreaming can build wikis — linked pages that map what Claude knows.

Experiment with 350,000 files (~420M tokens):

Wiki + Search tool combined reached 61%, versus 53% for search alone.

Why wikis help:

• Links create a navigable map through large knowledge bases
• Claude can locate relevant memories efficiently without exhaustive search
• Saves ~20,000 tokens per question

When wikis don't help:

• When answers can be found by simple text search in one document
• When the wiki grows larger than the source material (the Borges problem — a map as large as the territory abstracts nothing)

---

Function 3: Promote Notes to Injected Context

The top layer — injected context — loads automatically into every session without Claude needing to search.

Critical constraints:

• Uses valuable tokens → must stay small
• Wrong notes propagate into every session
• Longer instruction files reduce adherence

How Claude Code handles this:

• Maintains a MEMORY.md file
• Loads only the first 200 lines or 25 KB as an index header
• The header tells Claude what it knows and where to find it — not everything itself

Design principle: The top layer is an index, not an archive.

---

Function 4: Fill Gaps Across Sessions

Single sessions have limited context. Dreaming can search across many sessions to find patterns.

Example: After building a wiki, Claude had nine links pointing to a page that didn't exist. A second dreaming pass:

• Found all nine broken links
• Redirected them to the correct existing page
• Added three new pages including an index

Also: Dreaming can optimize the instructions for building memory itself. When a wiki was missing contract terms because agents overwrote each other's work, a dreaming loop:

1. Reflected on failures
2. Proposed new instructions
3. Rebuilt the wiki

Result: Performance jumped from 72% → 100% of graded criteria.

---

Step 7: Open Design Tradeoffs — Thinking Like a Systems Designer

The article closes with unresolved tensions. Understanding these shows mature comprehension:

Tradeoff 1: In-Session Writing vs. Dreaming

Tradeoff 2: Keeping Memory Current

• Memory can be wrong from the start or drift as environments change
• Checking all memories continuously is computationally impractical
• Solution direction: Focus dreaming on frequently-accessed or likely-to-change memories

Tradeoff 3: Representations vs. Search

• Wikis help when knowledge is interconnected and requires synthesis
• Search alone works when answers are locatable in single documents
• Wikis require maintenance compute and can accumulate errors

---

Summary: The Complete Picture

SESSION HAPPENS
      ↓
Claude writes memory notes (predicting future relevance)
      ↓
Session ends → transcripts saved
      ↓
DREAMING (offline)
  ├── Validates notes against transcripts (corrects errors)
  ├── Builds/updates wikis (creates navigable knowledge maps)
  ├── Promotes key notes to injected context (always-available layer)
  └── Fills cross-session gaps (finds patterns across many sessions)
      ↓
NEXT SESSION BEGINS
  ├── Injected context loaded automatically
  ├── Wiki available for navigation
  ├── Search available for transcripts
  └── Claude acts with richer, more accurate memory

The central insight: Memory is not just storage — it is an active, maintained system that requires judgment about salience, validation against ground truth, and intelligent organization to be useful across time.