Cross-Session Memory - From Forgetting to Persistent Learning

Have you had this experience: every new Claude Code session, you have to repeat “I’m a backend engineer,” “this project uses Bun,” “don’t use mocks to test the database”?

An AI without memory is like a goldfish - starts from scratch every conversation. Today let’s talk about Claude Code’s cross-session memory system and see how AI can “develop long-term memory.”

Six-Layer Memory Architecture

Claude Code’s memory system has six layers, from high-frequency incremental to low-frequency global:

This is like human memory hierarchy:

• Memdir: long-term memory bank
• Extract Memories: short-term memory encoding
• Session Memory: working memory summary
• Transcript: complete memory backup
• Agent Memory: specialized skill memory
• Auto-Dream: sleep-time memory organization

Memdir: Memory Storage Layer

Memory Directory Location

Three-level priority chain determines memory storage location:

1. CLAUDE_COWORK_MEMORY_PATH_OVERRIDE environment variable
2. autoMemoryDirectory setting (excludes projectSettings to prevent malicious redirect)
3. Default: ~/.claude/projects/<git-root>/memory/

All worktrees share the same memory directory - memory is about the project, not the working directory.

MEMORY.md Index

MEMORY.md is the entry point of the memory system, each line points to a topic file:

- [Coding Standards](coding-style.md) - Project TypeScript coding standards
- [Database Configuration](database.md) - PostgreSQL connection info
- [API Documentation](api-reference.md) - REST API endpoint list

Dual truncation prevents bloat:

• Maximum 200 lines
• Maximum 25KB

When truncated, WARNING message is appended, prompting model to move detailed content to topic files - self-repair mechanism.

Topic File Format

Each memory is an independent Markdown file with YAML frontmatter metadata:

---
name: Coding Standards
description: TypeScript project code style guide
type: project
---

- Use 2-space indentation
- Prefer `const` over `let`
- ...

Four types:

• user: user role, preferences, knowledge level
• feedback: user’s corrections and guidance to Agent behavior
• project: ongoing work, goals, deadlines
• reference: pointers to external systems (Linear, Grafana, etc.)

KAIROS Log Mode

In KAIROS long-running mode, memory write strategy changes to appending to daily log files:

memory/logs/2026/04/2026-04-03.md

Append-only strategy avoids frequent rewriting, distillation handled by nightly Auto-Dream.

Extract Memories: Automatic Memory Extraction

Trigger Mechanism

At the end of each query loop, fork agent silently analyzes conversation and extracts information worth persisting.

Trigger conditions:

• Main Agent only (excludes sub-Agents)
• Fire-and-forget (doesn’t block next turn)

Throttling and Mutual Exclusion

Throttling: tengu_bramble_lintel flag controls frequency (runs every turn by default)

Mutual exclusion: when main Agent itself wrote a memory file, fork agent skips this turn’s extraction. Prevents two agents writing to the same file simultaneously.

Permission Isolation

Fork agent permissions are strictly limited:

• Allowed: Read/Grep/Glob (read-only)
• Allowed: Bash (only ls, find, grep, cat and other read-only commands)
• Allowed: Edit/Write (only paths within memoryDir)
• Denied: all other tools (MCP, Agent, write-capable Bash, etc.)

Efficient Operation Strategy

Extract agent prompt explicitly instructs:

Round 1: Parallel read all files that might need updating
Round 2: Parallel execute all write/edit operations

Maximum 5 rounds to prevent getting stuck in validation loops.

Session Memory: Rolling Session Summary

Session Memory solves the problem of within-session information retention. When context approaches saturation, it provides “what’s important” signals for the compression system.

Triple Threshold Protection

{
  minimumMessageTokensToInit: 10000,  // First trigger: 10K tokens
  minimumTokensBetweenUpdate: 5000,   // Update interval: 5K tokens
  toolCallsBetweenUpdates: 3         // Minimum tool calls: 3
}

Trigger conditions:

• Token threshold (5K) must be met
• Plus: (a) tool calls ≥ 3, OR (b) last assistant turn had no tool calls (natural conversation break)

