brain-ops

Brain Operations — アンビエントコンテキストレイヤー

応答する前に、関連するコンテキストを想起してください。明示的な依頼は出典情報とともに保存します。自動キャプチャは、ユーザーがオプトインするまで無効です。このスキルを読んでも、キャプチャ、委任、有料の情報拡充は有効になりません。チャットのみの指示は、そのターンの書き込みを抑制します。これは、常時キャプチャが有効な場合も同様です。

規約： 検索チェーンとコピーして使える取得フィルターについては、skills/conventions/brain-first.md を参照してください。 規約： 引用とバックリンクのルールについては、skills/conventions/quality.md を参照してください。 メモリ動詞（MEMORY_VERBS v1、gbrain ≥ 0.43）。 MCP 経由では、読み書きサイクルに次の5つのコアメモリ動詞を優先してください。**remember(fact, provenance, ttl?)は単一の永続的な事実を保存します（出典情報は必須。重複排除と置き換えを行います）。recall(query | entity, budget_tokens)は予算に収まるようまとめて読み戻します。entity(name)はLLMを使わずにカードを取得します。synthesize(question)はコストの高いページ横断の回答を生成します。forget(id)**は有効なメモリを取り消します（履歴、ソース資料、バックアップは残る場合があります）。context_packとdeltaを加えたものが、7つの動詞からなるインターフェースです。すでに1つの事実がまとまっている場合は、extract_factsではなくrememberを使ってください。ページ／グラフへの書き込みには、引き続きput_page／add_link／add_timeline_entryを使います。これらの動詞がインターフェースにない場合は、従来の操作にフォールバックしてください。仕様：docs/protocol/MEMORY_VERBS_v1.md。

厳しい予算制約のあるページに関する質問：「キリン望遠鏡」のような質問では、ページのランク付けされたエビデンスが最近の事実より先にパックされるよう、明示的に recall({query: "zebra telescope", budget_tokens: 75, budget_policy: "query_first"}) を使ってください。CLI： gbrain recall --query 'zebra telescope' --budget-tokens 75 --budget-policy query_first --json。 エンティティ優先、イベント／セッションで絞り込む質問、事実に焦点を当てた質問には、既存の事実優先の経路を引き続き使ってください。context_packは変更しないでください。コストは文字数に基づく推定値であり、最初の項目が大きすぎる場合はスキップも切り詰めもせず、その項目を除外します。結果が空の場合にメモリがないと判断する前に、budget_packingを確認してください。MCP リクエストと呼び出し元の例はskills/query/SKILL.mdを参照してください。ガイダンスはネイティブハーネスを有効化するものではありません。オプトインした呼び出しが実行される新しい会話を確認するまでは、導入は未検証のままです。

意図した可視性を参照できる読み戻し経路を選んでください。 信頼されたローカル CLI の呼び出し元は、非公開の事実を取得したり取り消したりできます。stdio を含むすべての MCP 呼び出し元と、MCP に接続された薄い CLI では、現在、事実の取得と取り消しはワールド可視のものに限られます。記憶を求めるリクエストは、実際の非公開情報をワールド可視にする許可にはなりません。利用できる場合は、非公開メモリに対して信頼されたローカルの書き込み／読み戻し経路を使ってください。リモートアクセスしか利用できない場合、非公開情報の書き込みが成功したことを示すレシートで保存は確認できますが、非公開情報の取得は未検証のままです。この制限と、非公開情報を読み戻したり取り消したりするために必要な信頼されたローカル経路を説明してください。検証に合格させるためだけに可視性を広げたり、より広範な OAuth スコープを要求したりしないでください。MCP 接続テストには、ユーザーのテスト承認を得た無害な合成 visibility: "world" フィクスチャのみを使い、その ID を保持して、テスト後に取り消してください。

**結果に含まれる<REDACTED:pattern>（例：<REDACTED:url_credentials>や <REDACTED:high_entropy_assignment>）**は、脳がその位置に認証情報のような値を保持しており、この応答からは伏せられていることを意味します。保存されたページは変更されていません。どの種類の値が伏せられたか、そして脳ホスト上では読み取り可能であることをユーザーに伝えてください。取り戻すために別の操作を再試行したり、推測した値を繰り返したりしないでください。ユーザーがrememberするよう依頼した認証情報は、設計上、リモートからの取得では伏せられます。stdio を含むすべての MCP 呼び出し元と、MCP に接続された薄い CLI はリモートであるため、記述されたとおりの値を表示できるのは、脳ホスト上で実行したgbrain recallのみです。ドキュメント： docs/guides/write-refusals.md#secret-scan-refusals-and-redaction。

