freshvault

freshvault

한국어 · 日本語

あなたの Obsidian vault は Claude のメモリです。常に最新で、常にローカルにあります。

ほかの vault 検索 MCP は、インデックスコマンドの再実行や、監視用ターミナルの管理、Web UI での「Update Index」のクリックを求めます。freshvault は MCP サーバー内で vault を監視します。ノートを編集すれば、数秒後には Claude に反映されます。自動で、いつまでも。

• 🔄 再インデックス不要 — ファイルウォッチャーはサーバープロセス内で動作し、起動時の同期処理でオフライン中の編集も反映します
• 🔒 100% ローカル — Ollama（bge-m3）で埋め込みを生成し、ノートが端末の外に出ることはありません
• 🌏 デフォルトで多言語対応 — bge-m3 は、英語のみを前提とするデフォルト設定では対応できない韓国語、日本語、その他 100 以上の言語を扱えます
• 🎯 ベンチマークに基づく検索 — 無条件の BM25 融合では韓国語の言い換えクエリの精度が大幅に低下したため（82.5% → 47.5%）、無効にしています。一方、純粋な密ベクトル検索では識別子クエリをまったく捉えられなかったため（57.1%）、こちらも廃止していません。字句スコアリングは コード形式のクエリトークンがある場合に限定 しています。言い換え：82.5% → 82.5%（同一）、識別子：57.1% → 100% — 検証データ
• 🪶 ベクトル DB、Docker、Python 不要 — JSON メタデータと Float32 サイドカー、素の Node だけで構成され、コードは一読で把握できます
• 🧠 文を尊重したチャンク分割 — YAML フロントマターを除去し、段落や文の境界で分割します（CJK 対応）

インストール

前提条件：Node 20+ と Ollama。

npx -y freshvault setup

これだけです。ウィザードが Obsidian vault を検出し、埋め込みモデルを取得してインデックスを構築し、Claude Code に登録します。手順 2 はありません。今後もありません。再実行する index コマンドも、watch ターミナルも、バックグラウンドサービスも不要です。

{
  "mcpServers": {
    "freshvault": {
      "command": "npx",
      "args": ["-y", "freshvault", "serve"],
      "env": { "FRESHVAULT_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

claude mcp add freshvault -s user -- npx -y freshvault serve

使い方

ノートについて Claude に尋ねるだけです。

「キャッシュ削除の戦略について書いたノートを検索して」

3 つのツールを利用できます。すべて読み取り専用です。

競合サービスでは設定や有料プランが必要な範囲指定クエリも、ここではクエリごとに利用できます。

「#project タグが付いていて、6 月以降に更新されたノートから、予算に関する議論を検索して」

仕組み

Obsidian vault ──fs.watch──▶ freshvault MCP server ──search_notes──▶ Claude
   (.md files)               (chunks → bge-m3 embeddings              (generation)
                              → one JSON index, incremental)

• 差分更新：変更または削除されたノートのみを再度埋め込みます（mtime とサイズの差分を確認）。4 秒間のデバウンスを行います
• 安全対策：60 秒ごとの mtime スキャンで、監視機能が見逃したイベント（ネットワークドライブ、アトミックリネームを行うエディター）を検出します
• 複数クライアントで安全：最初に起動したサーバープロセスが書き込み担当になります（ハートビート付きロック）。ほかのプロセスは読み取り専用となり、ホットリロードを行い、書き込み担当が停止した場合は自ら昇格します
• トランザクション対応：インデックス作成中に埋め込みサーバーが停止しても、ノートが失われたり破損したりすることはありません
• スケーラビリティ：ベクトルはパック形式の Float32 サイドカーファイルに保存されます（起動が速く、コンパクトです）。数千のチャンクに対する総当たりコサイン検索は数ミリ秒です。正直に言うと、検索は依然として線形です。数万のチャンクでも 100 ミリ秒未満ですが、大規模なコーパス向けのベクトル DB の代替ではありません

複数の Vault

Vault ごとにサーバーを 1 つ登録してください。インデックスファイルは Vault ごとに自動的に保持されます。

claude mcp add work-vault -s user -e FRESHVAULT_VAULT=/path/to/work -- npx -y freshvault serve
claude mcp add personal-vault -s user -e FRESHVAULT_VAULT=/path/to/personal -- npx -y freshvault serve

その他の埋め込みサーバー（LM Studio、LiteLLM、OpenAI 互換）

FRESHVAULT_EMBED_API=openai FRESHVAULT_EMBED_URL=http://localhost:1234 npx -y freshvault serve

/v1/embeddings に対応するものなら使用できます。認証が必要なエンドポイントには FRESHVAULT_EMBED_KEY を指定します（設定ファイルには書き込まれません）。

設定

setup の後は、設定なしですべての機能を利用できます。必要に応じて上書きしてください。

コマンド：setup · serve（デフォルト）· index（手動実行用）· status

除外パターン

パターンは gitignore のセマンティクスに従い、Vault からの相対パスと照合されます。

• 末尾以外のどこかにスラッシュがある場合、パターンは Vault ルートに固定されます。末尾のスラッシュは「ディレクトリ」を意味するだけで、ルートには固定されません。
• * と ? は / をまたぎません。** がディレクトリをまたぐのは、パスセグメント全体として使われた場合のみです（**/x、x/**、x/**/y）。git と同様、セグメント内に連結すると単一の * に縮約されます。
• 一致はセグメント境界で終了します。Templates が TemplatesOld に一致することはありません。
• ! による否定と文字クラスには対応していません。このようなパターンは何にも一致しません。
• FRESHVAULT_IGNORE はカンマ区切りのため、パターンにカンマを含めることはできません。

v0.3.0 からの動作変更。 v0.3.0 では、末尾のスラッシュがルートへの固定として扱われていたため、Templates/ は Vault 直下の Templates/ のみを除外し、下層にあるものはすべて警告なくインデックスに含めていました。つまり、気づかないうちにインデックスが汚染されていました。現在は Templates/、/Templates、**/x、a/**/b のようなパターンで、以前より多くの対象が除外されます（以前は /Templates は何にも一致しませんでした）。逆に、セグメント内に連結された **（Daily**md）は / をまたがなくなりました。アップグレード後に freshvault status を実行し、必要に応じて除外数を比較してください。

ベンチマーク

2つの検索マイクロベンチマークをリポジトリに同梱しています（node scripts/bench.mjs）：ko-bench（韓国語のメモ30件、言い換えクエリ40件）とid-bench（技術メモ38件、識別子クエリ14件）です。どちらも3つのスコアリングモード（dense、hybrid-always、同梱のゲートモード）で実行され、スクリプト自体が非回帰の条件を確認します。結果と、bge-m3-ko（top-1 85.0％、634MB）のインポートガイドはdocs/ko-bench.mdにあります。

ロードマップ

• ワンクリックでClaude DesktopにインストールできるMCPBバンドル
• 大規模な保管庫向けの再ランキング処理
• インデックス作成時のPDFテキスト抽出

ライセンス

MIT © Kioko Lab