奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

Claude Code 的记忆没被读到：memory 的加载位置与优先级

2026-08-18

现象：规则写了，但看起来没被读到

三种说法其实是三件事，混在一起就查不动：

一是「我在 CLAUDE.md 里写了『提交前先跑 lint』，它照样直接提交」。 二是「我在子目录里放了一份 CLAUDE.md，会话开头完全没有它的影子」。 三是「一开始还守规矩，/compact 之后就全忘了」。

这三种现象在 Claude Code 官方文档《How Claude remembers your project》（code.claude.com/docs/en/memory）里分别落在不同的段落：第二种和第三种是加载路径问题，第一种很可能根本不是加载问题。区分它们的第一步不是改文件，而是先确认这一次会话到底加载了什么。

第一步：先做能出结果的判定动作

官方文档在「Troubleshoot memory issues」一节给的第一条排查动作很具体：

在会话里运行 /context，查看 Memory files 下面那份列表，确认你的 CLAUDE.md 和 CLAUDE.local.md 加载了没有。文档原话是，如果某个文件不在那里，Claude 就看不到它。

这是整篇排查的分水岭。/context 回答的是「本次会话实际加载了哪些」。

另一个命令是 /memory，它列出 CLAUDE.md、CLAUDE.local.md 以及其它记忆文件的位置，包括那些还不存在的用户级与项目级 CLAUDE.md 条目；选中一个不存在的条目会先把文件创建出来。它同时提供 auto memory 的开关，以及打开 auto memory 文件夹的入口。

两个命令别搞混：/memory 告诉你「文件应该在哪、有没有」，/context 告诉你「这一次真的读进去了没有」。文档自己也在这一节里写明，要检查哪些文件真正加载进当前会话，用 /context。

还有一条更细的手段，文档以 Tip 的形式给出：用 InstructionsLoaded hook 记录到底哪些指令文件被加载、什么时候加载、为什么加载。文档说明这对调试路径作用域规则和子目录里的懒加载文件有用。

第二步：按加载位置对号入座

官方文档给出了 CLAUDE.md 的存放位置表，并明确说明「表格按加载顺序列出，从范围最广到最具体」：

范围位置
Managed policymacOS：/Library/Application Support/ClaudeCode/CLAUDE.md；Linux 与 WSL：/etc/claude-code/CLAUDE.md；Windows：C:\Program Files\ClaudeCode\CLAUDE.md
User instructions~/.claude/CLAUDE.md
Project instructions./CLAUDE.md 或 ./.claude/CLAUDE.md
Local instructions./CLAUDE.local.md

Windows 侧要多看一眼：code.claude.com/docs/en/claude-directory 写明，在 Windows 上 ~/.claude 解析为 %USERPROFILE%\.claude；如果你设了 CLAUDE_CONFIG_DIR，文档里所有 ~/.claude 路径都改到那个目录下面。所以「用户级规则没生效」的一个常见原因，是你把文件放在某个自以为是家目录的地方，而实际生效的是 CLAUDE_CONFIG_DIR 指向的位置。

项目级有两个合法位置：./CLAUDE.md 和 ./.claude/CLAUDE.md，文档把两者并列写明。放在别处会怎样，文档没有说明这一点——能确认的只有一件事：文档要求你运行 /context 看 Memory files 里有没有它，没列出来就是没被加载。

顺序方面，文档描述得很直白：Claude Code 从当前工作目录向上遍历目录树，逐级检查 CLAUDE.md 和 CLAUDE.local.md；发现的文件是拼接进上下文而不是互相覆盖，内容从文件系统根往下排，越靠近启动目录的越靠后被读到；同一目录内，CLAUDE.local.md 追加在 CLAUDE.md 之后。

这里藏着第二种现象的答案：工作目录下面子目录里的 CLAUDE.md 和 CLAUDE.local.md 不在启动时加载，文档写明它们是在 Claude 读取那些子目录里的文件时才被带进来。所以会话刚开始时你在 /context 里看不到它，属于文档描述的行为，不是丢了。

还有几条容易撞上的：

  • --add-dir 加进来的额外目录，默认不加载其中的 CLAUDE.md。要加载得设环境变量：
CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