キーのない脳：extract_factsがskipped: extraction_unavailableを返した場合、抽出を行うのはあなたです。そのターンから事実を自分で取り出し、kindを設定して（event | preference | commitment | belief | fact — この5つが固定されたプロトコルの列挙値です。抽出器と DB が扱うidea種別は、そのいずれにも含まれません）、エンベロープのagent_actionが指定する可視性（既定値は非公開です。明示的に指定してください。rememberの既定値はワールド可視です）で、それぞれをremember経由で書き込んでください。または、エンティティページに## Factsフェンスを記述してください。skipped: extraction_failedのエンベロープ（サーバー側の抽出器がこのターンでエラーになり、理由はreasonに示されています）が返された場合も、そのターンについて同様に手動でrememberにフォールバックします。今後の書き込みでは、自動抽出が引き続き有効です。

契約

このスキルは、以下を保証します。

• 外部 API を呼び出す前に、必ず Brain を確認します（Brain を最初に参照）
• 明示的な保存リクエストと、オプトインされた受信シグナルによって、READ → WRITE のループが実行されます。情報の補完には、別途設定された権限が必要です
• すべての送信応答で、関連するコンテキストがないか Brain を確認します
• 書き込むすべての事実に出典を明記します（インラインの [Source: ...] 引用）
• ユーザーの直接の発言を、最も権威のあるデータとして扱います
• Brain への書き込みごとに、バックリンクを維持します（鉄則）

鉄則：バックリンク（必須）

Brain ページがある人物または企業に言及するたびに、そのエンティティのページから、言及しているページへのバックリンクを作成する必要があります。リンクされていない言及は、壊れた Brain です。形式については skills/conventions/quality.md を参照してください。

フェーズ

フェーズ 1：Brain を最初に参照（必須）

人物、企業、トピックを調査するために外部 API を使う前に、必ず以下を実行します。

1. gbrain entity "<name>"（v0.43+）— 既知の人物、企業、プロジェクトが 1 つの場合、完全なカード（説明、別名、未解決の話題、最近の出来事、エッジ、バックリンク数／事実数）を取得します。LLM 呼び出しはゼロで、100 ミリ秒未満です。既知のエンティティを調べる場合、この 1 回の呼び出しで手順 2～6 を置き換えられます。近似する名前が見つかった場合は候補が提示されます。
2. gbrain search "name" — 既存ページを完全一致トークンで検索します（低コストのハイブリッド検索。拡張なし）。
3. gbrain query "natural question about name" — 概念や全体像に関する質問は、まずここで検索します（意味マッチングと再ランキングにより、類義語を使った表現も検出します。結果が少ない場合は --expand により LLM でクエリを書き換えます。search の件数がゼロでないからといって、結果が網羅的とは限りません）。
4. gbrain get <slug> — スラッグが分かっている場合は、ページ全体を読み込みます。
5. バックリンクを確認します。このエンティティを参照しているのは誰ですか？
6. タイムラインを確認します。このエンティティに関する最近の出来事はありますか？

Brain には、ほとんどの場合、何らかの情報があります。外部 API は不足分を補うために使い、ゼロから調査を始めるためには使いません。Brain ファイルを直接読み込んだり、grep したり、クエリしたりする前に gbrain で検索してください。フィルター（--types、--match keyword、query --since/--until、--source、--json）については、brain-first 規約の「Retrieval: gbrain first」ブロックを参照してください。

⚠️ 浅い ls でコーパスの範囲や件数を調べてはいけません。gbrain または find でクエリしてください。 フェデレーションされたソースには、複数のディレクトリ構成が共存していることがよくあります。フラットなレガシー構成と、日付ごとにネストされた meetings/YYYY/MM/ 構成の両方がある場合があります。再帰しない ls dir/*.md ではどちらか一方しか確認できず、件数を大幅に過少カウントします。実例：あるソースの meetings/ を浅い ls で調べたところ、132 件が数えられ、そのほとんどがユーザーのファイルだったため、それがコーパス全体だと結論づけました。その結果、meetings/YYYY/MM/ の下にネストされた数千件のトランスクリプトを見落としました。Brain コーパスの件数や範囲を調べるには、次のようにします。

• 最適な方法： gbrain sources list（ソースごとにインデックス化されたページ数を表示）と gbrain query を使います。gbrain はすべてのフェデレーションソースを正しくインデックス化します。ファイルシステムではなく、インデックスを信頼してください。
• ファイルシステムを調べる必要がある場合： find <dir> -name '*.md' | wc -l を使います。ls *.md は使わないでください。その後、レイアウトを確認します：find <dir> -name '*.md' | sed -E 's#(.*/)[^/]+$#\1#' | sort | uniq -c。
• 問題は決して「gbrain がソースを認識できない」ことではありません。ほとんどの場合、浅いファイルシステムのグロブが原因です。少ない件数を信じる前に、gbrain sources list と照合してください。

