Claude Code Memory Locations: How CLAUDE.md Is Loaded and Overridden

Claude Code memory is not one file. It is a hierarchy of CLAUDE.md, CLAUDE.local.md, .claude/rules/, imports, and auto memory. If Claude ignores an instruction, first run /memory to see what loaded in the current session. Then check path, scope, conflicts, and whether the instruction should be a hook or skill instead.

The short version:

CLAUDE.md is instruction memory. It is useful when it stays short, current, and scoped. It is not a secret manager, not a full runbook library, and not a guarantee that the model will behave like a deterministic program.

Which memory files Claude Code can load

Claude Code can load instruction files from several locations.

User instructions live at:

~/.claude/CLAUDE.md

Use this for preferences that should follow you across projects: preferred shell style, personal review habits, or "ask before creating commits." Do not put repo-specific secrets, customer names, staging URLs, or team-only rules here.

Project instructions live at either:

./CLAUDE.md
./.claude/CLAUDE.md

Use project memory for rules the whole team should share: package manager, test commands, architecture boundaries, code style, generated-file warnings, deployment constraints, and common workflows. This file usually belongs in version control.

Local project instructions live at:

./CLAUDE.local.md

Use local memory for personal project-specific preferences. Claude Code docs say it loads alongside CLAUDE.md and is treated the same way, but it should be added to .gitignore. Good content: your local sandbox URL, preferred seed account, or a machine-specific command path. Bad content: API keys, production passwords, or anything the agent could copy into a diff.

User rules live under:

~/.claude/rules/

Use user rules for personal preferences that should apply to every project on your machine. Claude Code loads user-level rules before project rules, so project rules appear later in context. Do not rely on ambiguous override semantics. Remove conflicts instead of hoping the later rule wins.

Project rules live under:

./.claude/rules/

Rules are useful when CLAUDE.md is getting too large or when instructions only apply to certain files. A rule can be path-scoped with YAML frontmatter, such as paths: ["src/api/*/.ts"], so Claude only loads it when it works with matching files.

Managed organization memory can be deployed by administrators. The official docs list managed-policy locations such as /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. Treat this as organization guidance, not a repo-owned file.

Auto memory lives under:

~/.claude/projects/<project>/memory/

Claude uses this folder for notes it saves during sessions. The folder includes a MEMORY.md entrypoint and optional topic files. Auto memory is machine-local, and worktrees or subdirectories in the same git repo share one auto memory directory.

How CLAUDE.md files load

Claude Code walks up the directory tree from your current working directory and checks each directory for CLAUDE.md y CLAUDE.local.md.

If you start Claude inside:

repo/packages/web/

Claude may load files like:

repo/CLAUDE.md
repo/CLAUDE.local.md
repo/packages/CLAUDE.md
repo/packages/web/CLAUDE.md
repo/packages/web/CLAUDE.local.md

The important detail is that discovered files are concatenated into context rather than truly overridden like config keys. Content closer to the working directory appears later, and CLAUDE.local.md is appended after CLAUDE.md at the same level. Practically, the later instruction may carry more weight because Claude reads it later, but conflicting instructions can still create unpredictable behavior.

Subdirectory CLAUDE.md files below the current working directory are different. Claude can discover them on demand when it reads files in those subdirectories. That is useful in monorepos, but it also explains why a nested instruction may appear to "start working" only after Claude touches a file under that folder.

Imports and AGENTS.md

CLAUDE.md can import other files with @path/to/import syntax.

@AGENTS.md

## Claude Code

Use plan mode before changing `src/billing/`.

This is the clean pattern when a repo already uses AGENTS.md for other coding agents. Claude Code reads CLAUDE.md, not AGENTS.md directly, so CLAUDE.md can import AGENTS.md and then add Claude-specific instructions below it.

Imports are expanded into context at launch alongside the file that references them. Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the shell working directory. Imported files can recursively import other files up to four hops.

Imports are good for organization. They are not a context-saving trick. The imported content still enters the context window at launch. If a file is only relevant to one subdirectory or file type, path-scoped rules are usually better.

What to commit

Commit the memory that describes how the team should work in the repo.

Usually commit:

