Claude Code Persistent Memory: Setup Guide [2026]

Why Claude Code Memory Matters

You open Claude Code. You explain your project. You describe your stack, your naming conventions, your current progress. An hour later, you've made real progress.

Then you close the session. Next day, everything is gone. Same explanations, same conventions, same context restoration. Claude Code persistent memory eliminates this. Five to ten minutes lost every session - unless you set it up right.

Claude Code now has built-in memory that partially solves this. But "partially" matters. The native system handles project instructions and basic learnings. It does not handle project state, progress tracking, session handoffs, or semantic recall across domains.

This guide walks through all four layers of Claude Code persistent memory - from the native features you should use today to the advanced systems that make Claude Code genuinely learn over time.

Layer 1: CLAUDE.md - Your Project Instructions

CLAUDE.md is Claude Code's native instruction system. It loads automatically at the start of every conversation and tells Claude how to work in your project.

How CLAUDE.md Scoping Works

Claude Code reads CLAUDE.md files from multiple scopes, all concatenated into context:

More specific scopes take precedence. Claude also walks up the directory tree, loading CLAUDE.md files from parent directories. Subdirectory CLAUDE.md files load on demand when Claude reads files in those directories.

What Goes in CLAUDE.md

CLAUDE.md is for stable instructions - things that don't change between sessions:

• Coding standards and naming conventions
• Architecture decisions ("use server components by default")
• Banned patterns ("never use em-dashes", "no any types")
• Build and test commands
• Project-specific terminology

What does NOT belong in CLAUDE.md: progress tracking, current tasks, session state. Those change constantly and belong in a different layer.

For real-world examples of how to structure CLAUDE.md across different project types, see 5 CLAUDE.md templates you can copy. For modularizing large instruction sets with rules files, see CLAUDE.md rules.

Rules Files: Modular Instructions