フェーズ 1.5：分析クエリ（gbrain think）

単に「ページを見つける」のではなく、質問への回答が必要な、情報の統合、時間軸を踏まえた分析、または分析的な回答を求める場合：

1. gbrain think "<question>" を使います。ページ、takes、グラフを横断して複数段階の情報を統合します。時間に関する質問は軌跡分析に振り分けられ、それ以外は、矛盾と情報の欠落を分析したうえで、LLM が引用付きの回答を合成します。一致したページの一覧だけでなく、根拠に基づいた回答が返されます。
2. 適した質問の例：「acme-example が最後に資金調達したのはいつか」「3 月の ARR はいくらだったか」「Q1 以降、何が変わったか」「alice-example の共同創業者は誰で、何に取り組んでいるか」「acme-example との関係を要約してください」。
3. タイムライン上の事実が見つからない場合は、標準的な検索に適切にフォールバックします。
4. コスト：質問ごとに LLM 呼び出しが発生します。これはコストの高い方法です。スラッグや簡単なコンテキスト確認だけが必要な場合は、シンプルなページ検索に query を使ってください。

フェーズ 2：許可された記録（READ → WRITE）

明示的な保存依頼がある場合、またはチャットのみという制限がないユーザーのオプトイン済み記録範囲内のメッセージの場合：

1. エンティティを検出する — 言及された人、会社、案件
2. ブレインのページを読み込む — 回答前に既存のページを読み、背景情報を確認する
3. 新しい情報を特定する — この情報は、ページがまだ把握していない何を示しているか？
4. 書き戻す — 新しい情報、タイムライン項目、出典の引用をブレインのページに追加する
5. 存在しない場合は作成する — 注目に値する場合、提供された情報を出所情報とともに保存する。エンリッチメントは別途許可されている場合にのみ実行する

ユーザーの直接の発言には [Source: User, YYYY-MM-DD] を付けてください。 記録の許可がない場合は、現在の会話内で情報を使用し、永続化しないでください。 明示的に記憶するよう依頼されても、継続的な記録は有効になりません。

フェーズ 2.5：構造化グラフの更新（自動リンク）

「自動リンク」の照合処理では、ページからエンティティ参照を抽出し、推定した関係タイプとともにグラフ（links テーブル）へ書き込みます。ページ本文に存在しなくなった古いリンクは削除されます。実行する主体は書き込み経路によって異なります。

• 信頼されたローカル書き込み（gbrain put、gbrain capture、 gbrain call put_page）では、自動リンク処理がインラインで実行され、 auto_links: { created, removed, errors } が返されます。
• **MCP 呼び出し元（stdio と HTTP の両方）**では、auto_links: { skipped: "remote", hint } と auto_timeline: { skipped: "remote" } が返されます。本文中のウィキリンクはテキストとして保存されます。 コミット後の処理では、同じソース内にすでに存在するページに対して、通常の mentions エッジが追加されます（auto_links.mention_links: "queued"。gbrain config set mcp.remote_auto_links off で無効化できます）。型付きエッジ、フロントマターのエッジ、タイムラインのエッジは対象外です。stdio の gbrain serve は、メンテナンススイープ（起動時と 10 分間のアイドル時のティック）で、それらを非同期に照合します。 gbrain serve --http は自動スイープを実行しません。gbrain sweep --once（IPC 経由で稼働中のサーバーに処理を委譲）または gbrain extract links --source db で必要に応じて照合してください。 会議ページから自動リンクされる会議への出席を除き、すぐに必要な関係には add_link を使用してください。信頼されていない本文テキストによってランキングを高めるエッジが仕込まれるおそれがあるため、インライン処理はローカル限定です。
• 推定されるリンクタイプ：attended、works_at、invested_in、founded、advises、source（フロントマター）、mentions（デフォルト）。有効なスキーマパックが出席情報を上書きしない場合（gbrain init が設定する gbrain-base-v2）、attended は会議ページに明示された出席者リスト（Attendees: 行または attendees: フロントマター）からのみ作成され、person -> meeting の向きになります。古い gbrain-base など、これを上書きするパックでは独自のルールと方向が設定されます。
• 無効にするには、gbrain config set auto_link false を実行します。デフォルトはオンです。
• 日付が指定されたタイムライン項目には、引き続き明示的な gbrain timeline-add（または gbrain extract timeline --source db による一括処理）が必要です。

フェーズ 3：すべての送信応答時（READ → PULL → RESPOND）

人、会社、トピックに関する質問に回答する前に、必ず次の手順を実行してください。

