compile-knowledge

compile-knowledge

何时触发

只有以下两种触发条件：

1. 明确要求持久保存 — “保存这个”“把这个写入 wiki”、 “更新 wiki/记忆”“记录这个发现”“整理这些知识”、 “遵循 karpathy 方法”。
2. 具有持久价值的判断性输出 — 决策记录、某个发现背后的原因、差距分析、通过实际工作才学到且很容易再次耗费精力才会了解到的非显而易见事实。

普通分析工作不会触发此流程。回答事实性问题、 总结文件、解释代码或报告常规任务结果，都不会产生值得整理的持久知识。如果你唯一能写下的内容只是重述仓库或对话记录已有的信息，就跳过。

值得保留的持久知识应当是许多小型、相互关联的 Markdown 文件，随着时间不断整理，并通过索引呈现，而不是一份巨型文档、一段聊天记录，或一份很快过时的一次性文件。这项技能能让整理过程保持一致，让你的 Agent 随着时间不断变得更聪明，而不是一再重复学习相同的内容。

放在哪里——选择合适的存储位置

• Agent 记忆（默认，始终可用）：你的 .claude/.../memory/ 文件夹，以 MEMORY.md 作为索引。这是每个 Agent 独有的存储位置，重启后仍会保留——这是 karpathy 所说的“外部记忆”，能让你在不同会话中保持敏锐。它受系统提示词中已有的记忆规则约束——请遵循这些规则。对大多数 Agent 来说，这就是唯一需要的存储位置。
• 团队 wiki（其他 Agent 与你共用同一环境时）：供整个团队了解拥有者业务的信息——客户、价格、供应商、决策、拥有者喜欢的做事方式。使用 5dive memory add --store=wiki --name=<slug> --description="<one line>" 发布（正文通过 stdin 输入）；此命令会写入文件和对应的索引行，每位同事执行 5dive memory search 都能找到它。不要在项目中改用 wiki/ 文件夹：其他 Agent 的搜索不会读取该文件夹。如果你是唯一的 Agent，就跳过此项；不要凭空制造团队流程。

经验法则：“只有我会用到这个” → 记忆。“团队中的任何人都可能需要这个” → 团队 wiki。有关联时，用 [[slug]] 在两者之间建立交叉链接。

异步流程与你——分工说明

有些平台会自动整理已结束的会话（在 5dive 上：5dive memory consolidate，由心跳机制为你安排）。如果你的平台支持此功能，请了解它覆盖哪些内容，以及哪些事情只有你能做：

• 自动处理——普通事实。 此流程会将你已结束的会话记录提炼成记忆条目，存入你自己的存储位置。它从不读取正在进行的会话，也不会将其写入的任何内容带出你的环境。你不必手动复制会话中的普通事实来留存它们——这正是防止知识随上下文窗口消失的机制。
• 仍由你负责——判断。 wiki 页面、决策及其理由、差距分析、某个发现背后的原因：此流程只能提取对话记录中明确陈述的内容，而你得出的结论并不会自动出现在记录里。它也无法发布到共享 wiki——它没有存储位置选择器，而且共享存储默认拒绝访问——因此，向团队存储位置发布内容仍需要经过筛选，这件事由你负责。

这会缩小需要整理的范围，但不会取代整理工作。具有判断性的知识仍须在你结束任务前按照以下流程处理。

写入前——内容卫生检查

只整理持久且非显而易见的事实。如果内容符合以下任一条件，请跳过并继续：

• 属于常规内容／可从仓库、Git 历史记录或现有文档中推导，
• 仅在当前对话中成立，
• 已由现有文件涵盖（→ 更新该文件，而非重复创建）。

大多数任务（部署、重启、单行修复）都不会产生持久知识。这完全没问题——不要为了“写点东西”而凭空制造记忆。无关内容比什么都不写更糟；它会污染检索结果。

流程

1. 先搜索。 查找此主题是否已有文件（在 5dive 上，5dive memory search "<topic>" 会搜索你的存储和团队 wiki）。如果已有文件，就编辑它——绝不要创建近似重复的文件。
2. 保持原子性。 每个文件只记录一个事实／一个主题。如果你想再添加第二个无关事实，就应该新建第二个文件。
3. 命名。 使用 kebab-case 短名称；记忆文件需带类型前缀（feedback_…、project_…、reference_…、user_…），wiki 文件则使用清晰的主题短名称。短名称就是链接目标。
4. Frontmatter。 包含 name（即短名称）、description（一行——召回时会根据它进行匹配，因此要具体）以及 type／类别。
5. 正文。 清楚地陈述事实。使用 [[slug]] 链接相关条目——尽管添加；尚不存在的文件也可以先链接，作为 TODO 标记。对于 feedback／project，后面需加上 Why: 和 How to apply: 行。
6. 索引。 在索引中添加或更新一条指针（一行即可；记忆文件用 MEMORY.md，5dive memory add 会自动写入团队 wiki 的索引行）： - [Title](slug.md) — hook。控制在约 200 个字符以内；细节写在文件中，不要放进索引。
7. 保持整洁。 删除后来发现有误的文件。将相对日期改为绝对日期。如果索引太长，就精简条目——不要让它膨胀。

生命周期——标记取代关系，不要悄悄覆盖

事实会过时。如果某条事实有时效性、不确定，或取代了旧事实，就在 frontmatter 中标记，让召回系统能够使其过期，而不是继续显示过时信息：

• valid_to: YYYY-MM-DD —— 事实过期／需要重新核查的日期。超过此日期后，召回系统会保留该事实，但降低其优先级，并标记为 ⚠ expired。
• supersedes: <slug> —— 新事实取代旧事实时，指向旧短名称。这样在召回时，旧事实会被降级并标记为 ⤴ superseded，而不是作为第二条互相矛盾的答案继续存在。如果旧值仍值得保留（用于审计追踪），优先使用此方式；如果不值得保留，则直接编辑原文件。
• confidence: high|medium|low —— 低／中置信度的事实会被降级，避免未经证实的猜测排在已验证事实之前。
• provenance: "<source>" —— 事实来源；这不同于记录笔记的 compiled_by（撰写者）。

如果你的存储提供 CLI，它很可能会将这些字段作为参数开放；在 5dive 上，5dive memory add 支持 --valid-to=、--supersedes=、--confidence=、--provenance=。这些参数均为可选——省略后行为不变；上述 frontmatter 字段则具有可移植性。

反模式

• 用一篇长篇文档代替多个原子文件。
• 将研究内容单独留在 notes.md 中，之后从未整理归档——那只是工作笔记，不是知识。将其中经得起时间考验的部分整理后存入知识库。
• 在记忆和 wiki 中重复记录同一事实——选定一个存放位置，并相互链接。
• 索引条目重复陈述整个文件的内容。
• 为了满足习惯／清单而填充无用内容。

快速检查清单

[ ] 持久且不显而易见？[ ] 存放位置正确？[ ] 更新现有文件还是新建？ [ ] 内容原子、命名清晰且含 frontmatter？[ ] 有 [[链接]]？[ ] 已添加索引行？