Claude Code memory 渐进式披露机制 · 学习记录
核心结论
是。 memory（auto memory）采用「索引常驻 + 正文按需」的两层渐进式披露，和 skill 的「元数据常驻 + 正文按需」是同一思想，但触发器略有不同。
一、memory 的两层机制
| 层 | 文件 | 加载时机 | 限额 |
|---|---|---|---|
| 索引层 | MEMORY.md |
每次会话开头加载 | 前 200 行或前 25KB（取先到者），超出截断 |
| 正文层 | topic files（如 debugging.md、api-conventions.md） |
不在启动加载，Claude 判断需要时用标准文件工具按需 Read | 无（按需才进 context） |
- Claude 靠把详情从
MEMORY.md移到 topic files，保持索引在 200 行 / 25KB 限额内。 - 若超限：写入仍成功，但下次加载时超出部分被丢弃，并提示 Claude 重写索引。
- 存储位置 ：
~/.claude/projects/<project>/memory/，每个 git 仓库一个目录、同仓库的 worktree / 子目录共享；machine-local，不跨机器 / 云环境共享。 - 默认开启 ：auto memory 默认 on（
autoMemoryEnabled），可用/memory切换或CLAUDE_CODE_DISABLE_AUTO_MEMORY=1关闭。 - 目录结构示例：
plain
~/.claude/projects/<project>/memory/
├── MEMORY.md # 索引/入口，每次会话加载（截断 200 行/25KB）
├── debugging.md # topic file，按需 Read
├── api-conventions.md # topic file，按需 Read
└── ... # 其它 topic files二、"Recalled N memories" 是怎么回事
文档原文：topic files「reads them on demand using its standard file tools when it needs the information」。
UI 上看到的 Recalled N memories / Saved N memories，就是 Claude 在会话中主动 读写 ~/.claude/projects/<project>/memory/ 目录------不是某种神秘的全自动语义注入，而是 Claude（我）判断"现在需要这条信息"时，用 Read 工具去读对应 topic file。
流程：索引行先提醒"有这条记忆存在" → Claude 判断需要时 → 用 Read 工具读 topic file → 正文进入 context。
三、与 skill 对比
文档原文：skills「only load when you invoke them or when Claude determines they're relevant to your prompt」。
| 常驻部分 | 正文触发器 | |
|---|---|---|
| memory | MEMORY.md 索引（截断 200 行 / 25KB） |
Claude 判断需要该信息时，用 Read 工具读 topic file |
| skill | name + description 元数据 | 你用 Skill 工具显式调用，或 Claude 判定与 prompt 相关时自动加载 |
两者都是"轻量摘要常驻 + 正文按需"，区别在于：
- skill 多了一条"Claude 自动按相关性加载正文"的路径；
- memory 正文更偏"Claude 判断需要时主动 Read"。
四、与 CLAUDE.md 对比（CLAUDE.md 不是渐进式）
- CLAUDE.md 文件全量加载 （in full regardless of length），不分批------所以 CLAUDE.md 不算渐进式披露；文档只是建议 <200 行以兼顾 token 占用与遵循度。
- 两个按需例外：
- 子目录里的 CLAUDE.md：Claude 读到那些目录的文件时才加载；
- **带
pathsfrontmatter 的 **.claude/rules/：Claude 读匹配文件时才触发。
五、三者触发差异小结
| 机制 | 启动加载 | 按需加载 | 性质 |
|---|---|---|---|
| CLAUDE.md（根 / 上溯目录） | 全量 | --- | 非渐进 |
CLAUDE.md（子目录）/ paths rules |
--- | 读匹配文件时 | 渐进 |
memory MEMORY.md |
截断全量（200 行 / 25KB） | --- | 半渐进（有上限的常驻） |
| memory topic files | --- | Claude 判断需要时 Read | 渐进 |
| skill | 元数据 | 调用 / 相关性自动加载 | 渐进 |
六、实际影响（针对本项目的记忆）
本次创建的 bump-version-on-every-change.md 是 topic file ，下次会话不会自动加载正文 ；只有 MEMORY.md 里那一行索引（在限额内）每会话加载。
下次涉及版本号任务时的预期流程：
- 会话启动 →
MEMORY.md索引行加载 → 我看到"改动后升版本号"这条记忆存在； - 触及版本号相关任务 → 我判断需要详情 → 用 Read 工具读
bump-version-on-every-change.md； - 套用其中的 sed 三步流程（试替换 → 批量 → 对比）与双重验证（旧归零 / 新等数）。
这正是渐进式设计的目的：常驻轻量索引 + 按需正文，省 context。