Cross-Session Memory in Claude Code — Three Patterns for Persistent AI Workflows

Every Claude Code session starts from zero. Context window resets. Working memory gone. The only things that survive are files on disk and instructions in CLAUDE.md.

This is the fundamental constraint. The three patterns below are strategies for working with it, not against it.

Pattern 1: Auto-Memory Directory

Claude Code provides a built-in persistent memory directory at:

~/.claude/projects/<project-path-hash>/memory/

Files in this directory persist across sessions and are available to Claude automatically. The key file is MEMORY.md — its contents are loaded into the system prompt at session start.

How to structure MEMORY.md

Keep it under 200 lines. Lines beyond 200 get truncated. This is a hard constraint, not a suggestion.

# Project Memory

## Architecture
- Engine: Elixir backend at /backend — do NOT modify unless critical
- Frontend: Astro at /frontend — main development area
- API base: localhost:4000/api, responses wrapped in {data: ...}

## Key Constraints
- Local LLM processes ONE request at a time — never parallelize
- Database pool = 10 connections max

## Patterns That Work
- Sequential doseq + wait pattern for LLM workflows
- EDN workflows must be pre-processed (parser rejects comments)

## Patterns That Failed
- Parallel LLM submission — causes queue timeout
- Direct staging without score threshold — floods with noise

The most valuable entries in MEMORY.md are mistakes you’ve already made. Recording “this doesn’t work because X” prevents every future session from repeating the same error.

Topic files

For detailed reference that doesn’t fit in 200 lines, create separate files in the memory directory:

memory/
  MEMORY.md              — index, under 200 lines
  api-reference.md       — detailed API docs
  debugging-notes.md     — past debugging sessions
  architecture.md        — system design decisions

MEMORY.md links to these. Claude reads them on demand when relevant.

When to update

Add to auto-memory when you discover:

• An API response format that’s non-obvious
• A constraint that caused a failure (e.g., “field is canonical_name not name”)
• A tool/library behavior specific to your environment
• A pattern that consistently works or consistently fails

Do not add: temporary state, session-specific decisions, things that change weekly.

Pattern 2: Supervisor State

Auto-memory stores facts. Supervisor state stores cognitive context — what you’re working on, what was decided, what’s next.

project/
  supervisor_state/
    CURRENT_STATE.md     — what happened, what remains
    STRATEGIC_VECTORS.md — long-term goals (rarely changes)
    OPEN_QUESTIONS.md    — unresolved decisions
    RESOURCES.md         — available tools, APIs, constraints

The critical file is CURRENT_STATE.md. Every session reads it first and updates it last.

CURRENT_STATE.md structure

# Current State — 2026-02-05 (Session N)

## Session Summary
Session 1: Built X.
Session 2: Added Y, discovered Z constraint.
Session N: [current session fills this in at end]

## What Was Done
- Implemented feature A
- Discovered that B doesn't work because C

## What Remains
1. Task D — blocked by E
2. Task F — ready to start
3. Task G — needs human decision

## Next Session Entry Point
1. Read this file
2. Check status of E
3. Start with F if E is resolved

Why this works

The session summary is a compressed history. Each line encodes an entire session’s learning. After 10 sessions, you have 10 lines that carry more useful context than any single session’s full transcript.

“Next Session Entry Point” is the handoff protocol. It tells the next session (which has zero memory) exactly where to pick up. Without this, every session wastes 10-15 minutes re-orienting.

Workflow trigger integration

In CLAUDE.md, add:

- After completing any concrete feature, update
  supervisor_state/CURRENT_STATE.md with what was done,
  state changes, and remaining tasks.

This makes state updates automatic. Claude writes the handoff before the session ends.

Pattern 3: External Memory via MCP

Auto-memory and supervisor state are file-based. They work for a single project. For cross-project knowledge accumulation, connect an external database via MCP (Model Context Protocol).

Architecture

Claude Code ←→ MCP Server ←→ Database (PostgreSQL + pgvector)

The MCP server exposes tools like:

• search_knowledge(query) — semantic search over accumulated knowledge
• list_entities() — browse knowledge by topic
• get_sample(id) — retrieve specific entry

Claude calls these tools mid-session to check: “Do I already know something relevant before I start researching?”

The query-before-act pattern

Session starts
  → Read supervisor_state (what are we doing?)
  → Query external memory (what do we already know about this?)
  → Only then: research, build, or analyze

This prevents duplicate work. Without the query step, Claude will re-derive insights that previous sessions already discovered and stored.

Staging pattern for quality control

Never write directly to the knowledge base. Use a staging layer:

Claude extracts insight → POST to /staging → Human reviews → Approved → Knowledge base

The human review step is not overhead — it’s the quality gate that keeps the knowledge base dense. Without it, the database fills with LLM-repackaged common knowledge scored as “novel.”

Choosing the Right Pattern

Start with auto-memory. Add supervisor state when your project has multi-session workflows. Add MCP when you need knowledge that spans projects or requires semantic retrieval.

The Awakening Protocol

When all three patterns are combined, a session bootstrap looks like:

1. CLAUDE.md loads (constraints, scope, tools)
2. MEMORY.md loads (project facts, past mistakes)
3. Read supervisor_state/CURRENT_STATE.md (what's happening)
4. Query MCP knowledge base (what do I already know)
5. Decide highest-value action
6. Execute
7. Update CURRENT_STATE.md before session ends

This is a repeatable cognitive boot sequence. Every session starts calibrated and exits with a clean handoff. No context is lost. Each session stands on the accumulated learning of all previous sessions.

The compounding effect is real: session 1 is slow and exploratory. Session 10 is fast and surgical, because it inherits the compressed wisdom of sessions 1-9 through MEMORY.md and CURRENT_STATE.md.