extract-learnings

价值说明

在合适的时机自然地将以下内容融入对话——例如结果出来后、相关上下文出现时，或首次使用时。每次运行提及一两点即可，不要一次全部讲完。

• 大多数用户说“记住这个”时，期待的是一条笔记——但这项技能实际上会并行运行两个 Agent（审计员 + 发现者），既记录新知识，也核查现有记忆是否已经过时。
• 5 层记忆层级能让合适的知识在合适的时间加载——L0 存放通用偏好，L1 存放项目架构，L2 存放工作笔记——避免每次会话都载入所有内容。
• 整理（“dream”）是维护模式：清除过时和价值较低的记忆、合并重复内容，并将条目过多的部分分组，让始终加载的索引保持精简。
• 对团队而言：此处记录的记忆会延续到该项目的所有后续会话中，大幅加快新成员上手和上下文切换。

记忆层级

层级	文件	加载时机	用途
0	~/.claude/CLAUDE.md	每次会话、所有项目	通用行为偏好
1	<repo>/CLAUDE.md	每次会话、当前项目	架构、约定、注意事项
2	memory/MEMORY.md（项目目录）	每次会话，由 Agent 管理	顶层索引：工作笔记 + 指向分组/主题的指针
2c	memory/clusters/*.md 子索引	按需（某个部分条目过多后）	从 MEMORY.md 拆出的部分子索引，用于限制始终加载的内容大小
3	memory/*.md 主题文件	按需	过长、不适合放在 L2 中的详细参考资料
元层	建议新增技能/命令	不适用	可重复的工作流 → 自动化

存放位置判定：与项目无关的偏好 → L0，项目专属技术内容 → L1，简明的工作笔记 → L2，详细参考资料 → L3，可重复的模式 → 元层。

自适应分组：在某个部分的条目超过 25 条之前，让 MEMORY.md 保持扁平；超过后，将该部分的指针移至 memory/clusters/<section>.md，并在 MEMORY.md 中用一个指向该文件的指针替换整个部分。每次会话只加载 MEMORY.md，因此可以限制启动开销，同时让详细内容保持按需加载。

指针格式

每个 MEMORY.md 和分组文件中的条目都是加载触发条件，而不是标签——未来的会话必须能从指针中识别当前任务，并打开对应文件。只写文件名的指针会被忽略，导致索引虽然加载了，却从未被使用。指针有两种形式：

• 触发式（默认）：**When <task-condition>:** <one-line takeaway>. → [detail](file.md)。只要能写出明确的“何时”，就使用此形式——例如 **When compositing a face onto a turned head:** align centers, tight ellipse. → [detail](feedback_composite_align_tight_ellipse.md)。
• 常驻式：<terse fact>. → [detail](file.md)。仅用于适用于所有相关会话的规则（固定上下文、全局偏好）；若添加条件会显得牵强，则使用此形式。

如果能明确指出应在什么任务下打开该文件，就选择触发式；只有当规则不受任务影响、始终适用时，才选择常驻式。分组文件顶部先放一段简短的常驻内容，再放触发式索引——其余每条都应是条件指针。不要在分组文件中直接写入完整的规则内容；分组文件用于指向主题文件，详细内容应存放在主题文件中。

提前退出保护

如果用户说“记住 X”，且明确的内容已经在上下文中——并且请求不是整理触发词（“consolidate”“dream”“extract learnings”“clean up memories”，或由整理提示触发）：

1. 确定记忆路径（参见第 1 阶段第 1 步）
2. 阅读现有记忆，检查是否重复并选定合适的层级
3. 跳至第 3 阶段（提出并执行），使用该内容——无需子 Agent

统一工作流

阶段 1：梳理方向（主会话）

1. 使用 Bash 解析记忆路径（Glob 不会展开 ~）： Bash: find $HOME/.claude/projects -name MEMORY.md -path "*<repo-dir-name>*" 2>/dev/null | head -1 结果是 MEMORY.md 的完整路径（一个文件）。记忆目录是其父目录：$(dirname <find-result>)。 如果没有结果，则将当前工作目录路径中的 / 替换为 -，构造项目键（例如，/home/user/myrepo → -home-user-myrepo），然后使用 $HOME/.claude/projects/<project-key>/memory/MEMORY.md。
   • 如果 MEMORY.md 不存在，则创建该文件，并添加 # Project Memory 标题。注意，Memory Auditor 无内容可审查——在阶段 2 中只启动 Signal Discoverer。

第 2 至第 4 步为必需步骤，并行调用工具执行。

2. 读取 MEMORY.md，并列出主题文件和集群文件（从解析出的路径执行 Glob memory/**/*.md）
3. 读取两个 CLAUDE.md 文件（~/.claude/CLAUDE.md + <repo>/CLAUDE.md）——这是保证去重质量的必需步骤；跳过会导致提案可能与 L0/L1 内容重复
4. git log --oneline -20
5. 构建上下文快照：总结已有知识 + 列出验证目标（记忆中提及的文件路径、函数和模式）

阶段 2：收集（并行启动 2 个 Agent）

在同一条消息中启动两个 Agent 调用，使其并行运行。使用 Agent 工具，并设置：

