Obsidian MCP + ハイブリッド検索：2026年リファレンス

Obsidianは単なるノートアプリではありません。ローカルファーストのプレーンテキストで、グラフ構造を持つMarkdownコーパスです。検索基盤を加えることで、AIコンテキストの貯水池になります。 16,894ファイル。49,746チャンク。23msのクエリ。API呼び出しはゼロ。1つの83 MB SQLiteファイル。このガイドでは、vaultアーキテクチャからhybrid検索、MCP連携、運用ワークフローまで、システム全体を扱います。

要点

メモ取りではなく、コンテキストエンジニアリングです。 AIにとってObsidian vaultの価値はノート自体ではなく、ノートを検索可能にする取得レイヤーにあります。取得機能のない16,000ファイルのvaultは、書き込み専用データベースです。hybrid検索とMCP統合を備えた200ファイルのvaultは、AI knowledge baseです。取得インフラストラクチャこそがプロダクトであり、ノートはその原材料です。

hybrid retrievalは、純粋なキーワード検索や純粋なセマンティック検索を上回ります。 BM25は完全一致の識別子や関数名を捉えます。ベクトル検索は、異なる用語間の同義語や概念的な一致を捉えます。Reciprocal Rank Fusion（RRF）は、スコアのキャリブレーションを必要とせずに両者を統合します。どちらか一方だけでは、両方の失敗モードをカバーできません。MS MARCOのパッセージランキングに関する研究でも、この傾向は確認されています。hybrid retrievalは一貫して、各手法を単独で使う場合を上回ります。³ hybrid retrieverの詳細解説では、RRFの数式、実数値を用いた例、失敗モードの分析、インタラクティブな融合計算機を扱っています。

MCPにより、AIツールはvaultへ直接アクセスできます。 Model Context Protocol（MCP）サーバーは、Claude Code、Codex CLI、CursorなどのAIツールから直接呼び出せるツールとしてretrieverを公開します。エージェントはvaultにクエリを実行し、ソースの帰属情報付きでランク付けされた結果を受け取り、ファイル全体を読み込むことなくコンテキストを利用できます。MCPサーバーは、取得エンジンを薄くラップしたものです。

local-firstはAPIコストをゼロにし、完全なプライバシーを実現します。 スタック全体が1台のマシン上で動作します。ストレージにはSQLite、embeddingsにはModel2Vec、キーワード検索にはFTS5、ベクトルKNNにはsqlite-vecを使用します。クラウドサービス、API呼び出し、ネットワーク依存はいずれもありません。個人のノートがマシンの外に出ることはありません。49,746チャンクを完全に再embedすると、OpenAIのAPI価格では約$0.30かかります。しかし本当のコストは、オフラインで動作すべきシステムにおけるレイテンシー、プライバシーの露出、ネットワーク依存です。⁴

インクリメンタルインデックスにより、10秒未満でシステムを最新に保てます。 ファイルの更新時刻を比較して変更を検出します。再chunkingおよび再embeddingを行うのは、変更されたファイルだけです。完全な再インデックスには、Apple Mシリーズのハードウェアで約4分かかります。一般的な1日の編集に対するインクリメンタル更新は、10秒未満で完了します。手動で介入しなくても、システムは常に最新の状態に保たれます。

このアーキテクチャは200件から20,000件超のノートまで拡張できます。 同じ3層設計（取り込み、取得、統合）は、どのvault規模でも機能します。小規模なvaultでは、BM25のみの検索から始めます。キーワードの衝突が問題になったらベクトル検索を追加します。完全一致とセマンティックな一致の両方が必要になったら、RRF融合を追加しましょう。各レイヤーは単独で有用であり、単独で取り除くこともできます。

このガイドの使い方

このガイドではシステム全体を扱います。どこから始めるかは、現在の状況によって異なります。

Contractと記されたセクションには、実装の詳細、設定ブロック、失敗モードが含まれます。Narrativeと記されたセクションでは、コンセプト、アーキテクチャ上の判断、デザイン選択の背景にある理由を扱います。Recipeと記されたセクションでは、段階的なワークフローを提供します。

AIインフラストラクチャにObsidianを使う理由

このガイドの主張は次のとおりです。Obsidian vaultは、local-first、plaintext、グラフ構造であり、ユーザーがスタックのあらゆるレイヤーを制御できるため、個人向けAI knowledge baseに最適な基盤です。

ObsidianがAIにもたらし、代替手段にはないもの

Plaintextのmarkdownファイル。 すべてのノートは、ファイルシステム上の.mdファイルです。独自形式も、データベースのエクスポートも、コンテンツの読み取りに必要なAPIもありません。ファイルを読み取れるツールであれば、どれでもvaultを読み取れます。grep、ripgrep、Pythonのpathlib、SQLite FTS5は、いずれもソースファイルを直接処理できます。取得システムを構築するときにインデックス化するのは、APIの応答ではなくファイルです。ソースがファイルシステムであるため、インデックスは常にソースと整合します。

Local-firstアーキテクチャ。 vaultは手元のマシンに存在します。サーバーも、クラウド同期への依存も、APIのレート制限も、自分のコンテンツの処理方法を規定する利用規約もありません。外部サービスなしで、ノートのembedding、インデックス化、chunking、検索を行えます。AIインフラストラクチャでは、取得パイプラインの速度がAPIエンドポイントの応答速度ではなく、ディスクの速度によって決まるため、これは重要です。プライバシーの面でも重要です。認証情報、健康データ、金融情報、個人的な振り返りを含むノートが、マシンの外に出ることはありません。

wiki-linksによるグラフ構造。 Obsidianの[[wiki-link]]構文は、ノート間に有向グラフを作成します。OAuth実装に関するノートは、トークンローテーション、セッション管理、APIセキュリティに関するノートへリンクします。グラフ構造は、トピックについて考える過程で著者が作った、コンセプト間の人間がキュレーションした関係を符号化します。ベクトルembeddingsはセマンティックな類似性を捉えますが、wiki-linksは意図的なつながりを捉えます。グラフは、embeddingsでは再現できないシグナルです。

プラグインエコシステム。 Obsidianには2,500以上のコミュニティプラグインがあります（2026年3月に2,500を超え、2025年半ばの1,800以上から増加しました）。Dataviewはvaultをデータベースのようにクエリできます。TemplaterはJavaScriptロジックを用いてテンプレートからノートを生成します。Git統合はvaultをリポジトリに同期します。Linterはフォーマットの一貫性を強制します。Basesコアプラグイン（v1.9.10で導入）は、frontmatterプロパティをフィールドとして使用し、vaultファイル上にテーブル、ギャラリー、カレンダー、kanbanボードといったデータベース風ビューを追加します。これらは.baseファイルとして保存されます。¹⁵ これらのプラグインは、基礎となるplaintext形式を変更せずにvaultへ構造を加えます。取得システムがインデックス化するのは、プラグインそのものではなく、その出力です。

500万人以上のユーザー。 Obsidianには、テンプレート、ワークフロー、プラグイン、ドキュメントを生み出す大規模で活発なコミュニティがあります。vaultの整理やプラグイン設定で問題に遭遇しても、誰かがすでに解決策を文書化している可能性が高いでしょう。コミュニティは、Obsidian周辺のツールも生み出しています。MCPサーバー、インデックス作成スクリプト、公開パイプライン、APIラッパーなどです。

ファイルシステムだけでは得られないもの

markdownファイルのディレクトリにはplaintextという利点がありますが、Obsidianが加える次の3つがありません。

1. 双方向リンク。 Obsidianはbacklinksを自動的に追跡します。ノートAからノートBへリンクすると、ノートBにはノートAが参照していることが表示されます。グラフパネルは接続クラスタを可視化します。この双方向の認識は、生のファイルシステムにはないメタデータです。

2. プラグインレンダリングを備えたライブプレビュー。 Dataviewクエリ、Mermaid図、calloutブロックがリアルタイムでレンダリングされます。ストレージ形式をplaintextのまま保ちながら、テキストエディタよりも豊かな執筆体験を提供します。豊かな環境で記述・整理し、取得システムは生のmarkdownをインデックス化します。

3. コミュニティインフラストラクチャ。 プラグインの発見、テーママーケットプレイス、同期サービス（任意）、公開サービス（任意）、そしてドキュメントエコシステムです。個々の機能はスタンドアロンツールで再現できますが、Obsidianはそれらを一貫したワークフローにまとめています。

Obsidianが行わないこと（そして構築するもの）

Obsidianには取得インフラストラクチャが含まれていません。基本的な検索（全文、ファイル名、タグ）はありますが、embeddingパイプライン、ベクトル検索、融合ランキング、MCPサーバー、credential filtering、chunking戦略、外部AIツールとの統合フックはありません。このガイドでは、Obsidianの上に構築するインフラストラクチャを扱います。 vaultは基盤です。取得パイプライン、MCPサーバー、統合フックがインフラストラクチャです。

ここで説明するアーキテクチャは、markdown-firstであり、Obsidian専用ではありません。 Logseq、Foam、Dendron、または単なるmarkdownファイルのディレクトリを使っている場合でも、取得パイプラインは同じように動作します。chunkerは.mdファイルを読み取ります。embedderはテキスト文字列を処理します。indexerはSQLiteへ書き込みます。これらのコンポーネントはいずれも、Obsidian固有の機能には依存しません。Obsidianの貢献は、retrieverがインデックス化するmarkdownファイルを生成する、執筆・整理環境にあります。

Obsidian MCP のセットアップ

Model Context Protocol（MCP）は、Claude Code、Codex CLI、Cursor などのAIツールからObsidian vaultへ直接アクセスするための標準インターフェースです。このセクションでは、5分でvaultをAIツールに接続します。Obsidianをインストールし、vaultを作成して、MCP serverをインストールし、最初のクエリを実行します。クイックスタートでは、すぐに結果を得られるコミュニティ製MCP serverを使用します。後続のセクションでは、本番利用向けのカスタム検索パイプラインの構築を扱います。

前提条件

• macOS、Linux、またはWindows
• Node.js 18+（MCP server用）
• Obsidian 1.12+（CLI 統合用。1.13.7は現在の公開デスクトップリリースです。stableとbetaが統合され、1.13系は2026年7月30日にCatalystを離れました。以前のバージョンでもMCPのみのセットアップでは動作します）
• Claude Code、Codex CLI、またはCursorがインストール済みであること

ステップ1：vaultを作成する

obsidian.mdからObsidianをダウンロードし、新しいvaultを作成します。覚えやすい場所を選んでください。MCP serverには絶対パスが必要です。

# Example vault location
~/Documents/knowledge-base/

retrieverが処理できるように、いくつかノートを追加します。結果を確認するには、10〜20件のノートでも十分です。各ノートは、意味のあるタイトルと少なくとも1段落の内容を含む.mdファイルにしてください。

ステップ2：MCP serverをインストールする

複数のコミュニティ製MCP serverが、すぐにvaultへのアクセスを提供しています。このエコシステムは2025〜2026年に大きく成長しました。注目すべきものにMCPVault（npm @bitbonsai/mcpvault、リポジトリ bitbonsai/mcpvault）があります。現在はv0.15.0です（2026年8月14日にnpmで確認）。これは下記のMarkusPfundstein/mcp-obsidianとは別プロジェクトであり、名称変更版ではありません。v0.11.0（2026年3月）では、frontmatterとhashtagを件数付きで走査するlist_all_tags、ドット付きフォルダの処理改善、.base/.canvasのサポートが追加されました。2026年7月23日に同日公開された3つのパッチは導入する価値があります。v0.12.3ではwiki_link toolが追加され、[[Document Name]]、[[Name|Display]]、テーブル用にエスケープされた[[Name\|Display]]、#fragment形式を解決し、ノート内容に加えて解決済みパスと曖昧な候補を返します。これにより、agentは再検索せずにvault固有のリンクグラフをたどれます。また、デフォルトのパスフィルターにより、すべてのtoolから.trash/を除外します。v0.12.4ではwiki_linkが[[folder/Note]]のようなパス指定リンクにも対応します。v0.12.2では、$を含む置換パターンによる挿入でpatch_noteが破損する問題を解消し、誤ってvaultプレフィックスを含むパスを正規化します。パスフィルターの制限ディレクトリdeny-listには、中程度の深刻度のアドバイザリ2件（GHSA-9c83-rr99-vfwj、GHSA-j99q-93c9-h869）が報告されました。いずれも0.12系よりかなり前の0.11.4および0.11.5で修正済みのため、どの0.12.xリリースにも影響しません。¹³

2026年4月の転換点 — 推奨ブリッジとしてのObsidian CLI： Obsidian 1.12.0では、ファーストクラスのCLIが導入されました。公開版1.12.7インストーラー（2026年3月23日）には、ターミナルワークフローのインストールと実行を容易にするスタンドアロンバイナリ、TUI、socket-fileの改善が含まれていました。¹⁶ 1.13系は、2026年7月30日に1.13.4として公開チャンネルに到達しました。これは設定、画像、URIセキュリティに関するリリースであり、1.12.xのCLI surfaceを超える新しいAIまたは自動化機能はありません（変更点についてはchangelogの行を参照してください）。²⁵²⁶ コミュニティツールは、Local REST API plugin（mcp-obsidianで使用）からCLIベースの統合へ積極的に移行しています。MarkusPfundstein/mcp-obsidianリポジトリは現在も保守されており、2026年5月までのコミットでsearch_by_tagやget_frontmatterを含むtoolが追加されています。ただしタグ付きリリースは提供されていないため、固定したcommitからインストールしてください。Local REST APIベースであることに変わりはありません。新規セットアップではCLI bridgeのほうが一般に高速で安定しているため、こちら、または以下の新しいコミュニティ製代替手段を推奨します。²⁰ 推奨セットアップについては、このガイド後半の「AIワークフロー向けObsidian CLI」セクションを参照してください。

クイックスタートでは、.mdファイルを直接読み取るファイルベースserverが最も簡単です。npm名の衝突に注意してください。ファイルベースserverはnpmのobsidian-mcp（StevenStavrakis）です。一方、npm obsidian-mcp-serverはcyanheadsのREST-APIベースserverであり、Local REST API pluginとAPI keyが必要です。この取り違えは、起動できないserverを設定してしまう一般的な原因です。

npm install -g obsidian-mcp

ステップ3：AIツールを設定する

Claude Code — claude mcp addでserverを登録します（Claude Codeは、ユーザースコープのMCP serverを~/.claude.jsonに、プロジェクトスコープのものを.mcp.jsonに保存します。mcpServers blockを無視する~/.claude/settings.jsonではありません）。

# User scope (all your projects)
claude mcp add obsidian -s user -- npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/your/vault

# Or project scope, shared with the repo (writes .mcp.json)
claude mcp add obsidian -s project -- npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/your/vault

