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 passage rankingに関する研究でも、この傾向は確認されています。hybrid retrievalは、どちらか単独の手法よりも一貫して高い性能を示します。³ hybrid retriever deep diveでは、RRFの計算、実数を使った例、失敗パターンの分析、インタラクティブなfusion計算機を扱っています。

MCPにより、AIツールがvaultへ直接アクセスできます。 Model Context Protocol (MCP)サーバーは、検索器をツールとして公開します。Claude Code、Codex CLI、Cursor、その他のAIツールがそのツールを直接呼び出せます。エージェントはvaultにクエリを投げ、出典付きでランク付けされた結果を受け取り、ファイル全体を読み込まずにコンテキストを利用します。MCPサーバーは、検索エンジンを包む薄いラッパーです。

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

Incremental indexingにより、システムは10秒未満で最新状態を保てます。 ファイルの更新時刻を比較して変更を検出します。変更されたファイルだけを再chunkingし、再embeddingします。Apple M-seriesハードウェアでは、フルreindexに約4分かかります。典型的な1日の編集に対するincremental更新は10秒未満で完了します。手動操作なしで、システムを最新に保てます。

このアーキテクチャは、200件のノートから20,000件以上のノートまでスケールします。 同じ3層設計（取り込み、検索、連携）が、どのvaultサイズでも機能します。小さなvaultではBM25のみの検索から始めます。キーワードの衝突が問題になったら、ベクトル検索を追加します。正確な一致とセマンティックな一致の両方が必要になったら、RRF fusionを追加します。各レイヤーは、それ単体でも有用であり、個別に取り外すこともできます。

このガイドの使い方

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

Contract と記されたセクションには、実装の詳細、設定ブロック、失敗パターンが含まれます。Narrative と記されたセクションでは、概念、アーキテクチャ上の判断、デザイン選択の背後にある理由に焦点を当てます。Recipe と記されたセクションでは、手順に沿ったワークフローを示します。

AI InfrastructureにObsidianを使う理由

このガイドの主張は次のとおりです。Obsidian vaultは、personal AI knowledge baseの基盤として最適です。local-firstで、plaintextで、グラフ構造を持ち、スタックのすべてのレイヤーをユーザーが制御できるからです。

ObsidianがAIに提供し、代替ツールにはないもの

Plaintext markdownファイル。 すべてのノートは、ファイルシステム上の.mdファイルです。独自形式も、データベースのエクスポートも、内容を読むためのAPIも不要です。ファイルを読めるツールなら、どれでもvaultを読めます。grep、ripgrep、Pythonのpathlib、SQLite FTS5はいずれも、ソースファイルに直接作用します。検索システムを構築するときにインデックスするのは、APIレスポンスではなくファイルです。ソースがファイルシステムであるため、インデックスは常にソースと整合します。

Local-firstアーキテクチャ。 vaultは自分のマシン上にあります。サーバーも、クラウド同期への依存も、APIのレート制限も、自分のコンテンツをどう処理するかを制約する利用規約もありません。外部サービスなしで、ノートをembed、index、chunk、searchできます。AI infrastructureにおいて重要なのは、検索パイプラインの速度がAPIエンドポイントの応答速度ではなく、ディスクの速度で決まることです。プライバシー面でも重要です。認証情報、健康データ、金融情報、私的な考えを含む個人ノートがマシンの外へ出ることはありません。

Wiki-linkによるグラフ構造。 Obsidianの[[wiki-link]]構文は、ノート間に有向グラフを作ります。OAuth実装に関するノートは、token rotation、session management、API securityに関するノートへリンクします。グラフ構造は、概念間の関係を人間が整理したシグナルとして表します。Vector embeddingsは意味的類似性を捉えますが、wiki-linksは、著者がそのトピックについて考えながら作った意図的なつながりを捉えます。このグラフは、embeddingsでは再現できないシグナルです。

