How Claude Code Remembers Projects With CLAUDE.md

Each Claude Code session starts with a fresh context window, so the assistant has no memory of previous conversations by default. According to Anthropic’s documentation at https://code.claude.com/docs/en/memory, two mechanisms carry knowledge across sessions: CLAUDE.md files that developers write by hand, and auto memory, which is a set of notes that Claude writes for itself.

Both systems are loaded at the start of every conversation, and Claude treats them as context rather than enforced configuration. The documentation notes that there is no guarantee of strict compliance, especially for vague or conflicting instructions, and that the more specific and concise the instructions are, the more consistently Claude follows them.

CLAUDE.md Files Written By Developers

A CLAUDE.md file is a plain markdown file that gives Claude persistent instructions for a project, a personal workflow, or an entire organization. Developers write the file, and Claude reads it at the start of each session. The documentation describes good candidates for these files, including build and test commands, coding standards, architectural decisions, naming conventions, and common workflows.

The docs suggest adding to CLAUDE.md when Claude makes the same mistake a second time, when a code review catches something Claude should have known about the codebase, when the same correction gets typed in again, or when a new teammate would need the same context.

Anthropic recommends targeting under 200 lines per file, because longer files consume more context and can reduce adherence. The guidance also favors specificity: “Use 2-space indentation” is offered as a better instruction than “Format code properly,” and “Run npm test before committing” is preferred over “Test your changes.”

Files can live in several locations, each with a different scope. These include a managed policy file for organization-wide rules, a user file at ~/.claude/CLAUDE.md for personal preferences, a project file at ./CLAUDE.md or ./.claude/CLAUDE.md shared through source control, and a local ./CLAUDE.local.md for private per-project notes that can be added to .gitignore. Claude Code walks up the directory tree and concatenates all discovered files, ordering them from the filesystem root down to the working directory.

Auto Memory Written By Claude

Auto memory lets Claude accumulate knowledge across sessions without anyone writing it manually. As Claude works, it saves notes for itself covering build commands, debugging insights, architecture notes, code style preferences, and workflow habits. The documentation states that Claude does not save something every session and instead decides what is worth remembering based on whether the information would be useful in a future conversation.

Auto memory is on by default and requires Claude Code version 2.1.59 or later. Each project gets its own memory directory at ~/.claude/projects/<project>/memory/, derived from the git repository so that worktrees and subdirectories in the same repo share one directory. The directory holds a MEMORY.md index plus optional topic files such as debugging.md or api-conventions.md.

The first 200 lines of MEMORY.md, or the first 25KB, whichever comes first, are loaded at the start of every conversation, while topic files are read on demand. Auto memory files are plain markdown that can be edited or deleted at any time, and the /memory command lets developers browse and open them from within a session.

Setup And Verification

The documentation describes the /init command, which analyzes a codebase and generates a starting CLAUDE.md with build commands, test instructions, and discovered conventions. If a CLAUDE.md already exists, /init suggests improvements rather than overwriting it.

When an instruction is not being followed, the docs recommend running /memory to confirm the relevant files are loaded, making instructions more specific, and checking for conflicting guidance across files. For rules that must run at a fixed point, such as before every commit, the documentation points to hooks instead, since hooks execute as shell commands regardless of what Claude decides to do.