Build Lasting Project Memory with CLAUDE.md

Every Claude Code session starts with a fresh context window — the agent doesn't remember your last conversation. A CLAUDE.md file is how you carry knowledge across sessions: it's a plain Markdown file of persistent instructions that Claude reads at the start of every session.

Think of it as the project's onboarding doc, written for the agent. The build command, where things live, the conventions your team follows — anything you'd otherwise have to re-explain every time goes here once.

You don't have to write CLAUDE.md from scratch. Inside a Claude Code session, run:

/init

Claude analyzes your codebase and generates a starter CLAUDE.md with the build commands, test instructions, and conventions it can discover on its own. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it.

Treat the generated file as a first draft. Refine it with the things Claude couldn't infer — architectural decisions, "always do X" rules, and the context a new teammate would need.

CLAUDE.md can live in a few places, each with a different scope. Claude walks up the directory tree from where you launched it and loads every file it finds, broadest scope first:

• Project memory — ./CLAUDE.md or ./.claude/CLAUDE.md. Team-shared, committed to source control. This is the one you'll use most.
• User memory — ~/.claude/CLAUDE.md. Your personal preferences across all projects (just you).
• Local memory — ./CLAUDE.local.md. Personal, project-specific notes; add it to .gitignore so it isn't committed.
• Managed policy — an org-wide file deployed by IT (for example, /Library/Application Support/ClaudeCode/CLAUDE.md on macOS).

Files closer to your working directory are read last, so a project instruction layers on top of a user one.

The goal is facts and conventions Claude should hold in every session — not step-by-step procedures. Good entries are concrete and verifiable:

• Build and test commands: "Run npm test before committing."
• Conventions: "Use 2-space indentation."
• Project layout: "API handlers live in src/api/handlers/."
• "Always do X" rules specific to this repo.

What to leave out:

• Multi-step procedures or task-specific workflows → make a skill instead, so it loads only when relevant.
• Instructions that only matter for one part of the codebase → use a path-scoped rule in .claude/rules/.
• Vague guidance like "format code nicely" or "test your changes" — too fuzzy to follow reliably.

Keep each CLAUDE.md under ~200 lines: it's loaded in full on every session, so a bloated file burns context and actually reduces how well Claude follows it. Use Markdown headers and bullets so the agent can scan it the way you do.

As you work, you'll spot things to add — a mistake Claude repeated, a correction you keep retyping. To see and edit your memory files, run:

/memory

/memory lists every CLAUDE.md, CLAUDE.local.md, and rules file loaded in the current session and lets you open any of them in your editor. (It's also the fastest way to confirm a file is actually being loaded — if it's not in the list, Claude can't see it.) You can also just ask Claude "add this to CLAUDE.md," and it will edit the file for you.