How Claude Code memory works: CLAUDE.md, imports and /memory

How does Claude Code remember things between sessions?

Claude does not carry a conversation from one session to the next. The memory documentation names two mechanisms that carry knowledge across sessions: CLAUDE.md files, which are instructions you write, and auto memory, which are notes Claude writes itself based on your corrections and preferences. Claude can also read a repository's AGENTS.md in place of CLAUDE.md when the repo has no CLAUDE.md.

One caution from the docs applies to both. Claude treats them as context, not enforced configuration. The more specific and concise your instructions, the more consistently Claude follows them. If an action must be blocked regardless of what Claude decides, use a PreToolUse hook instead; see the hooks guide.

This page is about where memory lives and how it loads. For how to write a good CLAUDE.md, with templates, see how to write a CLAUDE.md file.

Where do CLAUDE.md files go, and which one wins?

CLAUDE.md files can live in several locations, each with a different scope. This table lists them in load order, from broadest to most specific, per the docs.

Nothing overrides anything. Claude Code loads CLAUDE.md and CLAUDE.local.md from your current working directory and 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. All discovered files are concatenated into context rather than overriding each other. Content is ordered from the filesystem root down to your working directory, so instructions closer to where you launched Claude are read last. Within a directory, CLAUDE.local.md is appended after CLAUDE.md, so your personal notes are the last thing Claude reads at that level.

Files in subdirectories under your working directory behave differently. They are not loaded at launch. Claude Code loads each one once Claude reads, writes or edits another file in that subdirectory. That is why a subdirectory CLAUDE.md does not appear in the Memory files list in /context, and why a Loaded line with its path appears in the terminal when it kicks in.

Because everything is concatenated, contradictions are your problem to catch. If two files give different guidance for the same behavior, Claude may pick one arbitrarily. Review your CLAUDE.md files, nested ones and .claude/rules/ from time to time to remove outdated or conflicting instructions. The docs offer an audit: run /doctor prompt-audit in a session (v2.1.283 or later) and Claude reports instructions written for older models, references to files or commands that do not exist, and files that contradict each other. Nothing changes until you ask Claude to apply the findings.

# Personal notes for this project (not committed)
- My local dev server runs on http://localhost:3001
- Use the seed data in scripts/seed-dev.sql when you need sample records
- Run tests with `npm test -- --watch=false`; never start the watcher

How do you import other files into CLAUDE.md?

Write @path/to/file anywhere in a CLAUDE.md. The imported file is expanded and loaded into context alongside the CLAUDE.md that references it. Both relative and absolute paths work. Relative paths resolve relative to the file containing the import, not the working directory. Imported files can import others, to a maximum depth of four hops.

See @README for project overview and @package.json for available npm commands for this project.

# Additional Instructions
- git workflow @docs/git-instructions.md

# Individual Preferences
- @~/.claude/my-project-instructions.md

• Spaces in a path: put a backslash before each space. A path wrapped in quotes is not imported at all.
• Mentioning a path without importing it: wrap it in backticks. Import parsing skips Markdown code spans and fenced code blocks, so ` @README stays literal while a bare @README` imports the file.
• Imports do not save context. The docs are explicit that imports help you organize a long file but do not reduce its context cost, because imported files load together with the CLAUDE.md that imports them.
• Imports outside the project need approval. An import in a project-level memory file that resolves outside your working directory, like the home-directory import above, triggers a dialog the first time Claude Code meets it. If you decline, the imports stay disabled and the dialog does not appear again. User-scope files such as ~/.claude/CLAUDE.md load their imports without the dialog.

The home-directory import solves a real problem with git worktrees. A gitignored CLAUDE.local.md exists only in the worktree where you created it. To share personal instructions across all worktrees of a repository, import a file from your home directory instead, as the last line of the template shows.

Block-level HTML comments, like <!-- maintainer notes -->, are stripped before the content reaches Claude's context. They let you leave notes for human maintainers without spending tokens. Comments inside code blocks are preserved.

What is the .claude/rules directory?

For larger projects you can split instructions into topic files under .claude/rules/. Each file covers one topic, with a descriptive name such as testing.md or api-design.md. All .md files are discovered recursively, so subfolders like frontend/ work. Rules without paths frontmatter load at launch with the same priority as .claude/CLAUDE.md.

The useful part is scoping. A rule with a paths field loads only when Claude works with files that match, so instructions that matter for part of the codebase stop costing tokens in every session:

---
paths:
  - "src/api/**/*.ts"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

A path-scoped rule loads when Claude uses the Read, Write or Edit tool on a matching file, or views one with a Bash command that counts as a read, such as cat on a single file. Patterns are relative to the directory containing the rule's .claude folder. Personal rules in ~/.claude/rules/ apply to every project on your machine and load before project rules. Neither set overrides the other, so keep them consistent.

For task-specific instructions that do not need to be in context all the time, the docs point to skills instead, which load only when invoked or judged relevant. See the guide to Claude Code skills.

What does the /memory command do?