Pluginエコシステム。 Obsidianには2,500以上のcommunity pluginsがあります（2026年3月時点。2025年半ばの1,800以上から増加）。Dataviewはvaultをデータベースのようにクエリします。TemplaterはJavaScriptロジックを使ってテンプレートからノートを生成します。Git integrationはvaultをリポジトリへ同期します。Linterはフォーマットの一貫性を強制します。Bases core plugin（v1.9.10で導入）は、frontmatter propertiesをフィールドとして使い、vaultファイル上にデータベースのようなビューを追加します。テーブル、ギャラリー、カレンダー、kanban boardsを作成でき、.baseファイルとして保存されます。¹⁵ これらのpluginsは、基盤となるplaintext形式を変えずにvaultへ構造を追加します。検索システムがインデックスするのは、plugins自体ではなく、これらのpluginsの出力です。

500万人以上のユーザー。 Obsidianには、テンプレート、ワークフロー、plugins、ドキュメントを生み出す大規模で活発なコミュニティがあります。vaultの整理やplugin設定で問題に遭遇した場合、誰かがすでに解決策を文書化している可能性が高いです。コミュニティはObsidian周辺ツールも生み出しています。MCPサーバー、indexing scripts、publishing pipelines、API wrappersなどです。

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

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

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

2. Pluginレンダリング付きのライブプレビュー。 Dataview queries、Mermaid diagrams、callout blocksはリアルタイムにレンダリングされます。保存形式はplaintextのまま、テキストエディタより豊かな執筆体験が得られます。リッチな環境で書き、整理し、検索システムは生のmarkdownをインデックスします。

3. コミュニティインフラ。 Plugin discovery、theme marketplace、sync service（任意）、publish service（任意）、ドキュメントエコシステムがあります。個々の機能はスタンドアロンのツールで再現できますが、Obsidianはそれらを一貫したワークフローとしてまとめています。

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

Obsidianには検索インフラは含まれていません。基本的な検索（全文、ファイル名、タグ）はありますが、embedding pipeline、vector search、fusion ranking、MCP server、credential filtering、chunking strategy、外部AIツール向けのintegration hooksはありません。このガイドでは、Obsidianの上に構築するインフラを扱います。 vaultは基盤です。検索パイプライン、MCP server、integration hooksがインフラになります。

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

Obsidian MCP セットアップ

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

前提条件

• macOS、Linux、またはWindows
• Node.js 18+（MCP server用）
• Obsidian 1.12+（CLI integration用。1.13.1が現在のpublic desktop releaseです。MCPのみのセットアップでは以前のバージョンでも動作します）
• Claude Code、Codex CLI、またはCursorがインストール済み

Step 1: vaultを作成する

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

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

retrieverが扱える材料として、いくつかノートを追加します。10〜20件のノートだけでも結果を確認するには十分です。各ノートは、意味のあるタイトルと少なくとも1段落の本文を持つ.mdファイルにしてください。

Step 2: MCP serverをインストールする

すぐにvaultへアクセスできるコミュニティ製MCP serverはいくつかあります。このエコシステムは2025〜2026年にかけて大きく成長しました。注目すべきものの1つがMCPVault（npm @bitbonsai/mcpvault、repo bitbonsai/mcpvault）で、現在はv0.12.1です。これは下記のMarkusPfundstein/mcp-obsidianとは別プロジェクトであり、名称変更ではありません。v0.11.0（2026年3月）では、frontmatterとhashtagsを件数付きでスキャンするlist_all_tags、dotted-folder処理の改善、.base/.canvasサポートが追加されました。path-filter restricted-directory deny-listに対して、中程度の深刻度のadvisoryが2件（GHSA-9c83-rr99-vfwjとGHSA-j99q-93c9-h869）公開されているため、現在のリリースを実行してください。¹³

