Obsidian Hybrid Search

Obsidian Hybrid Search

Obsidian の保管庫には、すでにあなたの最良の思考が蓄積されています。Obsidian Hybrid Search を使えば、その思考を見つけ、再利用し、AI を活用した作業に取り入れやすくなります。

保管庫に検索エンジンを提供し、実用的な 3 つの利用方法を用意します。ネイティブの Obsidian プラグインを使えば、執筆しながら高速検索、プレビュー、類似ノート、リンクの検出、グラフ表示を利用できます。MCP サーバーを使えば、AI エージェントはツール呼び出しでノートを検索して読み取れます。CLI では、上級ユーザーが同じエンジンを使ってインデックス作成、絞り込み、再ランキング、読み取り、スクリプト処理を行えます。

この検索は、実際の保管庫がどのように構成されているかを理解します。セマンティック検索、BM25 全文検索、タイトルと別名のあいまい一致、タグ、フォルダー、フロントマター、ウィキリンク、バックリンク、類似ノートの検索を組み合わせます。書いたときの正確な言葉を覚えていなくても、アイデア、フレーズ、タイトル、関連性、メタデータから検索できます。

これにより、Obsidian はより強力な個人向けナレッジシステムとなり、AI を活用する作業のより優れた出発点になります。エージェントはあなた自身のノートを起点とし、ソースファイルから引用付きのコンテキストを取り込み、関連資料をたどり、すでに信頼している知識を活用できます。OHS はデフォルトでローカル環境で動作し、SQLite、FTS5、sqlite-vec、RRF ランキング、およびオプションの OpenAI 互換埋め込み API を使用します。

検索品質

Obsidian Help 保管庫（ノート 171 件、クエリ 58 件、ローカルモデル）で評価：

	OHS（本プロジェクト）	qmd
nDCG@5	0.733	0.659
MRR	0.788	0.665
Hit@1	0.724	0.500
平均クエリ時間	571 ms ¹	754 ms ²
モデルのダウンロードサイズ	約 117 MB	約 2.2 GB

¹ CPU（Apple Silicon）、ハイブリッドモード、再ランキングなし。² GPU（Apple Silicon Metal）、LLM によるクエリ拡張と再ランキング。

OHS は Xenova/multilingual-e5-small を使用します。再現方法 → · ベンチマーク全文 →

実際のナレッジ保管庫のベンチマーク

OHS は Andy Matuschak の公開 evergreen notes でも評価されています。タイトルを基にしたノートのファイル名、フロントマター内のソース URL、ローカルの添付ファイルを備え、ノート 1,357 件にわたって 5,000+ 件の内部ノートリンクを含む Obsidian 保管庫に変換して使用します。

厳選されたゴールデンセットには、既知アイテムの検索、言い換え、引用の断片、曖昧なトピック、引用元の検索、複数ノートにまたがる証拠など、手動で判定したクエリが 78 件含まれています。

デフォルトのローカル埋め込みモデルを使用した場合、OHS はこの密なノートネットワークで優れた性能を発揮します。

指標	値
nDCG@5	0.722
nDCG@10	0.753
MRR	0.874
Hit@1	0.795
Hit@5	0.974
Recall@10	0.972
AllRel@10	0.949

このベンチマークでは、ノートのタイトルを単に繰り返すだけではないクエリを含め、実世界の相互に強く結び付いたナレッジ保管庫に対する検索を評価します。

結果 JSON · 再現方法と結果の解釈 →

大規模メモリーベンチマーク

より大規模な公開データセットで検索性能をテストするため、 LongMemEval-S を、22,419 件のノートと 470 件の検索クエリを含む Obsidian 形式の Vault に変換しました。 baai/bge-m3 の埋め込みを使用したところ、OHS は回答を含むノートを上位にランク付けしました。

指標	値
nDCG@5	0.895
MRR	0.920
Hit@1	0.889
Hit@5	0.968
Recall@10	0.950
AllRel@10	0.904

このベンチマークでは、各クエリの検索範囲に LongMemEval が提供するハイスタックを使用しています。 これにより、大規模な生成メモリー Vault での検索性能を検証しながら、結果を再現しやすくし、クエリごとに簡単に確認できます。

