2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
3> Use this file to discover all available pages before exploring further.3> Use this file to discover all available pages before exploring further.
4 4
5# Manage Claude's memory5# How Claude remembers your project
6 6
7> Learn how to manage Claude Code's memory across sessions with different memory locations and best practices.7> Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automatically with auto memory.
8 8
9Claude Code has two kinds of memory that persist across sessions:9Each Claude Code session begins with a fresh context window. Two mechanisms carry knowledge across sessions:
10 10
11* **Auto memory**: Claude automatically saves useful context like project patterns, key commands, and your preferences. This persists across sessions.11* **CLAUDE.md files**: instructions you write to give Claude persistent context
12* **CLAUDE.md files**: Markdown files you write and maintain with instructions, rules, and preferences for Claude to follow.12* **Auto memory**: notes Claude writes itself based on your corrections and preferences
13 13
14Both are loaded into Claude's context at the start of every session, though auto memory loads only the first 200 lines of its main file.14This page covers how to:
15 15
16## Determine memory type16* [Write and organize CLAUDE.md files](#claudemd-files)
17* [Scope rules to specific file types](#organize-rules-with-clauderules) with `.claude/rules/`
18* [Configure auto memory](#auto-memory) so Claude takes notes automatically
19* [Troubleshoot](#troubleshoot-memory-issues) when instructions aren't being followed
17 20
18Claude Code offers several memory locations in a hierarchical structure, each serving a different purpose:21## CLAUDE.md vs auto memory
19 22
20| Memory Type | Location | Purpose | Use Case Examples | Shared With |23Claude Code has two complementary memory systems. Both are loaded at the start of every conversation. Claude treats them as context, not enforced configuration. The more specific and concise your instructions, the more consistently Claude follows them.
21| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |
22| **Managed policy** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />• Linux: `/etc/claude-code/CLAUDE.md`<br />• 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 |
23| **Project memory** | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team-shared instructions for the project | Project architecture, coding standards, common workflows | Team members via source control |
24| **Project rules** | `./.claude/rules/*.md` | Modular, topic-specific project instructions | Language-specific guidelines, testing conventions, API standards | Team members via source control |
25| **User memory** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Just you (all projects) |
26| **Project memory (local)** | `./CLAUDE.local.md` | Personal project-specific preferences | Your sandbox URLs, preferred test data | Just you (current project) |
27| **Auto memory** | `~/.claude/projects/<project>/memory/` | Claude's automatic notes and learnings | Project patterns, debugging insights, architecture notes | Just you (per project) |
28 24
29CLAUDE.md files in the directory hierarchy above the working directory are loaded in full at launch. CLAUDE.md files in child directories load on demand when Claude reads files in those directories. Auto memory loads only the first 200 lines of `MEMORY.md`. More specific instructions take precedence over broader ones.25| | CLAUDE.md files | Auto memory |
26| :------------------- | :------------------------------------------------ | :--------------------------------------------------------------- |
27| **Who writes it** | You | Claude |
28| **What it contains** | Instructions and rules | Learnings and patterns |
29| **Scope** | Project, user, or org | Per working tree |
30| **Loaded into** | Every session | Every session (first 200 lines) |
31| **Use for** | Coding standards, workflows, project architecture | Build commands, debugging insights, preferences Claude discovers |
30 32
31<Note>33Use CLAUDE.md files when you want to guide Claude's behavior. Auto memory lets Claude learn from your corrections without manual effort.
32 CLAUDE.local.md files are automatically added to .gitignore, making them ideal for private project-specific preferences that shouldn't be checked into version control.
33</Note>
34
35## Auto memory
36 34
37Auto memory is a persistent directory where Claude records learnings, patterns, and insights as it works. Unlike CLAUDE.md files that contain instructions you write for Claude, auto memory contains notes Claude writes for itself based on what it discovers during sessions.35Subagents can also maintain their own auto memory. See [subagent configuration](/en/sub-agents#enable-persistent-memory) for details.
38 36
39<Note>37## CLAUDE.md files
40 Auto memory is enabled by default. To toggle it on or off, use `/memory` and select the auto-memory toggle.
41</Note>
42 38
43### What Claude remembers39CLAUDE.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.
44 40
45As Claude works, it may save things like:41### Choose where to put CLAUDE.md files
46 42
47* Project patterns: build commands, test conventions, code style preferences43CLAUDE.md files can live in several locations, each with a different scope. More specific locations take precedence over broader ones.
48* Debugging insights: solutions to tricky problems, common error causes
49* Architecture notes: key files, module relationships, important abstractions
50* Your preferences: communication style, workflow habits, tool choices
51 44
52### Where auto memory is stored45| Scope | Location | Purpose | Use case examples | Shared with |
46| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |
47| **Managed policy** | • macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`<br />• Linux and WSL: `/etc/claude-code/CLAUDE.md`<br />• 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 |
48| **Project instructions** | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Team-shared instructions for the project | Project architecture, coding standards, common workflows | Team members via source control |
49| **User instructions** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Just you (all projects) |
50| **Local instructions** | `./CLAUDE.local.md` | Personal project-specific preferences, not checked into git | Your sandbox URLs, preferred test data | Just you (current project) |
53 51
54Each project gets its own memory directory at `~/.claude/projects/<project>/memory/`. The `<project>` path is derived from the git repository root, so all subdirectories within the same repo share one auto memory directory. Git worktrees get separate memory directories. Outside a git repo, the working directory is used instead.52CLAUDE.md files in the directory hierarchy above the working directory are loaded in full at launch. CLAUDE.md files in subdirectories load on demand when Claude reads files in those directories. See [How CLAUDE.md files load](#how-claudemd-files-load) for the full resolution order.
55
56The directory contains a `MEMORY.md` entrypoint and optional topic files:
57
58```text theme={null}
59~/.claude/projects/<project>/memory/
60├── MEMORY.md # Concise index, loaded into every session
61├── debugging.md # Detailed notes on debugging patterns
62├── api-conventions.md # API design decisions
63└── ... # Any other topic files Claude creates
64```
65 53
66`MEMORY.md` acts as an index of the memory directory. Claude reads and writes files in this directory throughout your session, using `MEMORY.md` to keep track of what's stored where.54For large projects, you can break instructions into topic-specific files using [project rules](#organize-rules-with-clauderules). Rules let you scope instructions to specific file types or subdirectories.
67 55
68### How it works56### Set up a project CLAUDE.md
69 57
70* The first 200 lines of `MEMORY.md` are loaded into Claude's system prompt at the start of every session. Content beyond 200 lines is not loaded automatically, and Claude is instructed to keep it concise by moving detailed notes into separate topic files.58A 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.
71* Topic files like `debugging.md` or `patterns.md` are not loaded at startup. Claude reads them on demand using its standard file tools when it needs the information.
72* Claude reads and writes memory files during your session, so you'll see memory updates happen as you work.
73 59
74### Manage auto memory60<Tip>
61 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.
62</Tip>
75 63
76Auto memory files are markdown files you can edit at any time. Use `/memory` to open the file selector, which includes your auto memory entrypoint alongside your CLAUDE.md files. The `/memory` selector also includes an auto-memory toggle to turn the feature on or off.64### Write effective instructions
77 65
78To ask Claude to save something specific, tell it directly: "remember that we use pnpm, not npm" or "save to memory that the API tests require a local Redis instance".66CLAUDE.md files are loaded into the context window at the start of every session, consuming tokens alongside your conversation. Because they're context rather than enforced configuration, how you write instructions affects how reliably Claude follows them. Specific, concise, well-structured instructions work best.
79 67
80You can also control auto memory through settings or environment variables.68**Size**: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. If your instructions are growing large, split them using [imports](#import-additional-files) or [`.claude/rules/`](#organize-rules-with-clauderules) files.
81 69
82Disable auto memory for all projects by adding `autoMemoryEnabled` to your user settings:70**Structure**: use markdown headers and bullets to group related instructions. Claude scans structure the same way readers do: organized sections are easier to follow than dense paragraphs.
83 71
84```json theme={null}72**Specificity**: write instructions that are concrete enough to verify. For example:
85// ~/.claude/settings.json
86{ "autoMemoryEnabled": false }
87```
88 73
89Disable auto memory for a single project by adding `autoMemoryEnabled` to the project settings:74* "Use 2-space indentation" instead of "Format code properly"
75* "Run `npm test` before committing" instead of "Test your changes"
76* "API handlers live in `src/api/handlers/`" instead of "Keep files organized"
90 77
91```json theme={null}78**Consistency**: if two rules contradict each other, Claude may pick one arbitrarily. Review your CLAUDE.md files, nested CLAUDE.md files in subdirectories, and [`.claude/rules/`](#organize-rules-with-clauderules) periodically to remove outdated or conflicting instructions. In monorepos, use [`claudeMdExcludes`](#exclude-specific-claudemd-files) to skip CLAUDE.md files from other teams that aren't relevant to your work.
92// .claude/settings.json
93{ "autoMemoryEnabled": false }
94```
95 79
96Override all other settings with the `CLAUDE_CODE_DISABLE_AUTO_MEMORY` environment variable. This takes precedence over both the `/memory` toggle and `settings.json`, making it useful for CI or managed environments:80### Import additional files
97 81
98```bash theme={null}82CLAUDE.md files can import additional files using `@path/to/import` syntax. Imported files are expanded and loaded into context at launch alongside the CLAUDE.md that references them.
99export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 # Force off
100export CLAUDE_CODE_DISABLE_AUTO_MEMORY=0 # Force on
101```
102 83
103## CLAUDE.md imports84Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the working directory. Imported files can recursively import other files, with a maximum depth of five hops.
104 85
105CLAUDE.md files can import additional files using `@path/to/import` syntax. The following example imports 3 files:86To pull in a README, package.json, and a workflow guide, reference them with `@` syntax anywhere in your CLAUDE.md:
106 87
107```88```text theme={null}
108See @README for project overview and @package.json for available npm commands for this project.89See @README for project overview and @package.json for available npm commands for this project.
109 90
110# Additional Instructions91# Additional Instructions
111- git workflow @docs/git-instructions.md92- git workflow @docs/git-instructions.md
112```93```
113 94
114Both relative and absolute paths are allowed. Relative paths resolve relative to the file containing the import, not the working directory. For private per-project preferences that shouldn't be checked into version control, prefer `CLAUDE.local.md`: it is automatically loaded and added to `.gitignore`.95For private per-project preferences that shouldn't be checked into version control, use `CLAUDE.local.md`: it is automatically loaded and added to `.gitignore`.
115 96
116If you work across multiple git worktrees, `CLAUDE.local.md` only exists in one. Use a home-directory import instead so all worktrees share the same personal instructions:97If you work across multiple git worktrees, `CLAUDE.local.md` only exists in one. Use a home-directory import instead so all worktrees share the same personal instructions:
117 98
118```99```text theme={null}
119# Individual Preferences100# Individual Preferences
120- @~/.claude/my-project-instructions.md101- @~/.claude/my-project-instructions.md
121```102```
122 103
123<Warning>104<Warning>
124 The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the specific files. Approve to load them; decline to skip them. This is a one-time decision per project: once declined, the dialog does not resurface and the imports remain disabled.105 The first time Claude Code encounters external imports in a project, it shows an approval dialog listing the files. If you decline, the imports stay disabled and the dialog does not appear again.
125</Warning>106</Warning>
126 107
127To avoid potential collisions, imports are not evaluated inside markdown code spans and code blocks.108For a more structured approach to organizing instructions, see [`.claude/rules/`](#organize-rules-with-clauderules).
128 109
129```110### How CLAUDE.md files load
130This code span will not be treated as an import: `@anthropic-ai/claude-code`
131```
132 111
133Imported files can recursively import additional files, with a max-depth of 5 hops. You can see what memory files are loaded by running `/memory` command.112Claude Code reads CLAUDE.md files by walking up the directory tree from your current working directory, checking each directory along the way for CLAUDE.md and CLAUDE.local.md files. This means if you run Claude Code in `foo/bar/`, it loads instructions from both `foo/bar/CLAUDE.md` and `foo/CLAUDE.md`.
134 113
135## How Claude looks up memories114Claude also discovers CLAUDE.md files in subdirectories under your current working directory. Instead of loading them at launch, they are included when Claude reads files in those subdirectories.
136 115
137Claude Code reads memories recursively: starting in the cwd, Claude Code recurses up to (but not including) the root directory */* and reads any CLAUDE.md or CLAUDE.local.md files it finds. This is especially convenient when working in large repositories where you run Claude Code in *foo/bar/*, and have memories in both *foo/CLAUDE.md* and *foo/bar/CLAUDE.md*.116If you work in a large monorepo where other teams' CLAUDE.md files get picked up, use [`claudeMdExcludes`](#exclude-specific-claudemd-files) to skip them.
138 117
139Claude will also discover CLAUDE.md nested in subtrees under your current working directory. Instead of loading them at launch, they are only included when Claude reads files in those subtrees.118#### Load from additional directories
140
141### Load memory from additional directories
142 119
143The `--add-dir` flag gives Claude access to additional directories outside your main working directory. By default, CLAUDE.md files from these directories are not loaded.120The `--add-dir` flag gives Claude access to additional directories outside your main working directory. By default, CLAUDE.md files from these directories are not loaded.
144 121
145To also load memory files (CLAUDE.md, .claude/CLAUDE.md, and .claude/rules/\*.md) from additional directories, set the `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` environment variable:122To also load CLAUDE.md files from additional directories, including `CLAUDE.md`, `.claude/CLAUDE.md`, and `.claude/rules/*.md`, set the `CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD` environment variable:
146 123
147```bash theme={null}124```bash theme={null}
148CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config125CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config
149```126```
150 127
151## Directly edit memories with `/memory`128### Organize rules with `.claude/rules/`
152
153Use the `/memory` command during a session to open any memory file in your system editor for more extensive additions or organization.
154 129
155## Set up project memory130For larger projects, you can organize instructions into multiple files using the `.claude/rules/` directory. This keeps instructions modular and easier for teams to maintain. Rules can also be [scoped to specific file paths](#path-specific-rules), so they only load into context when Claude works with matching files, reducing noise and saving context space.
156 131
157Suppose you want to set up a CLAUDE.md file to store important project information, conventions, and frequently used commands. Project memory can be stored in either `./CLAUDE.md` or `./.claude/CLAUDE.md`.132<Note>
158 133 Rules load into context every session or when matching files are opened. For task-specific instructions that don't need to be in context all the time, use [skills](/en/skills) instead, which only load when you invoke them or when Claude determines they're relevant to your prompt.
159Bootstrap a CLAUDE.md for your codebase with the following command:134</Note>
160
161```
162> /init
163```
164
165<Tip>
166 Tips:
167
168 * Include frequently used commands (build, test, lint) to avoid repeated searches
169 * Document code style preferences and naming conventions
170 * Add important architectural patterns specific to your project
171 * CLAUDE.md memories can be used for both instructions shared with your team and for your individual preferences.
172</Tip>
173
174## Modular rules with `.claude/rules/`
175
176For larger projects, you can organize instructions into multiple files using the `.claude/rules/` directory. This allows teams to maintain focused, well-organized rule files instead of one large CLAUDE.md.
177 135
178### Basic structure136#### Set up rules
179 137
180Place markdown files in your project's `.claude/rules/` directory:138Place markdown files in your project's `.claude/rules/` directory. Each file should cover one topic, with a descriptive filename like `testing.md` or `api-design.md`. All `.md` files are discovered recursively, so you can organize rules into subdirectories like `frontend/` or `backend/`:
181 139
182```140```text theme={null}
183your-project/141your-project/
184├── .claude/142├── .claude/
185│ ├── CLAUDE.md # Main project instructions143│ ├── CLAUDE.md # Main project instructions
189│ └── security.md # Security requirements147│ └── security.md # Security requirements
190```148```
191 149
192All `.md` files in `.claude/rules/` are automatically loaded as project memory, with the same priority as `.claude/CLAUDE.md`.150Rules without [`paths` frontmatter](#path-specific-rules) are loaded at launch with the same priority as `.claude/CLAUDE.md`.
193 151
194### Path-specific rules152#### Path-specific rules
195 153
196Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns.154Rules can be scoped to specific files using YAML frontmatter with the `paths` field. These conditional rules only apply when Claude is working with files matching the specified patterns.
197 155
208- Include OpenAPI documentation comments166- Include OpenAPI documentation comments
209```167```
210 168
211Rules without a `paths` field are loaded unconditionally and apply to all files.169Rules without a `paths` field are loaded unconditionally and apply to all files. Path-scoped rules trigger when Claude reads files matching the pattern, not on every tool use.
212
213### Glob patterns
214 170
215The `paths` field supports standard glob patterns:171Use glob patterns in the `paths` field to match files by extension, directory, or any combination:
216 172
217| Pattern | Matches |173| Pattern | Matches |
218| ---------------------- | ---------------------------------------- |174| ---------------------- | ---------------------------------------- |
221| `*.md` | Markdown files in the project root |177| `*.md` | Markdown files in the project root |
222| `src/components/*.tsx` | React components in a specific directory |178| `src/components/*.tsx` | React components in a specific directory |
223 179
224You can specify multiple patterns:180You can specify multiple patterns and use brace expansion to match multiple extensions in one pattern:
225 181
226```markdown theme={null}182```markdown theme={null}
227---183---
228paths:184paths:
229 - "src/**/*.ts"185 - "src/**/*.{ts,tsx}"
230 - "lib/**/*.ts"186 - "lib/**/*.ts"
231 - "tests/**/*.test.ts"187 - "tests/**/*.test.ts"
232---188---
233```189```
234 190
235Brace expansion is supported for matching multiple extensions or directories:191#### Share rules across projects with symlinks
236 192
237```markdown theme={null}193The `.claude/rules/` directory supports symlinks, so you can maintain a shared set of rules and link them into multiple projects. Symlinks are resolved and loaded normally, and circular symlinks are detected and handled gracefully.
238paths:
239 - "src/**/*.{ts,tsx}"
240 - "{src,lib}/**/*.ts"
241 194
242# TypeScript/React Rules195This example links both a shared directory and an individual file:
243```
244 196
245This expands `src/**/*.{ts,tsx}` to match both `.ts` and `.tsx` files.197```bash theme={null}
198ln -s ~/shared-claude-rules .claude/rules/shared
199ln -s ~/company-standards/security.md .claude/rules/security.md
200```
246 201
247### Subdirectories202#### User-level rules
248 203
249Rules can be organized into subdirectories for better structure:204Personal rules in `~/.claude/rules/` apply to every project on your machine. Use them for preferences that aren't project-specific:
250 205
251```206```text theme={null}
252.claude/rules/207~/.claude/rules/
253├── frontend/208├── preferences.md # Your personal coding preferences
254│ ├── react.md209└── workflows.md # Your preferred workflows
255│ └── styles.md
256├── backend/
257│ ├── api.md
258│ └── database.md
259└── general.md
260```210```
261 211
262All `.md` files are discovered recursively.212User-level rules are loaded before project rules, giving project rules higher priority.
263 213
264### Symlinks214### Manage CLAUDE.md for large teams
265 215
266The `.claude/rules/` directory supports symlinks, allowing you to share common rules across multiple projects:216For organizations deploying Claude Code across teams, you can centralize instructions and control which CLAUDE.md files are loaded.
267 217
268```bash theme={null}218#### Deploy organization-wide CLAUDE.md
269# Symlink a shared rules directory
270ln -s ~/shared-claude-rules .claude/rules/shared
271 219
272# Symlink individual rule files220Organizations can deploy a centrally managed CLAUDE.md that applies to all users on a machine. This file cannot be excluded by individual settings.
273ln -s ~/company-standards/security.md .claude/rules/security.md221
222<Steps>
223 <Step title="Create the file at the managed policy location">
224 * macOS: `/Library/Application Support/ClaudeCode/CLAUDE.md`
225 * Linux and WSL: `/etc/claude-code/CLAUDE.md`
226 * Windows: `C:\Program Files\ClaudeCode\CLAUDE.md`
227 </Step>
228
229 <Step title="Deploy with your configuration management system">
230 Use MDM, Group Policy, Ansible, or similar tools to distribute the file across developer machines. See [managed settings](/en/permissions#managed-settings) for other organization-wide configuration options.
231 </Step>
232</Steps>
233
234#### Exclude specific CLAUDE.md files
235
236In large monorepos, ancestor CLAUDE.md files may contain instructions that aren't relevant to your work. The `claudeMdExcludes` setting lets you skip specific files by path or glob pattern.
237
238This example excludes a top-level CLAUDE.md and a rules directory from a parent folder. Add it to `.claude/settings.local.json` so the exclusion stays local to your machine:
239
240```json theme={null}
241{
242 "claudeMdExcludes": [
243 "**/monorepo/CLAUDE.md",
244 "/home/user/monorepo/other-team/.claude/rules/**"
245 ]
246}
274```247```
275 248
276Symlinks are resolved and their contents are loaded normally. Circular symlinks are detected and handled gracefully.249Patterns are matched against absolute file paths using glob syntax. You can configure `claudeMdExcludes` at any [settings layer](/en/settings#settings-files): user, project, local, or managed policy. Arrays merge across layers.
250
251Managed policy CLAUDE.md files cannot be excluded. This ensures organization-wide instructions always apply regardless of individual settings.
252
253## Auto memory
254
255Auto memory lets Claude accumulate knowledge across sessions without you writing anything. Claude saves notes for itself as it works: build commands, debugging insights, architecture notes, code style preferences, and workflow habits. Claude doesn't save something every session. It decides what's worth remembering based on whether the information would be useful in a future conversation.
277 256
278### User-level rules257### Enable or disable auto memory
279 258
280You can create personal rules that apply to all your projects in `~/.claude/rules/`:259Auto memory is on by default. To toggle it, open `/memory` in a session and use the auto memory toggle, or set `autoMemoryEnabled` in your project settings:
281 260
261```json theme={null}
262{
263 "autoMemoryEnabled": false
264}
282```265```
283~/.claude/rules/266
284├── preferences.md # Your personal coding preferences267To disable auto memory via environment variable, set `CLAUDE_CODE_DISABLE_AUTO_MEMORY=1`.
285└── workflows.md # Your preferred workflows268
269### Storage location
270
271Each project gets its own memory directory at `~/.claude/projects/<project>/memory/`. The `<project>` path is derived from the git repository, so all worktrees and subdirectories within the same repo share one auto memory directory. Outside a git repo, the project root is used instead.
272
273The directory contains a `MEMORY.md` entrypoint and optional topic files:
274
275```text theme={null}
276~/.claude/projects/<project>/memory/
277├── MEMORY.md # Concise index, loaded into every session
278├── debugging.md # Detailed notes on debugging patterns
279├── api-conventions.md # API design decisions
280└── ... # Any other topic files Claude creates
286```281```
287 282
288User-level rules are loaded before project rules, giving project rules higher priority.283`MEMORY.md` acts as an index of the memory directory. Claude reads and writes files in this directory throughout your session, using `MEMORY.md` to keep track of what's stored where.
289 284
290<Tip>285Auto memory is machine-local. All worktrees and subdirectories within the same git repository share one auto memory directory. Files are not shared across machines or cloud environments.
291 Best practices for `.claude/rules/`:
292 286
293 * **Keep rules focused**: Each file should cover one topic (e.g., `testing.md`, `api-design.md`)287### How it works
294 * **Use descriptive filenames**: The filename should indicate what the rules cover288
295 * **Use conditional rules sparingly**: Only add `paths` frontmatter when rules truly apply to specific file types289The first 200 lines of `MEMORY.md` are loaded at the start of every conversation. Content beyond line 200 is not loaded at session start. Claude keeps `MEMORY.md` concise by moving detailed notes into separate topic files.
296 * **Organize with subdirectories**: Group related rules (e.g., `frontend/`, `backend/`)290
297</Tip>291This 200-line limit applies only to `MEMORY.md`. CLAUDE.md files are loaded in full regardless of length, though shorter files produce better adherence.
292
293Topic files like `debugging.md` or `patterns.md` are not loaded at startup. Claude reads them on demand using its standard file tools when it needs the information.
294
295Claude reads and writes memory files during your session. When you see "Writing memory" or "Recalled memory" in the Claude Code interface, Claude is actively updating or reading from `~/.claude/projects/<project>/memory/`.
296
297### Audit and edit your memory
298
299Auto memory files are plain markdown you can edit or delete at any time. Run [`/memory`](#view-and-edit-with-memory) to browse and open memory files from within a session.
300
301## View and edit with `/memory`
302
303The `/memory` command lists all CLAUDE.md and rules files loaded in your current session, lets you toggle auto memory on or off, and provides a link to open the auto memory folder. Select any file to open it in your editor.
304
305When you ask Claude to remember something, like "always use pnpm, not npm" or "remember that the API tests require a local Redis instance," Claude saves it to auto memory. To add instructions to CLAUDE.md instead, ask Claude directly, like "add this to CLAUDE.md," or edit the file yourself via `/memory`.
306
307## Troubleshoot memory issues
308
309These are the most common issues with CLAUDE.md and auto memory, along with steps to debug them.
310
311### Claude isn't following my CLAUDE.md
312
313CLAUDE.md is context, not enforcement. Claude reads it and tries to follow it, but there's no guarantee of strict compliance, especially for vague or conflicting instructions.
314
315To debug:
316
317* Run `/memory` to verify your CLAUDE.md files are being loaded. If a file isn't listed, Claude can't see it.
318* Check that the relevant CLAUDE.md is in a location that gets loaded for your session (see [Choose where to put CLAUDE.md files](#choose-where-to-put-claudemd-files)).
319* Make instructions more specific. "Use 2-space indentation" works better than "format code nicely."
320* Look for conflicting instructions across CLAUDE.md files. If two files give different guidance for the same behavior, Claude may pick one arbitrarily.
321
322### I don't know what auto memory saved
323
324Run `/memory` and select the auto memory folder to browse what Claude has saved. Everything is plain markdown you can read, edit, or delete.
298 325
299## Organization-level memory management326### My CLAUDE.md is too large
300 327
301Organizations can deploy centrally managed CLAUDE.md files that apply to all users.328Files over 200 lines consume more context and may reduce adherence. Move detailed content into separate files referenced with `@path` imports (see [Import additional files](#import-additional-files)), or split your instructions across `.claude/rules/` files.
302 329
303To set up organization-level memory management:330### Instructions seem lost after `/compact`
304 331
3051. Create the managed memory file at the **Managed policy** location shown in the [memory types table above](#determine-memory-type).332CLAUDE.md fully survives compaction. After `/compact`, Claude re-reads your CLAUDE.md from disk and re-injects it fresh into the session. If an instruction disappeared after compaction, it was given only in conversation, not written to CLAUDE.md. Add it to CLAUDE.md to make it persist across sessions.
306 333
3072. Deploy via your configuration management system (MDM, Group Policy, Ansible, etc.) to ensure consistent distribution across all developer machines.334See [Write effective instructions](#write-effective-instructions) for guidance on size, structure, and specificity.
308 335
309## Memory best practices336## Related resources
310 337
311* **Be specific**: "Use 2-space indentation" is better than "Format code properly".338* [Skills](/en/skills): package repeatable workflows that load on demand
312* **Use structure to organize**: Format each individual memory as a bullet point and group related memories under descriptive markdown headings.339* [Settings](/en/settings): configure Claude Code behavior with settings files
313* **Review periodically**: Update memories as your project evolves to ensure Claude is always using the most up to date information and context.340* [Manage sessions](/en/sessions): manage context, resume conversations, and run parallel sessions
341* [Subagent memory](/en/sub-agents#enable-persistent-memory): let subagents maintain their own auto memory