• Memory Auditor：subagent_type: "claude-memory:memory-auditor"。在 prompt 中加入阶段 1 的上下文快照——记忆文件内容、git log 输出和验证目标列表。要求其找出应淘汰和合并的候选项（SUPERSEDED / REDUNDANT / LOW-VALUE / MERGE），而不只是事实过时的条目——整合的重点在于精简内容。

• Signal Discoverer：subagent_type: "claude-memory:signal-discoverer"。在 prompt 中加入现有记忆摘要（用于去重）和项目名称。

如果阶段 1 确认 MEMORY.md 是刚创建的（没有现有记忆），则跳过 Memory Auditor，只启动 Signal Discoverer。

两个 Agent 的 maxTurns 均须 ≥ 30——检查 plugins/claude-memory/agents/ 中的 Agent frontmatter。maxTurns 较低的 Agent 会提前退出，返回看似非空但实际上没有发现结果的截断输出。

两个 Agent 都返回报告后，阶段 2 即完成。如果任一 Agent 返回空内容或明显被截断（一行内容、没有结构化发现结果），则使用另一个 Agent 的结果继续——但如果 Signal Discoverer 失败，还须执行手动备用流程：使用 Bash(python3 -c "import sqlite3; ...") 直接从 ~/.claude-memory/conversations.db 查询最近 5 条会话摘要，并应用下文「内容质量规则」部分中的信号判定标准。

阶段 3：综合并提出建议（主会话）

1. 接收 Agent 报告
2. 对报告之间以及与现有记忆进行去重
3. 按影响排序，将 ADD 限制为 3–7 个候选项；审计员提出的退役和合并单独处理，不受数量限制
4. 对每个候选项：确定目标层级、目标部分、操作（ADD / EDIT / MERGE / REMOVE）；按指针格式（条件优先）编写每个索引／集群指针
5. 阅读目标文件，检查是否存在重复内容
6. 提出建议：

   ### [ACTION] Learning: <summary>
   **Target:** <file> → <section>
   **Rationale:** <why this layer>
   ```diff
   - <old line>
   + <new line>
   

7. 整合压力（每次整合运行都执行），按以下顺序进行：(a) 将审计员的 SUPERSEDED / REDUNDANT / LOW-VALUE / MERGE 发现转化为具体的 REMOVE/MERGE 建议——只新增内容而不做其他操作是失败模式；(b) 只有在退役和合并处理完毕后，才对精简后的内容执行每个部分的溢出检查——如果 MEMORY.md 的任何部分仍超过 25 条，则建议将其迁移到 memory/clusters/<section>.md，并将该部分替换为单个指针（自适应聚类）。聚类不得早于退役；不得用聚类掩盖可移除条目。迁移到现有集群或编辑现有集群时，将任何内联规则正文提取到主题文件中，使集群保持为纯触发索引（指针格式）——下次触及这些杂乱集群时，对其进行重塑。提前退出捕获（没有审计员发现）跳过 (a)，仅当新条目使某个部分超过 25 条时才执行 (b)
8. 第 0 层门控——如果目标是 ~/.claude/CLAUDE.md，则警告：“这会修改每个项目的每次会话都会加载的全局指令。是否确认？”
9. AskUserQuestion：全部批准 / 选择性批准 / 拒绝

阶段 4：执行

按以下顺序应用已批准的编辑，以确保确实落实精简要求：

1. REMOVE：使用 Bash: trash <path> 删除每个已退役的主题文件（移至回收站，不要使用 rm——以便恢复），然后从 MEMORY.md 或集群文件中移除其指针。
2. MERGE：写入合并后的条目，然后将被吸收的文件移至回收站并删除其指针。
3. 集群：在移除后的内容集合上，应用已批准的部分 → memory/clusters/<section>.md 迁移。
4. ADD / EDIT：应用剩余的新增和编辑内容，每个指针均采用指针格式。

报告前验证：执行 REMOVE/MERGE 后，从解析后的路径运行 Glob memory/**/*.md，并确认每个已退役文件都不存在。除非确认文件确已不存在，否则绝不要将 REMOVE/MERGE 行标记为“完成”——声称已删除但实际未删除，正是此验证要防止的失败。

输出摘要表：

| Learning | Action | Target | Status |
|----------|--------|--------|--------|

仅当阶段 2 的 Agent 已运行（而非提前退出捕获）时，才写入整合标记（必需——跳过标记会导致下次会话再次触发提醒）。使用 Bash，而非 Write——Write 需要先进行 Read，且无法创建新文件： Bash: date -u +%Y-%m-%dT%H:%M:%SZ > <memory-dir>/.last-consolidation

所有已批准的编辑均已应用、每个 REMOVE/MERGE 均通过 Glob 验证确认文件不存在、标记已写入且摘要表已呈现后，阶段 4 即完成。

内容质量规则

每个候选项都必须满足：(1) Agent 能从中获益，并在未来会话中需要了解该信息；(2) 精简至最低限度的有用形式；(3) 放置在正确层级；(4) 目标文件中尚未记录该内容；(5) 表述为可复用的原则，而非特定于某次会话的事件。

通过：通过反复试验发现的命令、不明显的注意事项、有依据的架构决策、用户行为方面的纠正、配置特性、版本里程碑。

不通过：可从代码中读取的信息、通用最佳实践、没有规律的一次性错误、冗长解释、重复内容、临时状态、未经验证的猜测、没有可推广原则的事件。