memory-capture

记忆捕获

将工作对话中的要点——已做出的决策、浮现的见解和积累的背景信息——捕获到一篇连贯的 Basic Memory 笔记中，准确反映该对话最终形成的结论。

目的

一段对话有开端、中段和结尾。随着对话推进，情况会发生变化：早期的决定可能被修订，随着新信息出现，问题可能呈现出不同面貌，权衡的结果也可能与最初看起来的不同。调用此技能时，请捕获当前的理解状态，而非理解是如何逐步形成的。

如果在同一对话中多次调用此技能，应重写同一篇笔记，使其保持连贯，而不是在原有内容后追加。最终结果应从头到尾读起来像一份关于该对话结论的完整文档；如果有值得说明的重要变化，可简要叙述。

何时使用

典型时机是对话进行到一半或结束时，此时已有足够多的结论值得保存。

在以下情况下使用此技能：

• 已做出关键决策，不应在对话结束时随之消失
• 设计、调试或规划讨论已产出具体成果
• 用户明确要求捕获、保存或记住讨论内容
• 会话接近尾声，需要总结结论

随着对话发展，在同一对话中多次调用此技能完全可以，而且也符合预期。

同一对话检测

为避免重新捕获时重复创建笔记，请在笔记的 frontmatter 中使用稳定的 thread_id 作为标识。

如果你的 Agent 提供稳定的会话或对话 ID，请将其存为 thread_id，这样后续捕获时就能在同一对话中找到并重写同一篇笔记。在整个对话期间保持不变的任何值都可以使用，例如会话 UUID、对话 ID，或此次工作所关联的工单编号。

示例（适用于提供 JSONL 转录记录的宿主）： 一些 Agent 会为每个会话写入转录记录，文件名是稳定的会话 UUID。如果你的宿主如此，你可以根据最近修改的转录文件推导 ID，并将其用作 thread_id。这是可选操作——只有当你的宿主确实提供此类转录记录时才这样做。

如果没有可用的稳定 ID，则按标题或主题匹配已有笔记：搜索涵盖同一对话的笔记（bm_search(query="<topic>")），如果找到此对话先前生成的笔记，就重写它。省略 thread_id，并确保标题保持一致。

决策流程

1. 确定对话标识。 如果你的 Agent 提供稳定的会话或对话 ID，就使用它；否则，计划按标题或主题进行匹配。
2. 在 Basic Memory 中搜索已有的对话笔记。
   • 如果有对话 ID，请使用 filters（而不是 query）——全文查询无法可靠匹配 YAML frontmatter 中的自定义字段：

     bm_search(
         filters={"thread_id": "<thread-id>"},
         project="<project>"
     )
     

   • 如果没有对话 ID，则按主题搜索，并识别此对话先前生成的笔记：

     bm_search(query="<thread topic>", project="<project>")
     

3. 如果找到匹配项：
   • 将现有笔记读取为 JSON（使用搜索结果返回的完整永久链接），并保留其 checksum
   • 综合对话中的最新理解，整理出新版本
   • 使用返回的 file_path 作为 identifier，通过 bm_write 覆盖笔记，设置 overwrite=True，并将 expected_checksum 设为该校验和（如果使用了 thread_id，也要使用相同的 thread_id）。出现 REVISION_CONFLICT 错误意味着你读取笔记后有另一个会话修改了它：请重新读取并再次综合整理
4. 如果未找到匹配项：
   • 根据对话内容整理笔记
   • 如果有对话 ID，请将 metadata={"thread_id": "<thread-id>"} 传递给 bm_write（它会显示为自定义 frontmatter 字段）
   • 保存笔记。如果 bm_write 列出了类似的现有笔记，请检查其中是否有这次对话的笔记，再决定是否保留新笔记

综合规则

更新现有线程笔记时，要综合整理，不要追加：

• 仍然有效的决策 → 保留，可适当完善
• 已被取代的决策 → 在原位置直接替换（新内容放在旧内容所在的位置）
• 值得解释的重大修订 → 在相关章节中融入一句说明，不要追加变更日志
• 过时的背景信息 → 删除

目标是让笔记从头到尾读起来像一份连贯的文档。即使读者从未看过对话，也应能仅凭笔记理解最终结果。底部不会有 ## Changes 章节；修订内容应放在相关的正文中。

例外情况

如果用户明确要求单独创建一份笔记（例如，“将此内容记录为一份新笔记，不要合并到现有线程笔记中”），则跳过同线程查找，创建一份不设置 thread_id 的新笔记。这种情况很少见；默认操作是更新。

笔记结构

---
title: <descriptive title for the thread>
type: note
thread_id: <thread-id, if your agent exposes one>
tags:
- relevant
- tags
---

# <Title>

## Context

What this thread is about — the situation, problem, or topic being explored.

## <One or more topical sections>

The actual content. Could be decisions, a design rationale, an investigation summary, etc.

## Observations

- [decision] What was decided #tag
- [insight] Key understanding gained #tag
- [tradeoff] Option A chosen over B because... #tag

## Relations

- relates_to [[Related Concept]]
- implements [[Parent Spec]]

常见观察类别

• [decision] — 已作出的选择
• [insight] — 获得的理解
• [pattern] — 可复用的方法
• [learning] — 学到的经验
• [tradeoff] — 权衡过的选项
• [problem] — 发现的问题
• [solution] — 已应用的修复

