Vault Cortex

Vault Cortex は、あらゆる AI エージェントに、Obsidian の保管庫へのハイブリッド検索、タスク管理、構造化メモリ、読み書きアクセスを提供するスタンドアロンの MCP サーバーです。プラグインも、Obsidian の起動も、別個のブリッジも不要です。Docker コンテナ 1 つと保管庫フォルダーだけで、ツール一式とガイド付きプロンプトを利用できます。Obsidian Sync を使ってリモートサーバーで実行すれば、同じ保管庫にスマートフォン、claude.ai、その他のリモート MCP クライアントから、OAuth 2.1 で保護された状態でアクセスできます。ワンクリックでデプロイすることも、セルフホストすることもできます。どちらの場合も、保管庫は常にあなたのものです。

目次 — できること · クイックスタート · 仕組み · ハイブリッド検索 · メモリ · タスク · ファイル · ツール · プロンプト · プロパティ · 設定 · デイリーノート · データの整合性 · 認証 · デプロイ方法 · ワンクリックデプロイ · コミュニティによるデプロイ

得られるもの

Vault を検索	ノートについて推論	Obsidian に書き戻す

3 つのデモはすべて Claude モバイルで動作しています。Vault はスマートフォン上ではなく、リモートサーバー上にあります。

• リモートアクセス — スマートフォン、リモートサーバー、または OAuth 2.1 経由の任意の MCP クライアントから動作します。Render または Railway でワンクリックで導入でき、管理するサーバーは不要です。VPS でも同様に動作します。
• プラグイン不要 — Obsidian が起動している必要はありません。サーバーはディスク上の .md ファイルを直接扱います。ヘッドレス同期により Vault は最新の状態に保たれます。
• ハイブリッド検索 — FTS5 によるキーワードマッチングと、RRF フュージョンによるベクトル意味的類似度を組み合わせ、意図の強いクエリにはクロスエンコーダーによる再ランキングで精度を高めます。キーワードは正確な用語や専門用語に対して精密さを保ち、ベクトルはあなたの言葉が Vault の表現と異なる場合でもノートを見つけ出します。
• 構造化メモリ — 日付付きの追記専用エントリが蓄積され、パーソナルなナレッジレイヤーを形成し、AI パーソナライゼーションのために自動初期化されます。トピックの想起は「X について自分はどう考えているか？」に対して、現在の見解とその背後にある日付付きの履歴を返します — 変化の過程も含めて。
• タスク — Kanban を認識したタスクのクエリと更新：ステータス、日付、優先度でトリアージし、1 回の呼び出しで完了、優先度変更、レーン間の移動を行えます。繰り返しタスクを完了すると、次の発生分が生成されます。Tasks プラグインの絵文字形式と Dataview のインラインフィールド形式の両方を解析します。
• リンクグラフ — Vault 全体にわたるバックリンク、発信リンク、孤立ノートの検出
• ファイル — Vault の非 Markdown ファイルも読み取ります：画像は実際の画像として（必要に応じて収まるよう縮小されて）届き、PDF は構造化テキストまたはレンダリングされたページとして、キャンバスは読みやすいアウトラインとして、データファイルはテキストとして扱われます
• Obsidian ネイティブ — frontmatter、wikilink、タグ、見出し、デイリーノートを理解します
• ガイド付きワークフロー — Vault の健全性、メモリのレビュー、日次の照合のための組み込みプロンプト — 毎回ライブの Vault データから組み立てられます

ヨーロッパを巡る 15 日間の旅行でテスト済み。 スマートフォンからの 30 以上のセッション、216 回のツール呼び出し、ノート PC へのアクセスは一切不要でした。あるセッションでの書き込みは、都市や日をまたいで、次のセッションですぐに利用できました。

クイックスタート

ローカル（2 分 — Docker + お使いの Vault フォルダ）

前提条件: Docker（または Docker 互換のランタイム。例: OrbStack、Colima、Podman）、Node.js >= 22.12（CLI のみで必要 — サーバー自体は Docker で動作します）、そして Obsidian Vault（または .md ファイルが入った任意のフォルダ）。

npx vault-cortex@latest init

以上です — CLI が Vault のパスを尋ね、認証トークンと設定ファイルを生成し、サーバーを起動して、お使いの MCP クライアント用の接続情報を表示します（CLI リファレンス →）。

CLI でセットアップしましたか？ 以降は CLI がサーバーを管理します — configure、upgrade、start、restart、logs、down（CLI リファレンス →）。

Compose でセットアップしましたか？ 更新も Compose で行ってください（docker compose pull && docker compose up -d） — CLI と Compose はそれぞれ独立してコンテナを管理します。

# 1. Get the quickstart files
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/local/.env.example

# 2. Configure
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN (openssl rand -hex 32) and VAULT_PATH

# 3. Start
docker compose up

