Claude Code Dreams: How Auto Dream Keeps Your AI Agent's Memory Clean and Useful

Claude Code's auto memory was a breakthrough — your AI agent finally took its own notes about your project. Build commands, debugging patterns, architecture decisions, code style preferences. All captured automatically across sessions.

But after 20 or 30 sessions, those notes become a problem. Contradictory entries pile up. Relative dates like "yesterday" lose meaning a week later. Stale debugging solutions reference files that were deleted during a refactor. The notebook that was supposed to help Claude remember instead becomes noise that confuses it.

That's the problem Auto Dream solves. Anthropic modeled it explicitly after how the human brain consolidates memories during REM sleep — reviewing what happened, strengthening what matters, discarding what doesn't, and reorganizing the rest into clean structures.

Here's everything you need to know about how it works and how to use it.

The Four Memory Layers in Claude Code

Before diving into Auto Dream specifically, it helps to understand where it fits in Claude Code's full memory architecture. There are four distinct layers, and they work together:

Layer	What It Does	Who Controls It
CLAUDE.md	Persistent project instructions — build commands, conventions, architecture notes	You write and maintain it
Auto Memory	Notes Claude writes itself based on corrections, patterns, and decisions	Claude writes automatically
Session Memory	Conversation continuity — what you discussed and decided in specific sessions	Claude tracks automatically
Auto Dream	Periodic consolidation of everything Auto Memory has accumulated	Runs automatically in background

Think of it this way: CLAUDE.md is the instruction manual you write. Auto Memory is the note-taker running during every session. Session Memory is short-term recall. And Auto Dream is REM sleep — the process that turns scattered daily notes into organized long-term knowledge.

The strongest setup runs all four. Each layer handles a different type of memory, and Auto Dream is what prevents the auto-generated layers from degrading over time.

How Auto Memory Works (and Why It Breaks Down)

Auto Memory has been available since Claude Code v2.1.59. When enabled, Claude saves notes for itself as it works. It decides what's worth remembering based on whether the information would be useful in a future conversation.

These notes live in ~/.claude/projects/<project>/memory/MEMORY.md and associated topic files. The first 200 lines or 25KB of MEMORY.md — whichever comes first — load automatically at session start. Additional topic files like debugging.md or api-conventions.md are loaded on demand.

This works well for the first dozen sessions. But then entropy sets in:

Contradictions accumulate. You switched from Express to Fastify three weeks ago, but the old "API uses Express" entry still exists alongside "Migrated to Fastify."
Relative dates decay. "Yesterday we decided to use Redis" is useful the next day. Two months later, it's meaningless.
Stale references persist. Debugging notes about a file that was deleted during a refactor serve no purpose.
Duplicates pile up. Three different sessions noted the same build command quirk. Now there are three entries saying the same thing.

Without a consolidation step, auto memory notes accumulate the same way unconsolidated short-term memories do in the human brain — becoming increasingly unreliable and hard to navigate.

How Auto Dream Works

Auto Dream runs as a background sub-agent that activates between your sessions. It follows a structured four-phase consolidation cycle.

Phase 1 — Inventory

Claude scans the memory directory, reads the current MEMORY.md index file, and builds a map of the current memory state. What exists? How is it organized? What's the baseline before making changes?

If subdirectories like logs/ or sessions/ exist, recent entries are reviewed to understand what's been added since the last consolidation.

Phase 2 — Gather Recent Signal

This is the knowledge extraction phase. Auto Dream searches through previous session transcripts (JSONL files stored locally), but it doesn't read them in full. It performs targeted searches for specific patterns:

User corrections — moments where you said "no, that's wrong" or corrected Claude's understanding
Recurring themes — patterns that keep coming up across sessions
Important decisions — architecture choices, tool selections, workflow changes

The prompt explicitly instructs: "Don't exhaustively read transcripts. Look only for things you already suspect matter." This selectivity is deliberate. Reading 500 full transcripts would burn tokens with diminishing returns.

Phase 3 — Consolidate

This is the core phase where the actual cleanup happens:

Merges new information into existing topic files rather than creating duplicates
Converts relative dates to absolute dates — "Yesterday we decided to use Redis" becomes "On 2026-03-15 we decided to use Redis"
Deletes contradicted facts — if you switched from Express to Fastify, the old entry gets removed at its source
Removes stale memories — debugging notes about deleted files, workarounds for bugs that were fixed, references to removed dependencies
Merges overlapping entries — if three sessions noted the same build quirk, they consolidate into one clean entry

Phase 4 — Prune and Index

The final phase focuses on keeping the MEMORY.md index file under its loading limits. Since only the first 200 lines load at startup, this file needs to be a tight, well-organized pointer system — not a content container.

Each index entry follows a standard format:

- [Title](file.md) — one-line hook

Entries are kept under 150 characters. Stale entries are removed, verbose lines get shortened, and contradictions between files are resolved. The total index is maintained under approximately 25KB.

Trigger Conditions

Auto Dream doesn't run after every session. It uses a dual-gate system to prevent unnecessary consolidation:

Time gate: At least 24 hours must have passed since the last dream cycle
Session gate: At least 5 new sessions must have accumulated

