Memory System Deep Dive

Advanced Guide · 18 min read

✓Based on source code analysis

Four-Layer Memory Architecture

Claude Code implements a sophisticated memory hierarchy inspired by cognitive science, from short-term session memory to long-term team knowledge.

Layer 1: Session Memory (Working Memory)

Temporary file, triggered at 10K tokens init + 5K incremental growth. Session-only scope.

Layer 2: Memdir / MEMORY.md (Episodic Memory)

~/.claude/projects/.../memory/, manual or extraction agent triggered. Personal persistent.

Layer 3: Magic Docs (Semantic Memory)

In-project files with # MAGIC DOC: header. AI auto-maintained. Project scope.

Layer 4: Team Memory Sync (Collective Memory)

Cloud API sync with secret scanning. Team-wide persistent knowledge.

Layer 1: Session Memory

Extracted during conversation when thresholds met:

  • Init threshold: 10,000 tokens
  • Update threshold: 5,000 tokens between updates
  • Tool calls: 3+ between updates

Uses Forked Agent pattern with shared prompt cache for efficiency.

Layer 2: Memdir (MEMORY.md)

Location Priority

  1. CLAUDE_COWORK_MEMORY_PATH_OVERRIDE env var
  2. autoMemoryDirectory in settings.json
  3. ~/.claude/projects//memory/ (default)

MEMORY.md Constraints

  • Max 200 lines (truncated with warning)
  • Max 25,000 bytes
  • Warning: > WARNING: MEMORY.md is X lines (limit: 200)

Memory Types

  • user: Always private (roles, goals, preferences)
  • feedback: Private or team (work style guidance)
  • project: Team-leaning (ongoing work, bugs)
  • reference: Usually team (external system pointers)

Layer 3: Magic Docs

AI auto-maintained documents detected by header:

# MAGIC DOC: API Endpoints List
_Keep this updated when endpoints change_

When Claude reads such files, a Sonnet model agent periodically updates them.

Layer 4: Team Memory Sync

Sync Semantics

  • Pull: Server-preferred (per-key overwrite)
  • Push: Incremental (only different hashes)
  • Delete: Not propagated

Secret Scanning

Before upload, 35+ gitleaks-based rules scan for:

  • Cloud providers (AWS, GCP, Azure)
  • AI APIs (Anthropic, OpenAI)
  • Private keys and certificates

Dream Consolidation

AutoDream service triggers memory consolidation when:

  • Time gate: 24+ hours since last consolidation
  • Session gate: 5+ new sessions
  • Lock gate: No other process consolidating

Four phases: Orient → Gather → Consolidate → Prune

💡 Pro Tip: See Memory Reference for complete source code analysis.