Codex CLI — ~/.codex/config.tomlに追加します。

[mcp_servers.obsidian]
command = "npx"
args = ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/your/vault"]

Cursor — .cursor/mcp.jsonに追加します。

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/your/vault"]
    }
  }
}

ステップ4：最初のクエリを実行する

AIツールを開き、vaultのノートで答えられる質問をします。

Search my Obsidian vault for notes about [topic you wrote about]

AIツールがMCP serverを呼び出し、vaultを検索して一致するコンテンツを返します。ファイルパスと関連する抜粋を含む結果が表示されるはずです。

接続後にClaudeでできること

正確なtool名はserverごとに異なりますが、主要な機能範囲は実装間で一貫しています。

実際には、Claudeは出典情報付きでノートから質問に回答し、過去の決定や参照資料をコーディングセッションに取り込み、ファイル全体をコンテキストに読み込まずにvault構造を探索します。コミュニティ製serverの一部は書き込み操作（作成、追記、タグ、frontmatter管理）も公開しています。一方、このガイド後半で構築するカスタムserverは意図的に読み取り専用であり、ノート作成は代わりにhooksで処理します。

詳細解説：MCP Server Architecture（toolと権限のデザイン）、Claude Code Integration（hooksとbridgeパターン）、Codex CLI IntegrationおよびCursor and Other Tools（他のagent向け）。

ここまでで構築したもの

標準プロトコルを介して、ローカルknowledge baseをAIツールに接続しました。MCP serverがvaultファイルを読み取り、基本検索を実行し、結果を返します。これが最小限の実用バージョンです。

このクイックスタートで得られないもの： - Hybrid retrieval（BM25 + vector search + RRF fusion） - Embeddingベースのセマンティック検索 - Credential filtering - Incremental indexing - Hookベースの自動コンテキスト注入

このガイドの残りでは、これらすべての機能を構築する方法を扱います。クイックスタートでコンセプトを実証し、完全なパイプラインで本番品質のretrievalを実現します。

AIワークフロー向けの Obsidian CLI

Obsidian 1.12（2026年2月）では、AIワークフロー向けの新たな統合面を開く組み込みのコマンドラインインターフェースが導入されました。これは1.13.7でも引き続き利用でき、1.13系は2026年7月30日にパブリックチャンネルへ到達して以降、新たな CLI 機能は追加されていません。¹⁶²⁵²⁶ CLI は Obsidian GUI のリモートコントロールとして機能します。Obsidian を実行しておく必要がありますが、最初のコマンド時には自動起動もされます。Settings > General > Command line interface で有効にしてください。

AIインフラストラクチャにおいて CLI が重要な理由

CLI では、以前は GUI またはプラグイン API が必要だった Obsidian ネイティブ操作にプログラムからアクセスできます。AIワークフローで重要な機能は次のとおりです。

• スクリプトとフックからの検索。 obsidian search "query" と obsidian search:context "query" は、任意のシェルスクリプト、フック、または自動化パイプラインから vault を検索します。search:context バリアントは一致した行と周辺コンテキストを返すため、結果をAIプロンプトへ渡す用途に便利です。
• デイリーノートの自動化。 obsidian daily は、今日のデイリーノートを開くか作成します。シェルスクリプトと組み合わせることで、日次ブリーフィングを自動化できます。たとえばフックで、AI生成の要約をデイリーノートに追記できます。
• テンプレートベースのノート作成。 obsidian template list と obsidian template create は Templater またはコアテンプレートからノートを生成します。これにより、AIエージェントは markdown ファイルを直接書き込まずに、構造化された vault エントリを作成できます。
• プロパティ管理。 obsidian property set と obsidian property get は frontmatter プロパティを読み書きします。YAML を解析せずに、スクリプトからメタデータを更新できます。
• プラグイン制御。 obsidian plugin enable/disable/list はプラグインをプログラムから管理します。バッチ操作中にインデックス作成プラグインを切り替える場合に便利です。
• タスク管理。 obsidian task list/add/complete は構造化されたタスクアクセスを提供します。vault 内の作業項目を管理するAIエージェントに役立ちます。

AIアクセスにおける CLI と MCP の比較

CLI と MCP サーバーは異なる役割を担っており、競合するものではなく相互補完的です。

推奨: インテークの自動化（ノート作成、プロパティ管理、Obsidian ネイティブ検索の実行）には CLI を、検索（embeddings を用いた hybrid 検索）には MCP を使用してください。UserPromptSubmit フックでは、より負荷の大きい hybrid 検索を実行する前の高速な事前チェックとして obsidian search:context を呼び出せます（ツールスコープのフックイベントは注入できず、stdout がモデルへ届くことはありません）。

例：CLI を利用したインテークフック

#!/bin/bash
# Hook: append today's signals to daily note via CLI
DATE=$(date +%Y-%m-%d)
SUMMARY="$1"
obsidian daily  # ensure daily note exists
obsidian file append "Daily Notes/${DATE}.md" "## AI Summary\n${SUMMARY}"

Obsidian Agent Plugins

AIコーディングエージェントを vault UI に直接組み込む Obsidian プラグインが増えています。外部 MCP サーバーの設定に代わる選択肢となるものです。これらのプラグインは、外部ツールから接続するのではなく、Obsidian のサイドバー内でAIエージェントを実行します。

Claudian

Claudian は、Claude Code を vault 内のAIコラボレーターとして組み込みます。vault ディレクトリが Claude の作業ディレクトリとなり、ファイルの読み書き、検索、bash コマンド、複数ステップのワークフローといった完全なエージェント機能を利用できます。¹⁷

AIインフラストラクチャ向けの主な機能： - コンテキスト認識プロンプト。 フォーカス中のノートを自動的に添付し、@notename によるファイル参照、タグベースの除外、エディター内の選択範囲をコンテキストとしてサポートします。 - Vision サポート。 ドラッグ＆ドロップ、ペースト、またはファイルパス経由で画像を分析できます。vault に保存したスクリーンショットや図を処理する際に便利です。 - スラッシュコマンド。 /command で起動する再利用可能なプロンプトテンプレートを作成でき、標準化された vault 操作を実現します。 - 権限モード。 安全ブロックリストと vault 内への制限を備え、YOLO（自動承認）、Safe（各操作を承認）、Plan（計画のみ）のモードを利用できます。

Agent Client

Agent Client は、Claude Code、Codex CLI、Gemini CLI を、Agent Client Protocol（ACP）を通じて統合された Obsidian サイドバーへ導入します。¹⁸

主な機能： - マルチエージェントの切り替え。 同じパネルから Claude Code、Codex、Gemini CLI とチャットでき、必要に応じてエージェントを切り替えられます。 - ノート参照。 @notename を使用してノートの内容をプロンプトに含められます。Claudian と似ていますが、エージェントに依存しません。 - シェル実行。 チャット内でターミナルコマンドを実行できます。スクリプトの作成、git コマンド、その他あらゆるターミナル操作を、会話から離れずに行えます。 - アクション承認。 ファイルの読み取り、編集、コマンド実行をきめ細かく制御できます。

エージェントプラグインと外部 MCP を使い分ける場合

推奨: vault 中心のワークフロー（ノートの作成、整理、要約）にはエージェントプラグインを使用してください。AIエージェントが完全な検索パイプラインと vault 外のコードベースへのアクセスを必要とする開発ワークフローには、外部 MCP サーバーを使用します。両方のアプローチは共存できます。ノート作業では Obsidian 内で Claudian を実行し、開発では外部で MCP とともに Claude Code を実行できます。

判断フレームワーク：Obsidian と代替案

すべてのユースケースに Obsidian が必要なわけではありません。このセクションでは、Obsidian が適した基盤となる場合、過剰になる場合、そして別の選択肢のほうが合う場合を整理します。

判断ツリー

START: What is your primary content type?
│
├─ Structured data (tables, records, schemas)
│  → Use a database. SQLite, PostgreSQL, or a spreadsheet.
│  → Obsidian is for prose, not tabular data.
│
├─ Ephemeral context (current project, temporary notes)
│  → Use CLAUDE.md / AGENTS.md in the project repo.
│  → These travel with the code and reset per project.
│
├─ Team wiki (shared documentation, onboarding)
│  → Evaluate Notion, Confluence, or a shared git repo.
│  → Obsidian vaults are personal-first. Team sync is possible
│    but not native.
│
└─ Growing personal knowledge corpus
   │
   ├─ < 50 notes
   │  → A folder of markdown files + grep is sufficient.
   │  → Obsidian adds value mainly through the link graph,
   │    which needs density to be useful.
   │
   ├─ 50 - 500 notes
   │  → Obsidian adds value. Wiki-links create a navigable graph.
   │  → BM25-only search (FTS5) is sufficient at this scale.
   │  → Skip vector search and RRF until keyword collisions appear.
   │
   ├─ 500 - 5,000 notes
   │  → Full hybrid retrieval becomes valuable. Keyword collisions
   │    increase. Semantic search catches queries that BM25 misses.
   │  → Add vector search + RRF fusion at this scale.
   │
   └─ 5,000+ notes
      → Full pipeline is essential. BM25-only returns too much noise.
      → Credential filtering becomes critical (more notes = more
        accidentally pasted secrets).
      → Incremental indexing matters (full reindex takes minutes).
      → MCP integration pays dividends on every AI interaction.

比較マトリクス

Obsidian が過剰になる場合

• 単一プロジェクトのコンテキスト。 AI が現在のコードベースに関するコンテキストだけを必要とするなら、CLAUDE.md、AGENTS.md、またはプロジェクトレベルのドキュメントに置きます。これらのファイルはリポジトリと一緒に移動し、自動的に読み込まれます。
• 構造化データ。 コンテンツがテーブル、レコード、スキーマである場合は、データベースを使います。Obsidian のノートは prose-first です。Dataview で frontmatter フィールドをクエリできますが、構造化クエリは本物のデータベースのほうが適しています。
• 一時的なリサーチ。 プロジェクト終了後にノートを破棄するなら、markdown ファイルを置いたスクラッチディレクトリのほうがシンプルです。一時的なコンテンツのために retrieval インフラを構築しないでください。

Obsidian が適した選択肢になる場合

• 数か月から数年かけて知識を蓄積する場合。 コーパスが育つほど価値は複利的に増えます。6か月間毎日クエリされる200ノートの vault は、1回だけクエリされる5,000ノートの vault より大きな価値を生みます。
• 1つのコーパスに複数ドメインがある場合。 プログラミング、アーキテクチャ、セキュリティ、デザイン、個人プロジェクトに関するノートを含む vault は、プロジェクト固有の CLAUDE.md では得られないクロスドメイン retrieval の恩恵を受けます。
• プライバシーに配慮が必要なコンテンツ。 Local-first であれば、retrieval パイプラインが外部サービスにコンテンツを送ることはありません。vault には、クラウドサービスにはアップロードしたくない内容も含め、入れたものがそのまま入ります。

メンタルモデル：3つのレイヤー

このシステムには、独立して動作しつつ、組み合わせることで価値が増す3つのレイヤーがあります。それぞれのレイヤーは関心ごとも障害モードも異なります。

┌─────────────────────────────────────────────────────┐
│                 INTEGRATION LAYER                     │
│  MCP servers, hooks, skills, context injection        │
│  Concern: delivering context to AI tools              │
│  Failure: wrong context, too much context, stale      │
└──────────────────────┬──────────────────────────────┘
                       │ query + ranked results
┌──────────────────────┴──────────────────────────────┐
│                  RETRIEVAL LAYER                      │
│  BM25, vector KNN, RRF fusion, token budget           │
│  Concern: finding the right content for any query     │
│  Failure: wrong ranking, missed results, slow queries │
└──────────────────────┬──────────────────────────────┘
                       │ chunked, embedded, indexed
┌──────────────────────┴──────────────────────────────┐
│                   INTAKE LAYER                        │
│  Note creation, signal triage, vault organization     │
│  Concern: what enters the vault and how it's stored   │
│  Failure: noise, duplicates, missing structure        │
└─────────────────────────────────────────────────────┘

取り込みは、何が vault に入るかを決めます。キュレーションがなければ、vault にはノイズが蓄積します。ツイートのスクリーンショット、注釈のないコピペ記事、コンテキストのない書きかけの考えなどです。取り込みレイヤーは、入口の時点で品質管理を担います。スコアリングパイプライン、タグ付け規約、手動レビューなど、vault に retrieval する価値のあるコンテンツが入るようにする仕組みです。

Retrievalは、vault をクエリ可能にします。ここがエンジンです。ノートを検索単位に chunking し、チャンクをベクトル空間に embeddings として埋め込み、キーワード検索とセマンティック検索向けにインデックスし、RRF で結果を融合します。retrieval レイヤーは、ファイルのディレクトリをクエリ可能な knowledge base に変換します。このレイヤーがなければ、vault は手動ブラウズや基本検索ではたどれますが、AI ツールからプログラム的にアクセスすることはできません。

統合は、retrieval レイヤーを AI ツールにつなぎます。MCP サーバーは、retrieval を呼び出し可能なツールとして公開します。Hooks はコンテキストを自動的に注入します。Skills は新しい知識を vault に書き戻します。統合レイヤーは、knowledge base と、それを利用する AI agents の間にあるインターフェースです。

各レイヤーは設計上、疎結合になっています。取り込みのスコアリングパイプラインは embeddings について何も知りません。retriever はシグナルルーティングルールについて何も知りません。MCP サーバーは、ノートがどのように作られたかを知りません。この疎結合により、どのレイヤーも独立して改善できます。取り込みパイプラインを変えずに embedding モデルを置き換えられます。retriever を変更せずに新しい MCP 機能を追加できます。インデックスに触れずにシグナルスコアリングのヒューリスティックを変えられます。

AIが利用しやすいVault Architecture

AI retrieval向けに最適化したvaultは、個人のブラウジング向けに最適化したvaultとは異なる慣習に従います。このセクションでは、フォルダー構造、note schema、frontmatterの慣習、retrieval品質を高める具体的なパターンを扱います。

フォルダー構造

トップレベルのフォルダーには番号付きprefixを使い、予測しやすい整理階層を作ります。この番号は優先度を意味するものではありません。関連する領域をまとめ、構造を見渡しやすくするためのものです。

vault/
├── 00-inbox/              # Unsorted captures, pending triage
├── 01-projects/           # Active project notes
├── 02-areas/              # Ongoing areas of responsibility
├── 03-resources/          # Reference material by topic
│   ├── programming/
│   ├── security/
│   ├── ai-engineering/
│   ├── design/
│   └── devops/
├── 04-archive/            # Completed projects, old references
├── 05-signals/            # Scored signal intake
│   ├── ai-tooling/
│   ├── security/
│   ├── systems/
│   └── ...12 domain folders
├── 06-daily/              # Daily notes (if used)
├── 07-templates/          # Note templates (excluded from index)
├── 08-attachments/        # Images, PDFs (excluded from index)
├── .obsidian/             # Obsidian config (excluded from index)
└── .indexignore            # Paths to exclude from retrieval index