ローカルセットアップの完全ガイド →（Windows でのセットアップを含む）

リモート（どこからでもアクセス）

サーバー上に Vault を置き、Obsidian Sync で最新の状態に保ち、スマートフォン、claude.ai、または任意の MCP クライアントからアクセスできます。ワンクリックのオプションでは、Vault 名とタイムゾーン（Vault が暗号化されている場合は Vault のパスワードも）を入力するだけで、HTTPS、再起動、生成された MCP トークン、永続ストレージが自動的に設定されます。デプロイ後は、セットアップページの案内に従ってブラウザーで Obsidian Sync にサインインします。自前のサーバーでは、CLI が公開 URL と Vault 名を尋ね、Sync トークンを取得し、MCP トークンを生成します。HTTPS の設定はご自身で行っていただく必要があります。

	Railway	Render	セルフホスト
			CLI でのセットアップ →
アカウント	Railway の Hobby プラン以上 — 5 GB のボリュームが含まれます	カード情報を登録した Render	Docker が使える VPS
コスト	従量課金制: 個人用の Vault で通常月額 $20～30 USD — 静かな Vault なら Render より少し安く、忙しい Vault なら少し高くなります	定額: Standard インスタンス (2 GB) と 5 GB ディスクで月額約 $26 USD、秒単位で請求	VPS の費用次第
こんな場合におすすめ	より簡単な始め方をしたい場合 — テンプレートを使えば設定済みのプロジェクトが立ち上がります	セットアップの洗練よりも予測可能な請求を重視する場合	すでにサーバーを運用している、または完全な制御を求める場合
ガイド	Railway ガイド →	Render ガイド →	リモートガイド →

3 つすべてに Obsidian Sync のサブスクリプションが必要です。どれを選んでも、サーバーは交換可能ですが Vault はそうではありません — Vault は Obsidian Sync とお使いのデバイス上にプレーンな Markdown として残り、コンテナはそのコピーを保持するだけです。

セットアップページ。 Obsidian Sync トークンなしでデプロイすると、サーバーはセットアップモードで起動します。ブラウザーでその URL を開くと /setup のサインインページが表示されます。Obsidian アカウントの認証情報を一度入力してください (二要素認証にも対応) — Obsidian に直接サインインする形になり、サーバーはそのサインインから Sync トークンのみを保持して再起動し、Vault をダウンロードします。

サインインページは MCP トークンで保護されています。各デプロイガイドで一連の流れを順に説明します。

Vault Cortex CLI は、実行する任意の Linux マシン上に同じコンテナをセットアップします — サーバー、イメージ、更新はご自身で管理します。CLI 自体には Node.js >= 22.12 が必要です。サーバーは Docker で動作します。

# On your VPS:
npx vault-cortex@latest init --mode remote

以上です — CLI が公開 URL、Obsidian Sync トークン（get-sync-token を代わりに実行できます）、Vault 名、暗号化された Vault の場合は Vault パスワード、認証設定を順に確認し、その後サーバーを起動します（CLI リファレンス →）。

CLI でセットアップしましたか? 以降は CLI がサーバーを管理します — configure、upgrade、start、restart、logs、down（CLI リファレンス →）。

Compose でセットアップしましたか? 更新も Compose で行ってください（docker compose pull && docker compose up -d）— CLI と Compose はそれぞれ独立してコンテナを管理します。

# On your VPS:
mkdir -p /opt/vault-cortex && cd /opt/vault-cortex
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/docker-compose.yml
curl -O https://raw.githubusercontent.com/aliasunder/vault-cortex/main/deploy/remote/.env.example
cp .env.example .env
# Edit .env — set MCP_AUTH_TOKEN, PUBLIC_URL, VAULT_NAME (OBSIDIAN_AUTH_TOKEN optional — /setup handles it)
docker compose up -d

MCP クライアントを接続する

任意の MCP クライアント — Claude Code、Claude Desktop、Cursor、OpenCode、その他 — にサーバー URL を追加してください。OAuth クライアントはブラウザで同意ページを開きます — トークンで承認すると、以降はクライアントがトークンの更新を処理します。OAuth を使用しないクライアント（MCP Inspector、スクリプト）は、トークンを Authorization: Bearer ヘッダーとして直接送信します。

Claude Code:

claude mcp add --scope user --transport http vault-cortex http://localhost:8000/mcp   # local (or <PUBLIC_URL>/mcp)

--scope user はすべてのプロジェクトに対してサーバーを登録します。省略すると現在のディレクトリのみにスコープされます。

{
  "mcpServers": {
    "vault-cortex": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "http://localhost:8000/mcp",
        "--header",
        "Authorization: Bearer <your MCP_AUTH_TOKEN>"
      ]
    }
  }
}

claude.ai（ウェブおよびモバイル） はリモートセットアップにのみ接続します — そのコネクタはサーバー側で取得されるため、localhost に到達することはできません。