• CLAUDE.md o .claude/CLAUDE.md
• .claude/rules/*.md
• Documentation that CLAUDE.md imports, such as AGENTS.md
• Examples or templates that contain no private data

Usually do not commit:

• CLAUDE.local.md
• Auto memory under ~/.claude/projects/<project>/memory/
• Machine paths that only work on one laptop
• Personal preferences that would annoy other contributors
• Secret values, tokens, private endpoints, or customer data

A good team CLAUDE.md should read like a compact onboarding note for an agent:

# Project instructions

- Use `pnpm`, not `npm`.
- Run `pnpm test` after changing server code.
- API routes live in `src/server/routes/`.
- Do not edit files under `src/generated/`.
- Shared agent instructions live in `@AGENTS.md`.

What to keep personal

Keep personal memory small and boring.

Good personal entries:

• "Prefer pnpm test -- --watch=false for this repo."
• "Use my local preview account dev-preview@example.com for screenshots."
• "Ask before installing new global tools."
• "My local docs clone is at ~/work/docs."

Bad personal entries:

• "Use PROD_API_KEY=...."
• "The admin password is..."
• "Always deploy after tests pass."
• "Ignore the billing tests because they are flaky."

The first group helps Claude work smoothly on your machine. The second group creates security or operational risk. Secrets should live in environment variables, secret stores, or host-specific credential systems, not memory files.

How to debug ignored memory

When Claude seems to ignore CLAUDE.md, debug what loaded before rewriting everything.

1. Run /memory.
2. Confirm the expected CLAUDE.md, CLAUDE.local.md, and rules files are listed.
3. Open the loaded files from /memory and inspect the actual content.
4. Check whether you launched Claude from the directory you expected.
5. Look for conflicting instructions across managed, user, parent, project, local, nested, and rules files.
6. Rewrite vague guidance into concrete checks.
7. If the rule must run at a specific lifecycle point, make it a hook.
8. If the content is a long repeatable procedure, make it a skill.

The official docs make one subtle point that matters: 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 vague or conflicting instructions are not guaranteed to win.

So do not write:

Be careful with tests.

Write:

After changing files under `src/billing/`, run `pnpm test billing`.
If the command cannot run, explain the blocker before final response.

If that command must run every time after a file edit, use a hook. Memory is guidance. Hooks are lifecycle automation.

Example CLAUDE.md that imports AGENTS.md

This pattern keeps cross-agent instructions in one place and avoids duplicating repo rules.

@AGENTS.md

# Claude Code

- Use plan mode before touching `src/payments/`, `src/auth/`, or database migrations.
- Prefer read-only exploration before edits in unfamiliar packages.
- When reviewing a diff, separate confirmed bugs from style preferences.
- If a task requires a repeatable procedure, check `.claude/skills/` before improvising.
- If an instruction conflicts with `AGENTS.md`, ask before choosing one.

This is better than copying the entire contents of AGENTS.md into CLAUDE.md. One source of shared truth stays shared, and Claude-specific guidance remains visible.

Anti-patterns

Avoid these patterns:

Huge memory files. Long files consume context and reduce adherence. If the file is over 200 lines, trim it, split it into rules, or move procedures into skills.

Conflicting parent and child rules. A root file says "use npm," while a nested package file says "use pnpm." Claude may choose either. Make the package-specific rule explicit and remove the outdated parent rule.

Secrets in memory. Agents can quote memory, write it into files, include it in logs, or expose it through tool output. Do not place credentials in CLAUDE.md, CLAUDE.local.md, rules, imports, or auto memory.

Runbooks as always-on context. A deploy runbook does not need to be read during every CSS change. Make it a skill or slash command.

Private local paths in committed files. ~/himanshu/local-api should not appear in team memory. Put it in CLAUDE.local.md or import a personal file from your home directory.

Assuming imports reduce context. Imports are expanded at launch. They organize memory, but they do not make imported text free.

Final memory checklist

Before you call the setup done, verify:

1. Team rules live in CLAUDE.md o .claude/CLAUDE.md.
2. Personal project notes live in CLAUDE.local.md and are gitignored.
3. Shared cross-agent rules live in AGENTS.md and are imported from CLAUDE.md.
4. Long or path-specific instructions live in .claude/rules/.
5. Repeatable procedures live in skills, not always-on memory.
6. Fixed lifecycle actions live in hooks, not reminders.
7. No secrets appear in memory files or imports.
8. /memory shows the files you expect for the current session.
9. Conflicting managed, user, parent, child, local, and rules files have been reconciled.
10. The instructions are concrete enough to verify.

Predictable Claude Code memory is mostly path hygiene. Put the rule in the right file, keep it short, avoid conflicts, and use /memory before assuming the model forgot.