How Claude Code loads CLAUDE.md and auto memory

Who this is for and what you will be able to do

This guide is for anyone whose Claude Code sessions forget project conventions, or who is not sure whether an instruction actually loaded. When you finish, you will know the two memory mechanisms, where a CLAUDE.md file belongs, when it enters the context, and how to confirm what loaded with /context all.^[1]

Two memory systems: CLAUDE.md and auto memory

Each Claude Code session starts with a fresh context window. Two mechanisms carry knowledge across sessions. CLAUDE.md files are instructions you write. Auto memory is notes that Claude writes for itself, based on your corrections and preferences.^[1]

Both are loaded at the start of every conversation. Claude treats them as context, not as enforced configuration. If an action must be blocked no matter what Claude decides, use a PreToolUse hook instead of a memory file.^[1]

The two differ in scope and content. CLAUDE.md can cover project, user, or organization scope, and it holds instructions and rules. Auto memory is kept per repository, shared across worktrees, and holds learnings and patterns. The first 200 lines or 25KB of MEMORY.md, whichever comes first, are loaded at the start of every conversation.^[1]

CLAUDE.md content reaches Claude as a user message that follows the system prompt. It does not become part of the system prompt. Claude tries to follow it, but strict compliance is not guaranteed, and vague or conflicting instructions are the least reliable.^[1]

Where a CLAUDE.md file goes

CLAUDE.md can live in four places, each with a different scope.^[1]

• Managed policy: /Library/Application Support/ClaudeCode/CLAUDE.md on macOS, /etc/claude-code/CLAUDE.md on Linux and WSL, and C:\Program Files\ClaudeCode\CLAUDE.md on Windows. It applies to all users in the organization and is managed by IT or DevOps.^[1]
• User instructions: ~/.claude/CLAUDE.md, which applies to all of your projects and is seen only by you.^[1]
• Project instructions: ./CLAUDE.md or ./.claude/CLAUDE.md, shared with the team through source control.^[1]
• Local instructions: ./CLAUDE.local.md, personal to you and specific to the current project. Add it to .gitignore.^[1]

Which files load at launch

When Claude Code starts, it loads CLAUDE.md and CLAUDE.local.md from the current working directory and from every directory above it. Run Claude Code in foo/bar/, and it loads foo/bar/CLAUDE.md, foo/CLAUDE.md, and any CLAUDE.local.md files alongside them.^[1]

The discovered files are concatenated rather than overriding each other. Content runs from the filesystem root down to the working directory, so the instructions nearest the launch point are read last. Inside each directory, CLAUDE.local.md is appended after CLAUDE.md.^[1]

A CLAUDE.md in a subdirectory does not load at launch. It loads once Claude reads, writes, or edits another file in that subdirectory.^[1]

Block-level HTML comments are stripped before the content enters Claude's context, which makes them a way to leave notes for maintainers without spending tokens. Comments inside code blocks are kept.^[1]

Directories added with --add-dir

The --add-dir flag gives Claude access to directories outside the main working directory. By default, the CLAUDE.md files in those directories are not loaded. To load them for one launch, set the environment variable inline:^[1]

``bash CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config ``^[1]

Writing a CLAUDE.md that holds up

Keep each file under 200 lines. Longer files use more context and are followed less reliably. Instructions that matter for only part of the codebase belong in path-scoped rules, which load only when Claude works with matching files.^[1]

Write instructions that can be checked. "Use 2-space indentation" is more useful than "format code properly," and "API handlers live in src/api/handlers/" is more useful than "keep files organized."^[1]

For a long file, @path imports help organize content. A relative import resolves from the file that contains it, not from the working directory. Imports can nest up to four hops deep. Import parsing skips Markdown code spans and fenced code blocks, so wrapping @README in backticks keeps it as plain text.^[1]

Organizing rules in .claude/rules/

Larger projects can split instructions across the .claude/rules/ directory. Every .md file there is discovered recursively, so subdirectories such as frontend/ and backend/ work too. Give each file one topic and a descriptive name, such as testing.md or api-design.md.^[1]

A rule with no paths field loads at launch, with the same priority as .claude/CLAUDE.md. Claude Code reads only the paths field from a rule's frontmatter and ignores the others without an error.^[1]

Storing and turning off auto memory

Auto memory is on by default in local sessions. Toggling it in /memory saves autoMemoryEnabled to ~/.claude/settings.json.^[1]

Each project's notes live in ~/.claude/projects/<project>/memory/. The project path comes from the git repository, so all worktrees and subdirectories of one repository share that folder.^[1]

Claude sorts what it saves into four types. user covers your role, expertise, and working preferences. feedback covers corrections you give and approaches you confirm. project covers ongoing work, deadlines, and decisions that cannot be derived from the code or git history. reference covers where to find information outside the project, such as an issue tracker or dashboard.^[1]

Claude skips anything it can derive from the codebase, and anything the CLAUDE.md files already say.^[1]

Topic files such as user_role.md are not loaded at startup. Claude reads them on demand with its standard file tools.^[1]

Checking why an instruction did not take effect

Run /context all and check the Memory files list. If a file is missing there, Claude cannot see it. A subdirectory CLAUDE.md does not appear in that list, because it loads on demand.^[1]

The /memory command lists the CLAUDE.md, CLAUDE.local.md, and other memory file locations, and it toggles auto memory. To put content in CLAUDE.md, ask Claude to add it or edit the file yourself through /memory.^[1]

If an instruction has to run at a fixed point, such as before every commit or after each file edit, write it as a hook. Hooks run as shell commands at fixed lifecycle events, whatever Claude decides to do.^[1]

Next steps

For the complete load order, the AGENTS.md behavior, and the organization-wide deployment details, read the memory page in Claude Code's official documentation.^[1]