「リモート MCP サーバー」は接続タイプ（HTTP）を指します — ローカルセットアップでも、サーバーは完全にあなたのマシン上で動作します。

両方の方法とトークンの有効期間については、認証を参照してください。

仕組み

すべてが 1 つの Docker コンテナ内で動作し、ディスク上の .md ファイルを直接操作します。

• Vault が信頼できる唯一の情報源であり続けます — サーバーは、お使いの Obsidian アプリと同じプレーンな Markdown ファイルを読み書きします。
• 検索は派生データです — ファイルウォッチャーがノートの変更に合わせてインデックス（キーワード + ベクトル）を最新の状態に保ち、いつでもノートから再構築できます。
• リモートイメージは同期ループを追加します — 同梱の Obsidian Sync サービスが、コンテナの vault をすべてのデバイスと同期させます。スマートフォンでノートを編集すれば、数秒後には検索可能になり、エージェントがノートを書き込めば、それが Obsidian に表示されます。

graph LR
    subgraph container ["One Docker container"]
        Sync["sync service<br/>(remote image)"]
        Vault[("/vault<br/>.md files — source of truth")]
        Index[("search index<br/>keywords + vectors")]
        Server["MCP server"]
        Sync <-->|read/write| Vault
        Vault -->|file watcher| Index
        Server <-->|read/write| Vault
        Server -->|query| Index
    end
    Obsidian["Your Obsidian apps<br/>(phone, laptop)"] <-->|Obsidian Sync| Sync
    Client["Any MCP client<br/>(Claude, Cursor, claude.ai)"] -->|OAuth 2.1 / Bearer| Server

完全な設計、認証フローの図、コンポーネントの内訳については ARCHITECTURE.md を参照してください。

ハイブリッド検索

キーワード検索だけでは、あなたの語彙が vault の語彙と一致しない場合に失敗します。「aspirations」では「targets」に関するノートは見つからず、「coworkers」では「references」ファイルが浮かび上がることはありません。実際の vault に対するテストでは、自然言語クエリの 30% がキーワードだけではゼロ件または的外れな結果を返しました。ハイブリッド検索は、同じテストでそうした取りこぼしを解消しました。

ハイブリッド検索は、キーワードとベクトルのランキングを Reciprocal Rank Fusion で統合し、その後リランカーが統合結果を精緻化します。

• キーワード（FTS5）は、正確な用語、専門用語、プロパティ値に対して精度を保ちます
• ベクトル（sqlite-vec）は、意味に基づいてマッチングすることで語彙のギャップを埋めます
• リランカー（クロスエンコーダー）は、各クエリとドキュメントのペアを同時にスコアリングして順序を精緻化します — キーワードとベクトルの両方が取りこぼす意図の強いクエリを救済します

すべてのモデルはローカルで動作します（合計約 45MB、外部 API 不要）。キーワードのみの検索にするには EMBEDDING_ENABLED=false を、レイテンシを下げるためにリランキングをスキップするには RERANK_MODE=none を設定してください。

モデルの詳細、ブレンドの重み、パイプライン全体の内訳については ARCHITECTURE.md → ハイブリッド検索 を参照してください。

メモリ

増え続けるだけのメモリレイヤーは、エージェントが毎回すべてを読み返すことなく適切なエントリを取得できる場合にのみ役立ちます。複数のファイルにわたって何百もの日付付きエントリ（好み、原則、コミュニケーションスタイル、進行中のコミットメント）があると、ファイル全体を読むと無関係な情報の中にシグナルが埋もれてしまいます。メモリシステムは、狙いを定めた取得のために設計されています。

このレイヤーは、トピックの見出しの下に日付付きエントリを保持するプレーンな Markdown ファイルのフォルダ（デフォルト: About Me/）です — 初回実行時にスターターテンプレートで自動作成され、エージェントが vault_update_memory を通じて育てていきます。3 つの特性がこれを機能させます。

• 追記のみ — エントリが上書きされることはありません。修正は新しい日付付きエントリとして追加されます。このレイヤーは、あなたの現在の状態 および その背後にある変遷を捉える個人のナレッジベースになります
• トピックの想起 — vault_memory_recall は、すべてのメモリファイルにわたる関連するすべてのエントリを、キーワードと意味の両方でマッチングし、古い順に一度に取得します。「X について自分はどう考えているか?」と尋ねれば、現在の見解とそれがどのように発展してきたかの日付付き履歴が得られます — ファイル全体を読んだり、どのファイルに何が入っているかを推測したりする必要はありません
• 劣化せずに成長 — 結果を上限で制限する（limit）と、最も関連性の低いエントリが除外され、タイムラインの一部が切り捨てられることはありません。500 件のエントリを持つメモリレイヤーは、50 件のものと同様に狙いを定めたクエリに対応します