結果 JSON · 再現方法と結果の解釈 →

機能

• ハイブリッド検索
  • BM25 + ファジータイトル検索 + セマンティック埋め込みを RRF で統合
• エイリアス検索
  • frontmatter に aliases: を持つノートをインデックス化し、あらゆるエイリアスで検索できます。エイリアスとの一致は BM25（重み 5×）とファジータイトルのスコアでブーストされます
• 4 つの検索モード
  • テキストクエリ向けの hybrid、semantic、fulltext、title
• 類似ノートの検索
  • --path を指定すると、保存されたチャンク埋め込みを使って意味的に関連するノートを検索します。タイトルと本文を使ったフォールバックにも対応しています
• グラフのたどり
  • --path --related で、深さを設定してリンク先のノートを表示します。--direction outgoing|backlinks|both で絞り込めます
• リンクとバックリンク
  • すべての検索結果に発リンクとバックリンクが含まれます
• 検索範囲の絞り込み
  • サブフォルダーに検索範囲を限定します。複数の値と除外（-notes/dev/）に対応しています
• タグの絞り込み
  • タグで絞り込みます。複数の値と除外（-category/cs）に対応しています
• スニペットの制御
  • --snippet-length でコンテキストウィンドウを設定します。スニペットが空の場合は常にノート本文にフォールバックします
• 拡張出力
  • --extended を指定すると、CLI テーブルに TAGS/ALIASES 列が追加され、frontmatter のタグ（#tag）とエイリアスが表示されます
• 増分インデックス作成
  • 変更されたファイルのみを再インデックス化します。編集内容をリアルタイムで監視します
• 複数クエリの一括検索
  • 複数のクエリを一度に渡せます（ohs "q1" "q2" または MCP の queries[]）。結果は RRF で統合されるため、いずれかのクエリで上位にランクされたノートが先頭に表示されます。クエリとは異なる語彙がノートで使われている場合に便利です
• クロスエンコーダーによる再ランキング
  • --rerank を指定すると、gte-multilingual-reranker-base（ONNX int8、初回のみ約 341 MB をダウンロード）で結果を再スコアリングします。概念的なクエリや多言語クエリの精度が向上します。複数クエリの統合後に適用されます
• ローカル埋め込み
  • @huggingface/transformers を使ってオフラインで動作します（API キーは不要）。デフォルトモデルは Xenova/multilingual-e5-small で、100 以上の言語に対応しています
• リモート埋め込み
  • OpenAI 互換 API（OpenRouter、Ollama など）
• ノートの読み取り
  • read は Vault からの相対パスで 1 件以上のノートを取得します。タイトル、エイリアス、タグ、リンク、バックリンクを含む全文を返します。パスが見つからない場合は、ファジー検索による上位 3 件の候補を返します
• 無視パターン
  • フォルダー、拡張子、特定のファイルを除外します
• Obsidian プラグイン
  • 同じ CLI を利用する、Obsidian 内蔵の検索モーダルです。obsidian-hybrid-search-plugin を参照してください

インストール

npm install -g obsidian-hybrid-search

CLI の使用方法

クイックスタート

推奨される設定方法は、~/.zshrc または ~/.bashrc で OBSIDIAN_VAULT_PATH を一度設定することです。これにより、どのディレクトリからでも CLI を実行できます。

export OBSIDIAN_VAULT_PATH="/path/to/your/vault"

新しいターミナルを開き、Vault のインデックスを一度作成します。

ohs reindex

これで、どのディレクトリからでも検索できます。

ohs "zettelkasten"

Vault 内から実行する

代わりに、環境変数を設定せず、Vault 内のどのディレクトリからでも CLI を実行できます。.obsidian/ フォルダーが見つかるまで親ディレクトリをたどり、Vault のルートを特定します。

cd /path/to/your/vault
ohs reindex
ohs "zettelkasten"

Vault の外から実行する場合は、OBSIDIAN_VAULT_PATH を設定するか、--db /path/to/vault/.obsidian-hybrid-search.db を明示的に指定してください。

オプションのリモート埋め込み

デフォルトでは、CLI はローカルの Xenova/multilingual-e5-small モデルを使用します。API キーなしでオフライン動作し、初回使用時に約 117 MB をダウンロードします。また、100 を超える言語に対応しています。

