Skip to main content

CLAUDE.md & Memory Files

Beginner

If you do one thing to make Claude Code better, do this. CLAUDE.md is a plain-text file Claude reads at the start of every session — your project's permanent briefing.

What you'll learn
  • Why CLAUDE.md is the single highest-leverage Claude Code setting
  • How the memory hierarchy loads, from managed policy down to CLAUDE.local.md
  • How auto memory differs from the CLAUDE.md you write
  • How to generate a starting file with /init and trim it down
  • What belongs in CLAUDE.md — and what to keep out
  • How @imports let you reference docs without duplicating them

Why it's the highest-leverage setting​

Without it, you re-explain your project every session ("we use pnpm, tests are in __tests__, don't touch /generated…"). With it, Claude already knows. Good instructions here improve every future interaction at once.

The memory hierarchy​

Claude Code loads memory from several locations and merges them in load order, broadest scope first — so a project instruction lands in context after a user instruction:

  • Managed policy — org-wide instructions your IT/DevOps team ships. Path is per-OS: /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, C:\Program Files\ClaudeCode\CLAUDE.md on Windows.
  • User instructions (~/.claude/CLAUDE.md) — your personal preferences across every project.
  • Project instructions (./CLAUDE.md or ./.claude/CLAUDE.md, committed) — how this repo works. Shared with your team. If your repo uses AGENTS.md, that can load instead of or alongside these.
  • Local instructions (./CLAUDE.local.md) — project-specific notes just for you, like a sandbox URL. Add it to .gitignore.

Files in the directory hierarchy above your working directory load at launch; files in subdirectories load on demand, when Claude touches something in that area.

Pro tip
  • Outgrown one file? Split instructions into .claude/rules/*.md — one topic per file, discovered recursively. Rules without paths frontmatter load at launch with the same priority as .claude/CLAUDE.md; add paths frontmatter to load a rule only when Claude works on matching files, which saves context.
Know your memory layers
Press Enter or Space to flip the card. Use the left and right arrow keys to move between cards.Term shown.
1 / 6

The other half: auto memory​

CLAUDE.md is the half of memory you write. Claude Code also keeps auto memory — notes Claude writes itself from your corrections and preferences, stored per repository and loaded into every session alongside your CLAUDE.md files.

CLAUDE.md filesAuto memory
Who writes itYouClaude
What it holdsInstructions and rulesLearnings and patterns
ScopeProject, user, or orgPer repository, shared across worktrees

Both are context, not enforcement: Claude treats them as guidance it can weigh, not as configuration it must obey. To hard-block an action regardless of what Claude decides, use a PreToolUse hook instead.

Watch out
  • Auto memory loads only its first 200 lines or 25 KB — a bloated MEMORY.md silently truncates. See Context Budget Audit for the full startup cost breakdown.

Generate a starting point​

Guided walkthrough1 of 3
  1. Claude inspects the code and drafts a CLAUDE.md for you automatically.

Generate a draft CLAUDE.md

/init

Grab a ready-made starter from CLAUDE.md Templates.

What to put in it​

  • What the project is, in two sentences.
  • Tech stack and how to run / test / lint.
  • Conventions Claude can't infer (naming, structure, commit style).
  • Guardrails: "run tests before declaring done", "never edit /vendor", "never commit secrets".

What NOT to put in it​

Watch out
  • Claude follows CLAUDE.md literally — stale, vague, or wishful instructions actively hurt.
  • Describe how the project actually works today; short and true beats long and aspirational.
  • Avoid giant pasted docs (use @imports instead), secrets, and rules you don't actually follow.
  • Review it periodically so it stays accurate as the project evolves.

Imports​

Pull in existing docs instead of duplicating them — e.g. reference your style guide with an @path/to/file import so there's one source of truth. Relative and absolute paths both work; relative paths resolve against the file containing the import, not your working directory. Imported files can import others, to a maximum depth of four hops.

Two syntax traps worth knowing before they bite:

  • Spaces need backslashes. @Design\ Docs/api-conventions.md works; without the backslash the path stops at the first space. Wrapping it in quotes doesn't import the file at all.
  • Backticks opt out. Import parsing skips code spans and fenced blocks, so `@README` stays literal text while @README on its own imports the file. That's how you mention a path without loading it.

See the official memory docs for the full reference.

Pro tip
  • One source of truth: reference a file with @imports rather than pasting its contents into CLAUDE.md.
  • If a doc already exists, link it — don't copy it. Copies drift out of date.

Check yourself​

Check yourself

0/6
  1. Which file does Claude Code read at the start of every session as your project's permanent briefing?
  2. What does running /init do in a project?
  3. What is the recommended way to include a large existing doc like a style guide?
  4. Where do personal, project-specific notes go — the ones you don't want committed?
  5. Who writes auto memory?
  6. A CLAUDE.md in a subdirectory loads when?
Key takeaways
  • CLAUDE.md is the highest-leverage setting: it improves every future session at once.
  • Memory loads broadest-first: managed policy, then user (~/.claude/CLAUDE.md), project (./CLAUDE.md or ./.claude/CLAUDE.md), then local (./CLAUDE.local.md). Subdirectory files load on demand.
  • Auto memory is the other half — Claude's own notes, per repository, loaded every session. Both are context, not enforcement: use a hook to hard-block something.
  • Outgrown one file? Split it into .claude/rules/*.md and scope rules with paths frontmatter.
  • Start with /init, then edit the draft down to what is actually true.
  • Keep it short and true — use @imports (max four hops) for big docs, and never commit secrets.

Next​