何が真実であったかではなく、何が現在であるかを記述するファイル（ルーティン、進行中のコミットメント）は、frontmatter で entry-policy: living を宣言できます — それらの期限切れエントリは保持されるのではなく削除可能になり、現在の状態の描写が正確に保たれます。

このレイヤー全体はオプションです — MEMORY_ENABLED=false を設定すると、メモリツールが非表示になり、フォルダの自動作成も完全にスキップされます。

想起パイプライン、インデックスモデル、自動初期化、オプトアウトの動作については ARCHITECTURE.md → メモリ を、ファイル形式、entry-policy の規約、スターターテンプレートについては templates/memory を参照してください。

タスク

タスクのメタデータはプレーンな Markdown として存在します — ファイルに散在し、絵文字シグニファイアやインラインフィールドでエンコードされ、Kanban の見出しの下に整理されています。「何が期限切れ？」と答えるエージェントは、すべてのファイルを解析し、あなたが選んだフォーマットを理解する必要があります。Kanban ボード上でタスクを完了するには、ボードのレーン構造、日付の構文、どの見出しが完了レーンなのかを知る必要があります。

タスクレイヤーは、エージェントがそれをしなくて済むように処理します:

• 検索 — ステータス、6 つの日付フィールド（期限、予定、開始、作成、完了、キャンセル）、優先度、フォルダ、または Kanban レーンでフィルタリングします。各結果にはノートのパス、行番号、およびタスクが何らかの見出しの下にある場合は最も近い見出し（Kanban ボード上のレーン）が含まれるため、タスクの位置を特定するための追加の読み取りは不要です
• 作成 — 正しくフォーマットされたタスクを 1 ステップで追加します: 説明、優先度、日付、繰り返し、「完了時」アクション、依存関係、ブロック ID（^id）、およびチェックリストのサブ項目（テキストのみ、日付なし）。見出しの下の先頭、末尾、または正確な位置に配置したり、親タスクの下に独自の日付を持つサブタスクとしてネストしたりできます。Kanban ボード上では、Kanban プラグインがボードを保存するときにサブタスクをカードにコピーするため、サブタスクにはブロック ID が付与されません
• 更新 — 完了、優先度の変更、テキストの編集、日付の設定またはクリア、繰り返し、「完了時」アクションの設定、チェックリスト項目の追加、見出し間のタスクの移動、およびレーン内での並べ替えを 1 回の呼び出しで行います
• 完了 — タスクを完了としてマークすると、完了レーンが自動検出され、完了日が記録されます。これはプラグインの「完了日を設定」設定に従います。元に戻すと日付が削除されます。完了時には Tasks プラグイン自体の動作も実行されます:
  • 繰り返しタスクは次の発生を生成し、日付はプラグインが計算する方法で進められます
  • 「完了時」に削除するよう設定されたタスクはノートから消えます
• 両方のフォーマット — どちらのフォーマットを使用しても、Tasks プラグインの絵文字シグニファイアでも Dataviewのインラインフィールドでも、サーバーは両方を読み取り、あなたの Tasks プラグインが設定されているフォーマットで書き込みます — ボールトが .obsidian/ を同期する場合はプラグインの設定から読み取り、それ以外の場合はデフォルトとして絵文字シグニファイアを使用します

インデックスモデル、日付カスケードソート、および Kanban レーン検出については、ARCHITECTURE.md → Tasks を参照してください。

ファイル

ノートにはスクリーンショットが埋め込まれ、アーキテクチャ図が参照され、キャンバスやデータファイルへリンクされています。しかし、Markdown を読むエージェントにとって、![[diagram.png]] は単なるテキストにすぎません。Vault Cortex はファイルを、Vault の周りにある雑多なものではなく、Vault の一部として扱います — リンクされ、サイズが調整され、読み取り可能で、それぞれがエージェントにとって使える形式です:

• 画像 — ファイル名ではなく、画像そのもの。スクリーンショットや図は、MCP クライアントが受け入れるサイズを超えるとサーバー側で縮小および再圧縮されるため、スマートフォンのセッションでも 5MB のアーキテクチャ図を見ることができます
• キャンバス — Canvas ボードは読み取り可能なアウトラインとして提供されます: そのグループ、各カードの内容が読み取り順に、そしてそれらの間の接続です。キャンバスの内容は全文検索可能で、ボード上のファイル参照はリンクグラフに現れます — バックリンクとアウトゴーイングリンクは、ノート間リンクとまったく同じように機能します。完全な忠実性が重要な場合は、正確な JSON ソースが 1 つのフラグで取得できます
• PDF — テキストは見出しの階層、コードブロック、ハイパーリンクを保持したまま抽出されます; PDF の内容はノートと並んで全文検索可能です。代わりにページを画像としてレンダリングするには raw: true を設定すると、テキスト抽出では保持できないレイアウト、図、表が表示されます — スキャンされた PDF や画像のみの PDF もこのモードで動作します
• テキストおよびデータファイル — TXT、SVG、JSON、XML、CSV、YAML、ログ、および Bases ファイルは書かれたとおりにそのまま返されます; 内容の最初の 100 KB が全文検索可能です。大きなデータファイルやログは一度に 1 行範囲ずつ読み取ることができ、各ページが現在位置と残りのファイル量を報告します
• 参照 — 任意の表示可能なフォルダーのファイルを、拡張子ごとの件数とファイルサイズとともに一覧表示します; ノートがリンクしているファイルも、リンクグラフでそのサイズを報告します