リモート API を使用するには、その設定をシェルのプロファイルに追加します。

export OPENAI_API_KEY="sk-..."

# Override the default API base for another provider
# export OPENAI_BASE_URL="https://openrouter.ai/api/v1"  # OpenRouter
# export OPENAI_BASE_URL="http://localhost:11434/v1"     # Ollama (no key needed)
# export OPENAI_BASE_URL="http://localhost:1234/v1"      # LM Studio (no key needed)

# Override the default text-embedding-3-small model
# export OPENAI_EMBEDDING_MODEL="text-embedding-3-small"

検索モード

CLI は、hybrid、fulltext、semantic、title と呼ばれる 4 つの検索モードに加え、リンクされたノートをたどるグラフ探索に対応しています。以下のコマンドでは、これらのモードの使い方、フィルターの適用方法、検索結果の再ランキング方法、出力の制御方法を示します。

# Hybrid search (default)
ohs "zettelkasten atomic notes"

# Fulltext BM25 search
ohs "permanent notes" --mode fulltext

# Fuzzy title search (fast, typo-tolerant)
ohs "zettleksten" --mode title

# Semantic / vector search
ohs "how to build a knowledge graph" --mode semantic

# Limit results and set a score threshold
ohs "productivity systems" --limit 5 --threshold 0.3

# Restrict to a subfolder
ohs "daily review" --scope notes/periodic/
ohs "daily review" --folder notes/periodic/    # alias for --scope

# Restrict to multiple subfolders (OR)
ohs "productivity" --scope notes/pkm/ --scope notes/2024/

# Exclude a subfolder
ohs "programming" --scope notes/ --scope -notes/archive/

# Filter by tag
ohs "productivity" --tag pkm
ohs "machine learning" --tag note/basic/primary

# Filter by multiple tags (AND include, exclude with -)
ohs "learning" --tag pkm --tag work

# Filter by frontmatter / properties (exact match, case-insensitive)
ohs "notes" --frontmatter status:todo
ohs "notes" --prop priority:high          # --prop is alias for --frontmatter

# Filter by multiple frontmatter fields (AND)
ohs "notes" --frontmatter status:todo --frontmatter priority:high

# Exclude by frontmatter value
ohs "notes" --frontmatter -status:done

# Filter-only mode: no query, just filters (returns all matching notes sorted by title)
ohs --frontmatter status:todo
ohs --folder notes/2024/
ohs --tag pkm
ohs --frontmatter status:done --tag archived

# Unlimited results in filter-only mode (default limit is 10)
ohs --folder notes/ --limit 0

# Find semantically similar notes
ohs --path notes/pkm/zettelkasten.md

# Graph traversal: show notes linked to/from this note
# Results show depth: -1/-2 = backlinks, 0 = source, +1/+2 = outgoing links
ohs --path notes/pkm/zettelkasten.md --related
ohs --path notes/pkm/zettelkasten.md --related --depth 2

# Only outgoing links (what this note references)
ohs --path notes/pkm/zettelkasten.md --related --direction outgoing

# Only backlinks (who references this note)
ohs --path notes/pkm/zettelkasten.md --related --direction backlinks

# Traverse standard Markdown note links instead of Obsidian wikilinks
ohs --path notes/pkm/zettelkasten.md --related --link-type markdown

# Traverse both wikilinks and standard Markdown note links
ohs --path notes/pkm/zettelkasten.md --related --link-type all

# Longer context around each link
ohs --path notes/pkm/zettelkasten.md --related --snippet-length 500

# Rerank results with a cross-encoder model (improves precision, ~1-3s extra latency)
# Downloads gte-multilingual-reranker-base ONNX (~341 MB) on first use, cached in ~/.cache/huggingface/
ohs "zettelkasten atomic notes" --rerank

# Show tags and aliases alongside results
ohs "zettelkasten" --extended

# JSON output (for scripting)
ohs "spaced repetition" --json

# Output only paths (one per line) — useful for piping into read
ohs --frontmatter id:OHS-4 --only-paths
ohs read ${(f)"$(ohs search --frontmatter status:todo --only-paths)"}  # zsh: read all matching notes

