Text of code.claude.com › docs › en › memory as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

How Claude remembers your project - Claude Code Docs

Documentation Index Fetch the complete documentation index at: /docs/llms.txt Use this file to discover all available pages before exploring further. Skip to main content Assistant Responses are generated using AI and may contain mistakes. 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.

Claude can also read a repository’s AGENTS.md files in place of CLAUDE.md Auto memory : notes Claude writes itself based on your corrections and preferences This page covers how to: Write and organize CLAUDE.md files Use an existing AGENTS.md as your project instructions Scope rules to specific file types with .claude/rules/ Configure auto memory so Claude takes notes automatically Troubleshoot when instructions aren’t being followed CLAUDE.md vs auto memory Claude Code has two complementary memory systems.

Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. 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. 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 Your preferences, corrections you give Claude, project context Claude can’t derive from the code Use CLAUDE.md files when you want to guide Claude’s behavior.

Auto memory lets Claude learn from your corrections without manual effort. Subagents can also maintain their own auto memory. See subagent configuration for details. CLAUDE.md files CLAUDE.md files are markdown files that give Claude persistent instructions for a project, your personal workflow, or your entire organization. You write these files in plain text; Claude reads them at the start of every session. If your repository uses AGENTS.md instead, see AGENTS.md .

When to add to CLAUDE.md Treat CLAUDE.md as the place you write down what you’d otherwise re-explain. Add 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, move it to a skill or a path-scoped rule instead. The extension overview covers when to use each mechanism. Choose where to put CLAUDE.md files CLAUDE.md files can live in several locations, each with a different scope. The table below lists them in load order, from broadest scope to most specific, so a project instruction appears in context after a user instruction.

Scope Location Purpose Use case examples 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 Organization-wide instructions managed by IT/DevOps Company coding standards, security policies, compliance requirements All users in organization User instructions ~/.claude/CLAUDE.md Personal preferences for all projects Code styling preferences, personal tooling shortcuts Only you (all projects) Project instructions ./CLAUDE.md or ./.claude/CLAUDE.md .

See AGENTS.md for when ./AGENTS.md loads instead of or alongside them Team-shared instructions for the project Project architecture, coding standards, common workflows Team members via source control Local instructions ./CLAUDE.local.md Personal project-specific preferences; add to .gitignore Your sandbox URLs, preferred test data Only you (current project) CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded at launch.

Files in subdirectories load on demand. See How CLAUDE.md files load for when they load and the full resolution order. For large projects, you can break instructions into topic-specific files using project rules . Rules let you scope instructions to specific file types or subdirectories. Set up a project CLAUDE.md A project CLAUDE.md can be stored in either ./CLAUDE.md or ./.claude/CLAUDE.md . Create this file and add instructions that apply to anyone working on the project: build and test commands, coding standards, architectural decisions, naming conventions, and common workflows.

These instructions are shared with your team through version control, so focus on project-level standards rather than personal preferences. To confirm the file loaded, run /context all in a session and check the list under Memory files . In fullscreen mode , /context alone collapses that list. 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. Refine from there with instructions Claude wouldn’t discover on its own. For an interactive multi-phase flow instead, set the CLAUDE_CODE_NEW_INIT environment variable to 1 before you run /init . Set it in your shell or in the env block of a settings file, as shown in Set environment variables . With it set, /init asks which artifacts to set up: CLAUDE.md files, skills, and hooks.

It then explores your codebase with a subagent, fills in gaps via follow-up questions, and presents a reviewable proposal before writing any files. The variable only changes how /init runs, so you can leave it set. Write effective instructions Claude treats CLAUDE.md files as context, not enforced configuration, so how you write instructions affects how reliably Claude follows them. Write instructions that are concrete enough to verify: “Use 2-space indentation” instead of “Format code properly” “Run npm test before committing” instead of “Test your changes” “API handlers live in src/api/handlers/ ” instead of “Keep files organized” Keep your files short, organized, and consistent: Size : target under 200 lines per CLAUDE.md file.

Longer files consume more context and reduce adherence. Move instructions that matter for only part of the codebase into path-scoped rules , which load only when Claude works with matching files. Imports help you organize a long file but don’t reduce its context cost, because imported files load together with the CLAUDE.md that imports them. Structure : group related instructions under markdown headers and bullets. Organized sections are easier for Claude to follow than dense paragraphs.

Consistency : if two instructions contradict each other, Claude may pick one arbitrarily. Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and .claude/rules/ periodically to remove outdated or conflicting instructions. To have Claude find them for you, run a prompt audit . Audit your instruction files To have Claude check your instruction files for outdated or conflicting content, run /doctor prompt-audit in a session.

Claude looks for problems such as instructions written for older models, references to files or commands that don’t exist, and files that contradict each other. You get a report of findings with proposed edits, and nothing in your files changes until you ask Claude to apply them. By default, the audit covers your CLAUDE.md, CLAUDE.local.md, and AGENTS.md files, plus the rules, skills, commands, subagents, and output styles under .claude/ and ~/.claude/ .

To audit one file or directory instead, pass its path, for example /doctor prompt-audit .claude/ski

The rest of this page is on the live site.