Claude Code Persistent Memory: Setup Guide

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.

Next day, how much of that comes back? More than it used to. Claude Code ships built-in memory in two forms: CLAUDE.md for the instructions you write, and auto memory - on by default - for notes Claude writes itself based on your corrections and preferences.

What comes back is bounded, though, and the bounds are documented. Claude "doesn't save something every session. It decides what's worth remembering." Only the first 200 lines or 25KB of its index load at the start of a conversation, and anything past that is not loaded at session start. The store is machine-local and tied to one repository. And nothing in it is built to hold where you left off - there is no progress field, no handoff, no next-step slot. Whether a note like that gets written at all is Claude's call, not yours.

That gap is what still costs five to ten minutes at the start of a session. This guide walks through all four layers of Claude Code persistent memory - the two native ones you already have, and the two you build when the native pair runs out.

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:

These do not override each other. Per the docs, "all discovered files are concatenated into context", ordered from the filesystem root down to your working directory, so the file closest to where you launched Claude is read last. Order is not precedence: "if two rules contradict each other, Claude may pick one arbitrarily." Subdirectory CLAUDE.md files are the exception to the load-at-launch rule - they 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. A rules file loads at launch, at the same priority as .claude/CLAUDE.md, simply because it sits in that directory - the filename is for you, not for Claude. To make one conditional, give it YAML paths: frontmatter, and it then loads only when Claude reads a file matching the pattern. 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 saves learnings without you writing anything. It is on by default - nothing to install, nothing to switch on.

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 writes it to ~/.claude/projects/<project>/memory/. That directory is derived from the git repository, so every worktree of the same repo shares one store.

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

Inside that directory, MEMORY.md is an index and the detail lives in topic files beside it. The split matters, because only part of it is in context when a session starts.

What Actually Loads

Three documented limits shape everything you can expect from this layer:

• Claude decides what is worth keeping. Per the docs, Claude "doesn't save something every session. It decides what's worth remembering." Something you wanted kept may simply never be written.
• The index is capped. The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, load at the start of every conversation. Content past that threshold is not loaded at session start. Claude can still open the file mid-session with its normal file tools - it just does not begin the session holding it.
• Topic files load on demand, not at startup. Claude reads them when it judges them relevant, which is not the same as starting the session knowing them.

Three more properties matter before you lean on this layer:

• It is machine-local. The store does not follow you to a second machine or into a cloud environment. The directory is derived from the git repo, or from the project root if you are not in one, and autoMemoryDirectory in settings.json moves it if you want it somewhere else.
• Subagents do not inherit it. The main conversation's auto memory is not loaded into subagents - a fork is the only exception. A subagent's own memory, enabled with its memory field, is a separate directory. If you run multi-agent work, this is the limit that bites first.
• It is context, not enforced configuration. To make something happen regardless of what Claude decides, the documented answer is a PreToolUse hook, not a memory file. That is true of CLAUDE.md as well, so it is not a knock on auto memory specifically - it is what this whole layer is.

And it can be switched off: the /memory command has a toggle, autoMemoryEnabled: false disables it per project, and CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 does it by environment variable. If your memory directory is empty, check that before you conclude nothing is being saved.

What Auto Memory Is Not For

Everything above is auto memory working as designed. What it is not is a place to keep project state. There is no progress field, no blocker list, no handoff artifact, and no query interface - and since Claude decides what is worth writing, you cannot rely on a where-we-left-off note being there when you need it. It also cannot reach across projects, because the store is per repository.

For state you want to depend on rather than hope for, 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 scoped to one repository on one machine, and it is not loaded into subagents. Kairn is knowledge-scoped, and the store is an ordinary file you can move or back up.

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.

If you would rather not build the handoff machinery yourself, the session memory plugin is this section as an installable package - it adds /project-status and the handoff commands in one clone.

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. Worth doing once: run /memory after a week, open the auto memory folder, and check MEMORY.md against both limits - 200 lines and 25KB, whichever it hits first. Frontmatter and block-level HTML comments are stripped before the measurement, so they do not count.

Step 3: Add Structured Memory (5 minutes)

Install Evolving Lite:

git clone https://github.com/primeline-ai/evolving-lite.git ~/.claude/skills/evolving-lite
bash ~/.claude/skills/evolving-lite/setup.sh

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 by adding this 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 - and it is also where you find out that the index has grown past the point where all of it loads.

Assuming a memory file will be obeyed. Memory is context, not enforced configuration. If a rule genuinely must hold every time, put it behind a PreToolUse hook and let the memory file be documentation.

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.