ファイルツールを非表示にするには FILE_TOOLS_ENABLED=false を設定します — リモート Vault が添付ファイルなしで同期される場合に便利です。

画像パイプラインとディスパッチモデルについては ARCHITECTURE.md → Files を参照してください。

ツール

プロンプト

ツールはモデル主導です — アシスタントがそれらを呼び出します。プロンプトは、_あなた_が起動するワークフローです。それぞれが呼び出し時に検索インデックス、リンクグラフ、メモリレイヤーを照会し、その結果をガイド付きの指示とともに組み立てます — こうしてセッションは、前提ではなく、あなたの保管庫の実際の状態に基づいて始まります。

プロンプトはあなたの設定（MEMORY_DIR、デイリーノートの設定）に適応し、どの保管庫でもすぐに機能します。クライアントにペイロードの上限がある場合は、max_chars を渡して埋め込むコンテンツを制限してください。

クライアント対応: プロンプトは Claude Desktop（Chat と Cowork — コネクターの下の + メニューから）、Claude Code（スラッシュコマンド）、OpenCode で動作します。その他のクライアント（Cursor、Windsurf）での対応はさまざまです — 最新情報は MCP クライアント一覧 をご覧ください。

プロパティ

Vault Cortex はノート内のすべてのプロパティをインデックスしますが、5 つだけは昇格された扱いを受けます — 高速なフィルタリングのための専用カラムを持ち、すべての検索およびディスカバリー結果においてトップレベルのフィールドになります。

その他すべてのプロパティも引き続き完全にクエリ可能です — テキストとメタデータを組み合わせたクエリには filters.properties を指定した vault_search を、メタデータのみの検索には vault_search_by_property を使用してください。vault_list_property_keys と vault_list_property_values は、Vault 全体にどのようなプロパティが存在するかを発見できます。

これらは規約であり、要件ではありません — Vault Cortex はどのようなプロパティスキーマでも動作します。昇格されたプロパティは、すぐに使えるより豊かなフィルタリングとよりクリーンな結果を提供します。

先頭のコールアウトも同じ扱いを受けます。ノートの最初の本文コンテンツが Obsidian のコールアウト(> [!type])である場合 — フロントマターの直後か、タイトル見出しの直後のいずれか — それはインデックスされ、すべてのディスカバリー結果とともに表示されます(vault_search では、include_leading_callout で要求できます)。これによりノートは自己記述的になります。結果をスキャンするエージェントは、どのノートを読むかを決める前に、各ノートが何の_ためのもの_かを確認できます。メモリテンプレートはこのために > [!info] Scope of this file コールアウトを使用しており、Vault 内のどのノートでも同じパターンを使用できます。

設定

すべての設定は、適切なデフォルト値を持つ環境変数です。一部のデフォルト値は他の設定から導出されます — Default 列に各導出が示されており、設定した値は導出されたデフォルト全体を置き換えます。リモートデプロイでは、Obsidian Sync 自身の設定 — DEVICE_NAME、SYNC_MODE、CONFLICT_STRATEGY、SYNC_CONFIGS、SYNC_EXCLUDED_FOLDERS、SYNC_FILE_TYPES — も転送されます。これらはリモートガイドの設定テーブルに記載されています。

デイリーノート

vault_get_daily_note とデイリーレビュープロンプトは、Obsidian の .obsidian/daily-notes.json から読み取ったフォルダーとファイル名の日付形式の設定を使って、デイリーノートを検索します。

• ローカルモードでは、バインドマウントされた Vault からファイルを直接読み取るため、設定は不要です。
• リモートモードでは、Obsidian Sync の Vault 設定同期を通じて受け取ります。サーバーはデフォルトで取得します（.env の SYNC_CONFIGS 設定）が、各デバイスからも送信する必要があります。各デバイスで Obsidian の「設定」→「Sync」→ Vault 設定の同期を有効にしてください。詳細は、リモートガイドの「デイリーノート」セクションをご覧ください。

ファイルが利用できない場合、または daily-notes.json に設定が保存されない Periodic Notes プラグインを使用している場合は、値を手動で設定してください。

• DAILY_NOTES_FOLDER — Vault からの相対パスを指定します。Journal、Planner/Daily、または Vault のルートを表す / を指定できます。
• DAILY_NOTES_FORMAT — Obsidian の日付形式設定と同じトークンを指定します。YYYY-MM-DD-dddd、YYYY/MM/DD、MMM D, YYYY、…

