How Claude Code Remembers Your Project: CLAUDE.md Files and Auto Memory

Two memory systems, two authors

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

Both are loaded at the start of every conversation. An important caveat from the docs: Claude treats these as context, not enforced configuration. If you need to block an action regardless of what Claude decides, use a PreToolUse hook instead. The more specific and concise your instructions, the more consistently Claude follows them.

A quick comparison:

	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 deliberately. Auto memory lets Claude learn from your corrections without manual effort. Subagents can also maintain their own auto memory, configured separately.

When to add something to CLAUDE.md

Treat CLAUDE.md as the place you write down what you'd otherwise re-explain. The documentation suggests adding to it when:

• 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 or clarification into chat that you typed last session
• A new teammate would need the same context to be productive

Keep it to facts Claude should hold in every session: build commands, conventions, project layout, "always do X" rules. If an entry is a multi-step procedure or only matters for one part of the codebase, the docs recommend moving it to a skill or a path-scoped rule instead.

Where CLAUDE.md files can live

CLAUDE.md files can exist at several scopes. They load from broadest to most specific, so a project instruction appears in context after a user instruction:

Scope	Location	Shared with
Managed policy	macOS: /Library/Application Support/ClaudeCode/CLAUDE.md; Linux and WSL: /etc/claude-code/CLAUDE.md; Windows: C:\Program Files\ClaudeCode\CLAUDE.md	All users in organization
User instructions	~/.claude/CLAUDE.md	Just you (all projects)
Project instructions	./CLAUDE.md or ./.claude/CLAUDE.md	Team members via source control
Local instructions	./CLAUDE.local.md (add to .gitignore)	Just you (current project)

Managed policy files are meant for organization-wide instructions managed by IT/DevOps, such as company coding standards, security policies, and compliance requirements. User instructions hold personal preferences that apply to all your projects. Local instructions are for personal, project-specific preferences like sandbox URLs or preferred test data.

CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded in full at launch. Files in subdirectories load on demand when Claude reads files in those directories.

For large projects, you can break instructions into topic-specific files using project rules under .claude/rules/, which let you scope instructions to specific file types or subdirectories.

Setting up a project CLAUDE.md

A project CLAUDE.md can be stored in either ./CLAUDE.md or ./.claude/CLAUDE.md. Add instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows. Because these files are shared through version control, keep them focused on project-level standards rather than personal preferences.

To confirm the file loaded, run /context in a session and check the list under Memory files.

Generate a starting point with /init

Run /init to generate a starting CLAUDE.md automatically. Claude analyzes your codebase and creates a file with build commands, test instructions, and project conventions it discovers. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it. From there, refine it with instructions Claude wouldn't discover on its own.

There is also an interactive mode: set CLAUDE_CODE_NEW_INIT=1 to enable a multi-phase flow. In this mode, /init asks which artifacts to set up (CLAUDE.md files, skills, and hooks), explores your codebase with a subagent, fills in gaps via follow-up questions, and presents a reviewable proposal before writing any files.

Auto memory in brief

Auto memory is the complement to CLAUDE.md: Claude accumulates learnings automatically based on your corrections and preferences, without you writing anything. It is scoped per repository and shared across worktrees, and the first 200 lines or 25KB of it is loaded into every session. Typical contents include build commands, debugging insights, and preferences Claude discovers during your work together.

A note on this guide

This guide is based on Anthropic's documentation page "How Claude remembers your project" at code.claude.com. This site is an independent publication and is not affiliated with or endorsed by Anthropic. The source page also covers troubleshooting memory issues and further detail on load resolution order; consult the official docs for the complete reference.

---

claudedetails.com is an independent publication and is not affiliated with, endorsed by, or sponsored by Anthropic. "Claude" is a trademark of Anthropic, PBC, used here for identification purposes only. Product details can change — always confirm specifics on Anthropic's own site before making decisions based on this post.