CLAUDE.md and Memory

0:30 CLAUDE.md is a plain Markdown file of instructions that Claude Code reads at the start of every session: the build and test commands, the code style, the rules of the project, written by you (How Claude remembers your project). Put one in the project root (./CLAUDE.md) to share it with the team through Git, one in ~/.claude/CLAUDE.md for preferences across all your projects, and CLAUDE.local.md for personal notes kept out of Git; /init writes a first draft. Alongside it, Claude Code keeps an auto memory: notes that Claude writes itself about what it learned, such as your corrections and preferences, stored on your machine and loaded next time. Both are context, not enforced configuration: Claude follows them as instructions but can still get things wrong, and a rule that must never be broken belongs in a hook or a permission rule.

Quick facts

Source: How Claude remembers your project, read Nov 6, 2026.

Where do CLAUDE.md files go?

1:34 Claude Code loads CLAUDE.md files from four levels, broadest first (How Claude remembers your project):

Source: How Claude remembers your project, read Nov 6, 2026.

Files in the folders above the one you start in are loaded too, root first, which suits monorepos. A CLAUDE.md in a subfolder loads only when Claude works on files there. Larger projects can split rules into .claude/rules/*.md; a rule file with a paths: line in its front matter, such as "src/api/**/*.ts", loads only when Claude reads or edits a matching file. In a monorepo, the claudeMdExcludes setting skips other teams' files. A file over 4 MiB is skipped entirely.

How do I write a good CLAUDE.md?

1. Run /init in the project. Claude Code reads the code and writes a starter file with build commands, tests and conventions; if one exists, it suggests improvements. It also folds in Cursor rules and .github/copilot-instructions.md it finds (How Claude remembers your project).
2. Cut it down. Anthropic's advice is to stay under 200 lines per file, since every line is loaded into every session and costs context.
3. Be concrete: "Use 2-space indentation" works, "format code properly" does not.
4. Add a line when Claude makes the same mistake twice.
5. Move long procedures into Skills, which load only when needed, and check the result with /doctor prompt-audit, which looks for outdated or conflicting instructions.

0:55 A short example:

# Project notes
- Build: `npm run build`. Test one file: `npm test -- path/to/file`.
- TypeScript strict mode; no `any`.
- API handlers live in src/api/, one file per route.
- Never edit files in generated/.
@docs/architecture.md

2:13 The @docs/architecture.md line imports that file. Imports are relative to the file that contains them, can nest up to four levels deep, and need a one-time approval when they point outside the project. HTML comments in a CLAUDE.md are stripped before Claude sees it, so they can hold notes for people. More advice is on Claude Code Best Practices.

What is Claude Code auto memory?

2:00 Auto memory is what Claude writes for itself. When you correct it or state a preference, it can save a note; the screen shows "Saved 2 memories" or "Recalled 2 memories" (How Claude remembers your project). Notes come in four types: user, feedback, project and reference, and Claude skips what it could work out from the code anyway. Saying "remember that..." saves to auto memory; saying "add this to CLAUDE.md" edits the file instead.

The notes live in ~/.claude/projects/<project>/memory/: one file per memory plus a MEMORY.md index. Only the first 200 lines or 25 KB of MEMORY.md, whichever comes first, load into each conversation; the topic files are read when needed. Auto memory is on by default for local sessions, stays on your machine and is shared between worktrees of one repository. Turn it off in /memory or with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Subagents can keep their own memory through the memory field. This is separate from the Memory feature in the Claude apps, which remembers chats on claude.ai.

CLAUDE.md and AGENTS.md

Many repositories already have an AGENTS.md, the instruction file other coding agents read. Since version 2.1.277, Claude Code reads AGENTS.md directly when there is no CLAUDE.md or CLAUDE.local.md in the folder or above it; it does not read AGENTS.local.md, AGENTS.override.md or an .agents/ folder. The Project instructions setting in /config chooses between claude-md-or-agents-md (the default), claude-md-and-agents-md, claude-md and managed-only. To keep one file for every tool, Anthropic suggests a CLAUDE.md that contains only @AGENTS.md, or a symbolic link (ln -s AGENTS.md CLAUDE.md, but use the import on Windows). /import brings configuration over from Codex, Gemini CLI or Cursor (Commands).

Frequently asked questions

What is CLAUDE.md? CLAUDE.md is a Markdown file of project instructions that Claude Code loads into every session, holding the commands, conventions and rules Claude should follow in that codebase.

Should I commit CLAUDE.md to Git? Yes, the project CLAUDE.md is meant to be shared with the team; personal notes for one project go in CLAUDE.local.md, which should be listed in .gitignore.

How long should CLAUDE.md be? Anthropic recommends keeping each CLAUDE.md under 200 lines, because Claude Code loads it in full into every session; longer procedures belong in skills.

Does Claude Code read AGENTS.md? Yes. Since version 2.1.277, Claude Code reads AGENTS.md when no CLAUDE.md or CLAUDE.local.md exists, and a CLAUDE.md can import it with @AGENTS.md.

Where does Claude Code store its memory? Claude Code's auto memory is stored on your computer in ~/.claude/projects/<project>/memory/, with a MEMORY.md index whose first 200 lines load into each conversation.

Does Claude always follow CLAUDE.md? Not always. Claude Code treats CLAUDE.md as context rather than enforced settings, so for something that must never happen, such as editing a protected file, use a PreToolUse hook or a deny rule.

Do cloud sessions use my CLAUDE.md? A Claude Code cloud session reads the repository's committed CLAUDE.md, but not your personal ~/.claude/CLAUDE.md, which stays on your machine.

Sources

• How Claude remembers your project, Claude Code Docs, read Nov 6, 2026
• Commands, Claude Code Docs, read Nov 6, 2026
• Claude Code overview, Claude Code Docs, read Nov 6, 2026
• Configure cloud environments, Claude Code Docs, read Nov 6, 2026
• The CLAUDE.md file, Claude, May 10, 2026 (video)