This won’t trigger in short conversations, nor interrupt workflow during intensive tool calls.

Relationship with Auto-Compression

Session Memory registers as post-sampling hook. But initialization gate checks isAutoCompactEnabled() - if auto-compression is disabled, Session Memory doesn’t run either.

Session Memory’s primary consumer is the compression system. Summary file summary.md is injected during compression.

Difference from Extract Memories

The two run in parallel, not interfering with each other.

Transcript Persistence: Complete Session Recording

sessionStorage.ts (5105 lines, one of the largest single files) is responsible for persisting session records in JSONL format.

JSONL Format

Each message serialized to one line of JSON, appended to session file:

{"type":"user","content":"Help me refactor this module","timestamp":"2026-04-03T10:00:00Z"}
{"type":"assistant","content":"Sure, let me first understand the code structure","tool_uses":[{"name":"Read","input":{"file_path":"/src/app.ts"}}]}

JSONL chosen for performance - incremental append only needs appendFile, no need to parse and rewrite entire file.

Special Entry Types

Beyond standard user/assistant messages, also includes:

• file_history_snapshot: file history snapshot for recovering file state after compression
• attribution_snapshot: attribution snapshot, records source of file modifications
• context_collapse_snapshot: compression boundary marker
• content_replacement: content replacement record for REPL mode output truncation

Session Recovery

When claude --resume:

1. Parse all JSONL entries
2. Reconstruct message tree from uuid/parentUuid
3. Apply context_collapse_snapshot, restore to post-compression state
4. Reconstruct file history snapshots to ensure model’s understanding of file state matches disk

This enables cross-session “continue where you left off.”

Agent Memory: Sub-Agent Persistence

Sub-Agents have their own memory needs:

• Code review agent needs to remember team’s code style preferences
• Test agent needs to remember project’s test framework configuration

Three-Scope Model

Each scope independently maintains MEMORY.md index and topic files.

VCS Snapshot Sync

Project-scope memory should be shared across team via Git, but .claude/agent-memory/ is in .gitignore.

Solution is separate snapshot directory .claude/agent-memory-snapshot/, tracking versions via updatedAt timestamp in snapshot.json.

Three strategies:

• none: no snapshots
• initialize: copy snapshot to local
• prompt-update: prompt model to merge (don’t auto-overwrite)

Auto-Dream: Nightly Memory Consolidation

Auto-Dream is the “sleep phase” of the memory system - background consolidation task, requires both time gate (default 24 hours) and session gate (default 5 new sessions).

Four-Layer Gating System

Layer 1: Master Gate

if (getKairosActive()) return false      // KAIROS mode uses its own dream skill
if (getIsRemoteMode()) return false      // Remote mode storage unreliable
if (!isAutoMemoryEnabled()) return false
return isAutoDreamEnabled()

Layer 2: Time Gate

• At least 24 hours since last consolidation
• Time info obtained from lock file’s mtime

Layer 3: Session Gate

• At least 5 new sessions modified since last consolidation
• Scanning has 10-minute cooldown

Layer 4: Lock Gate

• Acquire concurrent lock
• If another process is consolidating, current process gives up

PID Lock Mechanism

Lock file .consolidate-lock carries dual semantics:

• mtime = lastConsolidatedAt (last consolidation time)
• File content = holder’s PID

Lock acquisition process:

1. stat + readFile get mtime and PID
2. If mtime within 1 hour and PID alive → occupied
3. If PID dead or mtime expired → reclaim lock
4. Write own PID
5. Re-read to verify (prevent race condition)

Four-Phase Consolidation

Consolidation agent receives structured prompt:

Phase 1 - Orient: browse memory directory, read MEMORY.md, browse topic files

Phase 2 - Gather: search logs and session records for new signals

Phase 3 - Consolidate: merge into existing files, resolve contradictions, relative dates → absolute dates

Phase 4 - Prune & Index: keep MEMORY.md within 200 lines/25KB

Prompt emphasizes “merging over creating,” “fixing over preserving” - prevents memory files from growing infinitely.