index対象にすべきフォルダー: markdown proseを含むすべてのものです。projects、areas、resources、signals、daily notesなどが該当します。

index対象から除外すべきフォルダー: Templates（コンテンツではなくplaceholder変数を含むため）、attachments（binary files）、Obsidian設定、retrieval indexに含めたくない機密コンテンツを含むフォルダーです。

.indexignore ファイル

vault rootに.indexignoreファイルを作成し、retrieval indexから除外するpathを明示します。構文は.gitignoreと同じです。

# Obsidian internal
.obsidian/

# Templates contain placeholders, not content
07-templates/

# Binary attachments
08-attachments/

# Personal health/medical notes
02-areas/health/

# Financial records
02-areas/finance/personal/

# Career documents (resumes, salary data)
02-areas/career/private/

indexerはscan前にこのファイルを読み込み、一致するpathを完全にskipします。除外path内のファイルはchunk化されず、embeddingも作成されず、search resultsにも表示されません。

Note Schema

すべてのnoteにはYAML frontmatterを含める必要があります。retrieverはfrontmatter fieldsをfilteringとcontext enrichmentに使用します。

---
title: "OAuth Token Rotation Patterns"
type: note           # note | signal | project | moc | daily
domain: security     # primary domain for routing
tags:
  - authentication
  - oauth
  - token-management
created: 2026-01-15
updated: 2026-02-28
source: ""           # URL if captured from external source
status: active       # active | archived | draft
---

retrievalに必須のfields:

• title — search resultの表示と、BM25向けheading contextに使用されます
• type — typeで絞り込んだqueriesを可能にします（「MOCだけ表示」「signalsだけ表示」など）
• tags — FTS5 heading contextに0.3 weightでindexされ、本文で異なる用語を使っていてもkeyword matchを提供します

任意ですが価値の高いfields:

• domain — domain単位のqueriesを可能にします（「security notesだけをsearch」など）
• source — captured contentのattributionです。retrieverはresultsにsource URLsを含められます
• status — archivedまたはdraft notesをactive searchから除外できます

Chunkingの慣習

retrieverはH2（##）heading boundariesでchunk化します。つまり、note構造がretrievalの粒度に直接影響します。

retrievalに適した例:

## Token Rotation Strategy

The rotation interval depends on the threat model...

## Implementation with refresh_token

The OAuth 2.0 refresh token flow requires...

## Error Handling: Expired Tokens

When a token expires mid-request...

3つのH2 sectionsから、個別にsearch可能な3つのchunksが生成されます。各chunkには、embeddingが意味を捉えるのに十分なcontextがあります。「expired token handling」に関するqueryは、特に3つ目のchunkにmatchします。

retrievalに適さない例:

# OAuth Notes

Token rotation depends on threat model. The OAuth 2.0 refresh
token flow requires storing the refresh token securely. When a
token expires mid-request, the client should retry after refresh.
The rotation interval is typically 15-30 minutes for access tokens
and 7-30 days for refresh tokens...

H2 headingsのない長いsectionが1つだけだと、大きなchunkが1つ生成されます。embeddingはsection内のすべてのtopicを平均化します。どのsubtopicに関するqueryでも、note全体に同じようにmatchしてしまいます。

経験則: 1つのsectionが複数のconceptを扱う場合は、H2 subsectionsに分割してください。残りはchunkerが処理します。

Notesに入れるべきではないもの

retrieval品質を下げるコンテンツ:

• 注釈のない記事全文のraw copy-paste。 retrieverは元記事のkeywordsをindexするため、自分で書いていないコンテンツでvaultが薄まります。代わりにsummaryを追加する、key pointsを抽出する、source URLへlinkしてください。
• text descriptionのないscreenshots。 retrieverがindexするのはmarkdown textです。alt textや周辺descriptionのないimageは、BM25にもvector searchにも見えません。
• Credential strings。 API keys、tokens、passwords、connection stringsです。credential filteringがあっても、notesにsecretsを貼り付けないのが最も安全です。代わりに名前で参照してください（「~/.env内のCloudflare API token」など）。
• curationされていないauto-generated content。 toolがnoteを生成する場合（meeting transcript、Readwise highlights、RSS importなど）、permanent vaultに入れる前にreviewしてannotateしてください。curationされていないauto-importsは、retrievable valueを増やさずにvolumeだけを増やします。

AI ワークフロー向けプラグインエコシステム

AI 検索のために vault の品質を高める Obsidian プラグインは、構造化（一貫性を強制する）、クエリ（メタデータを公開する）、同期（vault を最新に保つ）の3種類に分けられます。

必須プラグイン

Dataview。 frontmatter フィールドを使い、vault をデータベースのようにクエリできます。たとえば「過去30日間に更新された security タグ付きの全ノート」や「status が active の全プロジェクトノート」といった動的インデックスを作成できます。Dataview は検索精度を直接高めるわけではありませんが、vault のカバレッジの不足を見つけたり、更新が必要なノートを特定したりするのに役立ちます。

TABLE type, domain, updated
FROM "03-resources"
WHERE status = "active"
SORT updated DESC
LIMIT 20

Templater。 動的フィールドを含むテンプレートからノートを作成します。created、type、domain フィールドを事前入力するテンプレートを使えば、すべての新規ノートを正しい frontmatter から始められます。一貫した frontmatter は検索フィルタリングを改善します。

<%* /* New Resource Note Template */ %>
---
title: "<% tp.file.cursor() %>"
type: note
domain: <% tp.system.suggester(["programming", "security", "ai-engineering", "design", "devops"], ["programming", "security", "ai-engineering", "design", "devops"]) %>
tags: []
created: <% tp.date.now("YYYY-MM-DD") %>
updated: <% tp.date.now("YYYY-MM-DD") %>
source: ""
status: active
---

## Key Points

## Details

## References

Linter。 vault 全体にフォーマットルールを適用します。一貫した見出し階層（タイトルは H1、セクションは H2、サブセクションは H3）により、chunker が予測しやすい結果を生成できます。検索に関係する Linter ルールは次のとおりです。

• 見出しの増分: 見出しレベルを順番どおりに強制します（H1 から H3 に飛ばない）
• YAML title: ファイル名と一致させます
• 行末スペース: 削除します（FTS5 の tokenization artifacts を避けるため）
• 連続する空行: 1行までに制限します（よりきれいな chunks になります）

Git integration。 vault のバージョン管理です。変更履歴の追跡、マシン間の同期、誤削除からの復旧ができます。Git は、indexer が差分変更検出に使う mtime データも提供します。

indexing に役立つプラグイン

Smart Connections。 Obsidian 内で AI による semantic search を提供する Obsidian プラグインです。Smart Connections v4 はデフォルトでローカル embeddings を作成します。vault の indexing が完了すると、意味的な接続や検索は API 呼び出しなしで完全にオフラインで動作します。¹¹ v4.5.0（2026年5月5日）では、footer connections が Smart Connections Core の一部になり、どのインストールでもサイドパネルを開かずに関連ノートの接続をフッターに表示できるようになりました。最近の v4 リリースでは、connection lists の graph views、設定可能な dock locations、中断された indexing 実行後の block-embedding 復旧の改善、そして Smart Connections、Smart Chat、Smart Composer が状態を共有できる cross-plugin 環境「Substrate」も追加されています。²¹ このガイドの retrieval system は Obsidian の外部で動作します（Python pipeline として実行されます）が、Smart Connections は執筆中に意味的な関係を探索するのに便利です。2つの system は同じコンテンツを index しますが、用途が異なります。Smart Connections はエディター内での発見に、外部 retriever は MCP 経由での AI tool 統合に使います。

2026年4月に登場した AI-native プラグイン。 新しいコミュニティプラグインの波が、Claude Code / Codex / Gemini-CLI ワークフローを直接対象にしています。

これは新しく広がりつつある領域として扱いましょう。これらのいくつかは、今後数四半期で Smart Connections や Obsidian core に統合される可能性があります。今日どれか1つを選ぶなら、VaultSearch と Hybrid Search MCP が、このガイドの外部 retriever に最も近い考え方です。

Dataview note: Dataview（長年使われている Obsidian query plugin）は、2025年4月に 0.5.70 を最後にリリースしており、それ以降は事実上休眠状態です。新しい作業では、Obsidian 組み込みの Bases 機能（1.9+）が暗黙の後継であり、推奨される選択肢です。

Metadata Menu。 フィールド値の autocomplete を備えた、構造化 frontmatter 編集を提供します。type、domain、tags フィールドの入力ミスを減らせます。一貫したメタデータは、retrieval filtering の精度を高めます。

indexing に悪影響を与えるプラグイン

Excalidraw。 図を markdown ファイル内に埋め込まれた JSON として保存します。JSON は構文的には有効な markdown ですが、chunking して embedding すると不要な内容が生成されます。.indexignore を使うか、ファイル拡張子でフィルタして、Excalidraw ファイルを index から除外してください。

Kanban。 board state を特殊な形式の markdown として保存します。この形式は Kanban rendering のために設計されており、prose retrieval 向けではありません。chunker はカードタイトルやメタデータの断片を生成しますが、うまく embed できません。Kanban boards は index から除外してください。

Calendar。 最小限の内容の日次ノートを作成します（多くの場合、日付見出しだけです）。空、またはほぼ空のノートは低品質な chunks を生成します。日次ノートを使う場合は、実質的な内容を書くか、日次ノートフォルダを index から除外してください。

重要なプラグイン設定

File recovery → Enabled。 誤ってノートを削除した場合に備えて保護します。retrieval とは直接関係しませんが、依存する knowledge base には不可欠です。

Strict line breaks → Disabled。 Markdown 標準の改行（段落には2つの改行）のほうが、Obsidian の strict mode（<br> のための1つの改行）よりもきれいな chunks を生成します。

Default new file location → Designated folder。 新規ファイルを 00-inbox/ に送ることで、未分類ノートが domain folders を汚さないようにします。inbox は staging area です。triage 後、ファイルは domain folders に移動します。

Wiki-link format → Shortest path when possible。 link targets が短いほど、link structure を indexing するときに retriever が解決しやすくなります。

Embedding Models: 選び方と設定

embedding modelは、semantic searchのためにテキストchunkを数値ベクトルへ変換します。モデルの選択によって、retrieval品質、indexサイズ、embedding速度、実行時の依存関係が決まります。このセクションでは、Model2Vecのpotion-base-8Mをデフォルトにしている理由と、代替モデルを選ぶべき場面を説明します。

Model2Vec potion-base-8Mを選ぶ理由

Model: minishlab/potion-base-8M Parameters: 7.6 million Dimensions: 256 Size: ~30 MB Dependencies: model2vec（numpyのみ、PyTorch不要） Inference: CPUのみ、static word embeddings（attention layersなし）

Model2Vecは、sentence transformerの知識をstatic token embeddingsへdistillします。BERT、MiniLM、その他のtransformerモデルのように入力に対してattention layersを実行するのではなく、Model2Vecは事前計算済みtoken embeddingsの加重平均によってベクトルを生成します。⁵ 実用上の結果として、逐次計算がないため、embedding速度はtransformerベースのモデルより50〜500倍高速です。

現在のModel2Vec resultsページでは、potion-base-8Mはall-MiniLM-L6-v2の全タスクスコアの約92%（51.32対55.80）に達しながら、桁違いに高速です。⁶ 残る品質差は、速度とシンプルさという利点とのトレードオフです。短いmarkdown chunk（一般的なvaultでは平均200〜400語）では、長いドキュメントほど品質差は目立ちません。短く焦点の定まったテキストでは、どちらのモデルも近い表現に収束するためです。

設定

# embedder.py
DEFAULT_MODEL = "minishlab/potion-base-8M"
EMBEDDING_DIM = 256

class Model2VecEmbedder:
    def __init__(self, model_name=DEFAULT_MODEL):
        self._model_name = model_name
        self._model = None

    def _ensure_model(self):
        if self._model is not None:
            return
        _activate_venv()  # Add isolated venv to sys.path
        from model2vec import StaticModel
        self._model = StaticModel.from_pretrained(self._model_name)

    def embed_batch(self, texts):
        self._ensure_model()
        vecs = self._model.encode(texts)
        return [v.tolist() for v in vecs]

Lazy loading。 モデルはimport時ではなく、初回使用時に読み込まれます。retrieverがBM25のみのfallback modeで動作する場合（例: embedding venvがインストールされていない場合）、embedderモジュールをimportしてもコストはかかりません。

分離されたvirtual environment。 モデルは専用venv（例: ~/.claude/venvs/memory/）で実行し、toolchainの他の部分との依存関係の衝突を避けます。_activate_venv()関数は、実行時にvenvのsite-packagesをsys.pathへ追加します。

# Create isolated venv
python3 -m venv ~/.claude/venvs/memory
~/.claude/venvs/memory/bin/pip install model2vec

Batch processing。 embedderはModel2Vecのオーバーヘッドをならすため、64件ずつテキストを処理します。indexerはchunkを1つずつembeddingするのではなく、embed_batch()へ渡します。

代替モデルを選ぶ場面

potion-base-32Mを選ぶのは、static embedding系から外れずにpotion-base-8Mより高い品質が欲しい場合です。baai/bge-base-en-v1.5からdistillされたより大きな語彙を使い、52.83の全タスクスコア（potion-base-8Mより約3%高い）を達成しつつ、同じ256次元出力とnumpyのみの依存関係を維持します。⁸ モデルファイルは4倍大きくなるためメモリ使用量は増えますが、embedding速度はtransformerモデルより桁違いに高速なままです。

potion-retrieval-32Mを選ぶのは、主な用途がretrievalの場合です（vault searchはまさにこれです）。このvariantはretrievalタスク専用にpotion-base-32Mからfine-tuneされており、Model2Vecのretrieval benchmark tableで35.06を記録します。potion-base-32Mは32.67です。⁸ トレードオフとして、汎用的なembedding品質ではなくretrieval向けに最適化されています。

potion-multilingual-128Mを選ぶのは、vaultに複数言語のノートが含まれる場合です。2025年5月にリリースされたこの101言語対応モデルは、多言語タスク向けのstatic embedding modelとして最高性能で、他のpotionモデルと同じnumpyのみの依存関係を維持しながら、任意の言語の任意のテキストに対してembeddingsを生成します。¹² より大きいモデルファイル（~500 MB）は、cross-lingual capabilityのためのトレードオフです。英語コンテンツに加えて、日本語、中国語、ドイツ語、その他の非英語ノートがある場合に使います。

