4 Memory Systems: Extraction, Session, Living Docs, and Dreams

In the previous article we analyzed how Claude Code compresses context to maintain the illusion of an infinite conversation. But there's a deeper question: what happens when you close your session and come back tomorrow?

The answer will surprise you. Claude Code doesn't simply "remember" what you told it. It has 4 completely independent memory systems, each with its own trigger, format, and philosophy. One extracts knowledge in the background after every interaction. Another takes periodic notes during the session. A third maintains living documentation that updates itself. And the fourth — the most fascinating — consolidates and reorganizes memories every night, like the human brain during REM sleep.

It's not a metaphor. The system is literally called auto-dream.

Before diving into each one, here's the complete map. Each system operates independently, with its own trigger, data format, and lifecycle:

The biological inspiration is deliberate. Just as the human brain has separate systems for encoding (hippocampus), working memory (prefrontal cortex), externalization (written notes), and consolidation during sleep — Claude Code replicates these 4 pillars with background agents and nightly tasks.

Auto-Memory is the most fundamental memory system. It activates at the end of each "query loop" — every time Claude Code finishes processing your request — via the handleStopHooks hook. Without you noticing, a parallel agent (fork) analyzes the conversation and extracts any data that should be remembered.

The key engineering trick: the forked agent shares the parent agent's prompt cache. This means it doesn't need to re-read the entire conversation — it already has the context cached. Extraction is cheap in tokens.

Each extracted memory is classified into one of 4 types:

# Format of an extracted memory (YAML frontmatter)
---
name: Prefers TypeScript over JavaScript
description: User always chooses TS and requests strict types
type: user          # user | feedback | project | reference
---

Additional context: uses strict mode,
prefers interfaces over types for public objects.

If Auto-Memory is long-term memory, Session Memory is working memory. Controlled by the feature gate tengu_session_memory, this system takes periodic "notes" about what's happening in the current session.

The trigger isn't time-based — it's based on token consumption and tool call count. When the session crosses a certain activity threshold, the system generates a snapshot of the current state using an 11-section template:

# Session Memory Template (11 sections)

## 1. Current State        — What's being done right now
## 2. Task Spec            — Description of the user's task
## 3. Files                — Relevant files touched/read
## 4. Workflow             — Steps completed and pending
## 5. Errors               — Errors encountered and their status
## 6. Codebase Documentation — Notes about the codebase
## 7. Learnings            — Discoveries from this session
## 8. Key Results          — Important results achieved
## 9. Worklog              — Chronological log of actions
## 10. [Reserved]          — Reserved for future expansion
## 11. [Reserved]          — Reserved for future expansion

Two constants govern the limits: MAX_SECTION_LENGTH = 2000 tokens per section and MAX_TOTAL = 12000 tokens for the entire note. This prevents session notes from becoming a complete conversation dump — they must be concise.

The best part? The template is customizable. You can create your own template at ~/.claude/session-memory/config/template.md to adapt the sections to your workflow. If you work in data science, you could add sections for datasets and metrics. If you work in frontend, sections for components and UI states.

The first two systems store memories about the user and the session. Magic Docs is different: it maintains documentation about the code itself, and it does so automatically.

The pattern is elegant in its simplicity. Any file that starts with the special header becomes a "magic document":

# MAGIC DOC: API Architecture

Overview of the REST API layer...

// This file auto-updates when related code changes.
// A background agent keeps it synchronized.

When you change code that's related to a Magic Doc, a background agent detects the change and updates the document. You don't need to ask for it — it just happens. The agent follows a strict philosophy:

"BE TERSE. High signal only. For OVERVIEWS, ARCHITECTURE, ENTRY POINTS."

No long-winded explanations or tutorials. Magic Docs are navigation maps — they tell you where things are and how they fit together, not how they work line by line. If you need to customize the behavior of the agent maintaining your docs, you can create a custom prompt at ~/.claude/magic-docs/prompt.md.

And now the most fascinating system. Auto-Dream is the reason this article's title says "dreams" without quotation marks. Claude Code literally has a consolidation process that runs periodically — every 24 hours or every 5 sessions — to reorganize and clean up accumulated memories.

The analogy with human sleep is precise. During REM sleep, the brain:

• • Consolidates the day's memories into long-term storage
• • Discards irrelevant information
• • Reorganizes connections between existing memories
• • "Compacts" the storage

Auto-Dream does exactly the same thing, in 4 phases:

In KAIROS mode (the advanced variant), Auto-Dream also uses daily logs as input and produces a "nightly distillation" — a high-level summary of what was learned that day, which gets integrated into long-term memory.

Everything is stored on the filesystem. No databases, no cloud services — markdown files on disk. The structure:

# Filesystem layout
~/.claude/memory/
├── MEMORY.md                  ← Main index (max 200 lines)
├── user-preferences.md        ← "user" type memories
├── project-goals.md           ← "project" type memories
└── logs/
    └── 2026/
        └── 07/
            └── 2026-07-04.md  ← Daily log

# Constants
ENTRYPOINT = 'MEMORY.md'
MAX_LINES  = 200
MAX_BYTES  = 25_600  // 25KB

The MEMORY.md file is the entry point. When Claude Code starts a new session, the first thing it reads is this file to orient itself — just like you'd read yesterday's notes before starting work.

There are two modes of operation: Individual (private memories per user) and TEAMMEM (shared + private memories). In TEAMMEM mode, there's a shared directory for team memories and a private one per developer, allowing project knowledge to be collective without losing personal preferences.

A common question: what's the difference between the memory system and CLAUDE.md? They're complementary but very different:

The /remember command is the bridge: it promotes an automatic memory to a permanent rule in CLAUDE.md. It's like when a provisional note becomes a team policy — it stops being an observation and becomes a permanent instruction.

Claude Code's 4 memory systems aren't just curious internals. They're design patterns you can apply to any agent or chatbot:

The boundary between a chatbot that "remembers" and an agent with real memory is exactly this: 4 independent systems, each optimized for a different type of retention. Auto-Memory extracts what you learn. Session Memory maintains current state. Magic Docs keeps the maps updated. And Auto-Dream consolidates everything while you sleep.

The most revealing aspect is what the system doesn't save. The explicit exclusions — no code patterns, no debugging solutions, nothing already in CLAUDE.md — reveal a precise philosophy: memory is for what can't be re-discovered. Everything else is read in real time.

In the next article in this series, we'll explore Claude Code's hidden features — commands, flags, and capabilities that don't appear in the official documentation but transform the user experience.