2026年4月の変化 — 推奨ブリッジとしてのObsidian CLI: Obsidian 1.12.0でファーストクラスのCLIが導入され、public 1.12.7 installer（2026年3月23日）にはstandalone binary、TUI、socket-file改善が同梱され、terminal workflowのインストールと実行が簡単になりました。¹⁶ 現在のpublic desktop releaseである1.13.1（public channel、2026年6月9日）は、1.13.0からのversion-currency bumpです。settings UXの改良とCodeMirror upgradeはありますが、1.12.xのCLI surfaceを超える新しいAI/automation機能はありません。²⁵²⁶ コミュニティツールは、mcp-obsidianを支えていたLocal REST API pluginから、より高速で安定したCLIベースのintegrationへ活発に移行しています。MarkusPfundstein/mcp-obsidian repoは現在もメンテナンスされています。2026年5月までのcommitsでsearch_by_tagやget_frontmatterなどのtoolsが追加されています。ただしtagged releasesは提供されていないため、pinned commitからインストールしてください。これは今もLocal-REST-APIベースです。新規セットアップでは、CLI bridgeのほうが一般に高速で安定しているため、これか下記の新しいコミュニティ代替を優先してください。²⁰ 推奨セットアップについては、このガイド後半の「AI Workflows向けObsidian CLI」セクションをご覧ください。

クイックスタートでは、.mdファイルを直接読み取るファイルベースのserverが最も簡単です。

npm install -g obsidian-mcp-server

Step 3: AIツールを設定する

Claude Code — ~/.claude/settings.jsonに追加します。

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "args": ["--vault", "/absolute/path/to/your/vault"]
    }
  }
}

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

[mcp_servers.obsidian]
command = "obsidian-mcp-server"
args = ["--vault", "/absolute/path/to/your/vault"]

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

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "args": ["--vault", "/absolute/path/to/your/vault"]
    }
  }
}

Step 4: 最初のクエリを実行する

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

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

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

接続後にClaudeでできること

正確なtool名はserverによって異なりますが、中心となるcapability surfaceは実装間で共通しています。

実際には、Claudeはsource attribution付きでノートから質問に答え、過去の意思決定や参照資料をcoding sessionへ取り込み、ファイル全体をcontextに読み込まずにvault構造を探索します。一部のコミュニティserverはwrite operations（作成、追記、tagとfrontmatter管理）も公開しています。このガイド後半で構築するカスタムserverは意図的にread-onlyとし、ノート作成はhooksで扱います。

詳細解説: toolとpermission設計についてはMCP Server Architecture、hooksとbridge patternについてはClaude Code Integration、その他のagentについてはCodex CLI IntegrationとCursor and Other Toolsをご覧ください。

ここまでで構築したもの

標準protocolを通じて、ローカルのknowledge baseをAIツールへ接続しました。MCP serverはvaultファイルを読み取り、基本的な検索を行い、結果を返します。これが最小限の実用版です。

このクイックスタートで得られないもの: - Hybrid retrieval（BM25 + vector search + RRF fusion） - Embeddingベースのsemantic search - Credential filtering - Incremental indexing - Hookベースのautomatic context injection

このガイドの残りでは、これらのcapabilityを1つずつ構築します。クイックスタートはconceptを証明するものです。完全なpipelineでは、本番品質のretrievalを実現します。

AI Workflows向けのObsidian CLI

Obsidian 1.12（2026年2月）では、AI workflowsの新しい連携面を開く組み込みコマンドラインインターフェースが導入されました。これは、設定UXとCodeMirrorのバージョン更新のみで新しいCLI機能は追加されていない、1.13.1のpublic desktop release（public channel、2026年6月9日）でも引き続き現行です。¹⁶²⁵²⁶ CLIはObsidian GUIのリモコンのように動作します。Obsidianが起動している必要があります（または、最初のコマンドで自動的に起動します）。Settings > General > Command line interfaceで有効にしてください。

AI infrastructureでCLIが重要な理由

CLIは、これまでGUIまたはplugin APIsが必要だったObsidianネイティブの操作に、プログラムからアクセスできるようにします。AI workflowsで重要な機能は次のとおりです。