High-Frequency Incremental + Low-Frequency Global

Extract Memories and Auto-Dream form complementary architecture:

User conversation
    ↓
Query Loop ends
    ↓
Extract Memories (every turn) ───→ Write topic files / append logs (KAIROS mode)
    ↓
Auto-Dream (periodic) ─────────→ Read logs + topic files, consolidate and write back
    ↓
Next session loads ─────────────→ System prompt injection

Practical: Managing Your Memory

Managing MEMORY.md

Understanding the 200-line limit is key. If index exceeds 200 lines, later entries get truncated.

Best practices:

• Most important entries first
• Each index entry under 150 characters
• Move detailed content to topic files

Understanding What Gets Remembered

Four types each have best use cases:

feedback (most valuable):

• “Don’t use mocks to test database”
• “Prefer early return over nested if”
• Directly changes Agent behavior

user:

• “I’m a backend engineer, not familiar with frontend”
• Helps Agent adjust communication style

project:

• “Goal is to complete refactoring by this Friday”
• Time-sensitive, needs periodic cleanup

reference:

• “Grafana dashboard: https://…”
• External resource shortcuts, keep short

Controlling Automatic Memory

# Disable all automatic memory
export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

settings.json:

{
  "autoMemoryEnabled": false,    // Disable per project
  "autoDreamEnabled": false      // Only disable nightly consolidation, keep instant extraction
}

Manually Triggering Consolidation

Use /dream command to run memory consolidation immediately:

• After completing large refactoring, update project context
• After team member switch, organize personal preferences
• When finding outdated or contradictory information in memory files

CLAUDE.md vs Memory System

The two complement each other:

• CLAUDE.md: stores instructions that shouldn’t be modified (coding standards, architecture constraints, team processes)
• Memory system: stores knowledge that can evolve (user preferences, project context, external references)

If information should not be pruned or modified by Auto-Dream, put it in CLAUDE.md.

Implications for Building AI Agents

Pattern 1: Multi-Layer Memory Architecture

Divide memory system into three layers:

• Raw signal layer (logs/session records): high-frequency, low-quality
• Structured knowledge layer (topic files): medium-frequency, medium-quality
• Index layer (MEMORY.md): low-frequency, high-quality

Pattern 2: Background Extraction via Fork Agent

• Start fork agent at end of query loop
• Inherit parent conversation’s prompt cache to reduce costs
• Strict permission isolation (can only write to memory directory)
• Coordinate with main agent via mutual exclusion check

Pattern 3: File mtime IS State

Use lock file where mtime is lastConsolidatedAt and content is holder’s PID. Implement read, get, rollback via stat/utimes/writeFile.

Pattern 4: Budget-Constrained Memory Injection

Multi-level truncation prevents memory from growing infinitely:

• MEMORY.md max 200 lines/25KB
• Max 200 memory files
• Session Memory max 2000 tokens per segment, 12000 total

Pattern 5: Complementary Frequency Design

Dual-frequency strategy:

• High-frequency incremental extraction: capture all potentially valuable signals, tolerate false positives
• Low-frequency global consolidation: prune noise, resolve contradictions, merge duplicates, fix false positives

Summary

Cross-session memory is the key to Claude Code evolving from “stateless function” to “stateful assistant”:

• Six-layer architecture: from high-frequency incremental to low-frequency global
• Automatic extraction: fork agent silently analyzes every turn
• Session summary: provides important signals for compression system
• Complete recording: JSONL format supports session recovery
• Sub-Agent memory: three-scope model supports specialization
• Nightly consolidation: Auto-Dream organizes memory like sleep

This is like human memory:

• Daytime: constantly receiving new information (Extract Memories)
• Nighttime: consolidating during sleep (Auto-Dream)
• Long-term: forming structured knowledge base (Memdir)

Understanding the memory system lets you:

• Manage project context more efficiently
• Let AI truly “develop long-term memory”
• Implement persistent learning in your own AI Agents

Next up: Harness Engineering Principles - Architecture Wisdom from Claude Code.