02 上下文与记忆系统

原文：How Claude remembers your project

核心问题

AI Agent 的每次对话都从空白开始——它没有”记忆”。那如何让它记住你的项目规范、偏好、踩过的坑？

Claude Code 的答案是两套互补的记忆系统：

	CLAUDE.md	Auto Memory
谁写	你	Claude 自己
内容	指令和规则	学习到的模式
类比	你给新同事写的入职文档	同事自己记的工作笔记
加载	每次会话开始	每次会话开始（前 200 行）

类比：CLAUDE.md 像是项目的 .editorconfig 或 tsconfig.json——你写的、团队共享的项目规范；Auto Memory 像是 .bash_history——系统在使用过程中自动积累的记录。

CLAUDE.md：你写的持久指令

作用域层级

CLAUDE.md 可以存在于多个位置，从宽到窄：

/Library/.../ClaudeCode/CLAUDE.md    ← 企业级（IT 部署）
~/.claude/CLAUDE.md                   ← 个人级（所有项目）
./CLAUDE.md 或 ./.claude/CLAUDE.md    ← 项目级（团队共享）
子目录/CLAUDE.md                      ← 子目录级（按需加载）

更具体的位置优先级更高。就像 CSS 的层叠优先级——最近的规则胜出。

写好 CLAUDE.md 的原则

该写什么：

Claude 猜不到的 bash 命令
与默认风格不同的代码规范
测试指令和偏好的测试框架
项目特有的架构决策
开发环境的”坑”

不该写什么：

Claude 能通过读代码推断的东西
标准的语言惯例（Claude 已经知道）
经常变化的信息
详细的 API 文档（用链接替代）
不言自明的东西（如”写干净的代码”）

关键指标：每行问自己”删掉这行会导致 Claude 犯错吗？“不会就删。

高级特性

@path 导入：@README.md 可以把其他文件内容拉进来
.claude/rules/ 目录：把指令拆分到多个文件，支持按文件路径条件加载
路径条件规则：只在编辑特定类型的文件时才加载对应规则

---
paths:
  - "src/api/**/*.ts"
---
# API 开发规则
- 所有 API 端点必须包含输入校验

Auto Memory：Claude 自己的笔记

Auto Memory 是 Claude 在工作中自动保存的笔记——构建命令、调试发现、架构模式、代码风格偏好。

存储位置：~/.claude/projects/<project>/memory/

结构：

memory/
├── MEMORY.md          ← 索引文件，每次加载前 200 行
├── debugging.md       ← 调试模式笔记
├── api-conventions.md ← API 设计决策
└── ...

关键点：

MEMORY.md 的前 200 行每次会话都加载，超出部分不加载
详细内容放在子文件里，Claude 按需读取
所有文件都是纯 Markdown，你可以随时编辑或删除
/memory 命令查看和管理

上下文压缩（Compaction）

当上下文接近极限时，Claude 自动压缩：

先清除旧的工具输出
再摘要对话
CLAUDE.md 完整保留（从磁盘重新读取）
只在对话中提到而没写进 CLAUDE.md 的指令可能丢失

/compact 可以手动触发，还能指定保留焦点：/compact focus on the API changes

知识检测

概念理解题

CLAUDE.md 和 Auto Memory 的本质区别是什么？为什么需要两套系统而不是合并成一套？
CLAUDE.md 被描述为”上下文而非强制配置”——这意味着什么？它和 .eslintrc 这种强制配置有什么区别？
为什么 Auto Memory 的 MEMORY.md 有 200 行限制？如果不限制会怎样？

应用题

你接手一个新的 Node.js/Express 后端项目，需要为团队写一份 CLAUDE.md。列出你会包含的 5 个要点。
一个场景：你告诉 Claude “所有 API 请求都要加 retry 逻辑”，但 /compact 之后 Claude 不再遵守这个规则了。问题出在哪？怎么解决？

迁移思考题

OpenClaw 没有 Auto Memory 机制。如果你要为 OpenClaw 设计一个类似的记忆系统，你会怎么做？（提示：OpenClaw 有 session 和 workspace 的概念）
CLAUDE.md 的 .claude/rules/ 机制支持按文件路径条件加载。这个设计和 Webpack/Vite 的多环境配置（development/production/staging）有什么相似之处？

参考答案

1. CLAUDE.md vs Auto Memory 的本质区别

CLAUDE.md 是你的意图（“Claude 应该怎么做”），Auto Memory 是Claude 的经验（“我发现了什么”）。需要两套系统是因为写入者、更新频率和内容性质不同：你不太可能每天更新 CLAUDE.md 记录构建命令，但 Auto Memory 会在第一次看到构建错误时自动记下解决方案。合并的问题是：如果 Claude 可以改你的规则，规则的权威性就丧失了；如果你每次都要手动记录经验，效率太低。

2. “上下文而非强制配置”

.eslintrc 是程序强制执行的——不合规则的代码无法通过检查。CLAUDE.md 是 LLM 看到的文本——Claude “尽量”遵守但不保证。越具体的指令遵守率越高，冲突指令可能被随机选择，上下文窗口越满遵守率越低。需要强制执行的规则应该用 Hook（确定性），而不是 CLAUDE.md（概率性）。

3. 200 行限制的原因

MEMORY.md 每次会话都完整加载——如果不限制，笔记会无限增长，占满上下文空间，挤压实际工作内容。200 行逼迫 Claude 保持精简，详细内容放到子文件按需加载。和控制 App 启动时加载的数据量是同一个思路。

4. Node.js/Express 项目的 CLAUDE.md 要点

(1) 启动命令（npm run dev、npm run build）(2) 测试框架和命令（Jest / Vitest + Supertest）(3) 代码规范（TypeScript strict, ESLint + Prettier）(4) 项目结构约定（routes/controllers/services/models 目录分工）(5) 数据库迁移流程（npx prisma migrate dev）。

5. /compact 后规则丢失

规则只存在于对话历史中，没有写入 CLAUDE.md。Compaction 时对话被摘要，口头指令丢弃，CLAUDE.md 从磁盘重新读取不受影响。解决：把规则写入 CLAUDE.md 或 .claude/rules/，越具体越好（如”使用 fetchWithRetry 函数”而非泛泛的”加 retry”）。

6. 为 OpenClaw 设计 Auto Memory

利用 OpenClaw 已有的 Memory 系统。设计：(1) agent_end Plugin Hook 分析对话中的新发现/纠正 (2) 将值得记住的内容追加到 memory/auto-learnings.md (3) 用 memory_search 向量搜索在下次运行前检索相关经验。OpenClaw 的向量搜索比 Claude Code 的纯文件方式更能找到语义相关的旧经验。

7. Rules 和多环境配置的相似性

两者都是条件化配置——根据上下文自动选择加载哪些规则。Webpack 的多环境配置根据 NODE_ENV 选配置，.claude/rules/ 根据编辑的文件路径选规则。相似点：减少全局配置膨胀，让不相关的配置不占资源。不同点：Webpack 环境在构建时确定，rules 在运行时动态触发。

参见

01-AI-Agent-架构原理 — 理解记忆在 Agentic Loop 中的位置
04-Skill-技能系统 — Skill 是按需加载的知识，与 CLAUDE.md 互补
SlipBox 相关：Context Window、Context Rot、Claude Code