Claude Code's Two Memory Layers

Every Claude Code session starts with an empty context window. There is no "long-term memory" in the model — but there are two mechanisms that carry knowledge between sessions.

CLAUDE.md — instruction files that you write yourself. Claude reads them at the start of each session.

Auto-memory — notes that Claude writes to itself during work: discovered build commands, code patterns, your preferences.

An important nuance: both mechanisms are context, not configuration. Claude reads CLAUDE.md and tries to follow its instructions, but there is no strict enforcement. For deterministic actions (e.g., "always run the linter before committing"), use Hooks — Lifecycle Events.

CLAUDE.md File Hierarchy

CLAUDE.md can live in several locations with different scopes. All discovered files are loaded — from the most general to the most specific.

flowchart TD
    A["🏢 Managed Policy\n/etc/claude-code/CLAUDE.md\nor managed-settings.json"] --> B
    B["👤 User\n~/.claude/CLAUDE.md\n~/.claude/rules/*.md"] --> C
    C["📁 Project\n./CLAUDE.md\n./.claude/CLAUDE.md\n.claude/rules/*.md"] --> D
    D["🔒 Local\n./CLAUDE.local.md"]

    style A fill:#e74c3c,color:#fff
    style B fill:#e67e22,color:#fff
    style C fill:#27ae60,color:#fff
    style D fill:#2980b9,color:#fff

    E["📝 Auto Memory\n~/.claude/projects/<project>/memory/MEMORY.md"]
    F["📖 Into each session's context:"] --> A
    F --> B
    F --> C
    F --> D
    F --> E

    style F fill:#8e44ad,color:#fff
    style E fill:#16a085,color:#fff

Load order: managed → user → project → local. Files do not override each other — they are concatenated into the context. Files from subdirectories are loaded lazily: only when Claude reads files in that directory.

Best practice: The project CLAUDE.md is committed to the repository and shared with the team. It contains architectural decisions, coding conventions, and common commands. Personal preferences (your sandbox URLs, local paths) go into CLAUDE.local.md, added to .gitignore.

Imports via @path

CLAUDE.md supports importing other files using the @path/to/file syntax. Imported files are expanded into the context at session start.

# CLAUDE.md

See @README.md for a project overview.
Available commands: @package.json


::widget{id="rc-3"}

## Git workflow
@docs/git-conventions.md

A few rules:

• Paths can be relative (from the file containing the import) or absolute
• Recursive imports up to 4 levels of nesting are supported
• Imported files are fully included in the context at startup — imports help with organization but do not save tokens

If you work across multiple git worktrees of the same repository and want to share personal instructions, import a file from your home directory:

# In the current project's CLAUDE.local.md
@~/.claude/my-project-prefs.md

On first encountering external imports, Claude Code will display a confirmation dialog listing the files.

The .claude/rules/ Directory

For large projects, you can split instructions into topic-specific files under .claude/rules/:

.claude/
├── CLAUDE.md
└── rules/
    ├── code-style.md     # style conventions
    ├── testing.md        # testing requirements
    └── api-design.md     # API standards

Rule files support path-scoped mode via YAML front matter. Such rules are loaded only when Claude is working with matching files:

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

# API Rules

- All endpoints must validate input data
- Use the standard error format from src/api/errors.ts

Path-scoped rules are a powerful tool for monorepos: frontend instructions won't pollute the context when working on the backend, and vice versa.

Auto-Memory

Auto-memory is stored in ~/.claude/projects/<project>/memory/ and includes:

• MEMORY.md — the main index file; the first 200 lines or 25 KB are loaded into every session
• Topic-specific files (debugging.md, api-conventions.md) — loaded on demand

Claude decides on its own what is worth remembering: a non-standard build command, a discovered bug pattern, your naming preference. When you see "Writing memory" in the interface, Claude is actively updating these files.

Important: auto-memory is local. All worktrees of the same git repository share a single memory directory. It is not automatically transferred to another machine or to cloud agents.

To ask Claude to remember something right now: type in the chat "remember that we always use pnpm, not npm" — Claude will save it to auto-memory. To add something to CLAUDE.md: "add this to CLAUDE.md".

To view and edit everything saved: use the /memory command in a session.

How to Write Effective CLAUDE.md

CLAUDE.md is not documentation for humans. It is instructions for a model that reads them at every startup. A few rules that genuinely impact how well they are followed:

Size: up to 200 lines. More means more tokens and lower adherence. If the file grows large, move specific things into .claude/rules/ with path-scoping.

Specifics, not abstractions. Compare:

# ❌ Bad
Format code neatly and test your changes.

# ✅ Good
- Indentation: 2 spaces (not tabs)
- Run `npm test` before every commit
- API handlers live in src/api/handlers/

Structure through Markdown. Claude scans headers and bullets the way a human reader does — structured sections work better than dense paragraphs.

Consistency. Two conflicting rules means Claude will pick one arbitrarily. Review CLAUDE.md periodically, especially after adding nested files.

What to put in CLAUDE.md:

• Build, test, and deploy commands
• Naming conventions and coding standards
• Architectural decisions that are not visible from the code
• "Always do X" rules

What not to put:

• Multi-step procedures — these are better packaged as Skills — Portable Skills
• Instructions needed only for one part of the codebase — use path-scoped rules
• Personal preferences — put those in ~/.claude/CLAUDE.md or CLAUDE.local.md

Note on HTML comments: <!-- notes for maintainers --> in CLAUDE.md are stripped before injection into the context. Use them for internal annotations — they don't consume tokens.

Quick Start: /init and /memory

/init — triggers automatic CLAUDE.md creation. Claude analyzes the codebase and generates a file with build commands, conventions, and the project structure. If CLAUDE.md already exists, it will suggest improvements. With the CLAUDE_CODE_NEW_INIT=1 flag, an interactive mode is launched: Claude walks you through a series of questions and shows a proposal before writing.

/memory — opens a list of all loaded memory files (CLAUDE.md, CLAUDE.local.md, rules). Lets you toggle auto-memory and open any file in an editor. Use it as a quick diagnostic tool: if an instruction is not being followed, the first step is to check via /memory that the file is actually being loaded.

See also

• Managing the Context Window — how CLAUDE.md interacts with context: what survives after /compact, token budget, and context hygiene
• Settings and Configuration Hierarchy — settings.json goes hand in hand with CLAUDE.md; their hierarchies are similar and complement each other
• Hooks — Lifecycle Events — when CLAUDE.md is not enough and you need a deterministic guarantee of execution rather than a contextual one
• Skills — Portable Skills — an alternative for procedural instructions that are not needed in every session
• Subagents and Context Isolation — subagents can have their own auto-memory
• Settings and Configuration Hierarchy — enterprise managed policy works analogously for both settings.json and CLAUDE.md
• Plan Mode and Test-Driven Development — a CLAUDE.md instruction to "always start in plan mode" is a common pattern in teams