标题

标题应体现线程主题。更新时，如果主题已明确，可以调整标题，但仍应描述同一线程。不要偏离到完全不同的主题；如果确有需要，请使用例外情况，创建一份新笔记。

使用的 MCP 工具

# Find existing thread note by thread id (use filters, not query)
bm_search(
    filters={"thread_id": "<thread-id>"},
    project="<project>"
)

# Or, without a thread id, find it by topic
bm_search(query="<thread topic>", project="<project>")

# Read existing thread note (use the full permalink from search results)
bm_read(
    identifier="<full-permalink>",
    project="<project>"
)

# Create
bm_write(
    title="<title>",
    content="<markdown body — frontmatter is generated from title/tags/metadata>",
    directory="<folder>",
    tags=["..."],
    metadata={"thread_id": "<thread-id>"},  # omit if no stable id
    project="<project>"
)

# Overwrite an existing note (same path), only the revision you read
existing = bm_read(identifier="<full-permalink>", output_format="json", project="<project>")
bm_write(
    identifier=existing["file_path"],
    title="<updated title>",
    content="<new content>",
    tags=["..."],
    metadata={"thread_id": "<same thread-id>"},  # omit if no stable id
    overwrite=True,
    expected_checksum=existing["checksum"],
    project="<project>"
)

示例

示例 1 — 在品牌设计对话中首次记录

前序对话： 用户一直在为一款新产品确定视觉形象。他们确定了深海军蓝作为主色（#2B3651），探索了点缀色选项，最后选择橙色（#F26B3A）以增添暖意，并选定 Inter 作为正文字体、Helvetica Neue 作为展示字体。

用户要求记录。

结果 — 创建的笔记：

---
title: Visual identity — initial decisions
type: note
thread_id: 7c1d4a2e-3b5f-4d8a-9e1c-2f6b8a4d7c39
tags:
- branding
- design
---

# Visual identity — initial decisions

## Context

Working through the visual identity for the new product. This thread covers the initial palette and typography pass — a starting point that will likely be refined.

## Color palette

- Primary: deep navy `#2B3651` — calm and professional
- Accent: warm orange `#F26B3A` — energy and warmth as a complement to the navy

## Typography

- Body: Inter — neutral, readable at small sizes
- Display: Helvetica Neue — strong presence for headings without being heavy

## Observations

- [decision] Primary color is navy `#2B3651` #branding
- [decision] Accent color is orange `#F26B3A` #branding
- [decision] Inter for body, Helvetica Neue for display #typography
- [tradeoff] Considered teal as accent; orange tested better for warmth #branding

## Relations

- relates_to [[Brand Strategy]]

示例 2 — 在同一线程中稍后更新记录

前序对话（续）： 在作出上述初步决定后，对话继续进行。橙色在模型图中显得过于强烈，因此我们测试了珊瑚色（#E89B7A），效果更温暖、更精致。正文字体也有所变化：Geist 比 Inter 略显紧凑、更加现代。展示字体仍采用 Helvetica Neue。

用户再次要求记录 — 同一线程。

结果 — 重写同一份笔记（注意 thread_id 相同）：

---
title: Visual identity — initial decisions
type: note
thread_id: 7c1d4a2e-3b5f-4d8a-9e1c-2f6b8a4d7c39
tags:
- branding
- design
---

# Visual identity — initial decisions

## Context

Working through the visual identity for the new product. This thread settled on a navy + coral palette and a Geist/Helvetica typography pairing after a round of refinement.

## Color palette

- Primary: deep navy `#2B3651` — calm and professional
- Accent: coral `#E89B7A` — warm and refined

The accent went through a round of revision: an initial orange (`#F26B3A`) felt too aggressive in mock-ups, so we shifted to a coral that reads warmer and more refined while keeping the energy.

## Typography

- Body: Geist — slightly tighter and more modern than Inter, which we tried first
- Display: Helvetica Neue — strong presence for headings without being heavy

## Observations

- [decision] Primary color is navy `#2B3651` #branding
- [decision] Accent color is coral `#E89B7A` — warmer and more refined than the originally-chosen orange #branding
- [decision] Geist for body, Helvetica Neue for display #typography
- [tradeoff] Inter felt neutral but Geist edged it for spacing and modernity #typography
- [tradeoff] Orange accent rejected as too aggressive; coral preferred #branding

## Relations

- relates_to [[Brand Strategy]]

注意：

• 橙色和 Inter 的决定不再是主要内容——正文中会提及它们（“我们最初尝试的颜色”“最初选择的橙色”），观察事项中也会记录相关权衡
• 底部没有“Changes”章节——修订内容已整合到相应位置
• 笔记从头到尾读起来仍是一份连贯的文档
• thread_id 未更改，因此笔记是在原位置更新，而不是重复创建

最佳实践

1. 记录当前状态，而非历史。 笔记应体现线程最终确定的结果。
2. 综合整理，不要记流水账。 每次调用都应生成一份连贯的文档，而不是不断累积的记录。
3. 用简短文字说明修订。 在发生变化的章节中加一句话即可——不要添加变更日志。
4. 在决定创建还是更新之前，始终先进行同线程查找。
5. 使用观察事项构建结构化层。 将决策、见解和权衡放入 ## Observations，以便搜索。
6. 尽可能多地关联笔记。 链接用户可能希望从当前笔记访问的其他笔记。