把工作线程/对话的当前结论沉淀为可复用 Basic…

在对话中做出决策、获得洞察或积累上下文后，将线程当前状态综合成一条连贯的 Basic Memory 笔记，并在同一线程再次捕获时重写同一条笔记。

适用场景

解决思路

1. 在线程中或结束时，当关键决策、设计/调试/规划讨论产生具体结果，或用户明确要求捕获/保存/记住已讨论内容时，执行本技能。
2. 捕获的是当前理解状态，不是到达该状态的历史。
3. 同一线程多次调用时，重写同一条笔记，而不是追加内容。
4. 为检测同一线程，在 frontmatter 中用稳定的 `thread_id` 作为键。
5. 如果 agent 暴露稳定的 session 或 thread id，将其存为 `thread_id`，以便后续捕获找到并重写同一条笔记；任何在线程期间保持不变的值都可以：session UUID、conversation id、工单号等。
6. 如果宿主有 JSONL transcript，可从最近修改的 transcript 文件名推导稳定 session UUID，并作为 `thread_id`；这是可选步骤，仅当宿主确实暴露该 transcript 时使用。
7. 如果没有稳定 id，则按标题/主题匹配已有笔记：`search_notes(query="<topic>")`；如果找到该线程已产生的笔记，则重写它；省略 `thread_id`，依赖一致标题。
8. 确定线程键：优先使用稳定 session/thread id；否则计划按标题/主题匹配。
9. 在 Basic Memory 中搜索已有线程笔记。
10. 有 thread id 时，使用 `metadata_filters`（不是 `query`）搜索：`search_notes(metadata_filters={"thread_id": "<thread-id>"}, project="<project>")`，因为全文查询不能可靠匹配 YAML frontmatter 自定义字段。
11. 没有 thread id 时，按主题搜索并识别该线程已产生的笔记：`search_notes(query="<thread topic>", project="<project>")`。
12. 如果找到匹配：读取已有笔记，使用搜索返回的完整 permalink：`read_note(identifier="<full-permalink>", project="<project>")`。
13. 如果找到匹配：综合一个整合对话最新理解的新版本。
14. 如果找到匹配：通过 `write_note` 覆盖，设置 `overwrite=True`，保持相同 title、相同 `thread_id`（如使用）、相同 directory。
15. 如果没找到匹配：从对话综合笔记。
16. 如果没找到匹配且有 thread id：向 `write_note` 传递 `metadata={"thread_id": "<thread-id>"}`，它会作为自定义 frontmatter 字段出现。
17. 如果没找到匹配：保存它。
18. 更新已有线程笔记时，综合而非追加。
19. 仍当前的决策：保留，可精炼。
20. 已被取代的决策：原地替换，新决策放在旧决策的位置。
21. 值得解释的重大修订：在相关章节中织入一句话，而不是追加变更日志。
22. 过时上下文：删除。
23. 目标是笔记从上到下读起来像一份连贯文档；没看过对话的读者仅凭笔记也能理解结果。
24. 底部没有 `## Changes` 章节；修订写在相关正文中。
25. 如果用户明确要求单独笔记（例如“capture this as a new note, don't merge with the existing thread note”），跳过同线程查找，创建新笔记且不设置 `thread_id`；这是罕见情况，默认更新。
26. 笔记 frontmatter 结构包含：`title`、`type: note`、`thread_id`（如 agent 暴露）、`tags` 列表。
27. 正文包含 `## Context`：该线程关于什么——正在探索的情境、问题或主题。
28. 正文包含一个或多个主题章节：实际内容，可以是决策、设计理由、调查总结等。
29. 正文包含 `## Observations`：以列表记录结构化观察，格式如 `- [decision] What was decided #tag`、`- [insight] Key understanding gained #tag`、`- [tradeoff] Option A chosen over B because... #tag`。
30. 正文包含 `## Relations`：如 `- relates_to [[Related Concept]]`、`- implements [[Parent Spec]]`。
31. 常用 observation 类别：`[decision]` 做出的选择；`[insight]` 获得的理解；`[pattern]` 可复用方法；`[learning]` 经验教训；`[tradeoff]` 权衡的选项；`[problem]` 识别的问题；`[solution]` 应用的修复。
32. 标题应反映线程主题；更新时可因主题澄清而精炼标题，但仍描述同一线程；不要漂移到全新主题；如需要新主题，用 escape hatch 创建新笔记。
33. MCP 工具查找已有线程笔记 by thread id：`search_notes(metadata_filters={"thread_id": "<thread-id>"}, project="<project>")`。
34. MCP 工具或没有 thread id 时按主题查找：`search_notes(query="<thread topic>", project="<project>")`。
35. MCP 工具读取已有线程笔记（使用搜索结果中的完整 permalink）：`read_note(identifier="<full-permalink>", project="<project>")`。
36. MCP 工具创建：`write_note(title="<title>", content="<markdown body — frontmatter is generated from title/tags/metadata>", directory="<folder>", tags=["..."], metadata={"thread_id": "<thread-id>"}, project="<project>")`；如果没有稳定 id 则省略 `metadata`。
37. MCP 工具覆盖已有笔记（相同路径）：`write_note(title="<same title>", content="<new content>", directory="<same folder>", tags=["..."], metadata={"thread_id": "<same thread-id>"}, overwrite=True, project="<project>")`；如果没有稳定 id 则省略 `metadata`。
38. 最佳实践：捕获当前状态，而非历史。
39. 最佳实践：综合，不记日志；每次调用产生连贯文档，而不是累积记录。
40. 最佳实践：修订用简短正文；在变化章节写一句话足够，不要加 changelog。
41. 最佳实践：在决定创建或更新前，总是先运行同线程查找。
42. 最佳实践：用 observations 作为结构化层；决策、洞察、权衡放进 `## Observations`，以便可搜索。
43. 最佳实践：自由链接 relations，链接用户可能想从本笔记到达的笔记。
44. 示例模式：首次捕获时创建笔记；后续同一 `thread_id` 捕获时重写同一笔记；旧决策（如 orange、Inter）不再作为主要内容，而是在正文中承认（“which we tried first”、“originally-chosen orange”）并进入 tradeoff observations；没有 `## Changes`；`thread_id` 不变，因此原地更新而非重复。

适用边界 · 注意事项

• 当用户明确要求创建独立新笔记、不要与已有线程笔记合并时，不要执行同线程查找和覆盖；改用 escape hatch 新建且不设 `thread_id`。
• 当话题已完全变成另一个全新主题时，不要继续改写旧笔记；应新建笔记。
• 若运行环境没有 Basic Memory / 对应 MCP 工具（`search_notes`、`read_note`、`write_note`），本技能无法按原文执行。