Lesson 2.215 min · 5 cards · 8 exercises · 1 mission

Layered memory and /init

The four CLAUDE.md levels, the order Claude loads them, @ imports, the memory Claude writes itself, and starting with /init.

todo-api now has a CLAUDE.md with the test commands and the soft-delete gotcha. Then a few small things come up. You want Claude to answer in Vietnamese, in every project, not just this repo. You have a personal sandbox URL your teammates don't need to see. And the company has just issued a rule about handling customer data. Cramming all of that into the project's CLAUDE.md puts it in the wrong place. This lesson covers Claude Code's memory levels and how to choose the right one for each thing.

The four CLAUDE.md levels

Claude Code reads CLAUDE.md at four levels, from broadest to narrowest:

  • Managed policy: for the whole organisation, placed on the machine by IT or DevOps. On macOS it lives at /Library/Application Support/ClaudeCode/CLAUDE.md; on Linux and WSL at /etc/claude-code/CLAUDE.md; on Windows at C:\Program Files\ClaudeCode\CLAUDE.md. It suits company coding standards, security policies and compliance requirements.
  • User: ~/.claude/CLAUDE.md, your own preferences across every project, such as the language you want answers in or the tools you reach for.
  • Project: ./CLAUDE.md or ./.claude/CLAUDE.md, the project's instructions, shared with the team through git. This is the file you wrote in lesson 2.1.
  • Local: ./CLAUDE.local.md, your own preferences for this project. Add it to .gitignore so it never gets committed. It suits a personal sandbox URL or the test data you like to use.

For the three cases above: answering in Vietnamese belongs at user level, the sandbox URL at local level, the data rule at managed level.

The order Claude loads them

At startup, Claude Code loads CLAUDE.md and CLAUDE.local.md from the working folder and every folder above it. Start Claude in foo/bar/ and it reads both foo/bar/CLAUDE.md and foo/CLAUDE.md.

The key point: the files are joined together, not overridden. The order runs from the filesystem root down to the working folder, so the file closest to where you started Claude is read last. Within one folder, CLAUDE.local.md comes after CLAUDE.md. Since nothing overrides anything, if two levels contradict each other Claude may follow either one. The fix is to keep the levels consistent, not to rely on the order.

A CLAUDE.md in a subfolder works differently: it isn't loaded at startup but when Claude reads, writes or edits a file in that subfolder. That lets a monorepo keep guidance for each part without weighing down every session.

Importing with @

A CLAUDE.md can pull in other files with @path/to/file:

See @README for an overview and @package.json for the npm scripts.

# Git
- Workflow: @docs/git-instructions.md

A few rules worth remembering:

  • Relative paths are resolved from the file that contains the import, not from the working folder.
  • Imported files can import further files, up to four hops deep.
  • Inside backticks, as in `@README`, it's just text and nothing is imported.
  • Imports help you split a file up, but they don't reduce context use: imported files load along with the file that imports them.

One safety point: if a project's CLAUDE.md imports a file outside the working folder, the first time Claude Code shows a dialog listing those files for you to approve. Decline and those imports stay off. The dialog protects you from files other people commit to a shared project.

Auto memory: what Claude writes itself

Alongside the CLAUDE.md you write, Claude Code has auto memory: notes Claude writes for itself as it works. It keeps four kinds: about you (user), corrections you make or approaches you confirm (feedback), ongoing work and decisions the code doesn't show (project), and where to find outside information such as an issue tracker (reference). Claude skips what it can derive from the code and what your CLAUDE.md already says.

Auto memory is on by default in sessions on your machine. It lives in ~/.claude/projects/<project>/memory/, is shared by every worktree of the same repository, and stays on this machine only; it doesn't sync to other machines. The folder holds a MEMORY.md index with one line per note. Each session loads the first 200 lines or the first 25KB of that index, whichever comes first; the detailed files are read only when needed.

Two ways of asking, two different results:

  • "remember that the API tests need a local Redis": Claude saves it to auto memory on your machine.
  • "add this to CLAUDE.md": Claude writes it into CLAUDE.md, which the team sees once you commit it.

To turn auto memory off, use the toggle in /memory, set autoMemoryEnabled: false in the project's settings, or set the environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

/init and /memory

/init reads the codebase and writes a starting CLAUDE.md with the build commands, how to run tests and the conventions it finds. If the project already has a CLAUDE.md, /init suggests improvements instead of overwriting it. What /init produces is a starting point, not a finished file: your job afterwards is mostly to delete what Claude could read for itself and add what it can't know, as in lesson 2.1.

For a step-by-step version, set CLAUDE_CODE_NEW_INIT=1 before running /init. It then asks what you want to set up: CLAUDE.md files, skills or hooks.

/memory is the control panel for the whole memory system. It lists the CLAUDE.md and CLAUDE.local.md files at user and project level, including ones that don't exist yet so you can create them; it has the auto memory toggle; and it opens the auto memory folder so you can read, edit or delete notes. Everything is plain Markdown.

After /compact

Long sessions get compacted, with /compact or automatically when the context fills up. The project-root CLAUDE.md survives this: after compaction Claude re-reads it from disk. Subfolder CLAUDE.md files and path-scoped rules load again when Claude touches a matching file.

What can get lost is anything you only said in the conversation. If an instruction matters enough that you don't want it to vanish after compaction, that's a sign it belongs in CLAUDE.md.

The last lesson of level 2 takes this to team scale: splitting rules by topic, rules for one part of the code, and choosing between CLAUDE.md, a skill and a hook.

Practice lesson 2.2

5 flashcards, 8 exercises checked right on the page, 1 mission on your machine.

Start practice

Related reference

Type to search the reference, templates and lessons.