AIエージェントのためのNoteBrain CLIスキル
NoteBrainは、ObsidianボールトをローカルChromaDBベクトルデータベースにインデックス化する高パフォーマンスなGo CLIツールです。マークダウンノートに対して、セマンティック検索、グラフ探索、バックリンク発見、隠れた関係の発見、全文取得、タグ分析を提供します。
核となる実行原則と根拠
効率的に動作し、トークンの無駄遣いやセッションのハングを防ぐために、以下の基本原則に従ってください。
- NoteBrainのみ使用 — 汎用ファイル検索は禁止: ユーザーの質問に答えるために、ボールト内のマークダウンファイルに対して
grep、find、lsやアドホックなシェルスクリプトを使用しないでください。NoteBrainのコマンドは、インデックス化されたベクトルデータベースとグラフデータベース上に構築されており、ファイルシステムレベルのテキスト検索よりも常に高品質で関連性の高い結果を生成します。notebrainをボールトコンテンツへの唯一のインターフェースとして扱ってください。notebrainコマンドが有用な結果を返さないように見える場合は、汎用ファイル検索にフォールバックするのではなく、notebrainのクエリ(別の言い回し、広い--limit、別のコマンド)を調整してください。 - 非対話型実行(
--format json): デフォルトでは、NoteBrainは人間のブラウジング用に設計された対話型ターミナルTUI(Bubble Tea)を起動します。この対話型インターフェースは自動化されたエージェントセッションをハングさせます。クエリコマンドでは常に--format json(または--format ndjson/--format tsv)を指定して、構造化された解析可能なデータを即座に受け取ってください。すべてのJSONエンベロープフィールドは、クリーンなsnake_caseキー(note_slug、title、file_path、score、tags、text)を使用していることに注意してください。 - AIエージェントコマンドチェーン(
--jsonpath): 特定のフィールドのみが必要な場合(後続のコマンドにパイプするためのノートスラッグやテキストの抽出など)は、--jsonpathを使用してください(例:--jsonpath="$.results[0].note_slug"または--jsonpath="$.results[*].note_slug")。--jsonpathを使用すると、スカラー値は生の引用符なし文字列として出力され、配列は各アイテムが新しい行に出力されるため、jqを使わずにシームレスにシェル変数を抽出できます。 - 完全なノートの取得(
notebrain get):searchが関連するノートチャンクを返した場合、チャンクインデックスを推測するのではなく、notebrain get <note-slug-or-path>を使用して、インデックス化されたすべてのチャンクをつなぎ合わせた完全な再構成マークダウンノートテキストを取得してください。基礎となるボールトファイルにcatを使用することは絶対に避けてください。getはチャンク化されたノートを正しく再構成し、ボールトのインデックス状態を尊重します。 - 合成のためのコンテンツ取得(
--include-text): デフォルトでは、searchとトラバーサルコマンドは軽量なメタデータエンベロープ(タイトル、ファイルパス、タグ、類似度スコア)を返します。検索結果から個々のチャンクについて直接要約や推論が必要なタスクの場合は、--include-textを追加してください。返されるtextフィールドには、コードブロックが保存されたリッチなマークダウンが含まれているため、コードスニペットはコピー&ペースト可能です。 - バイナリの解決と引用符: 開発環境では、
notebrainがシステムPATHにない場合は./notebrainを実行してください。ノートのタイトルにはスペースや括弧("Q3 Planning [Draft]")が含まれることが多いため、ノートのタイトル、タグ、検索クエリは常に二重引用符で囲んでください。 - 組み込み永続ストレージ: NoteBrainは埋め込みデータベース(
~/.notebrain/chroma)として排他的に実行されます。スタンドアロンのChromaDB DockerコンテナやHTTPサーバーは必要ありませんし、サポートもされていません。 - 自動化された取り込み: 取り込みはOSスケジューラ(cron/systemdタイマーで3時間ごと)を介して処理されます。ユーザーがノート編集後に明示的に即時再インデックスを要求しない限り、クエリの前に手動で
ingestを実行する必要はありません。
コマンド選択ガイド
ユーザーの分析目標に合わせて専門のコマンドを選択してください。
| ユーザーの意図 | コマンド | 理由と使用方法 |
|---|---|---|
| 「Xについてのノートは何と言っている?」 | search | すべてのノートチャンクに対してベクトル類似度検索を実行します。--tag="TagName" でタグによるフィルタリングが可能です。 |
| 「Yの完全な内容を読む」 | get | スラッグまたはファイルパスから、完全なノートテキストとメタデータを取得して再構成します。 |
| 「このノートに直接リンクしているものは?」 | backlinks | 対象ノートを指す明示的な [[wikilink]] 参照を見つけます。 |
| 「グラフ内で構造的に近いものは?」 | connections | ウィキリンクを --hops N まで幅優先探索(BFS)します。指数爆発を避けるため --hops 1 または --hops 2 に抑えてください。 |
| 「リンクされていないが意味的に関連しているものは?」 | hidden | リンクされていないが意味的に類似したノートを表面化します。概念的な橋渡しを発見するのに非常に価値があります。 |
| 「ノートYを中心としたXに関連する概念を見つける」 | boosted | ベクトル類似度と --seed ノートへのグラフ近接性を組み合わせます。 |
| 「Xとタグを共有するノートは?」 | tags | タグの重複を分析します。tags 配列にクリーンなタグ文字列を返します。 |
| 「データベースは最新ですか?」 | stats | コレクション数(chunks、links)を出力します。--format=json と --jsonpath をサポートします。 |
| 「ボールトをインデックス化または再インデックス化」 | ingest | マークダウンノートをChromaDBに同期します。再取り込みは冪等です。 |
コマンド構文
セマンティック検索とタグフィルタリング(search)
notebrain search "kubernetes reconciliation" --tag="Kubernetes" --limit 5 --format json --include-text
主要な検索フラグ
| フラグ | 目的 | デフォルト |
|---|---|---|
--top-k N | 保持するノートごとの最大チャンク数。1つの長いノートが結果を支配するのを防ぎ、深みを保ちます。 | 3 |
--context-window N | 各マッチの周囲から±N個の隣接チャンクを取得し、context 配列に格納します。ほとんどのタスクでは 1 または 2 を使用します。 | 0 |
--has-tasks | タスクリスト(チェックボックス)を含むチャンクのみを返します。 | off |
--has-code | フェンスで囲まれたコードブロックを含むチャンクのみを返します。 | off |
--section | 特定の見出しパス(例:"Architecture > Components")以下のチャンクに結果をフィルタリングします。 | — |
--limit N | 返す最大合計結果数。 | 10 |
--tag "TagName" | タグ名でフィルタリングまたは検索します。 | — |
--min-score F | この類似度スコア(0–1)未満の結果を抑制します。 | 0 |
--context-window と notebrain get の使い分け
--context-window 1を使用する場合: 複数の検索結果に対して軽量な周辺コンテキストを一度に取得する必要がある場合。効率的です。1回の検索呼び出しで、マッチしたチャンクとその隣接チャンクの両方を取得でき、ノート全体を取得しなくてもローカルコンテキストを理解するのに十分です。notebrain getを使用する場合: 完全な再構成ノートテキストが必要な場合。たとえば、ユーザーが特定のノートの読み取りや要約を求めている場合、または完全なドキュメント構造を確認する必要がある場合です。
ウィンドウアプローチは、多くの検索結果を処理する場合に特に価値があります。なぜなら、すべての結果に対してノート全体を取得するのは無駄だからです。まずウィンドウを取得し、その後、真に全文コンテキストが必要なノートだけを選択的に get してください。
完全なノート取得(get)
notebrain get "02areaskubernetesckadkubernetes-native-applications" --format json
グラフ接続と隠れたリンク(connections, hidden)
notebrain connections "Distributed Systems" --hops 2 --format json
notebrain hidden "Microservices" --limit 5 --format json --include-text
JSON出力スキーマ
結果構造を理解することは、信頼性の高いフィールド抽出に不可欠です。すべてのクエリコマンドは、結果を次のエンベロープでラップします。
{
"command": "search",
"query": "Semantic Search: \"kubernetes\"",
"total": 3,
"results": [
{
"note_slug": "02areaskubernetes-architecture",
"title": "Kubernetes Architecture",
"file_path": "02.Areas/Kubernetes/Architecture.md",
"score": 0.82,
"chunk_index": 2,
"tags": ["Kubernetes", "DevOps"],
"heading_path": "Components > Control Plane",
"text": "The API server validates and configures...",
"context": [
"Previous chunk text about etcd storage...",
"The API server validates and configures...",
"The scheduler watches for newly created Pods..."
]
}
]
}
| フィールド | 存在する場合 | 説明 |
|---|---|---|
note_slug | 常に | ファイルパスから派生したURLセーフな識別子。 |
title | 常に | フロントマターまたはファイル名からのノートタイトル。 |
file_path | 常に | ボールト内の相対パス。 |
score | 常に | 検索の場合は類似度スコア(0–1);接続の場合はホップ数。 |
chunk_index | 検索、hidden、boosted | マッチしたノートのチャンク(0始まり)。 |
tags | ノートにタグがある場合 | タグ文字列の配列。 |
heading_path | チャンクが見出しの下にある場合 | "Section > Subsection" のようなパンくずパス。 |
text | --include-text が渡された場合 | マッチしたチャンクの完全なマークダウンテキスト。コードブロックは保持されます。 |
context | --context-window N > 0 の場合 | チャンクインデックス順の、±N個の隣接チャンクテキストの配列。 |
extra | 接続、タグ、boosted | コマンド固有の情報(例:"2 hop(s)"、"graph-boosted")。 |
回答品質の向上:マルチシグナル検索
「Xについて私は何を知っているか」または「Xに関する私のノートを要約して」といった質問に答える前に、単一の search 呼び出しで止まらないでください。検索結果だけでは、クエリに意味的に近いチャンクしか表面化されません。ユーザーがグラフに意図的に構築した周囲のコンテキストを見逃してしまいます。常に視野を広げてください。
- コンテキスト付きで検索 —
--context-window 1 --include-text --top-k 2を指定してsearchを実行し、最も関連性の高いチャンクとその周囲の段落を取得します。これにより、1回の呼び出しで精度(マッチしたチャンク)とコンテキスト(その前後)の両方を得られます。 - 各シードのバックリンクを取得 —
notebrain backlinks <seed-slug> --format json --include-textを実行して、シードに明示的にリンクしているすべてのノートを抽出します。これらはユーザーが手動で関連性があるとキュレーションしたノートであるため、その内容はほとんどの場合シグナルが強く、合成において重み付けする必要があります。 - 接続を外側にたどる —
notebrain connections <seed-slug> --hops 2 --format jsonを実行して、シード周辺のローカルグラフ近傍をマッピングします。これにより、純粋なベクトル検索では現れないが、同じ知識クラスターの一部である構造的に隣接したノート(例:2リンク先のノート)が明らかになります。 - 隠れたリンクを確認 —
notebrain hidden <seed-slug> --include-text --context-window 1を実行して、ユーザーがまだリンクしていない概念的に関連するノートをキャッチします。これらをユーザーに対して、ボールト内の潜在的な欠落リンクとして明示的に指摘してください。これはNoteBrainがプレーンな検索よりも持つ最も価値のある差別化要因の1つです。 - 列挙するのではなく合成する — シードノート、そのバックリンク、その
connections近傍、およびhidden結果を単一の一貫した回答に結合し、明示的にリンクされているもの(高信頼度)と意味的に類似しているだけのもの(再確認が必要)を区別してください。
この search → backlinks → connections → hidden チェーンは、些細な探索質問であってもデフォルトのワークフローであるべきであり、単一の search 呼び出しに留まるべきではありません。なぜなら、ユーザーが構築した明示的な構造と、NoteBrainが検出できる暗黙的な構造の両方を表面化するからです。
AIエージェント連鎖パイプライン
# 1. 周囲コンテキストで検索 — top-k により結果がノート間で多様に保たれる
SLUG=$(notebrain search "message broker backpressure" --limit 3 --top-k 2 \
--context-window 1 --include-text --format json \
--jsonpath="$.results[0].note_slug")
# 2. トップヒットの完全な再構成ノートテキストを取得
notebrain get "$SLUG" --jsonpath="$.text"
# 3. このノートを指すすべてのバックリンクノートスラッグとその内容を見つけ、
# ユーザーが明示的にリンクしたものに回答を基づける
notebrain backlinks "$SLUG" --format json --include-text
# 4. グラフ近傍をたどり、ベクトル検索だけでは見逃される
# 構造的に隣接したノートを表面化
notebrain connections "$SLUG" --hops