Claude Code Memory: How CLAUDE.md Works (2026)

Why does Claude forget the convention you spelled out yesterday? Because nothing wrote it down where the agent looks. Claude Code memory is the fix: a Markdown file named CLAUDE.md that Claude Code reads automatically before it ever sees your prompt. Tell it once that you use pnpm, run tests with npm test, and never push straight to main, and it carries that into every session instead of guessing.

Most teams discover memory the hard way, correcting the same mistake three days running before someone asks "can't we just tell it once?" You can. The mechanism is simpler than the docs make it sound, and the hard part is discipline about what you write down. This guide covers what the file is, the three-level hierarchy, what belongs inside it (and what wrecks it), the two characters that save the most typing, and the habit that keeps a CLAUDE.md from rotting into noise.

What CLAUDE.md Is

CLAUDE.md is a plain Markdown file that Claude Code reads as standing instructions at the start of every session, before your first message. It holds the things you'd otherwise repeat: your build commands, code style, directory layout, and rules like "use tabs, not spaces." The agent treats it as context it already knows, so you stop re-explaining your project on every task.

Mei, a backend engineer on a four-person team, kept watching Claude Code reach for npm when the repo runs on pnpm. She added three lines to a CLAUDE.md at the repo root: the package manager, the test command, and "migrations live in db/migrations, never edit by hand." The next morning the whole team's sessions inherited those rules from git, and the correction she'd typed a dozen times stopped being necessary.

That is the entire value: write a rule once, never retype it. The file is human-readable Markdown, so you can open it, edit it, and review it in a pull request like any other code. If you've already set up custom slash commands or subagents, memory is the layer underneath them, the shared facts every part of your setup leans on. Browse the skill registry and you'll notice most skills assume a clean CLAUDE.md to build on.

The Memory Hierarchy: Enterprise, Project, User

Claude Code memory comes in three levels, and they stack. Enterprise is the system-level file an admin deploys to a whole machine; project is ./CLAUDE.md at your repo root, committed to git and shared with the team; user is ~/.claude/CLAUDE.md, which applies to every project you open. Claude Code loads all three top-down and combines them into one block of context, so a session sees enterprise, then project, then your personal rules all at once.

The split exists so each rule lives at the right blast radius. "We require signed commits" is enterprise. "This repo uses Vitest, not Jest" is a project rule, and it belongs in git so a new hire gets it on day one. "I like terse explanations and no emojis" is a user rule, true for you in every repo, irrelevant to your teammates. Because the files combine rather than overwrite, you don't pick one level, you put each instruction where its scope actually is.

What Actually Belongs in CLAUDE.md (and What Doesn't)

The best CLAUDE.md holds stable facts the agent would otherwise guess wrong, and nothing else. Good candidates: the exact build and test commands, the package manager, code style rules, the directory map, and hard constraints like "never commit to main" or "all API routes need a test." These are short, durable, and save a correction every single session.

What does not belong matters just as much. Leave out anything that changes per task, secrets and API keys (the file is committed to git), and long prose, the agent doesn't need a paragraph on why you chose a library, only the rule that follows from it. A useful test: if a sentence wouldn't still be true next month, it belongs in a prompt, not in memory.

A practical starter for a project file looks like this:

# Project: payments-api

## Commands
- Install: `pnpm install`
- Test: `pnpm test`
- Lint: `pnpm lint --fix`

## Conventions
- TypeScript strict mode; no `any`.
- Migrations live in `db/migrations`; never edit applied ones.
- Never commit directly to `main`; open a PR.

Notice what's missing: no prose, no history, no "please." Bullet points the agent can act on, the kind of thing a new teammate reads in thirty seconds. If you're standing up a fresh repo, run /init and Claude Code scans the project and drafts a CLAUDE.md for you to trim, faster than writing one from scratch. For wiring the agent into a new project, the skills setup guide pairs well with this.

Importing Other Files with @path

To pull another file's contents into memory, write @path/to/file on its own line. Claude Code inlines that file where the import sits, so a rule can live in one canonical place and be referenced from CLAUDE.md instead of copy-pasted. This keeps a single source of truth: edit the real doc, and every file that imports it updates too.

# Project memory

See @docs/style-guide.md for formatting rules.
See @docs/architecture.md for the module layout.

## Personal overrides
@~/.claude/my-defaults.md

Imports take relative paths (@docs/style-guide.md), home-directory paths (@~/.claude/my-defaults.md), and can nest a few levels deep. The win shows up on teams: instead of every developer's personal file repeating the org style guide, each one imports the shared copy, and a single edit propagates to everyone. One fintech team cut their per-developer memory file from 80 lines to 12 this way, with one @docs/conventions.md doing the heavy lifting.

One caution: an import inlines the entire target file into context every session. Importing a 600-line design doc means paying for 600 lines on every prompt whether the task touches it or not. Import lean files, or split a big doc and import only the section you need.

The # Quick-Add Shortcut

To add a memory mid-session without opening a file, start a prompt with # and type the rule. Claude Code captures the line and offers to save it to your project or user CLAUDE.md, so a correction you make once becomes permanent in two seconds. It's the fastest path from "ugh, it did that again" to "it won't next time."

The moment that earns it: you're mid-task, the agent uses American date formatting when your app is European, and you fix it inline. Instead of letting the lesson evaporate when the session ends, you type # Always use DD/MM/YYYY dates and pick "project." The rule lands in ./CLAUDE.md, and the next session, plus your teammates' sessions, never make the mistake. To edit those files directly later, run /memory, which opens them for a proper cleanup pass.

Treat # as capture and /memory as curation. Quick-add in the heat of work, then once a week open /memory and prune what you've piled up, because the easy part is adding rules and the discipline is removing them.

Keeping Memory From Rotting

A CLAUDE.md you never prune becomes noise the agent learns to ignore. Memory has a real cost: every line loads into the context window on every single prompt, so a bloated file is both an expense and a distraction that buries your important rules under stale ones. The discipline isn't writing memory, it's editing it.

Four habits keep a file healthy. Delete on sight: when a rule stops being true (you switched from Jest to Vitest), remove the old line in the same edit. Keep it scannable: if you can't read the whole file in under a minute, it's too long. Prefer specific over vague: "run pnpm test:unit before every commit" beats "test your code," because the agent acts on the first and only nods at the second. And review it in pull requests, since project memory is in git, a teammate can catch a dead rule the way they'd catch a bug.

Here's the failure mode. Over six months a project file grows to 200 lines, half of them contradicting each other, and the agent behaves as if the file weren't there, because functionally it isn't. The fix is the maintenance pass you'd give any config: open /memory, cut anything stale, duplicated, or vague, and you usually delete a third of it without losing a rule that mattered. A short CLAUDE.md the agent follows beats a long one it's learned to skim. When your memory and your hooks are both lean, the agent does the right thing by default, which is the whole point.

Browse next: Claude Code Commands (2026) | Claude Code Subagents (2026) | Claude Code Hooks (2026) | How to Add Skills to Claude Code (2026)

Back to Blog