all-MiniLM-L6-v2を選ぶのは、速度よりretrieval品質が重要で、PyTorchがインストール済みの場合です。384次元ベクトルは、256次元ベクトルと比べてSQLite databaseサイズを約50%増やします。M-series hardwareで15,000ファイルをfull reindexする場合、embedding速度は1分未満から約10分へ低下します。

nomic-embed-text-v1.5を選ぶのは、可能な限り最高のローカルretrieval品質が必要で、indexingが遅くなることを許容できる場合です。768次元ベクトルにより、databaseサイズはおおよそ3倍になります。PyTorchと、モダンなCPUまたはGPUが必要です。

text-embedding-3-smallを選ぶのは、network latencyとprivacyをトレードオフとして許容できる場合です。APIは最高品質のembeddingsを生成しますが、cloud依存、tokenごとのコスト（$0.02/million tokens）、そしてコンテンツをOpenAIのサーバーへ送信することを伴います。

それ以外の場合はpotion-base-8Mのままにします。 速度の優位性は反復的なindexing（開発中のreindex）に重要で、numpyのみの依存関係によりPyTorchインストールの複雑さを避けられます。また、256次元ベクトルによりdatabaseをコンパクトに保てます。

QuantizationとDimensionality Reduction

Model2Vec v0.5.0+は、精度と次元を落としてモデルを読み込むことに対応しています。⁸ 制約のあるhardwareへのdeploymentや、モデルを切り替えずにdatabaseサイズを減らしたい場合に有用です。

from model2vec import StaticModel

# Load with int8 quantization (25% of original size)
model = StaticModel.from_pretrained("minishlab/potion-base-8M", quantize=True)

# Load with reduced dimensions (e.g., 128 instead of 256)
model = StaticModel.from_pretrained("minishlab/potion-base-8M", dimensionality=128)

Quantized modelsは、メモリフットプリントを大幅に削減しつつ、ほぼ同等のretrieval品質を保ちます。Dimensionality reductionはMatryoshka-style truncationに従い、最初のN次元に最も多くの情報が含まれます。256次元から128次元へ減らすと、短文retrievalでの品質低下を最小限に抑えながら、ベクトルストレージを半分にできます。

Model2Vec v0.8.xではtokenizer/persistence internalsが更新され、Python 3.9サポートがdeprecatedとなり、公開結果が新しいMTEB tablesへ更新されています。本番indexerをアップグレードする前にmodel2vecをpinまたはtestしてください。embedding model名が同じでも、library upgradeによってmodel-loading pathsが変わる可能性があるためです。¹⁰

Vault専用EmbeddingsのFine-Tuning

Model2Vec v0.4.0+はstatic embeddings上でcustom classification modelsのtrainingに対応し、v0.7.0ではdistillation向けのvocabulary quantizationとconfigurable poolingが追加され、v0.8.xではtokenizerとpersistence behaviorがrefactorされています。¹⁰ これは、専門語彙（医療ノート、法律参照、ドメイン固有の専門用語）を含むvaultに関係します。デフォルトのpotionモデルではsemantic nuancesを捉えきれない場合があるためです。

from model2vec import StaticModel
from model2vec.train import train_model

# Fine-tune on vault-specific data
model = StaticModel.from_pretrained("minishlab/potion-base-8M")
trained_model = train_model(model, train_texts, train_labels)
trained_model.save_pretrained("./vault-embeddings")

ほとんどのvaultでは、デフォルトのpotion-base-8Mで十分なretrieval品質が得られます。Fine-tuningに価値があるのは、汎用モデルでは捉えられないドメイン固有のつながりをretrievalが継続的に取りこぼす場合だけです。

Model Hash Tracking

indexerは、model名とvocabulary sizeから派生したhashを保存します。embedding modelを変更すると、次回のincremental runでindexerが不一致を検出し、自動的にfull reindexをtriggerします。

def _compute_model_hash(self):
    """Hash model name + vocab size for compatibility tracking."""
    key = f"{self._model_name}:{self._model.vocab_size}"
    return hashlib.sha256(key.encode()).hexdigest()[:16]

これにより、同じdatabase内で異なるモデルのベクトルが混在することを防ぎます。混在すると、cosine similarity scoresは意味をなさなくなります。

Failure Modes

Model download failure。 初回実行時にHugging Faceからモデルをdownloadします。downloadに失敗した場合（network issue、corporate firewallなど）、retrieverはBM25のみのmodeへfallbackします。モデルは初回download後、ローカルにcacheされます。

Dimension mismatch。 databaseをclearせずにモデルを切り替えると、保存済みベクトルの次元が新しいembeddingsと異なります。indexerはmodel hashによってこれを検出し、full reindexをtriggerします。hash checkが失敗した場合（適切なhashを持たないcustom modelなど）、sqlite-vecは次元不一致のKNN queriesでエラーになります。

大規模vaultでのmemory pressure。 50,000件以上のchunkを単一batchでembeddingすると、大量のメモリを消費する可能性があります。indexerはpeak memory usageを抑えるため、64件ずつbatch処理します。それでもメモリが問題になる場合は、batch sizeを減らしてください。

FTS5によるFull-Text Search

SQLiteのFTS5拡張は、BM25ランキング付きのFull-Text Searchを提供します。FTS5は、hybrid検索パイプラインにおけるキーワード検索コンポーネントです。このセクションでは、FTS5の設定、BM25が有効な場面、そして具体的な失敗パターンを扱います。

FTS5仮想テーブル

CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text,
    section,
    heading_context,
    content=chunks,
    content_rowid=id
);

Content-syncモード。 content=chunksパラメータは、テキストの重複コピーを保存するのではなく、chunksテーブルを直接参照するようFTS5に指示します。これによりストレージ要件は半分になりますが、chunkが挿入、更新、削除されたときに、FTS5を手動で同期する必要があります。

カラム。 3つのカラムがインデックス化されます。 - chunk_text — 各chunkの主要コンテンツ（BM25 weight: 1.0） - section — H2見出しテキスト（BM25 weight: 0.5） - heading_context — ノートタイトル、タグ、metadata（BM25 weight: 0.3）

BM25ランキング

BM25は、term frequency、inverse document frequency、document length normalizationによってドキュメントをランク付けします。FTS5のbm25()補助関数は、カラムごとの重みを受け取れます。

SELECT
    c.id, c.file_path, c.section, c.chunk_text,
    bm25(chunks_fts, 1.0, 0.5, 0.3) AS score
FROM chunks_fts
JOIN chunks c ON chunks_fts.rowid = c.id
WHERE chunks_fts MATCH ?
ORDER BY score
LIMIT 30;

カラムの重み（1.0、0.5、0.3）は次の意味です。 - chunk_textでキーワードが一致すると、スコアへの寄与が最も大きくなります - section（見出し）で一致すると、その半分の寄与になります - heading_context（タイトル、タグ）で一致すると、30%の寄与になります

これらの重みは調整できます。vaultに、コンテンツ品質を強く予測できる説明的な見出しがある場合は、sectionの重みを増やしてください。タグが包括的で正確な場合は、heading_contextの重みを増やします。

BM25が有効な場面

BM25は、正確な識別子を含むクエリで力を発揮します。

• 関数名: _rrf_fuse、embed_batch、get_stale_files
• CLI flags: --incremental、--vault、--model
• 設定キー: bm25_weight、max_tokens、batch_size
• エラーメッセージ: SQLITE_LOCKED、ConnectionRefusedError
• 特定の専門用語: PostToolUse、PreToolUse、AGENTS.md

このようなクエリでは、BM25は完全一致をすぐに見つけます。vector検索は意味的に関連するコンテンツを返しますが、概念的な議論よりも完全一致を低くランク付けしてしまうことがあります。

BM25が失敗する場面

BM25は、保存されているコンテンツとは異なる用語を使ったクエリで失敗します。

• Query: “how to handle authentication failures” → Vaultには「login error recovery」や「session expiration handling」に関するノートがあります。キーワードが異なるため、BM25は一致しません。
• Query: “what is the best way to manage state” → Vaultには「Redux store patterns」や「context providers」に関するノートがあります。「state management」が具体的な技術名で表現されているため、BM25は見逃します。

BM25は、大規模環境ではキーワード衝突でも失敗します。15,000ファイルのvaultで「configuration」を検索すると、ほぼすべてのプロジェクトノートがconfigurationに言及しているため、何百ものノートが一致します。結果は技術的には正しいものの、実用上は役に立ちません。ランキングでは、どの「configuration」ノートが現在のクエリに関連しているかを判断できないためです。

FTS5 Tokenizer

FTS5はデフォルトでunicode61 tokenizerを使い、ASCIIとUnicodeテキストを処理します。CJK（中国語、日本語、韓国語）コンテンツが多いvaultでは、trigram tokenizerを検討してください。

-- For CJK-heavy vaults
CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text, section, heading_context,
    content=chunks, content_rowid=id,
    tokenize='trigram'
);

デフォルトのunicode61 tokenizerは単語境界で分割しますが、単語間にスペースがない言語ではうまく機能しません。trigram tokenizerは3文字ごとに分割するため、インデックスサイズが大きくなる（おおよそ3倍）代わりに、部分文字列マッチングが可能になります。

メンテナンス

FTS5では、基になるchunksテーブルが変更されたときに明示的な同期が必要です。

# After inserting chunks
cursor.execute("""
    INSERT INTO chunks_fts(chunks_fts)
    VALUES('rebuild')
""")

rebuildコマンドは、content tableからFTS5インデックスを再構築します。bulk insert（full reindex）の後に実行しますが、個別のincremental update後には実行しません。その場合は、INSERT INTO chunks_fts(rowid, chunk_text, section, heading_context)を使って個別行を同期してください。

sqlite-vec による Vector Search

sqlite-vec extension は、vector KNN（K-Nearest Neighbors）search を SQLite に持ち込みます。このセクションでは、sqlite-vec の設定、ノートから検索可能な vector までの embedding pipeline、そして具体的な query パターンを扱います。

sqlite-vec Virtual Table

CREATE VIRTUAL TABLE chunk_vecs USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[256]
);

vec0 module は、256次元の float vector を packed binary data として保存します。id column は chunks table と 1:1 で対応し、vector の結果と chunk metadata を join できるようにします。

Embedding Pipeline

pipeline は、ノートから検索可能な vector へと次のように流れます。

Note (.md file)
  → Chunker: split at H2 boundaries
    → Chunks (30-2000 chars each)
      → Credential filter: scrub secrets
        → Embedder: Model2Vec encode
          → Vectors (256-dim float arrays)
            → sqlite-vec: store as packed binary
              → Ready for KNN queries

Vector Serialization

Python の struct module は、sqlite-vec storage 用に float vector を serialize します。

import struct

def _serialize_vector(vec):
    """Pack float list into binary for sqlite-vec."""
    return struct.pack(f"{len(vec)}f", *vec)

def _deserialize_vector(blob, dim=256):
    """Unpack binary blob to float list."""
    return list(struct.unpack(f"{dim}f", blob))

KNN Query

vector search query では、入力 query を embed し、cosine distance によって最も近い K 個の chunks を見つけます。

def _vector_search(self, query_text, limit=30):
    query_vec = self.embedder.embed_batch([query_text])[0]
    packed = _serialize_vector(query_vec)

    results = self.db.execute("""
        SELECT
            cv.id,
            cv.distance,
            c.file_path,
            c.section,
            c.chunk_text
        FROM chunk_vecs cv
        JOIN chunks c ON cv.id = c.id
        WHERE embedding MATCH ?
            AND k = ?
        ORDER BY distance
    """, [packed, limit]).fetchall()

    return results

sqlite-vec の MATCH operator は、approximate nearest neighbor search を実行します。k parameter は返す結果数を制御します。distance column には cosine distance（0 = 同一、2 = 反対）が入ります。

Distance Constraints を使った KNN Pagination

sqlite-vec v0.1.7 以降、KNN queries は WHERE distance < ? constraints をサポートしています。これにより、大きな result set でも前のページを再スキャンせずに cursor-based pagination が可能になります。¹⁴ その後の v0.1.8 と v0.1.9 の stable release は、新しい query model の release ではなく packaging と DELETE bug-fix の release です。そのため、この pagination pattern の feature boundary は v0.1.7 のままです。²³

今後の予定として、v0.1.10-alpha line（2026年3月31日〜5月18日）は、sqlite-vec を brute-force KNN の先へ進める最初の release です。approximate-nearest-neighbor index types として、rescore、default では 有効化されていない 実験的な ivf（inverted-file）index、そして vector を memory に常駐させるには大きすぎる vault 向けの disk-based DiskANN index が導入されます。²³ これらは非常に大きな vault の scaling story を変える可能性がありますが、0.1.10 line はまだ pre-release（alpha） です。ANN indexing は実験的なものとして扱い、stable 0.1.10 が出荷されるまでは、production vault では stable v0.1.9 の brute-force KNN path を土台にし続けてください。

def _paginated_vector_search(self, query_vec, page_size=20, max_distance=None):
    """Paginate through KNN results using distance constraints."""
    packed = _serialize_vector(query_vec)
    constraint = f"AND distance < {max_distance}" if max_distance else ""

    results = self.db.execute(f"""
        SELECT cv.id, cv.distance, c.file_path, c.chunk_text
        FROM chunk_vecs cv
        JOIN chunks c ON cv.id = c.id
        WHERE embedding MATCH ?
            AND k = ?
            {constraint}
        ORDER BY distance
    """, [packed, page_size]).fetchall()

    # Use last result's distance as cursor for next page
    next_cursor = results[-1][1] if results else None
    return results, next_cursor

これは、大きな k を取得して Python 側で slicing する従来の pattern を置き換えるものです。大規模な vault に対する探索的 query で memory usage を削減できます。

vec0 Tables における DELETE Support

sqlite-vec v0.1.7 では、vec0 virtual tables に native DELETE support が追加されました。また v0.1.9 では、12文字を超える metadata text columns に関係する DELETE error path が修正されました。¹⁴²³ 以前は、vector を削除するには table を drop して作り直す必要がありました。現在は、indexer の file-removal path から vector を直接削除できます。

# Before v0.1.7: required workaround (drop + recreate, or mark as inactive)
# After v0.1.7: direct DELETE works
db.execute("DELETE FROM chunk_vecs WHERE id = ?", [chunk_id])

これにより、ノートが削除または移動されたときの incremental reindexing が簡単になります。indexer は shadow の「active IDs」table や batch rebuilds を維持する必要がなくなります。

Vector Search が有効な場面

vector search は、特定の単語よりも concept が重要な query で力を発揮します。