• スクリプトとhooksから検索できます。 obsidian search "query"とobsidian search:context "query"は、任意のshell script、hook、自動化pipelineからvault検索を実行します。search:context variantは、周辺文脈つきで一致行を返すため、結果をAI promptsに渡す用途に便利です。
• Daily notesを自動化できます。 obsidian dailyは、今日のdaily noteを開くか作成します。shell scriptingと組み合わせることで、自動daily briefing workflowsを実現できます。たとえばhookで、AIが生成した要約をdaily noteに追記できます。
• テンプレートベースでnoteを作成できます。 obsidian template listとobsidian template createは、Templaterまたはcore templatesからnotesを生成します。これにより、AI agentsはmarkdown filesを直接書き込まずに、構造化されたvault entriesを作成できます。
• Propertyを管理できます。 obsidian property setとobsidian property getはfrontmatter propertiesを読み書きします。YAMLをparseせずに、scriptsからmetadataを更新できます。
• Pluginを制御できます。 obsidian plugin enable/disable/listはpluginsをプログラムから管理します。batch operations中にindexing pluginsを切り替える用途に便利です。
• Taskを管理できます。 obsidian task list/add/completeは構造化されたtask accessを提供します。vault内のwork itemsを管理するAI agentsに役立ちます。

AI accessにおけるCLIとMCPの違い

CLIとMCP serversは役割が異なり、競合するものではなく補完関係にあります。

Recommendation: intake automation（notesの作成、propertiesの管理、Obsidianネイティブ検索の実行）にはCLIを使い、retrieval（embeddingsを使ったhybrid search）にはMCPを使いましょう。PreToolUse hookでは、ranked resultsを得るために完全なMCP retrieverへfallbackする前の高速な事前チェックとして、obsidian search:contextを呼び出せます。

例: CLIを使ったintake hook

#!/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

Obsidian pluginsの中でも、AI coding agentsをvault UIに直接組み込むカテゴリが増えています。これは、外部MCP server設定の代替になります。これらのpluginsは、外部toolから接続するのではなく、Obsidianのsidebar内でAI agentを実行します。

Claudian

Claudianは、Claude Codeをvault内のAI collaboratorとして組み込みます。vault directoryがClaudeのworking directoryとなり、file read/write、search、bash commands、multi-step workflowsといった完全なagentic capabilitiesを利用できます。¹⁷

AI infrastructure向けの主な機能: - Context-aware prompts。 focused noteを自動で添付し、@notenameによるfile mentions、tag-based exclusion、editor selectionのcontext利用に対応します。 - Vision support。 drag-and-drop、paste、file path経由でimagesを解析できます。vaultに保存したscreenshotsやdiagramsの処理に便利です。 - Slash commands。 /commandで起動する再利用可能なprompt templatesを作成し、標準化されたvault operationsを実行できます。 - Permission modes。 YOLO（auto-approve）、Safe（各actionをapprove）、Plan（plan-only）modesを提供し、safety blocklistとvault confinementも備えています。

Agent Client

Agent Clientは、Agent Client Protocol（ACP）を通じて、Claude Code、Codex CLI、Gemini CLIを統合されたObsidian sidebarに取り込みます。¹⁸

主な機能: - Multi-agent switching。 同じpanelからClaude Code、Codex、Gemini CLIとchatでき、必要に応じてagentsを切り替えられます。 - Note mentions。 Claudianと同様に@notenameを使ってnote contentsをpromptsに含められますが、agent-agnosticです。 - Shell execution。 chat内でterminal commandsをinline実行できます。conversationを離れずに、build scripts、git commands、その他のterminal operationを実行できます。 - Action approval。 file reads、edits、command executionsを細かく制御できます。

Agent pluginsと外部MCPの使い分け

Recommendation: vault中心のworkflows（notesの執筆、整理、要約）にはagent pluginsを使いましょう。AI agentが完全なretrieval pipelineとvault外のcodebasesへのアクセスを必要とするdevelopment workflowsには、外部MCP serversを使います。2つのapproachesは共存できます。note workにはObsidian内でClaudianを実行し、developmentには外部で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を公開します。このセクションでは、サーバーデザイン、機能の範囲、権限境界について説明します。

Protocolの選択: STDIO vs HTTP

