Understanding Claude Code’s Project Memory: Auto‑Memory and CLAUDE.md

Anthropic recently added an Auto Memory feature to its command‑line coding assistant Claude Code, aiming to let the model gradually accumulate knowledge of a long‑running project and reduce the developer’s burden of repeatedly providing context.

What is Project Memory?

Project memory consists of two complementary parts:

Auto Memory : Claude automatically records useful information during a session—e.g., "remember we use pnpm instead of npm "—and writes it to MEMORY.md.

CLAUDE.md : A developer‑authored Markdown file that explicitly defines project rules, conventions, and directives.

Together they form a sustainable AI‑assisted knowledge base.

Auto Memory vs CLAUDE.md

Writer : Auto Memory is written by Claude; CLAUDE.md is written by the developer.

Content : Auto Memory captures patterns, debugging tips, and preferences; CLAUDE.md contains explicit rules, coding standards, and context.

Location : Auto Memory lives under ~/.claude/projects/<project>/memory/; CLAUDE.md resides in the project directory hierarchy.

Management : Auto Memory is maintained automatically; CLAUDE.md must be kept up‑to‑date manually.

Scope : Auto Memory is per‑user per‑project; CLAUDE.md can be shared across a team.

Why Project Memory Matters

Without memory, Claude must be reminded of basics each time, such as:

"We use TypeScript"

"Indentation is two spaces"

"Error handling follows this pattern"

Repeating these statements interrupts the developer’s flow. With memory, the information loads automatically at session start, letting Claude act as a familiar collaborator.

CLAUDE.md Directive Mechanism

CLAUDE.md is a Markdown file read at every session start. Its location determines its scope:

Organization‑level : System directory – applies company‑wide policies.

Project‑level : ./CLAUDE.md or ./.claude/CLAUDE.md – applies to the current repository.

User‑level : ~/.claude/CLAUDE.md – personal preferences, not shared.

Claude walks up the directory tree from the current working directory, loading every CLAUDE.md it finds.

Writing Effective Directives

Control size : Keep each CLAUDE.md under 200 lines to avoid token overflow.

Structure : Use Markdown headings and lists for clear organization.

Specificity : Prefer concrete commands, e.g., "use two‑space indentation" over vague "format code".

Avoid conflicts : Ensure no contradictory directives exist across files.

Claude supports an @path/to/file import syntax, allowing reuse of existing docs (README, package.json, etc.) and keeping CLAUDE.md concise.

Organizing Large Projects

For monorepos, place modular rule files under .claude/rules/ (e.g., frontend/react.md, backend/api.md) and use YAML front‑matter paths to limit when each file loads.

Auto Memory Mechanics

Auto Memory records session information into MEMORY.md. Only the first 200 lines are loaded at the start of each session, which controls context consumption, keeps the index fresh, and enables on‑demand loading of detailed topic files (e.g., debugging.md).

Typical memory directory layout:

~/.claude/projects/<project>/memory/
├── MEMORY.md          # concise index loaded each session
├── debugging.md       # detailed notes on debugging
├── api-conventions.md # API design decisions
└── ...                # other topic files

Claude reads and writes these files automatically. Users can view, edit, or delete them at any time.

Enabling / Disabling Auto Memory

Method 1: Run /memory in a session and toggle the switch.

Method 2: Add { "autoMemoryEnabled": false } to the project’s JSON config.

Method 3: Set environment variable CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Reviewing and Editing Memory

Running /memory shows all loaded CLAUDE.md and rule files, lets you toggle Auto Memory, open the memory folder, or edit any file directly.

When you tell Claude "remember we use pnpm instead of npm" or "remember the API needs a local Redis instance", the statement is saved to MEMORY.md. To make it permanent, ask Claude to add it to CLAUDE.md or edit the file manually.

Sub‑Agent Persistent Memory

Sub‑agents can have their own memory scopes defined by a memory field in their Markdown definition:

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---
You are a code reviewer. Update your agent memory with patterns and conventions you discover.

Supported scopes: user: Shared across all projects (stored under ~/.claude/agent-memory/). project: Specific to the current repository (stored under .claude/agent-memory/). local: Private to the project and not committed (stored under .claude/agent-memory-local/).

When enabled, the sub‑agent automatically reads the first 200 lines of its MEMORY.md and can use read/write/edit tools to manage its knowledge.

Practical Best Practices

Default to the user scope for personal preferences.

Before a sub‑agent starts a task, ask it to "check its memory for known patterns".

After completing a task, have the sub‑agent "save what it learned" to its memory.

Project Initialization

Use the /init command to let Claude scan the repository and generate a starter CLAUDE.md with detected build commands, test scripts, directory layout, and common code patterns. The generated file can then be refined with team‑specific rules.

Team Collaboration vs Personal Preferences

Team‑wide rules (project architecture, coding standards, build commands, security policies) belong in the project‑level CLAUDE.md or .claude/rules/ and should be version‑controlled. Personal settings (editor shortcuts, local URLs, toolchain tweaks) go in user‑level files like ~/.claude/CLAUDE.md or CLAUDE.local.md, which are automatically ignored by Git.

Large‑Scale Organization

For monorepos, modularize rules under .claude/rules/ (e.g., frontend/, backend/, shared/) and use YAML paths to load files only when relevant files are processed. Exclude unrelated CLAUDE.md files via the claudeMdExcludes setting in settings.local.json and share common rule sets through symbolic links.

Common Issues & Solutions

Claude ignores CLAUDE.md directives : Verify the file is in a loaded location, make directives concrete, and check for conflicting rules.

Unclear what Auto Memory saved : Run /memory and open the memory folder; all files are plain Markdown.

CLAUDE.md exceeds 200 lines : Split large files using @path/to/file imports or move sections into .claude/rules/ sub‑files.

Commands disappear after /compact : Remember that /compact only affects the conversation view; persistent directives must be written to CLAUDE.md.

Conclusion and Outlook

Claude Code’s project memory mechanism enables the AI assistant to gradually understand a project’s structure and conventions, turning a one‑off helper into a long‑term virtual team member. By combining automatic learning (Auto Memory) with explicit developer rules (CLAUDE.md) and modular configuration, developers can achieve more stable, consistent, and efficient AI‑driven coding assistance.