memory-capture

メモリの記録

作業中のスレッドの要点、つまり下された決定、明らかになった洞察、築かれたコンテキストを、スレッドの最終的な状況を反映した、一貫性のある単一の Basic Memory ノートに記録します。

目的

スレッドには始まり、中盤、終わりがあります。会話が進むにつれて状況は変化します。初期の決定が見直されたり、新しい情報によって問題の見え方が変わったり、最初に考えていたものとは異なる形でトレードオフが決着したりします。このスキルを呼び出す際は、そこに至るまでの経緯ではなく、現時点での理解を記録します。

同じスレッドでこのスキルが複数回呼び出された場合は、一貫性を保つため、同じノートを書き換えます。追記はしません。結果は、意味のある変更に触れる必要がある場合は簡潔な文章を添えつつ、スレッドの結論をまとめた単一の文書として、上から下まで読めるものにしてください。

使用するタイミング

一般的なタイミングは、記録する価値がある程度のことが決まったスレッドの途中または終盤です。

次の場合にこのスキルを使用してください。

• スレッドの終了とともに忘れられては困る重要な決定がなされた
• 設計、デバッグ、計画についての議論から具体的な成果が得られた
• ユーザーが、話し合った内容を記録、保存、または記憶するよう明示的に依頼した
• セッションの終盤で、結果を要約したい

会話の進展に応じて、同じスレッド内でこのスキルを複数回呼び出しても問題ありません。むしろ、それを想定しています。

同一スレッドの判定

再度記録する際にノートを重複させず、同じノートを書き換えるには、フロントマターの安定した thread_id をキーにします。

エージェントが安定したセッション ID またはスレッド ID を公開している場合は、それを thread_id として保存してください。同じスレッド内で後から記録する際に、同じノートを見つけて書き換えられるようになります。スレッドの間、一定であり続ける値であれば、セッション UUID、会話 ID、作業の対象となるチケット番号など、どの値でもかまいません。

例（JSONL トランスクリプトを持つホストの場合）： エージェントによっては、セッションごとのトランスクリプトを安定したセッション UUID のファイル名で保存します。その場合は、最終更新日時が最も新しいトランスクリプトファイルから ID を取得し、thread_id として使用できます。これは任意です。ホストが実際にそのようなトランスクリプトを公開している場合に限り、使用してください。

安定した ID がない場合は、代わりにタイトルまたはトピックで既存のノートを照合します。同じスレッドを扱うノートを検索し（bm_search(query="<topic>")）、このスレッドですでに作成されたノートが見つかった場合は、それを書き換えてください。thread_id は省略し、一貫したタイトルを使用します。

判断の流れ

1. スレッドキーを決めます。 エージェントが安定したセッション ID またはスレッド ID を公開している場合はそれを使用し、そうでない場合はタイトルまたはトピックで照合します。
2. Basic Memory で既存のスレッドノートを検索します。
   • スレッド ID がある場合は、query ではなく filters を使用します。全文検索クエリでは、YAML フロントマターのカスタムフィールドを確実に照合できないためです。

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

   • スレッド ID がない場合は、トピックで検索し、このスレッドですでに作成されたノートを特定します。

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

3. 一致するノートが見つかった場合：
   • 検索結果で返された完全なパーマリンクを使って、既存のノートを JSON として読み込み、checksum を保持します
   • 会話から得られた最新の理解を反映した新しいバージョンを作成します
   • 返された file_path を identifier として使用し、overwrite=True およびそのチェックサムを設定した expected_checksum を指定して、bm_write で上書きします（使用している場合は同じ thread_id を使います）。REVISION_CONFLICT エラーが発生した場合は、別のセッションが読み込み後にノートを変更しています。ノートを再度読み込み、内容を再構成してください
4. 一致するノートが見つからない場合：
   • 会話をもとにノートを作成します
   • スレッド ID がある場合は、bm_write に metadata={"thread_id": "<thread-id>"} を渡します（これはカスタムのフロントマターフィールドとして表示されます）
   • ノートを保存します。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. 関連ノートには積極的にリンクします。 ユーザーがこのノートからアクセスしたいと思われるノートをリンクします。