Claude Code 的记忆系统

每次新开一个 Claude Code 会话，上下文窗口是空的。你之前告诉它的事情，它全忘了。

这不是 bug，是设计。问题在于，每次重新解释同一套规则，实在太麻烦。

Claude Code 提供了两套机制来解决这个问题：你自己写的 CLAUDE.md 文件，和它自己积累的自动记忆。两套机制互补，都在每次会话开始时加载到上下文里。

CLAUDE.md 是什么

CLAUDE.md 是一个普通的 Markdown 文件，你在里面写指令，Claude Code 每次启动时会读取它。可以理解为”给 AI 看的岗位说明书”。

它不是系统提示，不是强制配置。Claude 读它的方式和读你发送的消息一样——上下文而非硬约束。所以写法很重要：越具体，遵守度越高。

"使用 2 空格缩进" 比 "代码格式要好" 有效得多。

四个位置，四种作用域

CLAUDE.md 可以放在四个地方，作用范围不同：

托管策略（/Library/Application Support/ClaudeCode/CLAUDE.md on macOS）：公司 IT 部门管理，对机器上所有用户生效，个人无法排除。适合放安全策略、合规要求。

用户指令（~/.claude/CLAUDE.md）：你个人的全局配置，对你的所有项目生效。放代码风格偏好、个人工具快捷方式。

项目指令（./CLAUDE.md 或 ./.claude/CLAUDE.md）：随代码库版本控制，团队共享。放架构说明、编码标准、常见工作流。

本地指令（./CLAUDE.local.md，加入 .gitignore）：只影响你个人，不提交。放沙箱 URL、测试数据路径这类个人偏好。

加载顺序从上到下，全部拼接，不互相覆盖。离你工作目录越近的文件，在上下文里出现越晚，也就是越后被读到。

文件越短，遵守度越高

每个 CLAUDE.md 目标控制在 200 行以内。文件越长，消耗上下文越多，实际遵守度越低。

几个控制大小的办法：

@path/to/file 语法可以导入其他文件。比如 @README 或 @docs/git-instructions.md。导入的内容在启动时展开加载，跟直接写在文件里效果一样——不会省上下文，但能帮你组织结构。

块级 HTML 注释 <!-- 这段不会加载 --> 会在注入上下文前被剥离，可以给人类维护者留笔记而不占 token。

如果项目很大，用 .claude/rules/ 目录把规则拆成多个文件。

路径范围规则：按文件类型按需加载

.claude/rules/ 里的 Markdown 文件可以带 frontmatter，指定只对特定路径的文件生效：

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

# API 开发规则
- 所有端点必须包含输入验证
- 使用标准错误响应格式

没有 paths 字段的规则，在启动时无条件加载。有 paths 的规则，只在 Claude 读取匹配该路径的文件时才触发加载。

实际效果：后端规则不会出现在前端开发时的上下文里，减少噪音，节省空间。

.claude/rules/ 支持符号链接，可以把一份共享规则库链接到多个项目：

ln -s ~/shared-claude-rules .claude/rules/shared

自动记忆：Claude 自己的笔记本

自动记忆是另一套系统。不是你写，是 Claude 自己写。

当它发现一些跨会话值得记住的东西——你用的构建命令、你纠正过的偏好、调试某类问题的规律——它会主动保存下来。你在界面里会看到 “Writing memory” 的提示。

存储位置在本地：~/.claude/projects/<project>/memory/。机器本地，不同机器之间不同步。

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 索引，每次会话加载前 200 行
├── debugging.md       # 详细调试笔记（按需读取）
└── api-conventions.md # 约定记录（按需读取）

MEMORY.md 是入口，前 200 行或 25KB 在每次对话开始时加载。超过这个上限的内容，Claude 会把细节拆到主题子文件里——比如 debugging.md——启动时不加载，Claude 在需要时主动去读。

自动记忆默认开启。要关掉，在 /memory 命令里切换，或者在设置里加一行：

{
  "autoMemoryEnabled": false
}

两套系统的分工

CLAUDE.md 是你主动控制的。你想让 Claude 遵守什么规则，写进去。自动记忆是被动积累的，Claude 从你的对话里提炼它认为有用的东西。

两者都在每次会话开始时进入上下文，叠加生效。

常见问题

Claude 不遵循 CLAUDE.md 里的指令：运行 /memory 看这个文件是否被加载了。如果没列出来，Claude 看不到它。检查文件路径对不对。如果路径对但还是不遵守，多半是指令太模糊，或者不同文件里有冲突的指令。

/compact 之后指令消失了：项目根目录的 CLAUDE.md 在压缩后会重新注入。子目录里的嵌套文件不会自动重新加载，等 Claude 下次读到那个目录才会触发。会话过程中口头给的指令，压缩后不会恢复——想持久化就写进 CLAUDE.md。

Monorepo 里其他团队的 CLAUDE.md 被加载进来了：用 claudeMdExcludes 排除掉：

{
  "claudeMdExcludes": [
    "**/other-team/.claude/rules/**"
  ]
}

想看自动记忆存了什么：运行 /memory，选择自动记忆文件夹。全是普通 Markdown，可以直接编辑或删除。

作者：toy

CLAUDE.md 是上下文，不是约束。能不能遵守，取决于你写得够不够具体。200 行是经验值，不是硬限制，但超过了通常说明有些规则可以拆到更窄的范围去。