Claude Code Memory System: Five Layers from Injection to Consolidation

Most agent memory implementations are a single text file appended to the system prompt.

Claude Code has five distinct layers, each solving a different problem in the memory lifecycle.

File structure

src/
├── services/
│   ├── autoDream/
│   │   └── autoDream.ts
│   ├── extractMemories/
│   │   └── extractMemories.ts
│   ├── relevantMemories/
│   │   └── relevantMemories.ts
│   ├── SessionMemory/
│   │   └── SessionMemory.ts
├── tasks/
│   ├── DreamTask/
│   │   └── DreamTask.ts
└── utils/
    ├── memdir.ts

The five-layer model

Why five layers instead of one

A single-layer memory design hits predictable failure modes:

• inject everything: context overflows on long sessions
• extract and store: stale variants accumulate without compaction
• compact only: cross-session facts are lost between restarts
• no selection: a large memdir crowds context even when most of it is irrelevant
• no consolidation: retrieval quality degrades as memdir grows

Each layer in Claude Code addresses one of those failures.

The retrieval layer (memdir) is bounded. The selection layer (Relevant Memories) filters to what matters for the current turn. The compaction layer (SessionMemory) manages in-flight overflow. The extraction layer (ExtractMemories) populates the store with curated facts. The consolidation layer (AutoDream) keeps the store from degrading over time.

The distributed lock design

The mtime-based lock in AutoDream is worth examining separately.

The problem: if a user runs multiple Claude Code instances in the same environment — terminals, IDE integration, background sessions — each instance will independently check whether it is time to dream.

Without a lock, two instances would consolidate simultaneously, producing conflicting writes to memdir.

The solution is an mtime-based file lock:

1. check if the lock file exists and its mtime is within the throttle window
2. if not, write a new lock file (updating its mtime atomically)
3. proceed with consolidation
4. release by writing a completion marker

This is not a POSIX advisory lock. It is a time-window-based coordination primitive that works across processes without shared memory.

It is the right design for an agent runtime that runs concurrently without an always-on coordinator.

Sonnet-assisted extraction is a product decision

The choice to use Sonnet for memory selection inside extractMemories.ts deserves attention.

It means extraction quality is not just a function of what happened in the conversation — it is also a function of how well the selection prompt is written.

That is both a strength (the model can recognize nuanced facts that a regex would miss) and a risk (a poor selection prompt causes high-value facts to be filtered out before they reach memdir).

Claude Code controls this risk by using a specific extraction prompt tuned to the 4-type taxonomy. Changing the taxonomy means changing the extraction prompt.

type MemoryType = 'fact' | 'preference' | 'skill' | 'relationship'

interface MemoryCandidate {
type: MemoryType
content: string
confidence: number
sourceConversationId: string
}

async function extractMemories(
conversation: Message[],
existingMemories: MemoryCandidate[]
): Promise<void> {
// 1. Extract candidates using taxonomy-aware prompt
const candidates = await runExtractionPrompt(conversation)

// 2. Coalesce: deduplicate against existing memories
const novel = coalesceStash(candidates, existingMemories)

// 3. Sonnet-assisted selection: filter to high-value subset
const selected = await runSelectionPrompt(novel)

// 4. Write to memdir — each fact as its own file
for (const memory of selected) {
  await writeMemoryFile(memory)
}
}

// Coalescer: prevent stale variants accumulating
function coalesceStash(
candidates: MemoryCandidate[],
existing: MemoryCandidate[]
): MemoryCandidate[] {
return candidates.filter(c =>
  !existing.some(e =>
    e.type === c.type && semanticallySimilar(e.content, c.content)
  )
)
}