片方または両方を設定できます。設定した値は常に設定ファイルより優先されます。設定しなかった値は daily-notes.json から取得されます。そのファイルが存在しないか読み取れない場合、サーバーは Daily Notes と YYYY-MM-DD を使用します。

• Obsidian での変更は、サーバーの Vault で .obsidian/daily-notes.json が利用可能な場合、次回の呼び出しから反映されます。
• 環境変数の変更は、CLI の restart コマンドを実行するか、Compose コンテナを再作成するか、ホスティングプラットフォームに再デプロイして適用してください。
• Obsidian の「デイリーノート」オプションでフォルダーを空欄にすると、サーバーは .obsidian/app.json から読み取った Obsidian の 新しいノートのデフォルトの場所（「設定」→「ファイルとリンク」）に従います。Obsidian は開いているノートを基準にせずにデイリーノートを作成するため、現在のファイルと同じフォルダーは Vault のルートとして扱われます。app.json がサーバーの Vault にない場合（リモートモードで メイン設定が同期されるまでなど）、サーバーは Vault のルートを使用します。
• デイリーノートが Vault のルートにある場合、またはフォルダー設定が空欄のため新しいノートのフォルダーにある場合、削除と移動の操作では保護されず、孤立ノートの結果に含まれる可能性があります。そのフォルダーを保護または除外すると、その中の他のすべてのノートにも適用されます。

注: 一部の日付形式トークンはサポートされていません。序数（Do、Mo、DDDo、wo）、dd（2 文字の曜日）、d（曜日番号）、e、k/kk、w（週番号）、Q（四半期）、Z/ZZ（UTC オフセット）、およびローカライズ形式（L～LLLL、LT、LTS）です。これらのトークンを使ったファイル名をサーバーで再現できないため、ノートを検索できません。形式にこれらのいずれかが含まれている場合、vault_get_daily_note は明確なエラーを返します。Obsidian で形式を変更するか、DAILY_NOTES_FORMAT にサポートされている別の形式を設定してください。

データの整合性

Vault Cortex は個人用ノートに書き込むため、ファイル安全層はエラーを防ぐだけでなく、破損を防ぐように設計されています。

• アトミックな書き込み — ファイルへの書き込みはすべて一時ファイルにステージングしてから名前を変更します。読み取り側に途中までのノートや 0 バイトのノートが見えることはありません。排他的な作成には link()（POSIX の上書き禁止）を使用し、ノートの移動時に TOCTOU が発生する隙間を塞ぎます。
• ファイルごとのミューテックス — MCP ツール呼び出しが同時に行われた場合、ファイルごとに直列化するか、即座に失敗します。移動では、ソース、宛先、およびすべてのバックリンク元をひとまとまりとしてロックします。
• 本文の編集ではプロパティを記述どおりに維持 — ノートの本文を編集しても、プロパティ（Obsidian が「プロパティ」として表示する --- ブロック）はコメントも含め、元のまま維持されます。
• 維持できない場合はプロパティの書き換えを拒否 — vault_update_properties、vault_write_note による上書き、タスクツール、およびブロック内のリンクを変更する移動では、ブロックを書き換えます。すべてのプロパティと値は維持されますが、YAML コメントは削除され、書式が変わることがあります。ブロックが無効な YAML である場合、key: value 形式のプロパティではなくリストまたは単一の値である場合、あるいは !!str などの明示的なタグが付いた値を含む場合、書き換えを拒否し、ノートは変更されません。エラーには修復方法が示されます。
• プロパティが壊れたノートも引き続き利用可能 — 検索では、プロパティが無効な YAML のノートを、Obsidian と同様にプロパティなしとして扱います。ノートは検索結果やタスクリストに引き続き表示され、本文内のリンクはバックリンクとしてカウントされます。また、ブロックを記述どおりに維持したまま、読み取り、編集、移動ができます。サーバーログには修復が必要であることが記録されます。
• パストラバーサルをブロック — resolveSafePath() は各パスを解決してから、プレフィックスを照合します。正規化後に保護対象パスを削除しようとすると拒否されます。メモリファイル名には、境界で区切り文字を含められないようにしています。
• 隠しパスへのアクセスを禁止 — ドットで始まるファイルやフォルダー（.obsidian/、.trash/）は一覧や検索に表示されず、これらを直接対象とするツール呼び出しも Obsidian と同様に拒否されます。プラグイン設定とその API キーにはアクセスできません。
• 削除時は Obsidian のゴミ箱設定に従う — 「削除されたファイル」の設定が Obsidian のデフォルトである「システムゴミ箱に移動」または「Obsidian のゴミ箱に移動」の場合、削除したノートは削除されず、Vault 内の .trash/ に移動します（コンテナにはシステムゴミ箱がないため、Obsidian 独自の代替手段として .trash/ を使用します）。「完全に削除」すると、ノートは完全に削除されます。
• Obsidian Sync のデプロイでは完全に削除 — 削除はすべてのデバイスに同期され、復元にはゴミ箱フォルダーではなく Sync のバージョン履歴を使用します。
• 保持期間後に整理する上限付きゴミ箱 — システムのデフォルト設定でサーバーが .trash/ に移動したノートは、TRASH_RETENTION_DAYS（デフォルトは 30 日。none の場合は永久に保持）の日数が経過すると整理されます。整理対象はサーバーが記録したファイルだけです。Obsidian 自身がゴミ箱に移動したノートや、「Obsidian のゴミ箱に移動」設定による削除には触れません。
• インジェクションの防止 — 検索クエリはパラメーター化され、FTS5 用にサニタイズされます。プロンプトの内容は XML データマーカーで囲み、終了タグをエスケープすることで、タグの突破を利用したインジェクションを防ぎます。
• コンテナの強化 — 非 root ユーザー、PID 1 の init、ランタイムイメージにパッケージマネージャーを含めないこと、ダイジェストを固定したベースイメージ、正常なシャットダウンを採用しています。
• 読み取り専用モード — READONLY_MODE=true にすると、Vault を編集するすべてのツールが非表示になります。そのため、接続したクライアントは読み取りや検索はできますが、ノートを変更することはできません。

