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 关闭。
• 目录结构示例：

~/.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 读到那些目录的文件时才加载；
  • **带 paths frontmatter 的 **.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 里那一行索引（在限额内）每会话加载。

下次涉及版本号任务时的预期流程：

1. 会话启动 → MEMORY.md 索引行加载 → 我看到"改动后升版本号"这条记忆存在；
2. 触及版本号相关任务 → 我判断需要详情 → 用 Read 工具读 bump-version-on-every-change.md；
3. 套用其中的 sed 三步流程（试替换 → 批量 → 对比）与双重验证（旧归零 / 新等数）。

这正是渐进式设计的目的：常驻轻量索引 + 按需正文，省 context。

---

参考来源

• How Claude remembers your project — Claude Code 官方文档