CLAUDE.md — Claude Code memory files guide

tl;dr: CLAUDE.md is plain Markdown that Claude Code loads into every session. There are two memory systems — files you write, and notes Claude writes for itself (“auto memory”). This page covers the first kind, where to put it, how it loads across scopes, and the existing language-specific templates on this site.

CLAUDE.md vs auto memory

Both load into every Claude Code session. They are complementary, not alternatives — and neither is enforced configuration.

Source: Claude Code memory docs. To block an action regardless of what Claude decides, use a PreToolUse hook — settings-enforced, not context-shaped.

Where CLAUDE.md files live

Four scopes. Load order from broadest to most specific — project instructions appear in context after user instructions, so the more specific file is read last.

CLAUDE.md files above the working directory load at launch. Files in subdirectories load on demand when Claude reads files there. Files are concatenated, not overridden — root instructions appear first, then the closer-to-cwd file.

Managed policy CLAUDE.md cannot be excluded. Use claudeMdExcludes in .claude/settings.local.json to drop irrelevant ancestor files in large monorepos.

How to write one that actually gets followed

From the docs:

• Target under 200 lines per file. Longer files burn context and reduce adherence.
• 4 MiB hard cap. Claude Code skips files larger than that.
• Be specific. “Use 2-space indentation” beats “format code nicely.”
• Structure with headers. Markdown sections scan better than prose paragraphs.
• Check for conflicts. Two contradictory rules → Claude picks one arbitrarily.
• Drop /init first. It scans your codebase and proposes a starter CLAUDE.md you can refine.

If you write a rule that must run at a specific moment (before every commit, after every edit), write it as a hook, not as memory. Hooks are shell commands executed at fixed lifecycle events and apply regardless of what Claude decides.

To debug what loaded: run /context in a session. The Memory files section lists every CLAUDE.md, CLAUDE.local.md, and rule that was injected.

.claude/rules/ for path-scoped instructions

A whole-project CLAUDE.md gets noisy fast. Move topic-specific instructions into .claude/rules/ so Claude loads them by relevance, not all at once:

your-project/
├── .claude/
│   ├── CLAUDE.md           # main project instructions
│   └── rules/
│       ├── code-style.md   # one topic per file
│       ├── testing.md
│       └── frontend/
│           └── components.md

Rules without paths frontmatter load at launch with the same priority as .claude/CLAUDE.md. Rules with paths only load when Claude reads a matching file:

---
paths:
  - "src/api/**/*.ts"
  - "src/api/**/*.tsx"
---

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

Glob budget: 1,000 expanded patterns / 4 MiB per rule’s paths list. Brace expansion counts against the budget; bare patterns don’t.

Path-scoped rules trigger on file read, not on every tool call — different from always-on CLAUDE.md. For task-specific procedures that don’t need to be in context every session, use a skill instead.

Imports with @path/to/import

CLAUDE.md files can pull in additional files using @path:

See @README for project overview and @package.json for available scripts.

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

Imported files load at launch with the importer — they don’t save context, only organization. Max depth is four hops. Wrap a path in backticks (`@README`) to mention it without importing. Imports outside your working directory trigger a one-time approval dialog.

AGENTS.md interop

Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already uses AGENTS.md for Cursor, Aider, and friends, bridge it:

# in your CLAUDE.md
@AGENTS.md

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

Or symlink (macOS/Linux):

ln -s AGENTS.md CLAUDE.md

On Windows, symlinks need Developer Mode or admin — use the @AGENTS.md import instead. /init (v2.1.213+) reads .cursor/rules/, .cursorrules, .github/copilot-instructions.md, AGENTS.md, .devin/rules/, .windsurf/rules/, and .clinerules, then folds the relevant pieces into a starter CLAUDE.md. /import does the same thing as a one-shot copy.

The /init command

Run /init in a Claude Code session and it analyzes your repo, then proposes a CLAUDE.md with build commands, test instructions, and conventions it discovered. If a CLAUDE.md already exists, /init suggests improvements instead of overwriting.

Set CLAUDE_CODE_NEW_INIT=1 for the interactive multi-phase flow (picks which artifacts to set up — CLAUDE.md files, skills, hooks — then asks follow-ups before writing).

Auto memory in one paragraph

On by default. Claude records four kinds of notes — user, feedback, project, reference — into ~/.claude/projects/<project>/memory/, indexed by MEMORY.md (first 200 lines / 25 KB loaded every session). Topic files are read on demand. Disable per-project with autoMemoryEnabled: false in .claude/settings.json, or globally with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1. Run /memory to browse and edit.

Existing CLAUDE.md templates (this site)

These are the language- and framework-specific packs we already ship. Drop them in your project root and edit from there:

These are starting points, not the final word — every team should layer its own conventions on top via .claude/rules/ files (path-scoped) or imports.

CLAUDE.md vs Cursor’s .mdc vs AGENTS.md

If you support multiple editors, write AGENTS.md once and have CLAUDE.md import it. Cursor’s /init reads AGENTS.md and folds it in. One file, all agents.

Related

• Claude Code — Getting Started
• Claude Code CLI
• Claude / agent skills — on-demand procedures, the other side of context
• Cursor Rules — Complete Guide — .cursor/rules/*.mdc and AGENTS.md deep-dive
• Context Engineering Guide — meta-skill behind good rules
• CLAUDE.md for TypeScript · for Python · for Next.js
• Anthropic: How Claude remembers your project — primary doc