• Query: “how to handle authentication failures” → “login error recovery” に関するノートを見つけます（同じ semantic space、異なる keywords）
• Query: “what patterns exist for caching” → “memoization,” “Redis TTL strategies,” “HTTP cache headers” に関するノートを見つけます（関連する concepts、多様な terminology）
• Query: “approaches to testing asynchronous code” → “pytest-asyncio fixtures,” “mock event loops,” “async test patterns” に関するノートを見つけます（同じ concept が implementation details を通じて表現されています）

Vector Search が失敗しやすい場面

vector search は、正確な identifiers が苦手です。

• Query: _rrf_fuse → “fusion algorithms” や “rank merging” に関するノートを返しますが、実際の function definition は conceptual discussions より低く rank される場合があります
• Query: PostToolUse → specific hook name ではなく、”tool lifecycle hooks” や “post-execution handlers” に関するノートを返します

vector search は structured data も苦手です。JSON configuration files、YAML blocks、code snippets は、semantic meaning ではなく structural patterns を捉えた embeddings を生成します。"review": true を含む JSON file は、code review についての prose discussion とは異なる形で embed されます。

Graceful Degradation

sqlite-vec の読み込みに失敗した場合（missing extension、incompatible platform、corrupted library）、retriever は BM25-only search に fallback します。

class VectorIndex:
    def __init__(self, db_path):
        self.db = sqlite3.connect(db_path)
        self._vec_available = False
        try:
            self.db.enable_load_extension(True)
            self.db.load_extension("vec0")
            self._vec_available = True
        except Exception:
            pass  # BM25-only mode

    @property
    def vec_available(self):
        return self._vec_available

retriever は vector queries を試みる前に vec_available を確認します。無効な場合、すべての searches は BM25 のみを使用し、RRF fusion step は skip されます。

Reciprocal Rank Fusion（RRF）

RRFは、スコアの較正を必要とせずに、順位付きリストを2つ統合します。このセクションでは、アルゴリズム、実際のクエリのトレース、kパラメータの調整、そして代替手法ではなくRRFを選ぶ理由を扱います。順位を編集できるインタラクティブな計算ツール、シナリオプリセット、視覚的なアーキテクチャ探索については、hybrid retriever deep diveをご覧ください。

アルゴリズム

RRFは、各リスト内での順位だけに基づいて、各ドキュメントにスコアを割り当てます。

score(d) = Σ (weight_i / (k + rank_i))

ここで: - kは平滑化定数です（Cormackら³に従い、60） - rank_iは、結果リストiにおけるドキュメントの1始まりの順位です - weight_iは、リストごとの任意の乗数です（デフォルトは1.0）

複数のリストで上位にランクされるドキュメントほど、統合後のスコアは高くなります。1つのリストにしか現れないドキュメントは、その単一ソースからのスコアを受け取ります。

代替手法ではなくRRFを使う理由

重み付き線形結合では、BM25スコアとcosine distancesを較正する必要があります。BM25スコアには上限がなく、corpusのサイズに応じてスケールします。Cosine distancesは[0, 2]の範囲に収まります。これらを組み合わせるには正規化が必要であり、その正規化パラメータはデータセットに依存します。RRFは順位だけを使います。順位はスコアリング手法に関係なく、常に1から始まる整数です。

学習済みfusionモデルには、ラベル付きの訓練データ、つまりクエリとドキュメントの関連度ペアが必要です。個人のナレッジベースでは、このような訓練データは存在しません。有用なモデルを訓練するには、何百ものクエリとドキュメントのペアを手作業で判定する必要があります。RRFは訓練データなしで機能します。

Condorcet voting手法（Borda count、Schulze method）は理論的には洗練されていますが、実装と調整がより複雑です。元のRRF論文では、TREC評価データにおいてRRFがCondorcet手法を上回ることが示されています。³

実践でのFusion

クエリ: “how does the review aggregator handle disagreements”

BM25はreview-aggregator.pyを3位にランクします（”review,” “aggregator,” “disagreements”というキーワードの完全一致）が、2つのconfigファイルをより上位に置きます（それらは”review”により強く一致するためです）。Vector searchは同じchunkを1位にランクします（conflict resolutionに対する意味的な一致）。RRFで統合すると、次のようになります。

両方のリストで上位にあるchunksが、最上位に浮かび上がります。1つのリストにしか現れないchunksは単一ソースのスコアとなり、両方で順位を持つ結果より下に落ちます。実際のdisagreement resolutionロジックが勝つのは、両方の手法がそれを見つけたからです。BM25はキーワードから、vector searchは意味から見つけています。

順位ごとのRRF計算を含む完全なステップ別トレースは、interactive RRF calculatorでさまざまなk値を試して確認できます。

実装

RRF_K = 60

def _rrf_fuse(self, bm25_results, vec_results,
              bm25_weight=1.0, vec_weight=1.0):
    """Fuse BM25 and vector results using Reciprocal Rank Fusion."""
    scores = {}

    for rank, r in enumerate(bm25_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {
                "rrf_score": 0.0,
                "file_path": r["file_path"],
                "section": r["section"],
                "chunk_text": r["chunk_text"],
                "bm25_rank": None,
                "vec_rank": None,
            }
        scores[cid]["rrf_score"] += bm25_weight / (self._rrf_k + rank)
        scores[cid]["bm25_rank"] = rank

    for rank, r in enumerate(vec_results, start=1):
        cid = r["id"]
        if cid not in scores:
            scores[cid] = {
                "rrf_score": 0.0,
                "file_path": r["file_path"],
                "section": r["section"],
                "chunk_text": r["chunk_text"],
                "bm25_rank": None,
                "vec_rank": None,
            }
        scores[cid]["rrf_score"] += vec_weight / (self._rrf_k + rank)
        scores[cid]["vec_rank"] = rank

    fused = sorted(
        scores.values(),
        key=lambda x: x["rrf_score"],
        reverse=True,
    )
    return fused

kの調整

k定数は、上位の結果と下位の結果にどれだけ重みを与えるかを制御します。

• 低いk（例: 10）: 最上位の結果が支配的になります。順位1のスコアは1/11 = 0.091、順位10のスコアは1/20 = 0.050です（1.8倍の差）。個々のrankerが最上位の結果を正しく出せると信頼できる場合に向いています。
• デフォルトのk（60）: バランス型です。順位1のスコアは1/61 = 0.0164、順位10のスコアは1/70 = 0.0143です（1.15倍の差）。順位差が圧縮されるため、複数のリストに現れることへより大きな重みが置かれます。
• 高いk（例: 200）: 順位そのものよりも、両方のリストに現れることがはるかに重要になります。順位1のスコアは1/201、順位10のスコアは1/210で、ほぼ同じです。個々のrankerの順位がノイズを含む一方で、リスト間の一致は信頼できる場合に使います。

k=60から始めましょう。 元のRRF論文では、この値が多様なTRECデータセット全体で堅牢であることが示されています。調整するのは、自分のクエリ分布で失敗ケースを測定してからで十分です。

同点の処理

2つのchunksが同じRRFスコアになる場合（まれですが、片方のリストで同じ順位になり、もう片方には現れない場合などに起こり得ます）、次の順序で同点を解消します。

1. 1つのリストにしか現れないchunksより、両方のリストに現れるchunksを優先します
2. 両方のリストに現れるchunks同士では、合計順位が低いものを優先します
3. 1つのリストにしか現れないchunks同士では、そのリスト内での順位が低いものを優先します

完全な retrieval pipeline

このセクションでは、クエリが入力から出力へ進む流れを、pipeline 全体に沿って追います。BM25 search、vector search、RRF fusion、token budget truncation、context assembly を扱います。

End-to-End の流れ

User query: "PostToolUse hook for context compression"
  │
  ├─ BM25 Search (FTS5)
  │    → MATCH "PostToolUse hook context compression"
  │    → Top 30 results ranked by BM25 score
  │    → 12ms
  │
  ├─ Vector Search (sqlite-vec)
  │    → Embed query with Model2Vec
  │    → KNN k=30 on chunk_vecs
  │    → Top 30 results ranked by cosine distance
  │    → 8ms
  │
  └─ RRF Fusion
       → Merge 60 candidates (may overlap)
       → Score by rank position
       → Top 10 results
       → 3ms
       │
       └─ Token Budget
            → Truncate to max_tokens (default 4000)
            → Estimate at 4 chars per token
            → Return results with metadata
            → <1ms

合計レイテンシ: 約23ms。Apple M3 Pro ハードウェア上の 49,746 chunk のデータベースでの値です。

Search API

class HybridRetriever:
    def search(self, query, limit=10, max_tokens=4000,
               bm25_weight=1.0, vec_weight=1.0):
        """
        Search the vault using hybrid BM25 + vector retrieval.

        Args:
            query: Search query text
            limit: Maximum results to return
            max_tokens: Token budget for total result text
            bm25_weight: Weight for BM25 results in RRF
            vec_weight: Weight for vector results in RRF

        Returns:
            List of SearchResult with file_path, section,
            chunk_text, rrf_score, bm25_rank, vec_rank
        """
        # BM25 search
        bm25_results = self._bm25_search(query, limit=30)

        # Vector search (if available)
        if self.index.vec_available:
            vec_results = self._vector_search(query, limit=30)
            fused = self._rrf_fuse(
                bm25_results, vec_results,
                bm25_weight, vec_weight,
            )
        else:
            fused = bm25_results  # BM25-only fallback

        # Token budget truncation
        results = []
        token_count = 0
        for r in fused[:limit]:
            chunk_tokens = len(r["chunk_text"]) // 4
            if token_count + chunk_tokens > max_tokens:
                break
            results.append(r)
            token_count += chunk_tokens

        return results

Token Budget Truncation

max_tokens パラメーターは、AI ツールが利用できる量を超える context を retriever が返さないようにします。推定には 1 token あたり 4 文字を使います（英語の文章では妥当な近似です）。結果は greedily に切り詰められます。つまり、予算を使い切るまで、順位順に結果を追加していきます。

これは保守的な戦略です。より高度な方法では、結果ごとの品質スコアを考慮し、長くて品質の低い結果よりも、短くて品質の高い結果を優先するでしょう。greedy な方法はより単純で、実運用でもうまく機能します。RRF ranking によって、すでに関連度順に結果が並んでいるためです。

Database Schema（完全版）

-- Chunk content and metadata
CREATE TABLE chunks (
    id INTEGER PRIMARY KEY,
    file_path TEXT NOT NULL,
    section TEXT NOT NULL,
    chunk_text TEXT NOT NULL,
    heading_context TEXT DEFAULT '',
    mtime_ns INTEGER NOT NULL,
    embedded_at REAL NOT NULL
);

CREATE INDEX idx_chunks_file ON chunks(file_path);
CREATE INDEX idx_chunks_mtime ON chunks(mtime_ns);

-- FTS5 for BM25 search (content-synced to chunks table)
CREATE VIRTUAL TABLE chunks_fts USING fts5(
    chunk_text, section, heading_context,
    content=chunks, content_rowid=id
);

-- sqlite-vec for vector KNN search
CREATE VIRTUAL TABLE chunk_vecs USING vec0(
    id INTEGER PRIMARY KEY,
    embedding float[256]
);

-- Model metadata for compatibility tracking
CREATE TABLE model_meta (
    key TEXT PRIMARY KEY,
    value TEXT
);

Graceful Degradation Path

Full pipeline:     BM25 + Vector + RRF  →  Best results
No sqlite-vec:     BM25 only            →  Good results (no semantic)
No model download:  BM25 only            →  Good results (no semantic)
No FTS5:           Vector only           →  Decent results (no keyword)
No database:       Error                 →  Prompt user to run indexer

retriever は初期化時に機能を確認し、クエリ戦略を適応させます。コンポーネントが欠けている場合、品質は低下しますがエラーにはなりません。唯一の hard failure は、データベースファイルが存在しない場合です。

Production Stats

16,894 ファイル、49,746 chunk、83 MB SQLite データベース、Apple M3 Pro の vault で測定した結果です。

Content Hashing と Change Detection

indexer は、前回の index 実行以降にどのファイルが変更されたかを把握する必要があります。このセクションでは、change detection の仕組みと hashing 戦略を扱います。

File Modification Time Comparison

indexer は、chunks テーブル内のすべての chunk について mtime_ns（ファイル更新時刻、ナノ秒）を保存します。incremental run では、indexer は次の処理を行います。

1. 許可されたフォルダー内のすべての .md ファイルを vault からスキャンします
2. 各ファイルの mtime_ns を filesystem から読み取ります
3. データベースに保存されている mtime_ns と比較します
4. 3つのカテゴリを特定します。
5. 新規ファイル: path が filesystem には存在するが、データベースには存在しない
6. 変更ファイル: path は両方に存在するが、mtime_ns が異なる
7. 削除ファイル: path はデータベースには存在するが、filesystem には存在しない

def get_stale_files(self, vault_mtimes):
    """Find files whose mtime changed or are new."""
    stored = dict(self.db.execute(
        "SELECT DISTINCT file_path, mtime_ns FROM chunks"
    ).fetchall())

    stale = []
    for path, mtime in vault_mtimes.items():
        if path not in stored or stored[path] != mtime:
            stale.append(path)
    return stale

def get_deleted_files(self, vault_paths):
    """Find files in database that no longer exist in vault."""
    stored_paths = set(r[0] for r in self.db.execute(
        "SELECT DISTINCT file_path FROM chunks"
    ).fetchall())
    return stored_paths - set(vault_paths)

Content Hash ではなく mtime を使う理由

content hashing（ファイル内容の SHA-256）は、mtime 比較よりも信頼性が高い方法です。たとえば、ファイルが変更されずに touch された場合（git checkout によって元の mtime が復元される場合など）も検出できます。ただし、hashing では incremental run のたびにすべてのファイルを読む必要があります。16,894 ファイルの場合、ファイル内容の読み取りには 2〜3 秒かかります。filesystem から mtime を読むだけなら <100ms です。

トレードオフはこうです。mtime 比較では、変更されていないファイルを不要に re-indexing してしまうことがまれにあります（false positive）。しかし、実際の変更を見逃すことはありません。false positive のコストは、1 回の実行あたり数回余分に embedding call が発生する程度です。速度差（100ms 対 3 秒）を考えると、すべての AI interaction で動くシステムでは mtime が実用的な選択です。

Deletion の処理

vault からファイルが削除されると、indexer はそのファイルのすべての chunk をデータベースから削除します。

def remove_file(self, file_path):
    """Remove all chunks and vectors for a file."""
    chunk_ids = [r[0] for r in self.db.execute(
        "SELECT id FROM chunks WHERE file_path = ?",
        [file_path],
    ).fetchall()]

    for cid in chunk_ids:
        self.db.execute(
            "DELETE FROM chunk_vecs WHERE id = ?", [cid]
        )
    self.db.execute(
        "DELETE FROM chunks WHERE file_path = ?",
        [file_path],
    )

DELETE FROM chunk_vecs ステートメントは sqlite-vec v0.1.7 以降でネイティブに動作します。また、v0.1.9 では、長い metadata text columns を持つ vec0 テーブルに対する DELETE 操作のバグ修正が入っています。¹⁴²³ それ以前のバージョンでは、回避策（virtual table を drop して再作成する、または外部の「active IDs」セットを維持するなど）が必要でした。pre-0.1.9 バージョンを実行している場合は、metadata-heavy な schema で direct deletes に依存する前にアップグレードしてください。

FTS5 content-sync テーブルでは、削除された各行について INSERT INTO chunks_fts(chunks_fts, rowid, ...) VALUES('delete', ?, ...) による明示的な削除が必要です。indexer は、ファイル削除処理の一部としてこれを処理します。

Incremental Reindex と Full Reindex

indexer は incremental（高速、日常利用向け）と full（低速、たまに実行）の2つのモードに対応しています。このセクションでは、それぞれを使う場面、冪等性の保証、破損時の復旧について説明します。

Incremental Reindex

使う場面: ノートを編集した後の日常的な indexing。デフォルトのモードです。

実行内容: 1. vault をスキャンしてファイル変更を検出します（mtime 比較） 2. 削除されたファイルの chunks を削除します 3. 変更されたファイルを再 chunking し、再 embed します 4. 新しいファイルの chunks を挿入します 5. FTS5 index を同期します

典型的な所要時間: 16,000ファイルの vault で1日分の編集なら10秒未満です。

python index_vault.py --incremental

Full Reindex

使う場面: - embedding model を変更した後（model hash の不一致が検出された場合） - schema migration の後（新しい columns、変更された indexes） - database 破損の後（integrity check が失敗した場合） - incremental indexing が予期しない結果を返す場合

実行内容: 1. 既存データをすべて削除します（chunks、vectors、FTS5 entries） 2. vault 全体をスキャンします 3. すべてのファイルを chunking します 4. すべての chunks を embed します 5. FTS5 index をゼロから構築します

典型的な所要時間: Apple M3 Pro で16,894ファイルなら約4分です。

python index_vault.py --full

冪等性

どちらのモードも冪等です。同じ command を2回実行しても同じ結果になります。indexer は新しい chunks を挿入する前に、そのファイルの既存 chunks を削除します。そのため、すでに最新の database に対して incremental indexing を再実行しても、変更はゼロになります。full indexing を再実行すると、同一の database が生成されます。

破損時の復旧

SQLite database が破損した場合（write 中の電源断、disk error、transaction 途中での process kill など）:

# Check integrity
sqlite3 vectors.db "PRAGMA integrity_check;"

# If corruption detected, full reindex rebuilds from source files
python index_vault.py --full

信頼できる唯一の情報源は常に vault files であり、database ではありません。database はいつでも再構築できる派生 artifact です。これは重要なデザイン特性です。database をバックアップする必要はありません。

--incremental Flag

indexer を --incremental 付きで実行すると、次の処理が行われます。

1. Model hash check。 保存済みの model hash を現在の model と比較します。異なる場合は、自動的に full reindex mode へ切り替え、ユーザーに警告します。
2. File scan。 許可された folders をたどり、file paths と mtimes を収集します。
3. Change detection。 保存済みデータと比較します。
4. Batch processing。 変更されたファイルを64件ずつの batch で再 chunking し、再 embed します。
5. Progress reporting。 処理済みファイル数と経過時間を出力します。
6. Graceful shutdown。 SIGINT を受け取った場合は、現在のファイル処理を完了してから停止します。

Credential Filtering とデータ境界

個人ノートには secrets が含まれます。API keys、bearer tokens、database connection strings、debugging session 中に貼り付けた private keys などです。credential filter は、これらが retrieval index に入るのを防ぎます。

問題

OAuth integration の debugging に関するノートには、次のような内容が含まれる場合があります。

The token was: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
I used this curl command:
  curl -H "Authorization: Bearer sk-ant-api03-abc123..."

filtering しない場合、JWT と API key の両方が chunking され、embedded され、database に保存されます。”authentication” を検索すると、実際の secrets を含む chunk が返されてしまいます。さらに悪いことに、retriever が MCP 経由で結果を AI tool に渡す場合、secrets が AI の context window に現れ、tool の logs に残る可能性もあります。

Pattern-Based Filtering

credential filter は storage 前にすべての chunk で実行され、25個の vendor-specific patterns と generic patterns に一致するか確認します。

Vendor-Specific Patterns:

Generic Patterns:

Filter Implementation

def clean_content(text):
    """Scrub credentials from text before indexing."""
    result = ScanResult(is_clean=True, match_count=0, patterns=[])

    for pattern in CREDENTIAL_PATTERNS:
        matches = pattern.regex.findall(text)
        if matches:
            text = pattern.regex.sub(
                f"[REDACTED:{pattern.name}]", text
            )
            result.is_clean = False
            result.match_count += len(matches)
            result.patterns.append(pattern.name)

    return text, result

主要なデザイン上の選択:

1. embedding の前に filter します。 cleaned text が embed される対象です。vector representation が credential patterns を encode することはありません。”API key” で query すると、実際の keys を含むノートではなく、API key management について説明しているノートが返されます。

2. 削除ではなく置換します。 [REDACTED:pattern-name] token により、周囲の text の semantic context が保たれます。embedding は credential そのものを encode せず、「credential のようなものがここにあった」ことを捉えます。

3. 値ではなく patterns を log します。 filter は一致した patterns（例: “Scrubbed 2 credential(s) from oauth-debug.md [jwt, bearer-token]”）を log しますが、credential value は絶対に log しません。

Path-Based Exclusion

.indexignore file は、path による大まかな exclusion を提供します。credential filter は、indexed files の内部で細かな scrubbing を行います。両方が必要です。

• sensitive content を含むことが分かっている folders 全体には .indexignore を使います（health notes、financial records、career documents）
• それ以外は index できる content に誤って埋め込まれた secrets には credential filter を使います

データ分類

多様な content を含む vault では、sensitivity によってノートを分類することを検討してください。

MCP サーバーアーキテクチャ

Model Context Protocol (MCP) サーバーは、AIエージェントが呼び出せるツールとして retriever を公開します。このセクションでは、サーバー設計、機能の範囲、権限境界について説明します。

プロトコルの選択：STDIO と HTTP

MCP は、2つのトランスポートモードをサポートしています。

STDIO — AIツールが MCP サーバーを子プロセスとして起動し、stdin/stdout 経由で通信します。これはローカルツールの標準モードです。Claude Code、Codex CLI、Cursor はいずれも STDIO MCP サーバーをサポートしています。

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/path/to/vault",
        "DB_PATH": "/path/to/vectors.db"
      }
    }
  }
}