MCPは2つのtransportモードをサポートしています。

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仕様の進化。 2025年6月のMCP仕様では、OAuth 2.1認可、構造化されたツール出力（型付き戻りスキーマ）、elicitation（サーバー主導のユーザープロンプト）が追加されました。2025年11月のリリースでは、Streamable HTTPが第一級のtransportモードとして提供され、サーバー機能の自動閲覧に使える.well-known URL discovery、ツールが読み取り専用か変更を伴うかを宣言する構造化ツールアノテーション、そしてSDK tier標準化システムが導入されました。⁷⁹ 次の改訂内容はすでに具体化しています。2026-07-28仕様は、2026年5月21日にRelease Candidateへ入りました。これはローンチ以来最大のMCP改訂です。主な変更点は、ステートレスなprotocol core（initializeハンドシェイクとMcp-Session-Idヘッダーが削除され、サーバーは接続ごとのセッション状態を追跡しなくなります）、MCP Apps（サーバーが、サンドボックス化されたクライアントiframe内に表示されるサーバーレンダリングのHTMLを返せます）、Tasksがexperimental coreから公式extensionへ昇格（長時間実行操作向けのtasks/get、tasks/update、tasks/cancel）、強化されたOAuth 2.0 / OIDC認可、そして12か月の機能非推奨ライフサイクルポリシーです。最終仕様は2026年7月28日にリリースされます。²⁴ 個人用vaultサーバーでは、STDIOが引き続き最もシンプルな道筋です。また、ステートレスcoreにより、単一ユーザー向けSTDIOサーバーはさらに薄くなります。Streamable HTTP transport、.well-known discovery、MCP Appsは主に、マルチテナントルーティングやロードバランシングを伴うエンタープライズHTTPデプロイメントで効果を発揮します。transportの選択に影響する更新については、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 — パスで指定した特定のノートの全文を読み取ります。エージェントが検索結果の完全なcontextを確認したい場合に役立ちます。

