Claude Code Memory: CLAUDE.md and Persistent Context

Claude Code has three layers of memory, and the difference between people who get a lot out of the tool and people who get a little is mostly about understanding which layer to use for which kind of fact.

Layer 1: Conversation Context

Within a single session, Claude remembers everything you have said and every tool result it has seen. This is the smallest and most expensive layer — every token is paid for, every turn. When you start a new session, this resets.

Two slash commands control it:

• /clear — Wipe and start fresh. Use between unrelated tasks.
• /compact — Summarize the conversation so far into a shorter form so the session can keep going.

Conversation context is for the current task. Anything you want to outlive this session belongs in one of the next two layers.

Layer 2: CLAUDE.md

CLAUDE.md is a Markdown file Claude Code automatically loads at the start of every session in a directory. It is the durable, project-wide context. There are several scopes, in order of specificity:

• ./CLAUDE.md — Project root. Checked into git. Shared with everyone on the team.
• ./CLAUDE.local.md — Project root. Gitignored. Personal notes about this project.
• Subdirectory CLAUDE.md — Loaded when Claude works in that subtree. Useful for monorepos.
• ~/.claude/CLAUDE.md — User-global. Loaded in every project.

Bootstrap one with /init — Claude scans the codebase and proposes a draft. Edit it down. The temptation is to write a novel; the discipline is to keep it skimmable. Build commands, architecture overview, conventions, gotchas. If a fact appears in the code or git log, it does not need to be in CLAUDE.md.

A useful structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# Project Name

## Commands
- Dev: `npm run dev`
- Test: `npm test`
- Build: `npm run build`

## Architecture
One paragraph. Where things live, what is unusual.

## Conventions
- Bullet point each rule.
- One sentence each.

## Gotchas
- Known traps a new contributor would hit.

The # shortcut at the start of a prompt adds a line to CLAUDE.md directly — Claude asks which scope and writes the entry for you.

Layer 3: Auto-Memory

The newest layer is auto-memory — a structured store under ~/.claude/projects/<project>/memory/ where Claude saves things on its own when the user reveals durable facts. There are four types:

• user — Who you are, your role, your preferences, what you know.
• feedback — Corrections and validations. “Don’t mock the database in tests” lives here, with the why attached so future sessions can judge edge cases.
• project — Ongoing work, deadlines, incidents, decisions. State that decays.
• reference — Pointers to external systems. “Bugs are tracked in Linear project INGEST.”

Each memory is a small Markdown file with frontmatter, indexed in MEMORY.md. The system prompt tells Claude when to save (user reveals a non-obvious fact) and when not to (the fact is in the code, the git log, or CLAUDE.md).

You manage it through:

• /memory — Edit the store directly.
• /remember <fact> — Append a single durable note.
• Natural language: “remember that I prefer tabs over spaces” — Claude will write the right entry.

What Goes Where

The decision tree is short:

• Live for one task? Conversation. No action needed.
• Project-specific, useful to the team, stable? CLAUDE.md.
• Project-specific, personal, stable? CLAUDE.local.md.
• About you, across all projects? ~/.claude/CLAUDE.md or auto-memory user type.
• A correction or a working principle? Auto-memory feedback.
• Where to find external info? Auto-memory reference.

The mistake to avoid: dumping everything into CLAUDE.md. It loads every session. Bloat costs tokens and dilutes signal. If a fact only matters to you, keep it personal. If it only matters this week, keep it in auto-memory project so it can decay gracefully.

Hygiene

• Review CLAUDE.md quarterly. Conventions change. Stale rules cause drift.
• Trust auto-memory, but verify. A memory naming a specific function is a claim about the past. Before acting on it, check the function still exists.
• Treat CLAUDE.md as code. Review changes in PRs. Lint it for length. Refactor it like you would a config file.

The agent that knows your project — your conventions, your gotchas, your taste — is a different tool than the one that does not. The memory layers are how you get there. Spend an hour writing a good CLAUDE.md today and every session for the next year is better for it.