文档说明它会加载该目录下的 CLAUDE.md、.claude/CLAUDE.md、.claude/rules/*.md 和 CLAUDE.local.md；如果你在 --setting-sources 里排除了 local，CLAUDE.local.md 会被跳过。

  • monorepo 里祖先目录的 CLAUDE.md 被捎带进来，可以用 claudeMdExcludes 按路径或 glob 跳过，文档给的示例是写进 .claude/settings.local.json：
{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

模式按绝对路径匹配，各设置层的数组会合并。反过来说，如果你排查的是「某份规则怎么被排除了」，这个键就是嫌疑对象。文档同时写明：managed policy 位置的 CLAUDE.md 不能被排除。

  • 项目里的 .claude/rules/ 也可能整批不加载：文档写明，如果你在 --setting-sources 里排除了 project，项目 rules 会被跳过；并注明在 v2.1.211 之前，按需加载的规则（含路径作用域规则和嵌套 .claude/rules/ 里的规则）即使排除了 project 也照样加载。版本不同结论不同，这类差异只能回文档核。

  • 用户级 ~/.claude/rules/ 与项目级 rules 都存在时，文档写明用户级规则先于项目规则加载，项目规则优先级更高。

  • AGENTS.md 不会被读。文档明说 Claude Code 读 CLAUDE.md，不读 AGENTS.md；已有 AGENTS.md 的仓库要建一个 CLAUDE.md 用 @AGENTS.md 导入它。也可以做 symlink，但文档特别提示：在 Windows 上创建 symlink 需要管理员权限或开发者模式，所以改用 @AGENTS.md 导入。这条对本站读者格外实用。

  • 项目级记忆文件里的 import，如果路径解析到工作目录之外（例如导入家目录下的文件），文档写明首次遇到时会出现一个列出这些文件的批准对话框；如果你拒绝了，这些 import 就保持禁用，而且对话框不会再出现。这意味着你以后不会再被提醒，只会看到「导入的内容一直不在上下文里」。用户范围记忆文件（如 ~/.claude/CLAUDE.md 和 ~/.claude/rules/）里的 import 不走这个对话框。

第三步：路径作用域规则为什么不触发

.claude/rules/ 下的文件可以用 YAML frontmatter 的 paths 字段限定作用范围：

---
paths:
  - "src/api/**/*.ts"
---

# API Development Rules

- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments

没有 paths 的规则无条件加载，加载优先级与 .claude/CLAUDE.md 相同；带 paths 的规则，文档写明是在 Claude 读取匹配的文件时触发，而不是每次工具调用都触发。所以「规则没生效」经常只是这一轮压根没碰到匹配的文件。

两个 glob 的坑，文档单独写了：

一是花括号展开有预算限制。文档说明每个 brace group 会让展开出的模式成倍增加，一条规则的整个 paths 列表共享一份展开预算；超预算的模式会被原样使用，其中的字面花括号匹配不到任何文件。文档还注明，在 v2.1.217 之前，带很多 brace group 的 paths 会让 CLI 在启动时卡住或崩溃。

