How Claude remembers your project

Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automatically with auto memory.

Each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions:

CLAUDE.md files — instructions you write to give Claude persistent context
Auto memory — notes Claude writes itself based on your corrections and preferences

CLAUDE.md vs auto memory

	CLAUDE.md files	Auto memory
Who writes it	You	Claude
What it contains	Instructions and rules	Learnings and patterns
Scope	Project, user, or org	Per repository, shared across worktrees
Loaded into	Every session	Every session (first 200 lines or 25KB)
Use for	Coding standards, workflows, project architecture	Build commands, debugging insights, preferences Claude discovers

Use CLAUDE.md when you want to guide Claude's behavior. Auto memory lets Claude learn from your corrections without manual effort.

To block an action regardless of what Claude decides, use a PreToolUse hook instead.

CLAUDE.md files

CLAUDE.md files are markdown files that give Claude persistent instructions. Claude reads them at the start of every session.

When to add to CLAUDE.md

Add to it when:

Claude makes the same mistake a second time
A code review catches something Claude should have known
You type the same correction you typed last session
A new teammate would need the same context

Keep facts Claude should hold every session: build commands, conventions, project layout, "always do X" rules. Move multi-step procedures to skills or path-scoped rules.

Choose where to put CLAUDE.md files

Scope	Location	Purpose
Managed policy	macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`; Linux/WSL: `/etc/claude-code/CLAUDE.md`; Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`	Organization-wide instructions
User	`~/.claude/CLAUDE.md`	Personal preferences for all projects
Project	`./CLAUDE.md` or `./.claude/CLAUDE.md`	Team-shared project instructions
Local	`./CLAUDE.local.md`	Personal project preferences (gitignore)

Set up a project CLAUDE.md

Create ./CLAUDE.md or ./.claude/CLAUDE.md with build and test commands, coding standards, architecture, naming conventions, and workflows.

Run /init to generate a starting CLAUDE.md. Set CLAUDE_CODE_NEW_INIT=1 for an interactive multi-phase flow.

Write effective instructions

Size: target under 200 lines per file
Structure: markdown headers and bullets
Specificity: "Use 2-space indentation" not "Format code properly"
Consistency: remove conflicting instructions across CLAUDE.md and .claude/rules/

Import additional files

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

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

Use CLAUDE.local.md for private preferences. Share across worktrees:

- @~/.claude/my-project-instructions.md

AGENTS.md

Claude Code reads CLAUDE.md, not AGENTS.md. Import shared instructions:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude walks up from your cwd for CLAUDE.md and CLAUDE.local.md. Content is concatenated root-down; closer directories are read last. Subdirectory CLAUDE.md files load when Claude reads files in those subdirectories.

Load from --add-dir directories with:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Organize rules with `.claude/rules/`

Place markdown files in .claude/rules/. Path-specific rules use frontmatter:

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

# API Development Rules

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

Rules without paths load every session. Path-scoped rules load when Claude reads matching files.

User-level rules in ~/.claude/rules/ apply to every project and load before project rules.

Exclude CLAUDE.md files in monorepos

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Managed policy CLAUDE.md files cannot be excluded.

Auto memory

Auto memory lets Claude accumulate knowledge across sessions. Claude saves notes as it works: build commands, debugging insights, architecture notes, and workflow habits.

Requires Claude Code v2.1.59 or later (claude --version).

Enable or disable

Toggle in /memory or:

{
  "autoMemoryEnabled": false
}

Or CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Storage location

~/.claude/projects/<project>/memory/ with MEMORY.md as index and optional topic files.

Custom directory in ~/.claude/settings.json:

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

Run /memory to verify files are loaded
Make instructions more specific
Look for conflicting instructions
For must-run steps, use hooks or --append-system-prompt (automation)

Instructions seem lost after `/compact`

Project-root CLAUDE.md is re-read after /compact. Nested CLAUDE.md reload when Claude reads files in those subdirectories again. Put durable rules in CLAUDE.md, not chat only.