仕組みの詳細については、ARCHITECTURE.md → データの整合性を、サーバーの各部分をどのように強化しているかについては、SECURITY.md → ランタイムの強化を参照してください。

認証

個人ノートへの読み書きアクセス権を持つサーバーにとって、認証は任意ではありません。Vault Cortex は PKCE とリフレッシュトークンのローテーションを含む OAuth 2.1 仕様のすべてを実装しています。AWS (SST) デプロイでは多層防御を追加しています。リクエストは 2 つの独立したレイヤー（API Gateway Lambda オーソライザー + Express ミドルウェア）で検証されます。BlueRock の 2026 年 MCP セキュリティ分析によると、OAuth を実装している MCP サーバーはわずか 8.5% で、41% は認証がまったくありません。

2 つの方法があります:

方法はお使いのクライアントによって決まります。対応していれば OAuth、そうでなければヘッダーに生のトークンを指定します（MCP クライアントの接続では両方を示しています）。

OAuth は動的クライアント登録を使用するため、手動でのクライアント ID やシークレットは不要です:

1. クライアントは自動的に登録され、クライアント ID とシークレットを受け取ります。
2. ブラウザーの同意ページで MCP_AUTH_TOKEN を入力し、アクセスを承認します。
3. クライアントは以降のトークンリクエストに発行されたシークレットを自動的に含めます。

リフレッシュトークンには 60 日間のスライド式有効期限があります。アクセストークンはサーバーの URL に紐付けられるため、あるデプロイメント用に発行されたトークンが別のデプロイメントで受け入れられることはありません。MCP_AUTH_TOKEN をローテーションするとすべてのセッションが終了し、各クライアントは同意ページを通じて再認証します。

フローの全体図については ARCHITECTURE.md → Auth を参照してください。

デプロイ方法

ローカルではお使いのマシン上で実行します。リモートデプロイではVPSまたはホスト型コンテナプラットフォームで実行するため、ノートパソコンを閉じていてもボルトにアクセスできます。

どの方法を選んでも、サーバーは交換可能ですが、ボルトはそのまま残ります。ノートはプレーンなMarkdownファイルで、Obsidianによってお使いのすべてのデバイスに同期されます。コンテナにはそのコピーと、最初から再構築できるインデックスが保存されます。VPSを停止したり、RenderやRailwayのサービスを削除したり、ホストを切り替えたりしても、同じファイルがお使いのマシンとObsidian Syncに残り、どのツールからでも読み取れます。これは、実体の保存場所がベンダーのデータベースであるAIノートブックとの違いです。ここでは、ホストは利便性のためのものであり、保管者ではありません。

AWSの方法には、このリポジトリ向けに構築されたCI/CDワークフローが含まれています。フォークした場合は、デプロイ前に各自の認証情報とステージを設定する必要があります。

どの方法でも同じイメージ ghcr.io/aliasunder/vault-cortex を使用します。:latest はMCPサーバー単体（ローカル用）で、:remote は s6-overlay の監視下でObsidian Syncを同じコンテナにまとめたもの（ワンクリック、セルフホスト、AWS用）です。コンテナは1つなので、どのOCIランタイムでも動作します。docker run、Podman、nerdctlを使えます。Docker Composeは任意です。

Docker Hubでも公開中： 同じイメージがaliasunder/vault-cortexにもミラーされています。プライマリソースはGHCRで、Hubのタグは同一です。