If you had one long session over two days, Auto Dream won't trigger — not enough sessions. If you ran 10 quick sessions in two hours, it won't trigger either — not enough time has passed. This prevents unnecessary consolidation on projects with light usage while ensuring active projects get regular cleanup.

When both gates are satisfied, Claude spawns a forked sub-agent specifically for the dream cycle. The process also uses file locking to prevent conflicts — if two Claude Code instances are open on the same project, only one can run Auto Dream.

Safety Guarantees

During dream cycles, Claude operates under strict constraints:

Memory files only. Auto Dream can only write to files in the memory directory. It never touches source code, configuration files, tests, or any project files.
No session blocking. The consolidation happens in a separate background process. Your active sessions continue without interruption.
One dreamer at a time. File locking prevents concurrent dream cycles on the same project.

That said, Auto Dream prunes aggressively. If it removes something you wanted to keep, you'll need a backup to recover it. More on that below.

How to Check if Auto Dream Is Active

Run /memory inside any Claude Code session. Look for "Auto-dream: on" in the output. If you see it, Claude is already consolidating your memory files in the background between sessions.

The feature is controlled by a server-side feature flag, meaning Anthropic manages the rollout. Not every user has access yet — if you don't see the toggle, your account hasn't received it.

Using the Manual /dream Command

Even without the automatic feature, you can trigger memory consolidation manually. The /dream command runs the same four-phase process on demand.

The /dream slash command is still rolling out and may return "Unknown skill" for some users. If that happens, you can achieve the same result by telling Claude directly:

Consolidate my memory files

Run a dream cycle on my memory

Claude will execute the same consolidation process interactively.

When to Manually Trigger a Dream Cycle

Even with automatic consolidation enabled, manual triggering makes sense in specific situations:

After a major refactor — framework migrations, directory restructures, or significant architecture changes leave a trail of outdated memory entries
After deleting or renaming many files — stale file references accumulate quickly
Before starting a complex multi-session task — clean memory means Claude starts with accurate context
After onboarding a new team member — if someone else has been using Claude Code on the project with different conventions, consolidation resolves the conflicts

Practical Tips for Working with Auto Dream

Back Up Before Your First Dream Cycle

Auto Dream prunes aggressively by design. Before enabling it or running /dream for the first time, back up your memory directory:

cp -r ~/.claude/projects/YOUR_PROJECT/memory ~/.claude/projects/YOUR_PROJECT/memory.backup

If the consolidation removes something you wanted to keep, you can recover it from the backup.

Write Good CLAUDE.md Instructions

Auto Dream consolidates what Claude learns organically. But your CLAUDE.md file takes priority — it loads with high authority at every session start. If you want Claude to always follow a specific convention, put it in CLAUDE.md rather than relying on auto memory to eventually capture it.

The two systems complement each other:

CLAUDE.md for rules you want enforced
Auto Memory + Auto Dream for patterns that emerge naturally during work

Keep Memory Files Focused

If you notice auto memory creating very large topic files, consider splitting them manually. Auto Dream merges entries but respects existing file boundaries. A focused debugging.md and separate api-conventions.md will stay organized better than a single monolithic notes file.

Monitor Memory Quality

Periodically check your memory files to see what Claude is remembering and what Auto Dream is pruning. Run /memory and browse the files. If you see important information being removed, consider promoting it to your CLAUDE.md file where it won't be subject to consolidation.

Auto Dream vs. Manual Memory Management

Before Auto Dream, the recommended approach was to periodically review and clean up memory files yourself. That still works, and some developers prefer the control. Here's how the approaches compare:

	Manual Management	Auto Dream
Effort	You review and edit memory files	Runs automatically in background
Control	Full control over what stays and goes	Algorithmic pruning based on relevance
Consistency	Depends on how often you remember to do it	Runs on a consistent schedule
Risk	You might forget, letting memory degrade	May occasionally prune something useful
Best for	Small projects with few sessions	Active projects with many sessions

The practical recommendation: let Auto Dream handle the routine cleanup and manually intervene only when you notice issues or after major project changes.

What's Coming: KAIROS and the Always-On Agent

Auto Dream is one piece of a larger system found in Claude Code's architecture called KAIROS. References to KAIROS appear extensively in the codebase and describe an always-on agent that goes beyond memory consolidation:

Maintains append-only daily logs of observations
Can trigger proactive actions based on patterns it notices
Runs dream cycles at night to consolidate and prune memory
Supports scheduled tasks and push notifications

KAIROS is currently gated behind internal feature flags and isn't available to end users. But it signals where Claude Code's memory system is heading — from reactive note-taking toward proactive, always-on project awareness.

Getting Started

If you're new to Claude Code's memory system, here's the recommended path:

Set up CLAUDE.md with your project's essential context — build commands, conventions, architecture decisions
Enable Auto Memory if it isn't already on (check with /memory)
Work normally for 10-20 sessions and let Claude accumulate notes
Check your memory files to see what Claude has captured
Run /dream (or ask Claude to consolidate) to clean up accumulated notes
Enable Auto Dream when it's available for your account to automate ongoing consolidation

The goal is a memory system that improves with use rather than degrading. Auto Dream is the missing piece that makes that possible — the cleanup process that keeps auto-generated knowledge accurate, current, and useful across hundreds of sessions.