How Claude remembers your project changedmemory
Nearest release: v2.1.284, published 16 hours after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 28 Sep 2026 00:42 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 28 Sep 2026 23:37 UTC.
Upstream edited
Recorded here
Lines+46added
Lines−46removed
From line
19
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits28to this page, all time
The whole hunk
from line 19, old and new numbered
/
from line 19
1919
2020Claude 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](/docs/en/hooks-guide) instead. The more specific and concise your instructions, the more consistently Claude follows them.
2121
22| | CLAUDE.md files | Auto memory |
23| :------------------- | :------------------------------------------------ | :----------------------------------------------------------------------------------------------- |
24| **Who writes it** | You | Claude |
25| **What it contains** | Instructions and rules | Learnings and patterns |
26| **Scope** | Project, user, or org | Per repository, shared across worktrees |
27| **Loaded into** | Every session | Every session (first 200 lines or 25KB) |
28| **Use for** | Coding standards, workflows, project architecture | Your preferences, corrections you give Claude, project context Claude can't derive from the code |
22| | CLAUDE.md files | Auto memory |
23| :- | :- | :- |
24| **Who writes it** | You | Claude |
25| **What it contains** | Instructions and rules | Learnings and patterns |
26| **Scope** | Project, user, or org | Per repository, shared across worktrees |
27| **Loaded into** | Every session | Every session (first 200 lines or 25KB) |
28| **Use for** | Coding standards, workflows, project architecture | Your preferences, corrections you give Claude, project context Claude can't derive from the code |
2929
3030Use CLAUDE.md files when you want to guide Claude's behavior. Auto memory lets Claude learn from your corrections without manual effort.
3131
from line 50
5050
5151CLAUDE.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.
5252
53| Scope | Location | Purpose | Use case examples | Shared with |
54| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------- |
55| **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 |
56| **User instructions** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Just you (all projects) |
57| **Project instructions** | `./CLAUDE.md` or `./.claude/CLAUDE.md`. See [AGENTS.md](#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 |
58| **Local instructions** | `./CLAUDE.local.md` | Personal project-specific preferences; add to `.gitignore` | Your sandbox URLs, preferred test data | Just you (current project) |
53| Scope | Location | Purpose | Use case examples | Shared with |
54| - | - | - | - | - |
55| **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 |
56| **User instructions** | `~/.claude/CLAUDE.md` | Personal preferences for all projects | Code styling preferences, personal tooling shortcuts | Just you (all projects) |
57| **Project instructions** | `./CLAUDE.md` or `./.claude/CLAUDE.md`. See [AGENTS.md](#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 |
58| **Local instructions** | `./CLAUDE.local.md` | Personal project-specific preferences; add to `.gitignore` | Your sandbox URLs, preferred test data | Just you (current project) |
5959
6060CLAUDE.md and CLAUDE.local.md files in the directory hierarchy above the working directory are loaded at launch. Files in subdirectories load on demand when Claude reads files in those directories. See [How CLAUDE.md files load](#how-claude-md-files-load) for the full resolution order.
6161
from line 198
198198
199199Use glob patterns in the `paths` field to match files by extension, directory, or any combination:
200200
201| Pattern | Matches |
202| ---------------------- | ---------------------------------------- |
203| `**/*.ts` | All TypeScript files in any directory |
204| `src/**/*` | All files under `src/` directory |
205| `*.md` | Markdown files in the project root |
201| Pattern | Matches |
202| - | - |
203| `**/*.ts` | All TypeScript files in any directory |
204| `src/**/*` | All files under `src/` directory |
205| `*.md` | Markdown files in the project root |
206206| `src/components/*.tsx` | React components in a specific directory |
207207
208208You can specify multiple patterns and use brace expansion to match multiple extensions in one pattern:
from line 228
228228
229229Configure a rule with YAML [frontmatter](/docs/en/glossary#frontmatter) between `---` markers at the top of the file. `paths` is the only field Claude Code reads from a rule; any other field is ignored without an error. Claude Code removes the frontmatter before loading the rule into context.
230230
231| Field | Required | Description |
232| :------ | :------- | :--------------------------------------------------------------------------------------------------------------------------- |
233| `paths` | No | Glob patterns that [scope the rule to matching files](#path-specific-rules). Accepts a YAML list or a comma-separated string |
231| Field | Required | Description |
232| :- | :- | :- |
233| `paths` | No | Glob patterns that [scope the rule to matching files](#path-specific-rules). Accepts a YAML list or a comma-separated string |
234234
235235If the YAML between the markers doesn't parse, Claude Code ignores the frontmatter and loads the rule as if it had no `paths`. Run `claude --debug` to see the parse error.
236236
from line 299
299299
300300A managed CLAUDE.md and [managed settings](/docs/en/managed-settings) serve different purposes. Use settings for technical enforcement and CLAUDE.md for behavioral guidance:
301301
302| Concern | Configure in |
303| :--------------------------------------------- | :-------------------------------------------------------- |
304| Block specific tools, commands, or file paths | Managed settings: `permissions.deny` |
305| Enforce sandbox isolation | Managed settings: `sandbox.enabled` |
306| Environment variables and API provider routing | Managed settings: `env` |
307| Login method and organization restrictions | Managed settings: `forceLoginMethod`, `forceLoginOrgUUID` |
308| Code style and quality guidelines | Managed CLAUDE.md |
309| Data handling and compliance reminders | Managed CLAUDE.md |
310| Behavioral instructions for Claude | Managed CLAUDE.md |
302| Concern | Configure in |
303| :- | :- |
304| Block specific tools, commands, or file paths | Managed settings: `permissions.deny` |
305| Enforce sandbox isolation | Managed settings: `sandbox.enabled` |
306| Environment variables and API provider routing | Managed settings: `env` |
307| Login method and organization restrictions | Managed settings: `forceLoginMethod`, `forceLoginOrgUUID` |
308| Code style and quality guidelines | Managed CLAUDE.md |
309| Data handling and compliance reminders | Managed CLAUDE.md |
310| Behavioral instructions for Claude | Managed CLAUDE.md |
311311
312312Settings rules are enforced by the client regardless of what Claude decides to do. CLAUDE.md instructions shape Claude's behavior but are not a hard enforcement layer.
313313
from line 336
336336
337337Claude Code can read [`AGENTS.md`](/docs/en/glossary#agents-md) as your project instructions, so a repository already set up for other coding agents works without adding a `CLAUDE.md`, an import, or a setting. This table shows what Claude reads by default for each combination of instruction files in your repository:
338338
339| Your repository has | Claude reads |
340| :-------------------------------------------------------------------------------------------- | :------------------------------------------------------------- |
341| An `AGENTS.md`, and no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | Your `AGENTS.md` |
342| An `AGENTS.md` and a `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | Your `CLAUDE.md` files only |
343| A `CLAUDE.md` that already [imports `AGENTS.md`](#share-one-file-with-other-coding-tools) | Your `CLAUDE.md`, with `AGENTS.md` included through the import |
339| Your repository has | Claude reads |
340| :- | :- |
341| An `AGENTS.md`, and no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | Your `AGENTS.md` |
342| An `AGENTS.md` and a `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it | Your `CLAUDE.md` files only |
343| A `CLAUDE.md` that already [imports `AGENTS.md`](#share-one-file-with-other-coding-tools) | Your `CLAUDE.md`, with `AGENTS.md` included through the import |
344344
345345To change the default, for example to have Claude always read both files, read only `CLAUDE.md`, or read only your organization's managed instructions, [change the **Project instructions** setting](#choose-which-instruction-files-load).
346346
from line 370
370370
371371To change which files Claude reads, type `/config` in a Claude Code session to open the settings panel, then set **Project instructions** to one of these values:
372372
373| Value | What Claude reads |
374| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
375| `claude-md-or-agents-md` | Your `CLAUDE.md` files, or your `AGENTS.md` files when you have no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it. This is the default |
376| `claude-md-and-agents-md` | Your `CLAUDE.md` and `AGENTS.md` files together, each directory's `CLAUDE.md` files first and its `AGENTS.md` after them. Claude Code skips an `AGENTS.md` it has already loaded, so one that your `CLAUDE.md` imports or symlinks to isn't read twice |
377| `claude-md` | Your `CLAUDE.md` files only |
378| `managed-only` | Only your organization's managed `CLAUDE.md` and [auto memory](#auto-memory) at launch. Your project, local, and user `CLAUDE.md` files, your `.claude/rules/` files, and every `AGENTS.md` are left out. A subdirectory's `CLAUDE.md` and `.claude/rules/` files, and [path-scoped rules](#path-specific-rules), still load when Claude reads a file there |
373| Value | What Claude reads |
374| :- | :- |
375| `claude-md-or-agents-md` | Your `CLAUDE.md` files, or your `AGENTS.md` files when you have no `CLAUDE.md` or `CLAUDE.local.md` in your working directory or above it. This is the default |
376| `claude-md-and-agents-md` | Your `CLAUDE.md` and `AGENTS.md` files together, each directory's `CLAUDE.md` files first and its `AGENTS.md` after them. Claude Code skips an `AGENTS.md` it has already loaded, so one that your `CLAUDE.md` imports or symlinks to isn't read twice |
377| `claude-md` | Your `CLAUDE.md` files only |
378| `managed-only` | Only your organization's managed `CLAUDE.md` and [auto memory](#auto-memory) at launch. Your project, local, and user `CLAUDE.md` files, your `.claude/rules/` files, and every `AGENTS.md` are left out. A subdirectory's `CLAUDE.md` and `.claude/rules/` files, and [path-scoped rules](#path-specific-rules), still load when Claude reads a file there |
379379
380380You can also set the value in a settings file instead of `/config`. Add it under the built-in `agents-md` plugin's ID in [`pluginConfigs`](/docs/en/settings-reference#pluginconfigs), in `~/.claude/settings.json`, a `--settings` file, or [managed settings](/docs/en/managed-settings). Claude Code ignores it in project and local settings files. This example has Claude read both files:
381381
from line 405
405405
406406An `AGENTS.md` that Claude reads through the **Project instructions** setting differs from a `CLAUDE.md` in these places:
407407
408| | `CLAUDE.md` | `AGENTS.md` read through the setting |
409| :------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------ |
410| [`InstructionsLoaded` hooks](/docs/en/hooks#instructionsloaded) | Fire | Don't fire. They fire as usual for an `AGENTS.md` that a `CLAUDE.md` imports or symlinks to |
411| Directories you add with `--add-dir` while [`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD`](#load-from-additional-directories) is set | Their `CLAUDE.md` loads | Their `AGENTS.md` doesn't load |
412| An `@path` import of a file outside your working directory | Claude Code asks you to approve [external imports](#import-additional-files) | Loads only if you already approved external imports for this project, with no prompt |
408| | `CLAUDE.md` | `AGENTS.md` read through the setting |
409| :- | :- | :- |
410| [`InstructionsLoaded` hooks](/docs/en/hooks#instructionsloaded) | Fire | Don't fire. They fire as usual for an `AGENTS.md` that a `CLAUDE.md` imports or symlinks to |
411| Directories you add with `--add-dir` while [`CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD`](#load-from-additional-directories) is set | Their `CLAUDE.md` loads | Their `AGENTS.md` doesn't load |
412| An `@path` import of a file outside your working directory | Claude Code asks you to approve [external imports](#import-additional-files) | Loads only if you already approved external imports for this project, with no prompt |
413413
414414### Remove an earlier AGENTS.md workaround
415415
No line in this hunk matches that.