費用： リモート環境にはVPSまたはホスト型プラットフォームのプランに加え、Obsidian Syncの月額4米ドルが必要です。一般的なボルトであれば、2 GiBのインスタンスでセマンティック検索を十分に利用できます。4 GiBなら、検索の同時実行や大規模なボルトに対応する余裕が生まれます。さらに規模を小さくする場合は、セマンティック検索を完全に無効にしてください。ローカルのみなら無料です。AWSのリファレンスデプロイは、すべて込みで月額約17～29米ドルです。

複数のボルトを使いますか？ 各ボルトはそれぞれ独立したインストールとして実行され、専用のコンテナ、データ、コネクターを持ちます。お使いのマシンまたはサーバーでは、各インストールに固有の名前を付けてください。ローカルおよびリモートガイドの複数のボルトを実行するをご覧ください。RenderまたはRailwayでは、ボルトごとに別のサービスをデプロイしてください。

ワンクリックデプロイ

ボタンと前提条件はクイックスタート → リモートアクセスに記載されています。各ガイドでは、デプロイ手順、URLとトークンの確認方法、更新方法、削除方法を説明しています。deploy/render/（リポジトリのルートにあるrender.yaml Blueprintを使用） · deploy/railway/（公開済みテンプレートを使用）。

コミュニティによるデプロイ

コミュニティが作成・保守するデプロイテンプレートです。ここではテストされておらず、リリースより遅れている場合があります。

• vault-cortex-aca — @flytzen による Azure Container Apps 向け Bicep テンプレートです。Container Apps のイングレス経由で :remote イメージを実行し、無料のマネージド HTTPS を利用します。ストレージは意図的にエフェメラルにしてあり、Obsidian Sync を信頼できる唯一の情報源としています。

別のプラットフォーム向けにデプロイを作成した場合は、PR を送って追加してください。

開発

# Run locally with hot reload
PUBLIC_URL=http://localhost:8000 MCP_AUTH_TOKEN=local-dev-token VAULT_PATH=~/Vault npm run dev:mcp

# Tests
npm test

# Full check suite
npm run prettier:check && npm run lint && npm run markdownlint && npm run lint:shell && npm run knip && npm test && npm run build

npm test には、実際のサーバーを起動して HTTP 経由ですべてのツールとプロンプトを呼び出す統合テストが含まれています。認証の適用、設定によって有効化されるツールの範囲、書き込み変更の整合性（書き込みのたびに読み戻して確認）、誤った設定での起動拒否を検証します。セキュリティに関するテスト範囲については、SECURITY.md をご覧ください。

MCP Inspector — ツールをテストするための対話型ブラウザー UI：

# Start server (terminal 1), then:
npx @modelcontextprotocol/inspector
# Enter http://localhost:8000/mcp as URL, local-dev-token as Bearer token

開発環境の完全なセットアップについては、CONTRIBUTING.md をご覧ください。

関連ツール：obsidian-vault スキル

MCP サーバーは、どのクライアントでも単独で動作します。スキルに対応するエージェント（Claude Code、Cursor、Windsurf、Cline、その他70 以上）では、obsidian-vault スキルにより、Obsidian 形式の Markdown に関する詳しい知識を追加できます。フロントマターの慣習、コールアウト構文、Dataview、Tasks、Kanban などのプラグイン固有の形式が含まれます。

npx skills add aliasunder/agent-skills --skill obsidian-vault

スキルのソース →

ロードマップ

予定している作業、検討中の内容、明確な対象外項目については、 ROADMAP.md をご覧ください。

謝辞

Obsidian の同期には obsidian-headless を使用しています。コンテナ化の方法は、@Belphemur の obsidian-headless-sync-docker を参考にしています。:remote イメージの s6-overlay による監視の仕組みは、このプロジェクトの保守されているフォークから取り込まれ、現在はこのリポジトリに含まれています。

ハイブリッド検索パイプラインは、@tobi の qmd の手法を参考にしています。ランクボーナス付きの RRF 融合、クロスエンコーダーによる再ランキングのための位置を考慮したスコアのブレンド、コンテンツハッシュによる判定、見出しを考慮したチャンク分割が含まれます。

貢献

開発環境のセットアップ、コードの規約、PR のガイドラインについては、CONTRIBUTING.md をご覧ください。

ライセンス

MIT

:remote イメージには、obsidian-headless（ob CLI）がバンドルされています。これはプロプライエタリであり、その package.json では "license": "UNLICENSED" と宣言されています （© Dynalist Inc. / Obsidian）。ビルド時に公開 npm からインストールされます。この MIT ライセンスはこれを対象とせず、使用には有効な Obsidian Sync サブスクリプションが必要です。:latest （ローカル）イメージには、プロプライエタリなコンポーネントは含まれていません。

セキュリティ

脆弱性は非公開で報告してください。SECURITY.md をご覧ください。