Auto memory vs. CLAUDE.md: what to use when

Every Claude Code session starts with a blank context window. Two mechanisms carry knowledge across sessions: CLAUDE.md files, which you write, and auto memory, which Claude writes itself based on your corrections and preferences. Both load at the start of every conversation and both are context, not enforced configuration — for a hard rule that always applies regardless of what Claude decides to do, use a PreToolUse hook instead. This guide walks through both systems side by side: what each is for, exactly where the files live, the size limits that affect how reliably Claude follows them, and the day-to-day workflow for auditing or editing what's been saved.

Side by side

Where CLAUDE.md files live

Files are loaded in this order (broadest to most specific), so a project instruction is read after a user instruction. All discovered files are concatenated, not overridden — nothing you write disappears just because another file exists.

When to add to CLAUDE.md

• Claude makes the same mistake a second time
• A code review catches something Claude should have known about this codebase
• You type the same correction into chat that you typed last session
• A new teammate would need the same context to be productive

Size and structure that actually work

Target under 200 lines per CLAUDE.md file — longer files consume more context and reduce adherence. Use markdown headers and bullets so Claude can scan structure the way a reader would. Be concrete enough to verify: "Use 2-space indentation" and "Run npm test before committing" work better than "Format code properly" or "Test your changes." For large projects, split topic-specific instructions into .claude/rules/*.md files, optionally scoped to matching file paths with YAML frontmatter, so they only load when relevant.

Importing other files

CLAUDE.md can pull in other files with @path/to/import syntax — both relative and absolute paths work, and imports can recursively nest up to four hops deep. Wrap a path in backticks (`@README`) to mention it literally without importing it. A CLAUDE.local.md at the project root loads alongside CLAUDE.md for private, ungitted preferences.

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

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

How multiple CLAUDE.md files combine

Claude Code walks up the directory tree from your working directory, checking every directory along the way for CLAUDE.md and CLAUDE.local.md. Run it in foo/bar/ and it loads foo/CLAUDE.md, then foo/bar/CLAUDE.md, then any CLAUDE.local.md alongside them — files are concatenated, not overridden, with content ordered from the filesystem root down to your working directory so instructions closer to where you launched Claude are read last. CLAUDE.md and CLAUDE.local.md files in subdirectories beneath your working directory aren't loaded at launch; they load on demand when Claude reads a file in that subdirectory. In a large monorepo where unrelated teams' CLAUDE.md files get pulled in, claudeMdExcludes filters specific paths or globs out at any settings layer.

How auto memory works

Auto memory lets Claude accumulate knowledge — build commands, debugging insights, architecture notes, style preferences — without you writing anything. It decides what's worth remembering based on whether it would help a future conversation; it doesn't save something every session. Each project gets its own memory directory derived from the git repository, so every worktree and subdirectory of that repo shares one memory store.

What's inside the memory directory

MEMORY.md is the entrypoint — a concise index loaded into every session. Topic files such as debugging.md or api-conventions.md aren't loaded at startup; Claude reads them on demand with its normal file tools when it needs the detail. When Claude writes to MEMORY.md, Claude Code checks it against the 200-line/25KB read limit and reminds Claude to shorten it if it's close, or returns an error telling Claude to rewrite the index if it's already over.

~/.claude/projects/<project>/memory/
├── MEMORY.md          # concise index, loaded every session
├── debugging.md       # detailed debugging notes
├── api-conventions.md # API design decisions
└── ...                # any other topic files Claude creates

One nuance for subagents

The main conversation's auto memory is not loaded into subagents by default — the exception is a fork, which inherits the parent's full context. A subagent can maintain its own separate auto memory directory if you enable the memory field in its configuration.

Scoping instructions to specific files

For larger projects, split CLAUDE.md into .claude/rules/*.md files and scope each with YAML frontmatter so it only loads when Claude touches matching files — this keeps unrelated instructions out of context on unrelated work. Glob patterns support brace expansion, e.g. src/**/*.{ts,tsx} for both TypeScript and TSX files.

---
paths:
  - "src/**/*.{ts,tsx}"
---

# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format

Deploying CLAUDE.md across a whole organization

Organizations can deploy a centrally managed CLAUDE.md that applies to every session on a machine and cannot be excluded by individual settings — useful for company-wide coding standards, security policies, or compliance requirements. It's distributed via MDM, Group Policy, Ansible or similar tools to the managed-policy path for each OS, and loads before user and project CLAUDE.md files. A claudeMd key in managed-settings.json lets you embed the content directly instead of shipping a separate file.

Settings vs. CLAUDE.md: where each concern belongs

Settings are enforced by the client regardless of what Claude decides; CLAUDE.md instructions shape behavior but aren't a hard enforcement layer.

If your repo already has AGENTS.md

Claude Code reads CLAUDE.md, not AGENTS.md. If a repository already standardizes on AGENTS.md for other coding agents, create a CLAUDE.md that imports it with @AGENTS.md so every tool reads the same instructions without duplicating them, then add Claude-specific notes below the import — for example "Use plan mode for changes under src/billing/." A symlink (ln -s AGENTS.md CLAUDE.md) works too if you don't need anything Claude-specific, though on Windows that requires Administrator privileges, so the @-import is usually simpler. Run /init and it also picks up Cursor rules and Copilot instructions automatically when generating a starting CLAUDE.md.

@AGENTS.md

## Claude Code
Use plan mode for changes under src/billing/.

FAQ