# Output absolute filesystem paths
ohs "zettelkasten" --only-absolute-paths

# Open results in Obsidian (each in a new tab)
ohs "zettelkasten" --open

# Reindex the vault
ohs reindex
ohs reindex --threads 4  # Limit local CPU inference to 4 threads

# Force full reindex
ohs reindex --force

# Reindex a single file
ohs reindex notes/pkm/zettelkasten.md

# Retry only the notes whose chunks failed to embed
ohs reindex --errors

# Show indexing status
ohs status

# Show recent indexing activity
ohs status --recent

# Show chunks that failed to embed
ohs status --errors

# Read a note by path (outputs body content without frontmatter)
ohs read notes/pkm/zettelkasten.md

# Read raw file from vault (with frontmatter, like cat)
ohs read notes/pkm/zettelkasten.md --raw

# Read multiple notes (separator between each)
ohs read notes/pkm/zettelkasten.md notes/pkm/evergreen-notes.md

# Cap content length
ohs read notes/pkm/zettelkasten.md --snippet-length 2000

# Structured output with all metadata
ohs read notes/pkm/zettelkasten.md --json

シェルエイリアス

すばやくアクセスできるよう、~/.zshrc または ~/.bashrc に追加します。

alias ohss='ohs --mode semantic'
alias ohst='ohs --mode title'
alias ohsf='ohs --mode fulltext'
alias ohsr='ohs read'
alias ohsi='ohs reindex'
alias ohsst='ohs status'

その後、設定を再読み込み（source ~/.zshrc）して、次のように使用します。

ohs "zettelkasten"                        # hybrid search
ohss "how to build a knowledge graph"     # semantic
ohst "zettelkasten"                       # fuzzy title (typo-tolerant)
ohsf "permanent notes"                    # fulltext BM25
ohsr "notes/pkm/zettelkasten.md"          # read note by path
ohsi                                      # reindex vault
ohsst                                     # show status
ohsst --recent                            # show recent indexing activity
ohsst --errors                            # show chunks that failed to embed

出力例

ハイブリッド検索では、スコアとスニペットを含む表が返されます。スコアは関連度に応じて色分けされます。

スコア	色	意味
0.8 – 1.0	緑	関連性が非常に高い
0.5 – 0.8	黄	関連性が中程度
0.2 – 0.5	通常	関連性がやや高い
0.0 – 0.2	薄暗い	関連性が低い

┌───────┬───────────────────────────────┬────────────────────────────────────────────┐
│ SCORE │ PATH                          │ SNIPPET                                    │
├───────┼───────────────────────────────┼────────────────────────────────────────────┤
│  0.98 │ notes/pkm/zettelkasten.md     │ A note-taking method developed by Niklas   │
│       │                               │ Luhmann. Each note contains one atomic...  │
├───────┼───────────────────────────────┼────────────────────────────────────────────┤
│  0.72 │ notes/pkm/evergreen-notes.md  │ Evergreen notes are written to evolve over │
│       │                               │ time. Unlike fleeting notes, they are...   │
└───────┴───────────────────────────────┴────────────────────────────────────────────┘

--extended を指定すると、TAGS/ALIASES 列が追加されます。タグには # が先頭に付き、エイリアスはそのまま表示されます。

┌───────┬───────────────────────────────┬──────────────────┬──────────────────────────────┐
│ SCORE │ PATH                          │ TAGS/ALIASES     │ SNIPPET                      │
├───────┼───────────────────────────────┼──────────────────┼──────────────────────────────┤
│  0.98 │ notes/pkm/zettelkasten.md     │ #pkm             │ A note-taking method...      │
│       │                               │ ЗК               │                              │
│       │                               │ slip-box         │                              │
├───────┼───────────────────────────────┼──────────────────┼──────────────────────────────┤
│  0.72 │ notes/pkm/evergreen-notes.md  │ #pkm             │ Evergreen notes are written  │
│       │                               │ #writing         │ to evolve over time...       │
└───────┴───────────────────────────────┴──────────────────┴──────────────────────────────┘

タイトルモードでは、スニペット列が自動的に省略されます。

MCP サーバー