HTTP — MCP サーバーをスタンドアロンの HTTP サービスとして実行します。リモートアクセス、複数クライアント構成、または vault を共有サーバー上に置くチーム構成で役立ちます。

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

推奨事項： 個人用 vault には STDIO を使用してください。よりシンプルで安全であり（ネットワークに公開されません）、サーバーのライフサイクルは AIツールによって管理されます。複数のツールまたは複数のマシンから同じ vault へ同時アクセスする必要がある場合にのみ、HTTP を使用してください。

MCP Spec の進化。 2025年6月の MCP 仕様では、OAuth 2.1 認可、構造化ツール出力（型付きの戻り値スキーマ）、および elicitation（サーバー側から開始するユーザープロンプト）が追加されました。2025年11月リリースでは、ファーストクラスのトランスポートモードとして Streamable HTTP、サーバー機能を自動的に参照するための .well-known URL ディスカバリー、ツールが読み取り専用か変更を伴うかを宣言する構造化ツールアノテーション、そして SDK ティア標準化システムが導入されました。⁷⁹ 次の改訂もすでに具体化されています。2026-07-28 仕様は 2026年5月21日に Release Candidate に入りました。これは開始以来最大の MCP 改訂です。主な変更は、ステートレスなプロトコルコア（initialize ハンドシェイクと Mcp-Session-Id ヘッダーが削除され、サーバーが接続ごとのセッション状態を追跡しなくなります）、MCP Apps（サーバーがサンドボックス化されたクライアント iframe 内に表示する、サーバー生成の HTML を返せます）、experimental core から正式な拡張機能へ移行する Tasks（長時間実行操作向けの tasks/get、tasks/update、tasks/cancel）、強化された OAuth 2.0 / OIDC 認可、および 12か月間の機能廃止ライフサイクルポリシーです。これは予定どおり 2026年7月28日改訂としてリリースされ、現在の Current specification です（2026年8月14日に確認）。²⁴ 個人用 vault サーバーでは、STDIO が引き続き最もシンプルな選択肢であり、ステートレスなコアにより単一ユーザー向け STDIO サーバーはさらに軽量になります。Streamable HTTP トランスポート、.well-known ディスカバリー、MCP Apps は、主にマルチテナントルーティングとロードバランシングを備えるエンタープライズ HTTP デプロイメントで役立ちます。トランスポートの選択に影響する更新については、MCP roadmap を確認してください。

機能設計

MCP サーバーでは、最小限のツールセットを公開するべきです。

search — 主なツールです。hybrid retrieval を実行し、順位付けされた結果を返します。

{
  "name": "obsidian_search",
  "description": "Search the Obsidian vault using hybrid BM25 + vector retrieval",
  "parameters": {
    "query": { "type": "string", "description": "Search query" },
    "limit": { "type": "integer", "default": 5 },
    "max_tokens": { "type": "integer", "default": 2000 }
  }
}

read_note — パスで指定したノートの完全な内容を読み取ります。エージェントが検索結果の全体的な文脈を確認したい場合に役立ちます。

{
  "name": "obsidian_read_note",
  "description": "Read the full content of a note by file path",
  "parameters": {
    "file_path": { "type": "string", "description": "Relative path within vault" }
  }
}

list_notes — フィルター（フォルダー、タグ、種類、日付範囲）に一致するノートを一覧表示します。エージェントに具体的なクエリがない場合の探索に便利です。

{
  "name": "obsidian_list_notes",
  "description": "List notes matching filters",
  "parameters": {
    "folder": { "type": "string", "description": "Folder path within vault" },
    "tag": { "type": "string", "description": "Tag to filter by" },
    "limit": { "type": "integer", "default": 20 }
  }
}

get_context — 検索を実行し、その結果を会話へ注入するのに適したコンテキストブロックとして整形する便利なツールです。

{
  "name": "obsidian_get_context",
  "description": "Get formatted context from vault for a topic",
  "parameters": {
    "topic": { "type": "string", "description": "Topic to get context for" },
    "max_tokens": { "type": "integer", "default": 2000 }
  }
}

権限境界

MCP サーバーでは、厳格な境界を適用するべきです。

1. 読み取り専用。 サーバーは vault とインデックスデータベースを読み取ります。ノートの作成、変更、削除は行いません。新しいノートを記録する書き込み操作は、MCP サーバーではなく、別の hook または skill で処理します。

2. vault スコープ。 サーバーは、設定された vault パス内のファイルのみを読み取ります。パストラバーサルの試行（../../etc/passwd）は拒否する必要があります。

3. 認証情報をフィルタリングした出力。 データベースに事前フィルタリング済みのコンテンツが含まれていても、多層防御として出力時に認証情報のフィルタリングを適用してください。

4. トークン数を制限した応答。 AIツールが過度に大きなコンテキストブロックを受け取らないよう、すべてのツール応答で max_tokens を適用します。

エラー処理

MCP ツールは、AIツールの復旧を支援する構造化エラーメッセージを返すべきです。

def search(self, query, limit=5, max_tokens=2000):
    if not self.db_path.exists():
        return {
            "error": "Index database not found. Run the indexer first.",
            "suggestion": "python index_vault.py --full"
        }

    results = self.retriever.search(query, limit, max_tokens)

    if not results:
        return {
            "results": [],
            "message": f"No results found for '{query}'. Try broader terms."
        }

    return {
        "results": [
            {
                "file_path": r["file_path"],
                "section": r["section"],
                "text": r["chunk_text"],
                "score": round(r["rrf_score"], 4),
            }
            for r in results
        ],
        "count": len(results),
        "query": query,
    }

Claude Code Integration

Claude Code は、Obsidian 検索システムの主な利用者です。このセクションでは、MCP の設定、hook 統合、obsidian_bridge.py パターンを扱います。

MCP の設定

カスタムサーバーを claude mcp add で登録します（ユーザースコープでは ~/.claude.json に書き込まれ、-s project では共有可能な .mcp.json に書き込まれます。~/.claude/settings.json は MCP の設定対象ではありません）：

claude mcp add obsidian -s user \
  -e VAULT_PATH=/absolute/path/to/vault \
  -e DB_PATH=/absolute/path/to/vectors.db \
  -- python /path/to/obsidian_mcp.py

手動で記述する場合の、同等の .mcp.json エントリは次のとおりです：

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/vault",
        "DB_PATH": "/absolute/path/to/vectors.db"
      }
    }
  }
}

設定を追加したら、Claude Code を再起動します。MCP サーバーは子プロセスとして起動します。実行中であることを確認してください：

> What tools do you have from the obsidian MCP server?

Claude Code には、利用可能なツール（obsidian_search、obsidian_read_note など）が表示されるはずです。

Hook 統合

Hook は、定義されたライフサイクルの時点で Claude Code の動作を拡張します。Obsidian 統合に関係する hook は 2 つあります：

Hook は設定内で登録します（~/.claude/settings.json の hooks キー配下にイベント名と matcher を指定します）。標準入力から JSON ペイロードを受け取ります。Claude Code が自動検出する hooks ディレクトリは存在せず、ツールの詳細が $1/$2 引数として渡されることもありません。

UserPromptSubmit hook — プロンプト送信時に vault を検索し、関連コンテキストを注入します（このイベントの stdout は会話に追加されます）：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [{ "type": "command", "command": "/path/to/obsidian-context.sh" }]
      }
    ]
  }
}

#!/bin/bash
# obsidian-context.sh — read the JSON payload from stdin
PROMPT=$(jq -r '.prompt // empty')
[ -z "$PROMPT" ] && exit 0
CONTEXT=$(python /path/to/retriever.py search "$PROMPT" --limit 3 --max-tokens 1500)
if [ -n "$CONTEXT" ]; then
    printf 'Relevant vault context:\n%s\n' "$CONTEXT"   # stdout -> added as context
fi

PostToolUse hook — 重要なツール出力を将来の検索に備えて vault へ取り込みます（必要なツールでのみ発火するよう matcher を指定して登録します）：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write|Bash",
        "hooks": [{ "type": "command", "command": "/path/to/capture-insight.sh" }]
      }
    ]
  }
}

