Claude Code 的记忆体系：CLAUDE.md 和 MEMORY.md

每次 Claude Code 会话都从一个空白的上下文窗口开始。有两种机制负责跨会话传递知识：

CLAUDE.md 文件：由你编写，给 Claude 提供持久化的上下文指令
自动记忆（Auto memory）：由 Claude 自己编写，基于你的纠正和偏好自动积累

类比来说：如果把 Claude Code 比作一位长期合作的工程师，CLAUDE.md 就是你交给他的项目手册与团队规范，而自动记忆则是他在日常协作中自己记下的工作日志------构建技巧、调试经验、你的代码偏好。两者都在每次会话开始时加载，共同构成 Claude 的"认知背景"。

一、CLAUDE.md：你写给 Claude 的持久指令

1.1 文件位置与作用域

CLAUDE.md 可以放在多个位置，每个位置对应不同的作用域。更具体的位置优先级高于更宽泛的位置。

graph TD A["托管策略级 (Managed Policy)\nmacOS: /Library/Application Support/ClaudeCode/CLAUDE.md\nLinux/WSL: /etc/claude-code/CLAUDE.md\nWindows: C:\\Program Files\\ClaudeCode\\CLAUDE.md\n作用范围：组织内所有用户"] B["用户级 (User Instructions)\n~/.claude/CLAUDE.md\n作用范围：个人所有项目"] C["项目级 (Project Instructions)\n./CLAUDE.md 或 ./.claude/CLAUDE.md\n作用范围：团队共享，进入版本控制"] D["项目本地级 (Local Instructions)\n./CLAUDE.local.md\n作用范围：仅本人当前项目，不进入版本控制"] A --> B --> C --> D style A fill:#1a1a2e,color:#e0e0e0 style B fill:#16213e,color:#e0e0e0 style C fill:#0f3460,color:#e0e0e0 style D fill:#1a4a7a,color:#e0e0e0

作用域	路径	共享范围
托管策略级	系统目录（见上图）	组织内所有用户
用户级	`~/.claude/CLAUDE.md`	仅本人，所有项目
项目级	`./CLAUDE.md`	团队成员（通过版本控制）
项目本地级	`./CLAUDE.local.md`	仅本人，当前项目（自动加入 `.gitignore`）

1.2 初始化项目 CLAUDE.md

在项目根目录执行 /init，Claude 会分析代码库，自动生成包含构建命令、测试指令和项目约定的初始文件。如果 CLAUDE.md 已存在，/init 会给出改进建议而不是覆盖。

shell 复制代码

> /init

项目级 CLAUDE.md 适合写入：构建和测试命令、编码规范、架构决策、命名约定、常用工作流。这些内容通过版本控制与团队共享，因此应聚焦于项目级标准，而非个人偏好。

1.3 如何编写有效指令

CLAUDE.md 在每次会话开始时被加载进上下文窗口，消耗 token。它是上下文而非强制配置，指令的写法直接影响 Claude 的遵从程度。

大小：每个 CLAUDE.md 文件建议控制在 200 行以内。文件越长，消耗的上下文越多，遵从度越低。超出部分可通过 @path 导入或 .claude/rules/ 拆分。

结构：使用 Markdown 标题和列表组织相关指令。结构清晰的内容比密集段落更容易被遵循。

具体性：指令要具体到可验证：

模糊写法	推荐写法
"Format code properly"	"Use 2-space indentation"
"Test your changes"	"Run `npm test` before committing"
"Keep files organized"	"API handlers live in `src/api/handlers/`"

一致性：如果两条规则相互矛盾，Claude 可能随机选择其中一条执行。定期检查并删除过期或冲突的指令。

1.4 文件加载机制

Claude Code 从当前工作目录（cwd）开始，向上递归遍历目录树，读取沿途所有 CLAUDE.md 和 CLAUDE.local.md 文件。

位于当前目录子树中的 CLAUDE.md 不在启动时加载，而是在 Claude 读取对应子目录下的文件时才动态引入。

1.5 文件导入：`@path` 语法

CLAUDE.md 支持通过 @path/to/file 语法导入其他文件。被导入文件会在启动时与引用它的 CLAUDE.md 一起展开并加载进上下文。支持相对路径和绝对路径，最大递归深度为 5 层。

markdown 复制代码

See @README for project overview and @package.json for available npm commands.

# Additional Instructions
- git workflow @docs/git-instructions.md
- Individual preferences @~/.claude/my-project-instructions.md

注意：代码块和行内代码中的 @ 路径不会被解析，以避免误触。

二、MEMORY.md：Claude 自动积累的跨会话笔记

2.1 什么是自动记忆

