Communitygithub.com

nmdra/notebrain-cli

NoteBrainは、ObsidianボールトをローカルのChromaDBベクトルデータベースにインデックス化する高パフォーマンスなGo CLIツールです。AIエージェントが個人のナレッジベースをインテリジェントに探索できるよう、強力なセマンティック検索、バックリンク探索、タグベースの発見機能を提供します。

notebrain-cli とは?

NoteBrain CLI Skill for AI Agentsは、AIエージェントがObsidianボールトの内容を効率的に探索・分析するための専用インターフェースです。Goで実装されたCLIツールで、ボールト内のマークダウンノートをChromaDBベクトルデータベースにインデックス化し、セマンティック検索、グラフ探索、バックリンク発見、隠れた関係の発見、全文取得、タグ分析などをワンコマンドで実行できます。エージェントが対話型TUIでハングしないよう、`--format json`による非インタラクティブ実行が推奨され、`--jsonpath`オプションで必要なフィールドのみを抽出できます。特に、単一の `search` コマンドに止まらず、`search → backlinks → connections → hidden` というマルチシグナル検索チェーンを実行することで、明示的なリンク構造と暗黙的な意味的類似性の両方を考慮した高品質な回答合成が可能となります。

対応~Claude Code~Codex CLI~Cursor
npx skills add nmdra/notebrain-cli

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

AIエージェントのためのNoteBrain CLIスキル

NoteBrainは、ObsidianボールトをローカルChromaDBベクトルデータベースにインデックス化する高パフォーマンスなGo CLIツールです。マークダウンノートに対して、セマンティック検索、グラフ探索、バックリンク発見、隠れた関係の発見、全文取得、タグ分析を提供します。

核となる実行原則と根拠

効率的に動作し、トークンの無駄遣いやセッションのハングを防ぐために、以下の基本原則に従ってください。

  1. NoteBrainのみ使用 — 汎用ファイル検索は禁止: ユーザーの質問に答えるために、ボールト内のマークダウンファイルに対して grep、find、ls やアドホックなシェルスクリプトを使用しないでください。NoteBrainのコマンドは、インデックス化されたベクトルデータベースとグラフデータベース上に構築されており、ファイルシステムレベルのテキスト検索よりも常に高品質で関連性の高い結果を生成します。notebrain をボールトコンテンツへの唯一のインターフェースとして扱ってください。notebrain コマンドが有用な結果を返さないように見える場合は、汎用ファイル検索にフォールバックするのではなく、notebrain のクエリ(別の言い回し、広い --limit、別のコマンド)を調整してください。
  2. 非対話型実行(--format json): デフォルトでは、NoteBrainは人間のブラウジング用に設計された対話型ターミナルTUI(Bubble Tea)を起動します。この対話型インターフェースは自動化されたエージェントセッションをハングさせます。クエリコマンドでは常に --format json(または --format ndjson / --format tsv)を指定して、構造化された解析可能なデータを即座に受け取ってください。すべてのJSONエンベロープフィールドは、クリーンな snake_case キー(note_slug、title、file_path、score、tags、text)を使用していることに注意してください。
  3. AIエージェントコマンドチェーン(--jsonpath): 特定のフィールドのみが必要な場合(後続のコマンドにパイプするためのノートスラッグやテキストの抽出など)は、--jsonpath を使用してください(例:--jsonpath="$.results[0].note_slug" または --jsonpath="$.results[*].note_slug")。--jsonpath を使用すると、スカラー値は生の引用符なし文字列として出力され、配列は各アイテムが新しい行に出力されるため、jq を使わずにシームレスにシェル変数を抽出できます。
  4. 完全なノートの取得(notebrain get): search が関連するノートチャンクを返した場合、チャンクインデックスを推測するのではなく、notebrain get <note-slug-or-path> を使用して、インデックス化されたすべてのチャンクをつなぎ合わせた完全な再構成マークダウンノートテキストを取得してください。基礎となるボールトファイルに cat を使用することは絶対に避けてください。get はチャンク化されたノートを正しく再構成し、ボールトのインデックス状態を尊重します。
  5. 合成のためのコンテンツ取得(--include-text): デフォルトでは、search とトラバーサルコマンドは軽量なメタデータエンベロープ(タイトル、ファイルパス、タグ、類似度スコア)を返します。検索結果から個々のチャンクについて直接要約や推論が必要なタスクの場合は、--include-text を追加してください。返される text フィールドには、コードブロックが保存されたリッチなマークダウンが含まれているため、コードスニペットはコピー&ペースト可能です。
  6. バイナリの解決と引用符: 開発環境では、notebrain がシステムPATHにない場合は ./notebrain を実行してください。ノートのタイトルにはスペースや括弧("Q3 Planning [Draft]")が含まれることが多いため、ノートのタイトル、タグ、検索クエリは常に二重引用符で囲んでください。
  7. 組み込み永続ストレージ: NoteBrainは埋め込みデータベース(~/.notebrain/chroma)として排他的に実行されます。スタンドアロンのChromaDB DockerコンテナやHTTPサーバーは必要ありませんし、サポートもされていません。
  8. 自動化された取り込み: 取り込みは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 呼び出しで止まらないでください。検索結果だけでは、クエリに意味的に近いチャンクしか表面化されません。ユーザーがグラフに意図的に構築した周囲のコンテキストを見逃してしまいます。常に視野を広げてください。

  1. コンテキスト付きで検索 — --context-window 1 --include-text --top-k 2 を指定して search を実行し、最も関連性の高いチャンクとその周囲の段落を取得します。これにより、1回の呼び出しで精度(マッチしたチャンク)とコンテキスト(その前後)の両方を得られます。
  2. 各シードのバックリンクを取得 — notebrain backlinks <seed-slug> --format json --include-text を実行して、シードに明示的にリンクしているすべてのノートを抽出します。これらはユーザーが手動で関連性があるとキュレーションしたノートであるため、その内容はほとんどの場合シグナルが強く、合成において重み付けする必要があります。
  3. 接続を外側にたどる — notebrain connections <seed-slug> --hops 2 --format json を実行して、シード周辺のローカルグラフ近傍をマッピングします。これにより、純粋なベクトル検索では現れないが、同じ知識クラスターの一部である構造的に隣接したノート(例:2リンク先のノート)が明らかになります。
  4. 隠れたリンクを確認 — notebrain hidden <seed-slug> --include-text --context-window 1 を実行して、ユーザーがまだリンクしていない概念的に関連するノートをキャッチします。これらをユーザーに対して、ボールト内の潜在的な欠落リンクとして明示的に指摘してください。これはNoteBrainがプレーンな検索よりも持つ最も価値のある差別化要因の1つです。
  5. 列挙するのではなく合成する — シードノート、そのバックリンク、その 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

関連スキル