When CLAUDE.md gets too large, split instructions into .claude/rules/*.md files. Each rules file loads automatically based on file naming. This keeps your root CLAUDE.md focused on essentials while domain-specific instructions live in dedicated files.

.claude/
├── rules/
│   ├── delegation.md      # Agent routing rules
│   ├── seo.md             # Content standards
│   └── testing.md         # Test conventions

Layer 2: Auto Memory - Claude Learns As You Work

Claude Code's auto memory is a newer feature that saves learnings automatically without you writing anything.

What Auto Memory Captures

When Claude discovers something useful during a session - your preferred build command, a debugging pattern that worked, a project convention - it saves it to ~/.claude/projects/<project>/memory/MEMORY.md. Next session, these learnings load automatically.

Auto memory captures:

• Build commands and test patterns it discovers
• User preferences it observes ("you prefer X over Y")
• Technical details about your project setup

Limitations of Auto Memory

Auto memory is useful but passive. It captures observations, not structured knowledge. It cannot:

• Track project progress or milestones
• Create session handoffs for continuity
• Store decisions with reasoning and context
• Recall knowledge semantically across projects
• Organize knowledge by domain or topic

For these capabilities, you need Layers 3 and 4.

Layer 3: Structured Project Memory

This is where you go beyond the native features. A structured memory folder gives Claude Code explicit awareness of project state, progress, and next steps.

The Memory Folder Structure

_memory/
├── index.json        # Active project pointer + focus string
├── projects/         # Per-project state files
│   └── my-project.json  # Goals, progress, blockers, next steps
├── sessions/         # Session archive for continuity
└── experiences/      # Logged failures and learnings

How It Works in Practice

The system has two rituals:

Session Start (10 seconds):

1. Claude reads _memory/index.json to find the active project
2. Reads the project file for goals, recent progress, and blockers
3. Announces status: "Project X | Phase: Content | Last: Blog drafted | Next: SEO audit"
4. Picks one task. Atomic progress.

Session End (30 seconds):

1. Log what you accomplished
2. Update next steps
3. Log failures and lessons learned

Why This Layer Matters

CLAUDE.md tells Claude how to work. Structured memory tells Claude what to work on and where you left off. Without it, you spend the first 5-10 minutes of every session re-establishing context that should be automatic.

The Evolving Lite plugin implements this complete system - memory folder, session rituals, handoff automation, and 10 hooks that handle the bookkeeping automatically. Free and open source, installs in 30 seconds.

Layer 4: Semantic Memory with Kairn

The layers above store structured data - JSON files, markdown instructions, progress logs. But they can't answer questions like "what did I learn about rate limiting last month?" or "what workarounds exist for the hook schema bug?"

Kairn adds semantic memory as an MCP server. It stores decisions, patterns, solutions, gotchas, and workarounds as searchable knowledge nodes with tags, confidence levels, and cross-references.

What Kairn Stores

How Kairn Differs from Auto Memory

Auto memory observes passively. Kairn stores knowledge explicitly with context, reasoning, and cross-project relevance. A decision stored in Kairn includes why you chose that approach, not just what you chose.

Kairn knowledge also works across projects. A gotcha discovered in Project A surfaces when you encounter the same tool in Project B. Auto memory is project-scoped. Kairn is knowledge-scoped.

How the Layers Stack

Each layer solves a different problem. They're not alternatives - they stack.

Start with Layers 1 and 2 - they're built in and free. Add Layer 3 when you want session continuity and progress tracking. Add Layer 4 when you want cross-project knowledge that compounds over months.

Session Handoffs: Continuity Across Context Limits

Sessions hit context limits. When that happens, you need to close and start fresh. Without handoffs, you lose everything in the current session's working memory.

A session handoff captures three things:

1. What was accomplished this session
2. What was learned (any surprises, failures, or discoveries)
3. What comes next (specific, actionable items)

Next session, say "continue" and Claude loads the most recent handoff. Full context in under 10 seconds.

Handoff vs Compaction

Claude Code's built-in compaction summarizes conversation history to free up context space. This preserves the cached prefix and keeps you in the same session.

Handoffs are different - they're for ending a session and starting a new one with continuity. Compaction keeps a session alive. Handoffs bridge between sessions.

Use compaction when the session is still productive but context is filling up. Use handoffs when you're done for the day or switching focus.

Practical Setup: Persistent Memory in 15 Minutes

Step 1: CLAUDE.md (2 minutes)

Create a CLAUDE.md in your project root with the essentials:

# My Project

## Stack
- Next.js 15, TypeScript, Tailwind

## Rules
- Always use server components by default
- Test with vitest, not jest
- Run `npm run build` before committing

Step 2: Let Auto Memory Work (0 minutes)

Auto memory is on by default. Just use Claude Code normally. It learns as you go.

Step 3: Add Structured Memory (5 minutes)

Install Evolving Lite:

git clone https://github.com/primeline-ai/evolving-lite.git .claude/plugins/evolving-lite

This gives you the _memory/ folder, session rituals, and 10 hooks out of the box.

Step 4: Add Kairn (8 minutes, optional)

Install Kairn as an MCP server:

# Add to your .mcp.json
{
  "kairn": {
    "command": "uvx",
    "args": ["kairn"]
  }
}

Now Claude Code can kn_learn to save knowledge and kn_recall to retrieve it across sessions and projects.

What I Learned Running This Daily

1. Update memory at session end, not during. Don't context-switch mid-session to log progress. Work first, log last. It takes 30 seconds.

2. Keep focus strings short and actionable. Bad: "Working on various features and bug fixes." Good: "Ship email capture form with Turnstile CAPTCHA by EOD."

3. Log failures, not just successes. Your failures log is pure gold. Every time something breaks, log what happened, why, and what you learned. Over time, this becomes institutional knowledge that prevents repeat mistakes.

4. Layer 1 + 2 cover 80% of needs. Most developers only need CLAUDE.md and auto memory. Don't add complexity until you feel the pain of missing state or missing knowledge. If your sessions are short and project-scoped, Layers 1-2 are sufficient.

5. Kairn pays off after 50+ sessions. The cross-project knowledge graph becomes genuinely valuable after you've accumulated enough nodes. Before that, it's overhead. After that, it's the most useful part of the system.

Common Mistakes

Putting everything in CLAUDE.md. Your CLAUDE.md should be stable instructions, not a progress log. If it changes every session, the wrong things are in it.

Ignoring auto memory. Check ~/.claude/projects/<project>/memory/MEMORY.md occasionally. Auto memory sometimes captures useful things you didn't know it noticed.

Overcomplicating Layer 3. The memory folder structure should be simple. One index, one project file, session logs. If you're spending more than 30 seconds on session-end bookkeeping, simplify.

Skipping session handoffs. "I'll remember where I was" is always wrong. Write the handoff. Your future self will thank you.