#!/bin/bash
# capture-insight.sh — tool name and response arrive as stdin JSON
PAYLOAD=$(cat)
TOOL_NAME=$(printf '%s' "$PAYLOAD" | jq -r '.tool_name')
OUTPUT=$(printf '%s' "$PAYLOAD" | jq -r '.tool_response // "" | tostring')
if [ ${#OUTPUT} -gt 500 ]; then
    python /path/to/capture.py --text "$OUTPUT" --source "claude-code-$TOOL_NAME"
fi

obsidian_bridge.py パターン

ブリッジモジュールは、hook や skill から呼び出せる Python API を提供します：

# obsidian_bridge.py
from retriever import HybridRetriever

_retriever = None

def get_retriever():
    global _retriever
    if _retriever is None:
        _retriever = HybridRetriever(
            db_path="/path/to/vectors.db",
            vault_path="/path/to/vault",
        )
    return _retriever

def search_vault(query, limit=5, max_tokens=2000):
    """Search vault and return formatted context."""
    retriever = get_retriever()
    results = retriever.search(query, limit, max_tokens)

    if not results:
        return ""

    lines = ["## Vault Context\n"]
    for r in results:
        lines.append(f"**{r['file_path']}** — {r['section']}")
        lines.append(f"> {r['chunk_text'][:500]}")
        lines.append("")

    return "\n".join(lines)

/capture Skill

インサイトを vault に取り込むための Claude Code skill です：

/capture "OAuth token rotation requires both access and refresh token invalidation"
  --domain security
  --tags oauth,tokens

この skill は、適切な frontmatter を含む新しいノートを 00-inbox/ に作成し、増分再インデックスを実行します。これにより、新しいノートをすぐに検索できます。

カスタムコマンドのパターン

Claude Code の skill は、vault 操作を名前付きコマンドとしてラップできます。実践者は、vault を読み取り元と書き込み先の両方として扱う、Obsidian 専用コマンドのライブラリを構築しています。

シグナルスキャン。 /scan-intel コマンドは外部ソースを検索し、個人のリサーチ関心に照らして発見事項をスコアリングし、基準を満たすシグナルを frontmatter 付きの vault ノートとして書き込みます：

/scan-intel --topics "agent infrastructure, security" --lookback 7d

このコマンドは設定済みのソース（arXiv、HN、RSS）から取得し、スコアリングモデル（関連性、実行可能性、深さ、権威性）を適用して、基準を通過したシグナルをトピック別の vault フォルダーへ書き込みます。vault は、自動化されたインテリジェンスパイプラインの下流コンシューマーになります。

キャプテンの日誌。 /captains-log コマンドは、すべてのリポジトリにまたがる日々の git アクティビティを集約し、構造化されたジャーナルエントリを vault に書き込みます。そこには、下した決定、気づき、未解決のスレッドも含まれます：

/captains-log

このコマンドは GitHub からコミット履歴を取得し、リポジトリごとにグループ化して、ナラティブなジャーナルエントリとして整形します。日々のログが積み重なることで、何をリリースし、その理由は何だったのかを検索可能な記録として残せます。

Obsidian へのキャプチャ。 /obsidian-capture コマンドは、現在の Claude Code セッションで得たインサイトを受け取り、適切なメタデータとともに vault へ直接書き込みます：

/obsidian-capture "SAST gates in agent loops increase security degradation"
  --folder AI-Tools --tags security,agents

このパターンは、あらゆる vault 操作へ拡張できます。たとえば、MOC の作成、プロジェクト状況ノートの更新、関連シグナルのリンク、蓄積した日次ログからの週次ダイジェスト生成などです。

コミュニティの例。 実践者たちはコマンドライブラリを公開しています。ある開発者は、日次レビュー、プロジェクト計画、リサーチのキャプチャ、コンテンツワークフローをカバーする、Obsidian + Claude Code 向けのカスタムコマンド 22 個を共有しました。¹ また別の開発者は、コード分析から vault 内に図解ノートを生成する「Visual Explainer」skill を作成しました。² コマンドはさまざまですが、アーキテクチャは一貫しています。インターフェースとしての Claude Code skill、ストレージ層としての vault ノート、クエリエンジンとしての検索インフラストラクチャです。

コンテキストウィンドウの管理

統合では、Claude Code のコンテキストウィンドウを考慮する必要があります：

• クエリごとに注入するコンテキストは 1,500〜2,000 トークンに制限します。 これを超えると、エージェントのワーキングメモリと競合します。
• ソースの帰属情報を含めます。 エージェントがソースを参照できるよう、常にファイルパスとセクション見出しを含めてください。
• チャンクのテキストを切り詰めます。 長いチャンクは完全に省略せず、... で切り詰めます。通常、最初の 300〜500 文字に重要な情報が含まれています。
• すべてのプロンプトで注入しないでください。 注入は UserPromptSubmit（stdout がモデルに届くイベント）を通じて実行されるため、そこで予算を管理します。短い会話的なプロンプトはスキップし、コード、ファイル、過去の決定に言及するプロンプトに限って注入し、注入ブロックの上限を設定してください。PreToolUse のようなツールスコープのイベントではゲートやログ記録ができますが、その stdout はモデルには届きません。

Codex CLI Integration

Codex CLI は config.toml を通じて MCP サーバーに接続します。統合パターンは、設定構文と指示の渡し方において Claude Code と異なります。

MCP の設定

~/.codex/config.toml に追加します（Codex は $CODEX_HOME/config.toml を読み込みます。プロジェクトレベルの指示はプロジェクト設定ファイルではなく AGENTS.md に記述します）：

[mcp_servers.obsidian]
command = "python"
args = ["/path/to/obsidian_mcp.py"]

[mcp_servers.obsidian.env]
VAULT_PATH = "/absolute/path/to/vault"
DB_PATH = "/absolute/path/to/vectors.db"

AGENTS.md のパターン

Codex CLI は、プロジェクトレベルの指示として AGENTS.md を読み取ります。vault 検索のガイダンスを含めてください：

## Available Tools

### Obsidian Vault (MCP: obsidian)
Use the `obsidian_search` tool to find relevant context from the knowledge base.
Search the vault when you need:
- Background on a concept or pattern
- Prior decisions or rationale
- Reference material for implementation

Example queries:
- "authentication patterns in FastAPI"
- "how does the review aggregator work"
- "sqlite-vec configuration"

Claude Code との違い

主な違い： 現在では両ツールとも hook と skill をサポートしていますが、形態が異なります。Codex は Claude Code の権限モードの代わりに、承認ポリシーと OS レベルの sandbox モードを組み合わせます。また、hook イベントも異なります。設定を移植するのではなく、パターン（作業前に vault を検索し、作業後にキャプチャする）を移植してください。Codex で常に vault を先に検索する指示を置く場所としては、引き続き AGENTS.md が適切です。

Cursorとその他のツール

MCP をサポートするCursorやその他のAIツールは、同じObsidian MCP サーバーに接続できます。このセクションでは、一般的なツールの設定を説明します。

Cursor

プロジェクトルートの .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "obsidian": {
      "command": "python",
      "args": ["/path/to/obsidian_mcp.py"],
      "env": {
        "VAULT_PATH": "/absolute/path/to/vault",
        "DB_PATH": "/absolute/path/to/vectors.db"
      }
    }
  }
}

Cursorの .cursorrules ファイルには、vaultを使用するための指示を含めることができます。

When working on implementation tasks, search the Obsidian vault
for relevant context before writing code. Use the obsidian_search
tool with descriptive queries about the concept you're implementing.

互換性マトリクス

MCP 非対応ツール向けのフォールバック

MCP をサポートしないツールでは、retrieverを CLI としてラップできます。

# Search from command line
python retriever_cli.py search "query text" --limit 5

# Output formatted for copy-paste into any tool
python retriever_cli.py context "query text" --format markdown

CLI は、任意のAIツールの入力欄に手動で貼り付けられる構造化テキストを出力します。MCP 統合ほど洗練されてはいませんが、あらゆる環境で動作します。

構造化ノートからのプロンプトキャッシュ

vault内の構造化ノートは、AIとのやり取り全体でトークン使用量を削減する再利用可能なコンテキストブロックとして利用できます。このセクションでは、キャッシュキーの設計とトークン予算の管理を説明します。

パターン

毎回のやり取りでコンテキストを検索する代わりに、適切に構造化されたvaultノートからコンテキストブロックを事前に構築し、キャッシュします。

# cache_keys.py
CONTEXT_BLOCKS = {
    "auth-patterns": {
        "vault_query": "authentication patterns implementation",
        "max_tokens": 1500,
        "ttl_hours": 24,  # Rebuild daily
    },
    "api-conventions": {
        "vault_query": "API design conventions REST patterns",
        "max_tokens": 1000,
        "ttl_hours": 168,  # Rebuild weekly
    },
    "project-architecture": {
        "vault_query": "current project architecture decisions",
        "max_tokens": 2000,
        "ttl_hours": 12,  # Rebuild twice daily
    },
}

キャッシュの無効化

キャッシュの無効化は、次の2つのシグナルに基づきます。

1. TTLの期限切れ。 各コンテキストブロックには有効期限があります。TTLが切れると、vaultを再クエリしてブロックを再構築します。
2. Vaultの変更検出。 indexerがキャッシュ済みコンテキストブロックに寄与したファイルの変更を検出すると、そのブロックは即座に無効化されます。

トークン予算の管理

セッションは、合計コンテキスト予算から開始します。キャッシュ済みブロックはその予算の一部を消費します。

Total context budget:    8,000 tokens
├─ System prompt:        1,500 tokens
├─ Cached blocks:        3,000 tokens (pre-loaded)
├─ Dynamic search:       2,000 tokens (on-demand)
└─ Conversation:         1,500 tokens (remaining)

キャッシュ済みブロックはセッション開始時に読み込まれます。動的な検索結果は、クエリごとに残りの予算を埋めます。このhybridアプローチにより、エージェントは頻繁に必要となるコンテキストをベースラインとして持ちながら、特定のクエリのための予算も確保できます。

キャッシュ前後のトークン使用量

キャッシュなし： 関連する各クエリでvault検索が実行され、1,500〜2,000トークンのコンテキストが返されます。1セッション中に10件のクエリを実行すると、エージェントはvaultコンテキストとして15,000〜20,000トークンを消費します。

キャッシュあり： 事前構築した3つのコンテキストブロックが、合計4,500トークンを消費します。追加検索では、ユニークなクエリごとに1,500〜2,000トークンが加わります。10件のクエリのうち6件がキャッシュ済みブロックでカバーされる場合、エージェントの消費量は4,500 + (4 * 1,500) = 10,500トークンとなり、キャッシュなしの使用量のおよそ半分です。

冗長な出力の圧縮サマリーを記録する

ツール出力は冗長になりがちです。たとえば、スタックトレース、ファイル一覧、テスト結果などがあります。hookはモデルがすでに見た内容を縮小できません。PostToolUseが発火する時点では完全な出力がすでにコンテキストウィンドウに入っており、hookが何を出力しても置き換えられないためです。hookでできるのは、圧縮したサマリーをvaultに書き出すことです。これにより、将来のセッションでは5,000トークンの元データを再実行・再読込する代わりに、2行の判定結果を取得できます。これはセッション間のメモリ用キャプチャパターンであり、セッション内のコンテキスト節約策ではありません（セッション内で有効なのは /compact、スコープを絞ったプロンプト、より簡潔な出力の依頼です）。

問題

テストを実行する Bash ツール呼び出しは、次のような結果を返すことがあります。

PASSED tests/test_auth.py::test_login_success
PASSED tests/test_auth.py::test_login_failure
PASSED tests/test_auth.py::test_token_refresh
PASSED tests/test_auth.py::test_session_expiry
... (200 more lines)
FAILED tests/test_api.py::test_rate_limit_exceeded

出力全体は5,000トークンですが、重要な情報は「200 passed、1 failed」という2行にあります。

Hookの実装

Bash matcherを使用して PostToolUse に登録します（設定で登録し、stdin JSON を使用します。上記のHook Integrationを参照してください）。

#!/bin/bash
# summarize-and-capture.sh — write a compressed summary to the vault
PAYLOAD=$(cat)
OUTPUT=$(printf '%s' "$PAYLOAD" | jq -r '.tool_response // "" | tostring')