{
  "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 — フィルター（フォルダ、タグ、種類、日付範囲）に一致するノートを一覧表示します。エージェントが具体的なqueryを持たずに探索したい場合に便利です。

{
  "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 — 検索を実行し、その結果を会話へ注入しやすい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とindex databaseを読み取ります。ノートの作成、変更、削除は行いません。書き込み操作（新しいノートのcapture）は、MCPサーバーではなく、別のhooksまたはskillsで処理します。

2. Vaultスコープ。 サーバーは設定されたvaultパス内のファイルだけを読み取ります。パストラバーサルの試行（../../etc/passwd）は拒否しなければなりません。

3. Credential-filtered output。 databaseに事前フィルタ済みのcontentが含まれている場合でも、多層防御として出力時にcredential filteringを適用します。

4. Token制限付きレスポンス。 AIツールが過度に大きなcontextブロックを受け取らないように、すべてのツールレスポンスで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 連携

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

MCP 設定

Obsidian MCP サーバーを ~/.claude/settings.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 連携

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

PreToolUse hook — エージェントがツール呼び出しを処理する前に vault をクエリします。関連するコンテキストを自動的に注入します。

#!/bin/bash
# ~/.claude/hooks/pre-tool-use/obsidian-context.sh
# Automatically inject vault context before tool execution

TOOL_NAME="$1"
PROMPT="$2"

# Only inject context for code-related tools
case "$TOOL_NAME" in
    Edit|Write|Bash)
        # Query the vault
        CONTEXT=$(python /path/to/retriever.py search "$PROMPT" --limit 3 --max-tokens 1500)
        if [ -n "$CONTEXT" ]; then
            echo "---"
            echo "Relevant vault context:"
            echo "$CONTEXT"
            echo "---"
        fi
        ;;
esac

PostToolUse hook — 重要なツール出力を vault に戻して保存し、将来の検索に使えるようにします。

#!/bin/bash
# ~/.claude/hooks/post-tool-use/capture-insight.sh
# Capture significant outputs to vault (selective)

TOOL_NAME="$1"
OUTPUT="$2"

# Only capture substantial outputs
if [ ${#OUTPUT} -gt 500 ]; then
    python /path/to/capture.py --text "$OUTPUT" --source "claude-code-$TOOL_NAME"
fi

obsidian_bridge.py パターン

bridge モジュールは、hooks や skills から呼び出せる 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/ に新しい note を作成し、incremental reindex をトリガーします。そのため、新しい note はすぐに検索可能になります。

Custom Command パターン

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

Signal scanning。 /scan-intel コマンドは外部ソースをクエリし、個人的な研究関心に照らして findings をスコアリングし、条件を満たす signals を frontmatter 付きの vault notes として書き込みます。

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

このコマンドは、設定済みのソース（arXiv、HN、RSS）から取得し、スコアリングモデル（関連性、実行可能性、深さ、権威性）を適用し、合格した signals をトピック別の vault フォルダーに書き込みます。vault は、自動化された intelligence pipeline の下流の利用先になります。

Captain’s log。 /captains-log コマンドは、すべてのリポジトリにまたがる日次の git 活動を集約し、構造化された journal entry を vault に書き込みます。そこには、行った意思決定、気づき、未解決の話題も含まれます。

/captains-log

このコマンドは GitHub から commit history を取得し、リポジトリ別にグループ化して、物語調の journal entry として整形します。時間が経つにつれて、日次ログは何を出荷したのか、そしてなぜそうしたのかを検索できる記録になります。

Obsidian capture。 /obsidian-capture コマンドは、現在の Claude Code セッションから得た洞察を受け取り、適切な metadata 付きで vault に直接書き込みます。

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

このパターンは、あらゆる vault 操作に拡張できます。MOCs の作成、プロジェクト status notes の更新、関連 signals のリンク、蓄積された日次ログからの週次 digest 生成などです。

Community examples。 実践者たちは、自分たちのコマンドライブラリを公開しています。ある開発者は、daily reviews、project planning、research capture、content workflows をカバーする Obsidian + Claude Code の custom commands 22 個を共有しました。¹ 別の開発者は、コード分析から vault 内に diagram notes を生成する「Visual Explainer」skill を作りました。² コマンドの内容はさまざまですが、アーキテクチャは一貫しています。インターフェースとしての Claude Code skills、保存層としての vault notes、クエリエンジンとしての retrieval infrastructure です。

Context Window 管理

連携では、Claude Code の context window に注意する必要があります。

• 注入するコンテキストは、クエリごとに 1,500〜2,000 tokens に制限します。 これを超えると、エージェントの working memory と競合します。
• 出典情報を含めます。 エージェントが参照元を示せるように、必ずファイルパスとセクション見出しを含めます。
• chunk text を切り詰めます。 長い chunks は完全に省略するのではなく、... を使って切り詰めます。通常、最初の 300〜500 文字に重要な情報が含まれています。
• すべてのツール呼び出しで注入しないでください。 PreToolUse hook は、呼び出されるツールに基づいて選択的にコンテキストを注入するべきです。読み取り操作には vault コンテキストは不要です。Write と Edit 操作では有用です。

Codex CLI 連携

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

MCP 設定

.codex/config.toml または ~/.codex/config.toml に追加します。

[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 は、プロジェクトレベルの instructions として AGENTS.md を読み取ります。vault search のガイダンスを含めます。

## 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 との違い

主な違い: Codex CLI は hooks をサポートしていません。自動コンテキスト注入パターン（PreToolUse hook）は利用できません。代わりに、作業を始める前に vault を検索するようエージェントへ明示的に伝える instructions を 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 統合ほど洗練されてはいませんが、どのツールでも使えます。

構造化ノートによる Prompt Caching

vault 内の構造化ノートは、AI とのやり取り全体で token 使用量を減らす再利用可能な context ブロックとして使えます。このセクションでは、cache key の設計と token budget 管理を扱います。

パターン

毎回のやり取りで context を検索する代わりに、よく構造化された vault ノートから context ブロックを事前に構築し、cache します。

# 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
    },
}

Cache の無効化

Cache の無効化は、2つのシグナルに基づきます。

1. TTL の期限切れ。 各 context ブロックには time-to-live があります。TTL が期限切れになると、vault を再クエリしてブロックを再構築します。
2. Vault の変更検出。 cached context ブロックに寄与したファイルへの変更を indexer が検出すると、そのブロックは即座に無効化されます。

Token Budget 管理

session は、context budget の総量から始まります。cached ブロックは、その budget の一部を消費します。

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)

cached ブロックは session 開始時に読み込まれます。Dynamic search results は、query ごとに残りの budget を埋めます。この hybrid アプローチにより、agent は頻繁に必要になる context の基準値を持ちながら、具体的な query のための budget も保持できます。

Token 使用量の Before/After

Caching なし: 関連する query のたびに vault search が発生し、1,500〜2,000 tokens の context が返ります。1 session で 10 queries 実行すると、agent は vault context として 15,000〜20,000 tokens を消費します。

Caching あり: 事前構築された 3つの context ブロックが合計 4,500 tokens を消費します。追加の search は、unique query ごとに 1,500〜2,000 tokens を追加します。10 queries のうち 6つが cached ブロックでカバーされる場合、agent の消費量は 4,500 + (4 * 1,500) = 10,500 tokens となり、cache なしの場合のおよそ半分です。

Context 圧縮のための PostToolUse Hooks

Tool の出力は、stack trace、file listing、test result など冗長になりがちです。PostToolUse hook を使うと、これらの出力が context window の容量を消費する前に圧縮できます。

問題

test を実行する Bash tool call は、次のような結果を返すことがあります。

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 tokens ありますが、重要な情報は 2行にあります。200 passed、1 failed です。

Hook の実装

#!/bin/bash
# ~/.claude/hooks/post-tool-use/compress-output.sh
# Compress verbose tool outputs to preserve context window

TOOL_NAME="$1"
OUTPUT="$2"
OUTPUT_LEN=${#OUTPUT}

# Only compress large outputs
if [ "$OUTPUT_LEN" -lt 2000 ]; then
    exit 0  # Pass through unchanged
fi

case "$TOOL_NAME" in
    Bash)
        # Compress test output
        if echo "$OUTPUT" | grep -q "PASSED\|FAILED"; then
            PASSED=$(echo "$OUTPUT" | grep -c "PASSED")
            FAILED=$(echo "$OUTPUT" | grep -c "FAILED")
            FAILURES=$(echo "$OUTPUT" | grep "FAILED")
            echo "Tests: $PASSED passed, $FAILED failed"
            if [ "$FAILED" -gt 0 ]; then
                echo "Failures:"
                echo "$FAILURES"
            fi
        fi
        ;;
esac

再帰トリガーの防止

出力を発する compression hook は、ガードしないと自分自身をトリガーしてしまう可能性があります。

# Guard against recursive invocation
if [ -n "$COMPRESS_HOOK_ACTIVE" ]; then
    exit 0
fi
export COMPRESS_HOOK_ACTIVE=1

圧縮ヒューリスティック

Signal Intake と Triage Pipeline

intake layer は、何を vault に入れるかを決めます。curation がなければ、vault にはノイズが蓄積していきます。このセクションでは、signal を domain フォルダーへ振り分ける scoring pipeline を扱います。

Sources

signal は複数の channel から入ってきます。

• RSS feeds: 技術ブログ、security advisories、release notes
• Bookmarks via Web Clipper: 公式の Obsidian Web Clipper extension（Chrome、Firefox、Safari）は、ブラウザー側の capture として最も fidelity の高い intake 経路です。2026年4月の release cycle により、AI workflow で実質的にさらに使いやすくなりました:²²
  • 1.4.0 (Apr 9): Interactive YouTube transcript UI — 動画を pin し、transcript を scrub し、auto-scroll し、現在位置を highlight できます。さらに、1 click capture を直接 Reader mode に送る “Open in Reader” default も追加されました。
  • 1.5.0–1.5.1 (Apr 15): Highlights viewer — vault 全体で capture した highlights を browse、search できます。Reader への fade-in transition。より滑らかな YouTube play/pause。1.5.1 では webpack compilation regression が修正されました。
  • 1.6.0–1.6.2 (Apr 21–23): mobile support を含む Highlighter UX overhaul。Defuddle 0.18 では LinkedIn、Threads、Bluesky、Discourse、Medium 向けの source-specific extractors が追加されました。1.6.2 では Safari embedded-mode clipboard regression が修正されています。 source domain ごとに template を設定し、YouTube transcripts、GitHub READMEs、longform articles が、それぞれ scoring pipeline に適した frontmatter を持つ、わかりやすい名前の note として保存されるようにします。
• Newsletters: email newsletters からの重要な抜粋
• Manual capture: 読書中、会話中、research 中に書いた notes
• Tool output: hooks 経由で capture した重要な AI tool outputs
• iOS Share Extension: Obsidian の iOS アプリ（2026年初頭に更新）には Share Extension が含まれており、Safari、social networks、その他のアプリから Obsidian を開かずに直接 vault へ content を保存できます。¹⁹ これにより、摩擦の少ない mobile intake 経路ができます。Safari から記事を share すると、scoring 可能な vault note として届きます。
• Obsidian CLI: Shell scripts と hooks は、obsidian file create で notes を作成したり、obsidian file append で既存 notes に追記したりできます。desktop 上で automated intake pipelines を実現できます。

Scoring Dimensions

各 signal は 4 つの dimension で scoring されます（それぞれ 0.0 から 1.0）。

Composite Score and Routing

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

Domain Routing

0.55 を超えた signal は、keyword matching と topic classification に基づいて 12 個の domain フォルダーのいずれかへ routing されます。

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

Production Stats

14 か月間の運用結果です。

Knowledge Graph Patterns

Obsidian の wiki-link graph は、notes 間の関係を encode します。このセクションでは、link semantics、context expansion のための graph traversal、graph quality を低下させる anti-patterns を扱います。

Backlink Semantics

すべての wiki-link は、graph 内に directed edge を作ります。Obsidian は forward links と backlinks の両方を追跡します。

• Forward link: Note A contains [[Note B]] → A links to B
• Backlink: Note B shows that Note A references it

graph は、context に応じて異なる種類の関係を encode します。

Maps of Content (MOCs)

MOCs は、関連 notes を navigable な構造に整理する index notes です。

---
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]]