二是方括号。glob 把 [ 当作 [abc] 这种字符组的开头，像 photos [2024/** 这种解析不成字符组的模式是无效的：它谁也匹配不到，同一条规则里的其它模式照常工作。文档给的转义写法是 photos \[2024/**。

以上片段与命令均按官方文档中的参数语义组合，未经实测，以官方文档与 --help 的实际输出为准。

第四步：/compact 之后消失的那一类

文档对第三种现象给了明确划线：项目根目录的 CLAUDE.md 能挺过压缩，/compact 之后 Claude 会从磁盘重新读取并重新注入会话；而子目录里的嵌套 CLAUDE.md、以及带 paths: frontmatter 的规则不会自动重注入，它们要等下一次 Claude 读到那个子目录里的文件、或读到匹配规则模式的文件时才重新加载。

文档由此给出三个判断：压缩后消失的指令，要么当初只是在对话里说过一次，要么在一份还没重新加载的嵌套 CLAUDE.md 里，要么是一条至今没匹配到文件的路径作用域规则。第一种的处置是把它写进 CLAUDE.md。

auto memory 那一半

auto memory 是 Claude 自己写的笔记，和你写的 CLAUDE.md 是两套机制，排查口子也不同。

存放位置：~/.claude/projects/<project>/memory/。文档写明 <project> 路径由 git 仓库推导，因此同一仓库的所有 worktree 和子目录共用一个 auto memory 目录；不在 git 仓库里则用项目根目录。auto memory 是本机的，不跨机器、不跨云端环境共享。

目录里有一个 MEMORY.md 入口文件当索引，外加若干话题文件（文档举的例子是 debugging.md、api-conventions.md 这类）。关键机制是：只有 MEMORY.md 开头的一部分会在每次会话开始时加载，文档给出的是一个行数阈值和一个体积阈值、以先到者为准（具体数值见官方 memory 页，属于随版本可能调整的实现细节）；超出阈值的内容在会话开始时不会被加载。话题文件不在启动时加载，Claude 需要时才用普通文件工具按需读取。

所以「我明明让它记住了，它却没用上」有一个很朴素的解释：那条内容躺在索引的靠后位置，或者躺在某个话题文件里没被读。文档还写明，MEMORY.md 写入后 Claude Code 会拿它对照读取上限：接近上限会提醒 Claude 精简（一条一行、细节挪到话题文件、合并或丢弃过时条目），超过上限则写入照样成功，但会返回一个要求重写索引的错误，因为超出部分在下次加载时会被丢掉。这个检查只量真正会加载的内容，YAML frontmatter 和块级 HTML 注释在加载前被剥掉、不计入。

这个上限只针对 MEMORY.md。文档明确写着 CLAUDE.md 文件不论多长都会被完整加载，只是越短遵循度越好。

开关与位置的处置项：auto memory 默认开启，/memory 里的开关会把 autoMemoryEnabled 写进用户设置 ~/.claude/settings.json；只对某个项目关掉就写进该项目的设置：

{
  "autoMemoryEnabled": false
}

用环境变量关闭则是 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。换存放位置用 autoMemoryDirectory：

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

文档写明该值必须是绝对路径或以 ~/ 开头，可从用户、项目、local、policy 或 --settings 任一设置范围读取；写在项目 .claude/settings.json 或 .claude/settings.local.json 里时，遵循与设置文件中 hooks 相同的工作区信任规则。

还有一条容易踩：主会话的 auto memory 不会加载进 subagent，例外是 fork——它继承父会话与系统提示。subagent 自己的 auto memory 由 subagent 的 memory 字段启用，是另一个独立目录。所以「主会话记住的事，交给 subagent 就不认」在文档里是预期行为。

什么情况说明不是加载的问题

如果 /context 的 Memory files 里已经列出了你那份文件，那么加载这条线就到此为止了，再折腾路径没有意义。文档把原因写得很清楚：

  • CLAUDE.md 的内容是在系统提示之后作为一条 user message 送进去的，不是系统提示的一部分。Claude 会读并尽量遵守，但不保证严格合规，指令越含糊、越互相冲突越不稳。
  • 两条规则互相矛盾时，文档写明 Claude 可能任意挑一条。跨多个 CLAUDE.md、嵌套 CLAUDE.md 与 .claude/rules/ 找冲突项，是这一步该做的事。
  • 文档在开头就把话说死了：CLAUDE.md 和 auto memory 都被当作上下文，不是被强制执行的配置。要不管 Claude 怎么决定都拦下某个动作，文档给的是 PreToolUse hook；要在系统提示层面加指令，用 --append-system-prompt，但它每次调用都得传，文档说更适合脚本与自动化而不是交互使用。

也就是说：文件在清单里 + 行为仍不符合预期 = 这是「指令是上下文而非强制层」的问题，处置方向是 hooks 与 permissions，不是继续挪文件。反过来，文件不在清单里，才轮到本文前四步。

本文依据 Claude Code 官方文档（code.claude.com/docs）于 2026-08-17 的公开内容整理。 该产品闭源，本文只复述官方文档写明的机制，不推断其内部实现； 我们没有对文中涉及的功能做过实测，因此不涉及界面外观、操作手感与运行速度的任何描述。 该产品迭代频繁，文中涉及的命令、配置项与默认值随版本变动，请以官方文档最新内容为准。 本文不涉及价格、额度与限流的具体数值，相关信息请以官方定价与用量说明页为准。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员