多くの AI アシスタントは、ユーザーの個人的なナレッジにアクセスできず、会話に貼り付けられた内容だけを扱います。このサーバーを追加すると、MCP 対応アシスタントから、保管庫全体の永続的で検索可能なインデックスを利用できます。これはコピー＆ペーストでやり取りするのではなく、ツール呼び出しとして機能します。アシスタントは他のツールを呼び出すのと同じ方法でノートを検索し、スニペットやリンク付きのランキング結果を取得できます。また、リクエストに応じてナレッジグラフをたどることもできます。

MCP 設定（.mcp.json、claude_desktop_config.json、またはクライアントに応じた同等のファイル）に追加します。

最小限の設定（ローカル埋め込み、API キー不要）

組み込みの Xenova/multilingual-e5-small モデルを使用します。完全にオフラインで動作し、100 以上の言語に対応しています。初回実行時に約 117 MB をダウンロードします。

{
  "mcpServers": {
    "obsidian-hybrid-search": {
      "command": "npx",
      "args": ["-y", "-p", "obsidian-hybrid-search@latest", "obsidian-hybrid-search-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

完全な設定（OpenRouter）

{
  "mcpServers": {
    "obsidian-hybrid-search": {
      "command": "npx",
      "args": ["-y", "-p", "obsidian-hybrid-search@latest", "obsidian-hybrid-search-mcp"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_PREFIX": "myvault_",
        "OBSIDIAN_RESPECT_GITIGNORE": "true",
        "OBSIDIAN_IGNORE_PATTERNS": ".obsidian/**,templates/**,*.canvas",
        "OBSIDIAN_INCLUDE_PATTERNS": "private/notes/**",
        "OPENAI_API_KEY": "sk-or-v1-...",
        "OPENAI_BASE_URL": "https://openrouter.ai/api/v1",
        "OPENAI_EMBEDDING_MODEL": "openai/text-embedding-3-small"
      }
    }
  }
}

注記： 初回実行時に npx がパッケージを自動的にインストールします。無視パターンはデータベースに保存され、その後の起動時に環境変数がなくても復元されます。

共有 HTTP サーバー

複数の MCP クライアントで、長時間稼働する検索／インデックス作成プロセスを共有する場合に使用します。

バックグラウンドサーバーを起動するか、既存のサーバーを再利用します。

OBSIDIAN_VAULT_PATH="/path/to/your/vault" ohs serve

serve はデフォルトで HTTP 経由の MCP サーバーを起動します。serve --http を指定しても同じです。このコマンドは、サーバーの URL、PID、ログのパス、クライアント設定のスニペットを出力します。デフォルトのバインドアドレスは 127.0.0.1:3939 です。

次に、URL ベースの MCP クライアント設定（.mcp.json、claude_desktop_config.json、または同等のファイル）に追加します。

{
  "mcpServers": {
    "obsidian-hybrid-search": {
      "url": "http://127.0.0.1:3939/mcp"
    }
  }
}

サーバーを管理します。

ohs serve status
ohs serve stop
ohs serve --foreground
ohs serve --http --foreground

HTTP モードでは、ステートレスな MCP Streamable HTTP を使用します。Mcp-Session-Id の発行や検証は行わないため、古いセッションヘッダーが送信され続けていても、デーモンの再起動後に MCP クライアントはツール呼び出しを続けることができます。このモードは、サーバーのリクエスト／レスポンス型ツールを対象としており、永続的な SSE ストリーム、サーバー起点の通知、SSE の再開には対応していません。

ポート 3939 がすでに使用されている場合、コマンドは別のポートを自動的に選択せず、エラーで終了します。別の保管庫には --port を使用してください。

ローカルホスト以外にバインドする場合は、MCP クライアントが使用するすべてのホスト名またはアドレスを許可してください。

ohs serve \
  --host 0.0.0.0 \
  --allowed-host 192.168.1.20:3939 \
  --allowed-host notes.example.com:3939

複数の値を指定するには、--allowed-host を繰り返し指定します。OBSIDIAN_MCP_ALLOWED_HOSTS にカンマ区切りのリストを設定することもできます。--allow-any-host オプションを指定すると、信頼できるネットワーク向けに Host ヘッダーの保護が無効になります。

利用可能な MCP ツール

ツール	説明
search	Vault を検索します。テキスト検索には query（mode: hybrid/semantic/fulltext/title）、意味的類似性検索には path を使用します。グラフをたどるには path と related: true を組み合わせます。複数クエリのファンアウト（並列検索、RRF マージ）には queries[] を渡します。scope、tag、limit、threshold、depth、direction、snippet_length、rerank に対応しています
read	Vault 内の相対パスで指定したノートを 1 つ以上取得します。全文、タイトル、別名、タグ、リンク、バックリンクを返します。パスが見つからない場合は found: false と、類似度の高い候補を上位 3 件返します。単一のパスまたは配列を受け付けます。コンテンツのサイズを制限するには snippet_length を使用します
reindex	Vault 全体または特定のファイルを再インデックス化します
status	ノートの総数、インデックス化された数、最終インデックス化時刻を表示します

OBSIDIAN_PREFIX を設定すると、すべてのツール名に接頭辞を付けられます。たとえば、myvault_ を指定すると myvault_search と myvault_read になります。デフォルトでは接頭辞は空です。

設定

環境変数	デフォルト	説明
OBSIDIAN_VAULT_PATH	MCP では必須。CLI は自動検出します	Vault への絶対パス
OBSIDIAN_PREFIX	""	MCP ツールの任意のプレフィックス。例：myvault_ → myvault_search、myvault_read
OBSIDIAN_IGNORE_PATTERNS	.obsidian/**,templates/**,*.canvas	カンマ区切りの除外パターン
OBSIDIAN_RESPECT_GITIGNORE	true	ルートおよびネストされた .gitignore ファイルを読み込みます。無効にするには false に設定します
OBSIDIAN_INCLUDE_PATTERNS	""	.gitignore のみを理由に除外されたノートを再度含めるためのカンマ区切りパターン
OBSIDIAN_CONTENT_IGNORE_PATTERNS	""	ノート本文の検索対象から除外するカンマ区切りの正規表現ルール。例：/%%[\s\S]*?%%/g。元のファイルと read には変更を加えません。
OPENAI_API_KEY	なし	API キー。ローカルモデルの埋め込み、またはキー不要のサーバー（Ollama、LM Studio）を使用する場合は省略します
OPENAI_BASE_URL	https://api.openai.com/v1	API のベース URL
OPENAI_EMBEDDING_MODEL	text-embedding-3-small	埋め込みモデル名

除外パターン

• folder/** を使うと、ディレクトリとその中身をすべて除外します。
• *.canvas を使うと、拡張子でファイルを除外します。
• exact/path.md を使うと、特定のファイルを除外します。
• **/node_modules/** を使うと、階層を問わずディレクトリを除外します。

ルートおよびネストされた .gitignore ファイルは、デフォルトで尊重されます。この動作を無効にするには、OBSIDIAN_RESPECT_GITIGNORE=false を設定します。.gitignore のみを理由に除外された Markdown ノートを再度含めるには、OBSIDIAN_INCLUDE_PATTERNS を使用します。Include パターンは、OBSIDIAN_IGNORE_PATTERNS や内部の除外設定より優先されません。

データベースには除外設定が保存され、環境変数が存在しない場合でも、サーバーの再起動時に復元されます。

仕組み

1. インデックス作成では、見出しごとにノートを分割し、フォールバックとしてスライディングウィンドウを使用して埋め込みを作成します。結果は FTS5 および sqlite-vec とともに SQLite に保存されます。
2. 検索では、BM25、トライグラムによるタイトルと別名のあいまい検索、ベクトル KNN 検索を並行して実行します。BM25 では、タイトルに 10 倍、別名に 5 倍、本文に 1 倍の重みを付けます。次に RRF で、セマンティック検索と BM25 の結果にそれぞれ 1.5 倍、別名の完全一致に 2 倍、あいまい検索の部分一致に 0.25 倍の重みを付けます。最終スコアは 0〜1 の範囲で、スコアが高いほど関連性が高いことを示します。
3. リンクは、[[note]] のようなウィキリンクから解決してノートのパスに対応付け、保存されます。すべての検索結果には links と backlinks の配列が含まれます。
4. ウォッチャーは chokidar を使ってファイルの変更を検出し、バックグラウンドでインデックスを更新します。

ライセンス

MIT