1. ブレインを確認する — 関連するページを読む
2. 背景情報を取得する — 統合された情報と最近のタイムラインを使用する
3. 背景情報を踏まえて回答する — ブレインがあれば、すべての回答の質が高まります

ブレインのページが存在する場合、一般知識だけで回答しないでください。

フェーズ 4：任意のエンリッチメント

エンリッチメントは、ユーザーが追加で選択するものです。エンティティへの言及、リンクの共有、記録のオプトインのいずれも、それだけでは外部調査、有料の呼び出し、委任を許可しません。明示的な取り込み／エンリッチメント依頼、またはユーザーが保存した範囲と支出ポリシーに従ってください。その権限がない場合は、既存のコンテキストを想起し、ユーザーが保持を許可した提供情報のみを保存してください。

委任が許可され、実行環境でサポートされている場合にのみ、バックグラウンドエージェントを使用してください。生成されたルーチンが実行されたと主張せず、観測された結果を報告してください。

出力形式

取得したコンテキストを回答で使用し、引用してください。書き込みを行う場合は、読み戻しを確認してから完了を伝えてください。書き込みが依頼されていない、または明示的に許可されていない場合は、メモリーを更新するためだけに会話を保存しないでください。

複数ソースの引用形式（v0.18.0+）

脳に複数のソース（wiki、gstack、yc-media など）がある場合、すべての引用にソース ID を含めてください：[source-id:slug]。例：

リトライ予算のアプローチについてお聞きしました。詳しくは [wiki:topics/resilience] と [gstack:plans/retry-policy] をご覧ください。 これらが情報の出典です。

ルール：

• キーは sources.name（変更可能な表示名）ではなく、sources.id（不変）です。
• 単一ソースの脳では、[default:slug] を記載するか、後方互換性のために省略できます。
• search、query、get_page、list_pages が返す各ページのペイロードには source_id が含まれます。引用時には必ずこれを使用し、推測しないでください。

検索結果の source_id が "gstack" で、slug が "plans/foo" の場合、引用は [gstack:plans/foo] です。ルールはこれだけです。

失敗した場合

gbrain のエラー code、終了コード、[AGENT] ブロック、または notice ブロックが発生した場合は、エージェントオペレータープロトコルに従ってください。このスキルに固有の事項は次のとおりです。

• put_page が revision_conflict を返した場合：ページを再読み込みし、新しいテキストに変更を反映して、新しいリビジョンで保存してください。write_pending（終了コード 10）の場合：書き込みが完了したと伝える前に、get_write_request（gbrain write-request <request_id>）をポーリングしてください。
• put_page（または capture、tags、timeline）が detail: unbound_source を伴う owner_unavailable を返した場合：これは従来型の Postgres brain です。ソースのチェックアウト内にファイルとしてページを書き込み、コミットしてから gbrain sync --source <id> を実行してください。リモート環境にいる場合は、この3つの手順をユーザーに伝えてください。書き込みを通すためにソースを要求したり、モードを切り替えたりしないでください（エージェントオペレータープロトコルを参照）。
• シークレットスキャンまたは slug フェンスによって書き込みが拒否された（permission_denied）場合：回避するために内容を削除したり名前を変更したりしないでください。何が、なぜ拒否されたかをユーザーに伝えてください（docs/guides/write-refusals.md を参照）。
• recall / search が degraded notice または search_degraded とともに何も返さない場合：何も保存されていないと言うのではなく、現在は脳がキーワードのみで検索していると伝えてください。
• MCP 経由で insufficient_scope / scope_denied が発生した場合：接続に必要なスコープがありません。その旨をユーザーに伝えてください。書き込みを通すためだけに、より広いスコープのトークンを求めないでください。

アンチパターン

• まず脳を確認せずに、人や企業についての質問に答える
• まず脳を確認せずに外部 API を使用する
• インラインの [Source: ...] 引用なしで事実を書き込む
• 情報を補うために回答を遅らせる
• 権威性の低い情報源で、ユーザーの直接の発言を上書きする
• 重要ではないエンティティの脳ページを作成する
• 同じエンティティの重複ページを作成する。作成前に必ず確認してください：gbrain entity "<name>"（別名や類似候補も検出します）、次に名前のバリエーションを使って query

使用するツール

• search — 軽量なハイブリッド検索（ベクトル＋キーワード、展開なし）
• query — 概念や全体像に関する質問向けのハイブリッド検索（--expand を付けると LLM による複数クエリ展開が追加されます）
• get_page — 脳のページを読み取る
• put_page — 脳のページを作成・更新する
• add_link — エンティティを相互参照する
• add_timeline_entry — イベントを記録する
• get_backlinks — あるエンティティを参照しているページを確認する
• sync_brain — 変更をインデックスに同期する