/memory is the control panel. According to the docs it lists your CLAUDE.md, CLAUDE.local.md and other memory file locations across user and project scopes, including entries for files that do not exist yet. It lets you toggle auto memory on or off and provides an option to open the auto memory folder. Select any file to open it in your editor; selecting one that does not exist yet creates it first. GUI editors such as VS Code open the file in a separate window, while terminal editors such as Vim take over the terminal until you exit.

• See what loaded: run /context and check the Memory files list. If a file is missing there, Claude cannot see it. For AGENTS.md, run /memory and look for its path.
• Start a project file: run /init to generate a starting CLAUDE.md. Claude analyzes your codebase and writes build commands, test instructions and conventions it finds. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it.
• Add an instruction: say “add this to CLAUDE.md” and Claude edits the file, or edit it yourself through /memory.
• Add a memory: say “remember that the API tests require a local Redis instance”, or “always use pnpm, not npm”. The docs say Claude saves these to auto memory.

A common confusion: where does a casual “remember this” land? In auto memory, not CLAUDE.md, unless you say CLAUDE.md. If you want the instruction shared with your team through git, put it in the project CLAUDE.md, because auto memory is machine-local.

What is auto memory and where is it stored?

Auto memory lets Claude accumulate knowledge across sessions without you writing anything. Claude saves four kinds of notes, and records the kind as a type field in each memory file's frontmatter: user (your role, expertise and working preferences), feedback (corrections you give and approaches you confirm), project (ongoing work, deadlines and decisions that cannot be derived from code or git history) and reference (where to find information outside the project, such as an issue tracker). Claude skips what it can derive from the codebase and anything your CLAUDE.md already says, and it does not save something every session.

Each project gets its own directory at ~/.claude/projects/<project>/memory/. The <project> path comes from the git repository, so all worktrees and subdirectories of one repo share one directory. Auto memory is machine-local: files are not shared across machines or cloud environments.

~/.claude/projects/<project>/memory/
├── MEMORY.md           # index, one line per memory, loaded into every session
├── user_role.md        # one memory
├── feedback_testing.md # one memory
└── ...                 # any other topic files Claude creates

Only the first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, load at the start of every conversation. Topic files are not loaded at startup; Claude reads them on demand when it needs them. The 200-line and 25KB limit applies only to MEMORY.md. Claude gets the whole of each CLAUDE.md that loads at launch, as long as the file is 4 MiB or smaller; a file over that is skipped entirely.

Auto memory is on by default in local sessions. To turn it off, use the toggle in /memory, which saves autoMemoryEnabled to your user settings. For one project, set it in that project's settings. To disable it through the environment, set CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. To move it, set autoMemoryDirectory to an absolute path or one starting with ~/.

{
  "autoMemoryEnabled": false
}

Everything is plain markdown you can read, edit or delete. If you do not know what Claude saved, run /memory and open the auto memory folder. The messages “Saved 2 memories” or “Recalled 2 memories” in the interface mean Claude is writing to or reading from that directory.

What about AGENTS.md and monorepos?

Claude Code can read AGENTS.md as your project instructions, so a repository already set up for other coding agents works without a CLAUDE.md. By default, with an AGENTS.md and no CLAUDE.md or CLAUDE.local.md in your working directory or above, Claude reads AGENTS.md. With both present, Claude reads the CLAUDE.md files only. Direct reading requires Claude Code v2.1.277 or later. The easiest way to share one file between tools is a CLAUDE.md that imports AGENTS.md with @AGENTS.md; see how to update Claude Code if your version is older.

In a large monorepo, ancestor CLAUDE.md files from other teams may be picked up. The claudeMdExcludes setting skips files by absolute path or glob pattern, at any settings layer. Arrays merge across layers, and a managed CLAUDE.md cannot be excluded. Putting it in .claude/settings.local.json keeps the exclusion on your machine.

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

To load CLAUDE.md files from directories you add with --add-dir, set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. By default they are not loaded.

Why is Claude ignoring my CLAUDE.md?

The docs give the root cause first: CLAUDE.md content is delivered as a user message after the system prompt, not as part of the system prompt. Claude reads it and tries to follow it, but there is no guarantee of strict compliance, especially for vague or conflicting instructions. Work through these checks.

1. Is it loaded? Run /context and check Memory files. Use /memory to open and edit the file.
2. Is it in a location that loads for your session? Compare with the hierarchy table above. A subdirectory file loads only after Claude touches a file there.
3. Is it specific? “Use 2-space indentation” works better than “format code nicely”.
4. Does it conflict with another file? Run /doctor prompt-audit.
5. Is it too long? Target under 200 lines per file. Longer files use more context and reduce adherence. Claude Code skips a file over 4 MiB, and subdirectory or on-demand files have a smaller per-file limit: 40,000 characters on a 200K context window. Past it, Claude receives only the start of the file.
6. Did it survive compaction? A project-root CLAUDE.md is re-read from disk after /compact. An instruction you gave only in conversation is not, so add it to CLAUDE.md.

If an instruction must run at a fixed moment, such as before every commit, write it as a hook rather than a memory. Memory also costs usage every session, which is why trimming matters; see the usage limits guide. And if you are looking for something to build while you tune your setup, the ideas board has ideas with ready build prompts.