05｜Memory 入门：让上下文跨会话保留下来
理解记忆层级、初始化命令和跨会话上下文的生命周期。
理解记忆层级、初始化命令和跨会话上下文的生命周期。
上下文像会议桌面：摊得下的材料有限。把所有文件都倒上去不会更聪明，只会让关键证据被淹没。高质量上下文是及时、相关、可验证的信息组合。
本课交付物
把同一需求分别写成“倾倒全部背景”和“目标＋相关文件＋约束＋验收”两个版本，比较计划准确度、无关修改数和需要澄清的次数。
概览
Memory 让 Claude Code 在不同会话之间保留上下文。你可以把团队规范、项目规则、个人偏好和目录级约束写进 CLAUDE.md，让 Claude 在合适的时候自动加载。
Memory 命令速查
| 命令 | 作用 |
|---|---|
/init |
初始化项目级 CLAUDE.md |
/memory |
打开并编辑记忆文件 |
# |
快速把当前规则写入 memory |
快速上手：初始化 Memory
使用 /init
在项目目录中运行：
/init
Claude 会根据当前项目生成一个 CLAUDE.md，通常包含类似如下结构：
# 项目配置
## 项目概览
## 开发规范
使用 # 快速更新记忆
当你想把一句规则写入 memory 时，可以直接在输入前加 #：
# 这个项目始终使用 TypeScript 严格模式
# 优先使用 async/await，而不是 promise 链
# 每次提交前都运行 npm test
# 文件名统一使用 kebab-case
这会把规则加入当前会话能感知到的记忆中。
使用 /memory
/memory 会打开记忆编辑器，让你在不同范围之间切换：
- 受管策略记忆
- 项目记忆（
./CLAUDE.md） - 用户记忆（
~/.claude/CLAUDE.md） - 本地项目记忆
适合你把长期规则、项目规范和个人偏好分层管理。
Memory 架构
Claude Code 的记忆系统通常有以下层级：
| 层级 | 作用范围 | 典型内容 |
|---|---|---|
| 受管策略 | 组织级 | 合规、安全、统一流程 |
| 项目记忆 | 单个项目 | 架构、编码标准、工作流 |
| 目录记忆 | 子目录 | 模块约束、局部规范 |
| 用户记忆 | 单个用户 | 个人偏好、默认设置 |
记忆层级
Claude 会按更接近当前上下文的规则优先使用更具体的 memory。一般来说：
- 组织级规则优先于普通偏好
- 项目规则优先于个人偏好
- 目录级规则优先于项目级通用规则
排除规则
如果某些 CLAUDE.md 不应该被自动加载，可以通过 claudeMdExcludes 之类的设置排除。
配置文件层级
项目设置、用户设置和企业托管设置会共同影响 memory 的加载方式。你可以把它理解为：
- 组织策略
- 项目设置
- 本地设置
- 临时会话输入
模块化规则系统
Memory 不一定要写成一个巨大文件。你可以把规则拆成多个目录文件，再按路径组织。
通过 YAML frontmatter 设置路径规则
# API Development Rules
子目录与符号链接
你可以用子目录和 symlink 把局部规则复用到多个项目区域。
Memory 位置表
常见位置包括：
- 项目根目录的
CLAUDE.md - 用户目录的
~/.claude/CLAUDE.md - 子目录的
CLAUDE.md
Memory 更新生命周期
一般流程是：
- 创建或编辑
CLAUDE.md - Claude 重新加载
- 新规则在后续会话中生效
Auto Memory
Auto memory 让 Claude 根据当前目录自动寻找并加载合适的记忆文件。
工作方式
Claude 会根据当前工作目录、父目录和已配置路径，逐层查找相关 memory。
目录结构
project/
├── CLAUDE.md
├── src/
│ ├── CLAUDE.md
│ └── api/
│ └── CLAUDE.md
版本要求
某些 auto memory 行为依赖较新的 Claude Code 版本。
自定义 auto memory 目录
如果默认目录不适合你的项目，可以在设置中指定新的 memory 路径。
worktree 和仓库共享
在 worktree、monorepo 或多人协作场景中，auto memory 可以帮助保持规则一致。
Subagent 记忆
Subagents 也可以拥有自己的记忆范围，用于在各自职责内保持一致性。
控制 auto memory
# 当前会话禁用 auto memory
# 显式开启 auto memory
通过 --add-dir 添加额外目录
你可以用 --add-dir 把额外目录也加入 Claude 的可见范围，适合多目录协作。
实战示例
示例 1：项目记忆结构
# 项目配置
## 项目概览
## 架构
---
## 本站实战工作台
## 上下文不是越多越好
想象一张会议桌：系统规则、用户目标、仓库文件、命令输出和之前的对话都要争夺桌面。把整个仓库一次性倒上去，会让关键约束淹没在旧日志和无关代码里。上下文工程的目标不是“装满”，而是让当前决定所需的证据恰好在场。
相关性还会随步骤变化。规划时需要架构与接口，修复 CSS 时需要组件和设计 token，验证时需要测试命令与浏览器状态。昨天正确的上下文，今天可能只是噪声。
## 四层上下文清单
开始任务时按层准备：
- **恒定规则**：项目说明、安全边界、语言与设计约定。
- **任务契约**：目标、范围、禁止项、验收。
- **现场证据**：相关文件片段、Git 状态、错误输出。
- **阶段产物**：已确认事实、计划、差异、测试结果。
恒定规则应该短而稳定；现场证据应按需读取；阶段产物要压缩成可复用结论。不要反复粘贴整段终端日志。
## 做一次 A/B 上下文实验
选择同一小需求，创建两个新会话。A 会话粘贴长篇项目历史、多个无关文件和完整日志；B 会话只提供任务卡，并允许 Agent 先搜索再读取相关文件。
记录三项数据：计划中错误假设数、意外触碰文件数、需要返工的轮次。通常 B 不一定第一次回答更长，却更容易把每条结论接回证据。
## 如何压缩而不丢事实
当会话变长，创建一份阶段摘要：已完成、已证实、仍未知、当前改动、下一验收。摘要不要写“研究了很多文件”，而写“路由由 middleware/locale.global.ts 加前缀；无前缀请求 302 到中文；尚未验证查询参数”。
好的摘要保留决定和来源，删除探索过程中的死路。压缩后随机抽两条事实回到文件核对，防止摘要把推断固化成事实。
## 跑偏时不要继续堆提示
如果 Agent 开始重复旧结论或修改无关区域，暂停行动。重新声明当前唯一目标，给出最新 Git 状态和相关文件，把已失效计划明确标记为废弃。必要时新开会话，用阶段摘要恢复，而不是在混乱上下文上继续补丁。
“记住之前所有内容”不是可靠策略。可恢复的外部产物——任务卡、计划文件、测试输出、提交——比聊天记忆更稳定。
## 来源与时效
软件文档会变化。上下文中的命令必须带来源与版本日期；遇到 Claude Code 当前功能，以官方文档和本地 --help 为准。模型记忆、旧博客和截图只能用来提出线索，不能直接作为现在的事实。
## 本课练习
为一个跨前后端的双语缺陷制作 context-pack.md，只保留：一句目标、五条约束、相关文件地图、两个已知错误输出、验证命令。交给新会话，让它先指出缺失信息再计划。完成后检查它读取了多少无关文件，以及是否能解释每个读取动作。
## 完成标准
你能区分规则、契约、证据和阶段产物；能在长任务中写可核验摘要；能在跑偏时重建上下文；能说明为什么某份信息此刻相关。上下文不是模型的行李箱，而是当前决策的工作台。