Memory in Claude Code means context that persists across sessions. Unlike the conversation window which resets, memory files are loaded automatically every time Claude Code starts. This module explains the hierarchy of memory files, how to create and update them, and how auto memory works in the background.
The Memory Hierarchy
Claude Code has two main memory systems: CLAUDE.md files that you write, and auto memory that Claude writes for itself. Officially documented CLAUDE.md locations are managed policy (org-wide), user instructions (~/.claude/CLAUDE.md), project instructions (./CLAUDE.md or ./.claude/CLAUDE.md — two alternative locations for the same project scope, not one shared file), and local instructions (./CLAUDE.local.md — personal project-specific, gitignored). All discovered files are concatenated into context rather than overriding each other — managed policy loads first (broadest scope), then user, project, and local instructions in order, with instructions closer to your working directory read last.
Project memory is the one you’ll use most. It’s a markdown file committed to git and shared with your team. Put your tech stack, naming conventions, common commands, and non-obvious gotchas here. User memory is for personal preferences that apply across all your projects — your preferred patterns, how you like code explained, tools you always use.
In practice: Use project memory for everything a teammate would need to understand the codebase — setup steps, testing commands, architecture decisions. Use user memory for how you personally like to work, not what the project does. When a project memory entry only matters to you (for example, a custom alias or local shortcut), put it in CLAUDE.local.md instead so it stays private.
For larger projects, split instructions into .claude/rules/*.md files. Rules can be global to the project or scoped to paths with frontmatter. A rule with paths: src/api/**/*.ts only activates when Claude works with matching files:
---
paths: src/api/**/*.ts
---
All API endpoints must validate input with Zod. Return 400 with field-level errors on validation failure.Path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use involving those files. Rules without a paths field are loaded at launch with the same priority as .claude/CLAUDE.md. Circular symlinks are detected and handled gracefully.
AGENTS.md Support
AGENTS.md is the cross-tool instructions file that several coding agents read. Since Claude Code v2.1.277, Claude reads it as your project instructions too — so a repository already set up for other agents works without adding a CLAUDE.md, an import, or a setting.
By default Claude reads AGENTS.md only when there is no CLAUDE.md:
AGENTS.md, and noCLAUDE.md,.claude/CLAUDE.md, orCLAUDE.local.mdin your working directory or above it → Claude reads yourAGENTS.md.AGENTS.mdand aCLAUDE.md,.claude/CLAUDE.md, orCLAUDE.local.mdin your working directory or above it → Claude reads yourCLAUDE.mdfiles only.- A
CLAUDE.mdthat imports@AGENTS.md→ Claude reads theCLAUDE.md, withAGENTS.mdpulled in through the import.
Your ~/.claude/CLAUDE.md, managed policy, and .claude/rules/ files don’t count for that check — they keep loading alongside AGENTS.md. When Claude does read it, you’ll see a line like no CLAUDE.md found; AGENTS.md loaded: /path/to/AGENTS.md in the session. Note that an AGENTS.md read this way is not listed by /memory or in the /context Memory files list — to confirm it loaded, look for that line or ask Claude what its project instructions say.
To change the default, open /config and set Project instructions — for example claude-md-and-agents-md to read both files together, claude-md to ignore AGENTS.md, or managed-only for organization-managed instructions only. You can also set it under the built-in agents-md plugin in pluginConfigs:
{
"pluginConfigs": {
"agents-md@builtin": {
"options": { "instructionFiles": "claude-md-and-agents-md" }
}
}
}In sessions where AGENTS.md support is unavailable (a version before v2.1.277, or providers and setups that don’t fetch feature flags), import it from a CLAUDE.md with @AGENTS.md so every tool still shares the one file.
Creating and Updating Memory
The fastest way to start is /init. Run it in your project directory and Claude analyzes the codebase to generate a starter CLAUDE.md. Set CLAUDE_CODE_NEW_INIT=1 to enable an interactive multi-phase flow — /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.
For larger edits, /memory opens your memory files in your system editor. Make changes, save, and Claude reloads them automatically. If you want Claude to remember something automatically, ask it naturally, like “remember that the API tests require Redis.” If you want it written into CLAUDE.md, ask Claude explicitly to add it there. The @path/to/file import syntax expands imported files and loads them into context at launch alongside the CLAUDE.md that references them — imported files still consume context tokens:
# Project Standards
@README.md
@docs/architecture.md
@package.jsonImports support a maximum depth of four hops. First-time imports from external paths trigger an approval dialog. If you decline, the imports stay disabled and the dialog does not appear again.
Auto Memory
Auto memory is a directory where Claude writes its own notes during sessions — patterns it discovers, project-specific behaviors, debugging insights. The first 200 lines or 25KB of ~/.claude/projects/<project>/memory/MEMORY.md, whichever comes first, load automatically at session start. Additional topic files (debugging.md, api-conventions.md) are loaded on demand.
Subagents can also maintain their own auto memory. See subagent configuration for details.
You don’t need to maintain auto memory manually; Claude handles writes itself. You can read and edit the files if you want to correct or add to Claude’s notes. You can toggle it in /memory, disable it for a session with CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 claude, or set autoMemoryEnabled in settings. To move the directory to a synced location or a custom path, set autoMemoryDirectory in your settings file. The value is read from any settings scope (user, project, local, policy, or --settings); project or local settings are honored under the same workspace trust rule as hooks in settings files:
{
"autoMemoryEnabled": true,
"autoMemoryDirectory": "/path/to/shared/memory"
}In large monorepos with many CLAUDE.md files, use claudeMdExcludes in settings to skip irrelevant ones:
{
"claudeMdExcludes": ["packages/legacy-app/CLAUDE.md", "vendors/**/CLAUDE.md"]
}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. In monorepos, claudeMdExcludes helps keep unrelated instructions out of context.
Write effective instructions
The context window visualization shows where CLAUDE.md loads relative to the rest of the startup context. Use it to understand how much room your instructions consume. Target under 200 lines per CLAUDE.md file — longer files consume more context and reduce adherence. If instructions are growing large, use path-scoped rules so instructions load only when Claude works with matching files.