自动记忆让 Claude 无需你主动操作，就能跨会话积累知识。Claude 在工作过程中会为自己保存笔记，内容涵盖：构建命令、调试见解、架构笔记、代码风格偏好、工作流习惯。

Claude 并非每次会话都写入，而是自行判断哪些信息在未来对话中有复用价值，再决定是否保存。

当你要求 Claude 记住某些事情，例如"始终使用 pnpm 而不是 npm"，Claude 会将其保存到自动记忆中。如果想将指令写入 CLAUDE.md，需明确告诉 Claude："记住XXXX"，或通过 /memory 命令直接编辑文件。

2.2 开启与关闭

自动记忆默认开启。有三种方式控制它：

在会话中切换 ：执行 /memory，使用界面中的 auto memory 开关
通过配置文件关闭 ：在项目 settings 中设置：
json 复制代码
```
{
  "autoMemoryEnabled": false
}
```
通过环境变量关闭 ：
bash 复制代码
```
CLAUDE_CODE_DISABLE_AUTO_MEMORY=1
```

2.3 存储位置

每个项目拥有独立的记忆目录：

bash 复制代码

~/.claude/projects/<project>/memory/
├── MEMORY.md          # 简洁索引，每次会话加载前 200 行
├── debugging.md       # 调试模式的详细笔记
├── api-conventions.md # API 设计决策
└── ...                # Claude 创建的其他主题文件

<project> 路径从 git 仓库派生，因此同一仓库下的所有 worktree 和子目录共享同一个自动记忆目录。在 git 仓库之外则使用项目根目录。

自动记忆是机器本地的，不跨机器或云环境同步。

2.4 加载机制

flowchart TD A["会话启动"] --> B["加载 MEMORY.md 前 200 行作为索引"] B --> C["会话进行中"] C --> D{"需要详细笔记？"} D -->|"是"| E["Claude 按需读取\ndebugging.md / api-conventions.md 等主题文件"] D -->|"否"| F["继续使用已加载的索引内容"] E --> G["Claude 写入或更新记忆文件"] F --> G

MEMORY.md 作为记忆目录的索引，每次会话加载其前 200 行 。超过 200 行的内容不在会话启动时加载。Claude 通过将详细笔记移入独立主题文件来保持 MEMORY.md 的简洁。

主题文件（如 debugging.md）不在启动时加载，Claude 在需要时用标准文件工具按需读取。

当 Claude Code 界面出现 "Writing memory" 或 "Recalled memory" 提示时，说明 Claude 正在主动更新或读取 ~/.claude/projects/<project>/memory/ 下的文件。

注意：200 行限制仅适用于 MEMORY.md，CLAUDE.md 文件无论长度都会全量加载（但更短的文件遵从度更好）。

2.5 写入方式

flowchart TD A[产生值得记录的信息] --> B{写入方式} B --> C["Claude 自动写入\n（无需用户操作）"] B --> D["用户主动写入"] C --> C1["工作过程中自主识别并保存：\n构建命令 / 调试见解\n架构笔记 / 代码风格偏好 / 工作流习惯"] D --> D1["对话中告知 Claude\n如：'记住始终使用 pnpm'"] D --> D3["/memory 命令\n在编辑器中直接编辑"] C1 --> G[写入 MEMORY.md 或主题文件] D1 --> G D3 --> F["系统编辑器中直接编辑"] --> G

2.6 查看与编辑

执行 /memory 命令可以：

列出当前会话中已加载的所有 CLAUDE.md 和 rules 文件
切换自动记忆的开启/关闭状态
打开自动记忆目录的链接
选择任意文件在编辑器中打开

自动记忆文件是普通 Markdown，你可以随时读取、编辑或删除。

三、两者对比与定位

原文档对两种记忆机制的定位描述如下：

	CLAUDE.md 文件	自动记忆（MEMORY.md）
写入者	你	Claude
内容	指令与规范	学习成果与发现的模式
作用域	项目级、用户级或组织级	按工作树（working tree）
加载方式	每次会话全量加载	每次会话加载前 200 行
适合存放	编码标准、工作流、项目架构	构建命令、调试见解、Claude 发现的偏好

graph LR subgraph 你来写 CM["CLAUDE.md\n指令与规范\n层级分明 · 可版本控制\n编码标准 / 项目架构 / 工作流"] end subgraph Claude 来写 AM["MEMORY.md\n学习成果与模式\n机器本地 · 跨会话持久\n构建命令 / 调试见解 / 偏好习惯"] end CM -->|"启动时全量加载"| CTX["Claude Code 上下文"] AM -->|"启动时加载前 200 行"| CTX

用 CLAUDE.md 来引导 Claude 的行为；用自动记忆让 Claude 从你的纠正中学习，无需手动维护。两者共同作用，才能让 Claude Code 在每次会话中真正"开箱即用"。