# Only summarize large outputs
[ ${#OUTPUT} -lt 2000 ] && exit 0

if printf '%s' "$OUTPUT" | grep -q "PASSED\|FAILED"; then
    PASSED=$(printf '%s' "$OUTPUT" | grep -c "PASSED")
    FAILED=$(printf '%s' "$OUTPUT" | grep -c "FAILED")
    SUMMARY="Tests: $PASSED passed, $FAILED failed"
    [ "$FAILED" -gt 0 ] && SUMMARY="$SUMMARY
$(printf '%s' "$OUTPUT" | grep 'FAILED')"
    python /path/to/capture.py --text "$SUMMARY" --source "test-run-summary"
fi
exit 0

各hook呼び出しは新しいプロセスとして実行されるため、再帰ガードは不要です。hook自身の書き込みで再発火することはなく、exportした変数も次の呼び出しには引き継がれません。

圧縮ヒューリスティクス

シグナル取り込み・トリアージパイプライン

取り込みレイヤーは、何をvaultに入れるかを決定します。キュレーションがなければ、vaultにはノイズが蓄積します。このセクションでは、シグナルをドメインフォルダへ振り分けるスコアリングパイプラインを扱います。

ソース

シグナルは複数のチャネルから取得します。

• RSSフィード： 技術ブログ、セキュリティアドバイザリ、リリースノート
• Web Clipper経由のブックマーク： 公式のObsidian Web Clipper拡張機能（Chrome、Firefox、Safari）は、ブラウザ側でのキャプチャに最も忠実な取り込み経路です。2026年4月のリリースサイクルにより、AIワークフローでの有用性が大幅に向上しました。²²
  • 1.4.0（4月9日）： インタラクティブなYouTubeトランスクリプトUI — 動画を固定し、トランスクリプト内をスクラブして、自動スクロールと現在位置のハイライトを行えます。さらに、「Open in Reader」をデフォルトにすると、ワンクリックでReaderモードへ直接キャプチャを送れます。
  • 1.5.0–1.5.1（4月15日）： ハイライトビューア — vault全体でキャプチャしたハイライトを閲覧・検索できます。Readerへのフェードイン遷移、よりスムーズなYouTubeの再生・一時停止も追加されました。1.5.1ではwebpackコンパイルのリグレッションが修正されました。
  • 1.6.0–1.6.2（4月21日～23日）： モバイル対応を含むHighlighter UXの全面刷新。Defuddle 0.18ではLinkedIn、Threads、Bluesky、Discourse、Medium向けのソース固有エクストラクタが追加されました。1.6.2ではSafari埋め込みモードのクリップボードに関するリグレッションが修正されました。 ソースドメインごとにテンプレートを設定すると、YouTubeトランスクリプト、GitHub README、長文記事をそれぞれ適切な名前のノートとして保存し、以下のスコアリングパイプラインに必要なfrontmatterを付与できます。
• ニュースレター： メールニュースレターからの重要な抜粋
• 手動キャプチャ： 読書、会話、調査の最中に作成したノート
• ツール出力： フック経由でキャプチャした重要なAIツール出力
• iOS Share Extension： ObsidianのiOSアプリ（2026年初頭に更新）には、Obsidianを開かずにSafari、ソーシャルネットワーク、その他のアプリからコンテンツをvaultへ直接保存できるShare Extensionが含まれます。1.13系では、urlを含むテンプレート変数を備えた設定可能なShare Sheetターゲットが追加され、キャプチャしたページのソースリンクをfrontmatterへ自動記録できます。¹⁹ これにより、摩擦の少ないモバイル取り込み経路が実現します。Safariから記事を共有すれば、スコアリング可能なvaultノートとして届きます。
• Obsidian CLI： シェルスクリプトとフックでは、obsidian file createでノートを作成したり、obsidian file appendで既存ノートに追記したりできるため、デスクトップで自動取り込みパイプラインを構築できます。

スコアリングの次元

各シグナルは4つの次元で評価されます（各0.0～1.0）。

合成スコアとルーティング

composite = (relevance * 0.35) + (actionability * 0.25) +
            (depth * 0.25) + (authority * 0.15)

ドメインルーティング

0.55を上回るシグナルは、キーワード一致とトピック分類に基づいて12のドメインフォルダのいずれかへ振り分けられます。

05-signals/
├── ai-tooling/        # Claude, LLMs, AI development tools
├── security/          # Vulnerabilities, auth, cryptography
├── systems/           # Architecture, distributed systems
├── programming/       # Languages, patterns, algorithms
├── web/               # Frontend, backends, APIs
├── data/              # Databases, data engineering
├── devops/            # CI/CD, containers, infrastructure
├── design/            # UI/UX, product design
├── mobile/            # iOS, Android, cross-platform
├── career/            # Industry trends, hiring, growth
├── research/          # Academic papers, whitepapers
└── other/             # Signals that don't fit a domain

本番統計

14か月間の運用実績：

ナレッジグラフのパターン

Obsidianのwiki-linkグラフは、ノート間の関係をエンコードします。このセクションでは、リンクの意味論、コンテキスト拡張のためのグラフトラバーサル、グラフ品質を低下させるアンチパターンを扱います。

backlinkの意味論

すべてのwiki-linkはグラフ内に有向エッジを作成します。Obsidianはforward linkとbacklinkの両方を追跡します。

• forward link： ノートAに[[Note B]]が含まれる → AがBへリンクする
• backlink： ノートBには、ノートAがそれを参照していることが表示される

グラフはコンテキストに応じて異なる種類の関係をエンコードします。

Maps of Content（MOCs）

MOCは、関連ノートをナビゲート可能な構造に整理するインデックスノートです。

---
title: "Authentication & Security MOC"
type: moc
domain: security
---

## Core Concepts
- [[OAuth 2.0 Overview]]
- [[JWT Token Anatomy]]
- [[Session Management Patterns]]

## Implementation Patterns
- [[OAuth Token Rotation]]
- [[Refresh Token Security]]
- [[PKCE Flow Implementation]]

## Failure Modes
- [[Token Expiry Handling]]
- [[Session Fixation Prevention]]
- [[CSRF Defense Strategies]]

MOCは次の2つの方法でretrievalに役立ちます。

1. 直接一致。 「authentication overview」を検索するとMOC自体に一致し、関連ノートのキュレーション済みリストをエージェントに提供します。
2. コンテキスト拡張。 特定のノートを見つけた後、retrieverはそのノートがいずれかのMOCに含まれているか確認し、MOCの構造を結果に含められます。これにより、エージェントにより広いトピックの地図を提供できます。

コンテキスト拡張のためのグラフトラバーサル

retrieverに対する今後の強化案として、上位結果を見つけた後、リンクをたどってコンテキストを拡張できます。

def expand_context(results, depth=1):
    """Follow wiki-links from top results to find related context."""
    expanded = set()
    for result in results:
        # Parse wiki-links from chunk text
        links = extract_wiki_links(result["chunk_text"])
        for link_target in links:
            # Resolve link to file path
            target_path = resolve_wiki_link(link_target)
            if target_path and target_path not in expanded:
                expanded.add(target_path)
                # Include target's most relevant chunk
                target_chunks = get_chunks_for_file(target_path)
                # ... rank and include best chunk
    return results + list(expanded_results)

これは現在のretrieverには実装されていませんが、グラフ構造を自然に拡張する方法です。

アンチパターン

孤立クラスター。 相互にリンクしているものの、vaultの他の部分とは接続がないノート群です。Obsidianのグラフパネルでは、これらが切り離された島として表示されます。孤立クラスターは、MOCまたはドメイン横断リンクが不足していることを示します。

タグの乱立。 タグを一貫性なく使用したり、細分化しすぎたタグを作りすぎたりすることです。5,000ノートに500個のユニークタグがあるvaultでは、平均すると10タグにつき1ノートとなり、タグはフィルタリングに役立ちません。ドメインフォルダに対応する20～50個の上位レベルタグに統合してください。

リンクが多く、コンテンツが少ないノート。 散文なしでwiki-linkだけから成るノートです。chunkerにはembeddingするテキストがないため、こうしたノートはインデックスの品質が低くなります。リンクされたノートが関連する理由を説明する、少なくとも1段落のコンテキストを追加してください。

あらゆるものに双方向リンクを張ること。 すべての参照にwiki-linkが必要なわけではありません。「OAuth」に軽く触れるだけなら、[[OAuth 2.0 Overview]]は不要です。リンクをクリックすると有用なコンテキストが得られる、意図的でナビゲート可能な関係にのみwiki-linkを使用してください。

開発者向け Workflow レシピ

vault retrieval と日々の開発タスクを組み合わせる実践的な workflow です。

朝の Context Load

関連する context を読み込んで1日を始めます。

Search my vault for notes about [current project] updated in the last week

retriever は進行中のプロジェクトに関する最近の notes を返し、前回どこまで進めたかをすばやく思い出せます。昨日の commit messages を読み返すより効果的です。

Coding 中の Research Capture

機能を実装している途中で、エディターを離れずに気づきを capture します。

/capture "FastAPI dependency injection with async generators requires yield,
not return. The generator is the dependency lifecycle."
  --domain programming
  --tags fastapi,dependency-injection

capture した気づきはすぐに index され、今後の retrieval で利用できるようになります。数か月たつと、こうした小さな captures が実装固有の知識 corpus になります。

Project Kickoff

新しいプロジェクトや機能を始めるときは、次のように進めます。

1. vault を検索する: 「[technology/pattern] について自分は何を知っているか？」
2. 上位5件の結果を確認し、過去の判断や gotchas を把握する
3. その領域の MOC があるか確認し、なければ作成する
4. failure modes を検索する: 「[technology] の問題」

Vault Search を使った Debugging

エラーや想定外の挙動に遭遇したときは、次のようにします。

Search my vault for [error message or symptom]

過去の debugging notes には、root cause と fix が含まれていることがよくあります。これはプロジェクトをまたいで繰り返し発生する問題で特に有用です。vault は忘れてしまうことを覚えていてくれます。

Code Review の準備

PR を review する前に、次のようにします。

Search my vault for patterns and conventions about [module being changed]

vault は、review 対象の code に関連する過去の判断、architectural constraints、coding standards を返します。review は diff だけでなく、組織的な知識に基づいたものになります。

Performance Tuning

この section では、vault のサイズや使用パターンに応じた最適化戦略を扱います。

Index Size Management

50,000件以上の notes では、次を検討してください。 - embedding を高速化するため、batch size を 64 から 128 に増やす - concurrent access のために WAL mode（default）を使う - full reindex は利用の少ない時間帯に実行する

Query Optimization

WAL mode。 SQLite の Write-Ahead Logging mode により、indexer が書き込んでいる間も concurrent reads が可能になります。

db.execute("PRAGMA journal_mode=WAL")

これは、indexer が incremental update を実行している間に MCP server が queries を処理する場合に重要です。

Connection pooling。 MCP server は query ごとに新しい connection を開くのではなく、database connections を再利用するべきです。WAL mode の単一の長寿命 connection で concurrent reads をサポートできます。

# MCP server initialization
db = sqlite3.connect(DB_PATH, check_same_thread=False)
db.execute("PRAGMA journal_mode=WAL")
db.execute("PRAGMA mmap_size=268435456")  # 256 MB mmap

Memory-mapped I/O。 mmap_size pragma は、database file に memory-mapped I/O を使うよう SQLite に指示します。83 MB の database なら、file 全体を memory に map することで、ほとんどの disk reads をなくせます。

FTS5 optimization。 full reindex の後に、次を実行します。

INSERT INTO chunks_fts(chunks_fts) VALUES('optimize');

これにより FTS5 の internal b-tree segments が merge され、その後の searches の query latency が下がります。

Scaling Benchmarks

Apple M3 Pro、36 GB RAM、NVMe SSD で計測しました。

すべての benchmarks には、database access、query execution、result formatting が含まれます。MCP STDIO communication の network latency により、1〜2ms が追加されます。

Troubleshooting

Index Drift

Symptom: Search が stale results を返す、または最近追加した notes を見つけられない。

Cause: notes を追加した後に incremental indexer が実行されていない、または file の mtime が更新されていない（例: timestamps を保持したまま別の machine から同期した場合）。

Fix: full reindex を実行します: python index_vault.py --full

Embedding Model Swap

Symptom: embedding model を変更した後、vector search が意味不明な results を返す。

Cause: 古い vectors（以前の model 由来）が、新しい query vectors と比較されています。dimensions または vector space semantics に互換性がありません。

Fix: indexer は model hash mismatch を検出し、自動で full reindex を trigger するべきです。そうならない場合は、手動で database を clear して reindex します。

rm vectors.db
python index_vault.py --full

FTS5 Maintenance

Symptom: 多数の incremental updates の後、FTS5 queries が不正確または不完全な results を返す。

Cause: 多数の小さな updates により、FTS5 internal segments が fragmented になることがあります。

Fix: rebuild と optimize を実行します。

INSERT INTO chunks_fts(chunks_fts) VALUES('rebuild');
INSERT INTO chunks_fts(chunks_fts) VALUES('optimize');

MCP Timeout

Symptom: AI tool が MCP server の timeout を報告する。

Cause: 最初の query で model loading（lazy initialization）が発生し、2〜5秒かかります。AI tool の default MCP timeout はそれより短い場合があります。

Fix: server startup 時に model を pre-warm します。

# In MCP server initialization
retriever = HybridRetriever(db_path, vault_path)
retriever.search("warmup", limit=1)  # Trigger model load

SQLite File Locks

Symptom: SQLITE_BUSY または SQLITE_LOCKED errors。

Cause: 複数の processes が同時に database へ書き込んでいます。WAL mode は concurrent reads を許可しますが、writer は1つだけです。

Fix: database に書き込む process は1つ（indexer）だけにしてください。MCP server と hooks は read のみにするべきです。concurrent writes が必要な場合は、WAL mode を使い、busy timeout を設定します。

db.execute("PRAGMA busy_timeout=5000")  # Wait up to 5 seconds

sqlite-vec Not Loading

Symptom: Vector search が disabled になり、retriever が BM25-only mode で動作する。

Cause: sqlite-vec extension が installed されていない、library path で見つからない、または SQLite version と互換性がありません。

Fix:

# Install via pip
pip install sqlite-vec

# Or compile from source
git clone https://github.com/asg017/sqlite-vec
cd sqlite-vec && make

extension が load されることを確認します。

import sqlite3
db = sqlite3.connect(":memory:")
db.enable_load_extension(True)
db.load_extension("vec0")
print("sqlite-vec loaded successfully")

Large Vault Memory Issues

Symptom: 大規模 vault（50,000件以上の notes）の full reindex 中に out-of-memory errors が発生する。

Cause: Embedding batch size が大きすぎる、またはすべての file contents を同時に memory に読み込んでいます。

Fix: batch size を減らし、files を incremental に処理します。

BATCH_SIZE = 32  # Reduce from 64

また、indexer がすべての files を memory に読み込むのではなく、1 file ずつ（読み込み、chunking、embedding を行ってから次へ進む）処理していることも確認してください。

Migration Guide

Apple Notes から

1. Apple Notes を「Export All」option（macOS）で export するか、apple-notes-liberator のような migration tool を使う
2. HTML exports を markdownify または pandoc で markdown に変換する
3. 変換した files を vault の 00-inbox/ folder に移動する
4. 各 note を確認し、frontmatter を追加する
5. notes を適切な domain folders に移動する

Notion から

1. Notion から export する: Settings → Export → Markdown & CSV
2. export を unzip して vault の 00-inbox/ folder に入れる
3. Notion 固有の markdown artifacts を修正する:
4. Notion は checklists に - [ ] を使います。これは standard markdown です
5. Notion は property tables を HTML として含めます。YAML frontmatter に変換してください
6. Notion は images を relative paths として embed します。images を attachments folder に copy してください
7. standard frontmatter（type, domain, tags）を追加する
8. Notion page links を Obsidian wiki-links に置き換える

Google Docs から

1. Google Takeout を使ってすべての documents を export する
2. .docx files を markdown に変換する: pandoc -f docx -t markdown input.docx -o output.md
3. batch convert する: for f in *.docx; do pandoc -f docx -t markdown "$f" -o "${f%.docx}.md"; done
4. vault に移動し、frontmatter を追加して、folders に整理する

Plain Markdown（Obsidian なし）から

すでに markdown files の directory がある場合は、次のようにします。

1. directory を Obsidian vault として開く（Obsidian → Open Vault → Open folder）
2. directory が version-controlled の場合は、.obsidian/ を .gitignore に追加する
3. frontmatter templates を作成し、既存 files に適用する
4. 読みながら整理する中で、[[wiki-links]] を使って notes を link し始める
5. すぐに indexer を実行する。retrieval system は初日から機能します

別の Retrieval System から

別の embedding/search system から migration する場合は、次のようにします。

1. vectors を migrate しようとしないでください。 異なる models は互換性のない vector spaces を生成します。新しい model で full reindex を実行してください。
2. index ではなく content を migrate してください。 vault files が source of truth です。index は derived artifact です。
3. migration 後に verify してください。 答えが分かっている queries を 10〜20件実行し、results が期待どおりか確認します。

変更履歴

参考文献