MOCs は 2 つの点で retrieval に役立ちます。

1. Direct match。 “authentication overview” の search は MOC 自体に match し、curated された関連 notes の list を agent に提供します。
2. Context expansion。 特定の note が見つかった後、retriever はその note がどの MOCs に含まれているかを確認し、MOC の構造を results に含められます。これにより、agent はより広い topic の map を得られます。

Graph Traversal for Context Expansion

retriever の将来的な enhancement として、top results を見つけた後に links をたどって context を拡張できます。

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 には実装されていませんが、graph structure の自然な extension といえます。

Anti-Patterns

Orphan clusters。 互いに link しているものの、vault の他の部分とは接続がない notes の group です。Obsidian の graph panel では、これらは切り離された islands として表示されます。Orphan clusters は、MOCs が不足しているか、cross-domain links が不足していることを示します。

Tag sprawl。 tags を一貫性なく使ったり、細かすぎる tags を作りすぎたりすることです。5,000 notes に対して 500 unique tags がある vault では、平均すると 10 tags あたり 1 note です。これでは tags は filtering に役立ちません。domain folders に対応する 20〜50 個の high-level tags に統合しましょう。

Link-heavy, content-light notes。 prose がなく、wiki-links だけで構成される notes です。このような notes は、chunker が embed する text を持たないため、index の品質が低くなります。linked notes がなぜ関連しているのかを説明する context を、少なくとも 1 paragraph 追加してください。

Bidirectional links for everything。 すべての reference に wiki-link が必要なわけではありません。”OAuth” に軽く触れるだけなら、[[OAuth 2.0 Overview]] は不要です。wiki-links は、click したときに有用な context が得られる、意図的で navigable な関係に限定しましょう。

開発者向け 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 が期待どおりか確認します。

変更履歴

参照