rag-vault

RAG Vault

あなたのドキュメント。あなたのマシン。あなたの管理。

RAG Vault を使うと、AI コーディングアシスタントから、API 仕様書、研究論文、社内ドキュメントなどのプライベートなドキュメントを検索できます。すべての処理はローカルで行われ、リモート URL からコンテンツを取り込む場合を除き、データはマシン上に保持されます。

実行するコマンドは 1 つだけで、設定は最小限。プライバシーはデフォルトで保護されます。

RAG Vault を選ぶ理由

セキュリティ

RAG Vault にはセキュリティ機能が組み込まれています。

• API 認証：RAG_API_KEY による任意の API キー認証
• レート制限：リクエストを制限できます
• CORS 制御：許可するオリジンを制限できます
• セキュリティヘッダー：Helmet.js による保護

詳しくは SECURITY.md をご覧ください。

初回セットアップのチェックリスト

MCP の設定を追加する前に：

1. Node.js 20 以降をインストールします。
2. ドキュメントのディレクトリを選び、BASE_DIR にそのパスを設定します。
3. AI ツールのプロセスから BASE_DIR を読み取れることを確認します。
4. 設定を編集した後、AI ツールを再起動します。

すぐに始める

Cursor の場合

~/.cursor/mcp.json に追加します：

{
  "mcpServers": {
    "local-rag": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:RobThePCGuy/rag-vault"],
      "env": {
        "BASE_DIR": "/path/to/your/documents"
      }
    }
  }
}

/path/to/your/documents を実際の絶対パスに置き換えてください。

Claude Code の場合

プロジェクトディレクトリの .mcp.json に追加します：

{
  "mcpServers": {
    "local-rag": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:RobThePCGuy/rag-vault"],
      "env": {
        "BASE_DIR": "./documents",
        "DB_PATH": "./documents/.rag-db",
        "CACHE_DIR": "./.cache",
        "RAG_EMBEDDING_DEVICE": "cpu",
        "RAG_HYBRID_WEIGHT": "0.6",
        "RAG_GROUPING": "related"
      }
    }
  }
}

または、CLI からインラインで追加します：

claude mcp add local-rag --scope user --env BASE_DIR=/path/to/your/documents -- npx -y github:RobThePCGuy/rag-vault

Codex の場合

~/.codex/config.toml に追加します：

[mcp_servers.local-rag]
command = "npx"
args = ["-y", "github:RobThePCGuy/rag-vault"]

[mcp_servers.local-rag.env]
BASE_DIR = "/path/to/your/documents"

スキルをインストールする（任意）

AI がより適切なクエリを作成し、結果を正しく解釈できるようにするには、RAG Vault のスキルをインストールします：

# Claude Code (project-level - recommended for team projects)
npx github:RobThePCGuy/rag-vault skills install --claude-code

# Claude Code (user-level - available in all projects)
npx github:RobThePCGuy/rag-vault skills install --claude-code --global

# Codex (user-level)
npx github:RobThePCGuy/rag-vault skills install --codex

# Custom location
npx github:RobThePCGuy/rag-vault skills install --path /your/custom/path

スキルでは、Claude に以下のベストプラクティスを教えます：

• クエリの作成と拡張の方法
• スコアの解釈。boost モードでは、0.3 未満は良好な一致を示し、0.5 を超える結果はスキップする価値があります。RRF モードでは、スコアは順位に基づきます。
• ingest_file と ingest_data の使い分け
• HTML の取り込みと URL の処理

AI ツールを再起動して、話しかけてみましょう：

You: "Ingest api-spec.pdf"
AI:  Successfully ingested api-spec.pdf (47 chunks)

You: "How does authentication work?"
AI:  Based on section 3.2, authentication uses OAuth 2.0 with JWT tokens...

これだけです。Docker も Python も、管理が必要なサーバーインフラストラクチャもありません。

Web インターフェース

RAG Vault には Web UI があるため、コマンドラインを操作せずにドキュメントを管理できます。

Web UI を起動する

npx github:RobThePCGuy/rag-vault web

ブラウザーで http://localhost:3000 を開きます。

デフォルトでは、Web サーバーは 127.0.0.1（ループバック）にバインドされるため、このマシンからのみアクセスできます。ネットワーク上の別のデバイスから使用するには、RAG_BIND_HOST=0.0.0.0 を設定してください。また、API は認証なしで利用できるため、RAG_API_KEY も設定してください。

できること

• ドキュメントをアップロード：PDF、DOCX、Markdown、TXT、JSON、JSONL、NDJSON ファイルをドラッグ＆ドロップ
• すぐに検索：クエリを入力し、関連度スコア付きの結果を確認
• コンテンツをプレビュー：任意の結果をクリックして、前後の文脈を含むチャンク全体を表示
• ファイルを管理：インデックス化されたすべてのドキュメントを表示し、不要なものを削除
• データベースを切り替え：複数のナレッジベースを作成して切り替え
• ステータスを確認：ドキュメント数、メモリ使用量、検索モードを表示
• 設定をエクスポート／インポート：Vault の設定をバックアップおよび復元
• テーマ設定：ライト、ダーク、システムのテーマを切り替え
• フォルダーブラウザー：ディレクトリをたどってドキュメントを選択

REST API

Web サーバーには、直接呼び出せる REST API があります。認証を必須にするには、RAG_API_KEY を設定します。

# With authentication (when RAG_API_KEY is set)
curl -X POST "http://localhost:3000/api/v1/search" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication", "limit": 5}'

# Search documents (no auth needed if RAG_API_KEY isn't set)
curl -X POST "http://localhost:3000/api/v1/search" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication", "limit": 5}'

# List all files
curl "http://localhost:3000/api/v1/files"

# Upload a document
curl -X POST "http://localhost:3000/api/v1/files/upload" \
  -F "[email protected]"

# Delete a file
curl -X DELETE "http://localhost:3000/api/v1/files" \
  -H "Content-Type: application/json" \
  -d '{"filePath": "/path/to/spec.pdf"}'

# Get system status
curl "http://localhost:3000/api/v1/status"

# Health check (for load balancers)
curl "http://localhost:3000/api/v1/health"

Reader API エンドポイント

これらのエンドポイントを使うと、ドキュメントを読み取り、ドキュメント間のつながりを見つけられます。

# Get all chunks for a document (ordered by index)
curl "http://localhost:3000/api/v1/documents/chunks?filePath=/path/to/doc.pdf"

# Find related chunks for cross-document discovery
curl "http://localhost:3000/api/v1/chunks/related?filePath=/path/to/doc.pdf&chunkIndex=0&limit=5"

# Batch request for multiple chunks (efficient for UIs)
curl -X POST "http://localhost:3000/api/v1/chunks/batch-related" \
  -H "Content-Type: application/json" \
  -d '{"chunks": [{"filePath": "/path/to/doc.pdf", "chunkIndex": 0}], "limit": 3}'

リモートモード

RAG Vault は HTTP サーバーとしても実行できるため、Claude.ai、Claude Desktop など、Streamable HTTP または SSE に対応したリモート MCP クライアントから接続できます。

# Start remote server (default port 3001)
npx github:RobThePCGuy/rag-vault --remote

# Custom port
npx github:RobThePCGuy/rag-vault --remote --port 8080

Stdio モードに変更はありません。--remote を付けずに実行すれば、Cursor、Claude Code、Codex でこれまでどおり動作します。

Claude Desktop から接続する

Claude Desktop の設定に追加します。

{
  "mcpServers": {
    "rag-vault-remote": {
      "type": "url",
      "url": "http://localhost:3001/mcp"
    }
  }
}

または、Claude Code CLI を使います。

claude mcp add --transport http rag-vault http://localhost:3001/mcp

Claude.ai から接続する

Claude.ai（Pro/Max/Team/Enterprise）の場合、URL https://your-host:3001/mcp を使ってカスタムコネクターとして追加します。ローカル開発では、トンネルを使ってサーバーを公開します。

cloudflared tunnel --url http://localhost:3001

リモートサーバーも、デフォルトでは 127.0.0.1（ループバック）にバインドされます。他のマシンから直接接続できるようにするには、RAG_BIND_HOST=0.0.0.0 を設定します。トンネル経由も含め、ループバックの範囲外にサーバーを公開する場合は、必ず認証用に RAG_API_KEY を設定してください。サーバーは Streamable HTTP（/mcp）とレガシー SSE（/sse）の両方のトランスポートに加え、/health のヘルスチェックに対応しています。

実際の使用例

コードベースのドキュメントを検索する

You: "Ingest all the markdown files in /docs"
AI:  Ingested 23 files (847 chunks total)

You: "What's the retry policy for failed API calls?"
AI:  According to error-handling.md, failed requests retry 3 times
     with exponential backoff: 1s, 2s, 4s...

Web ドキュメントをインデックス化する

You: "Fetch https://docs.example.com/api and ingest the HTML"
AI:  Ingested "docs.example.com/api" (156 chunks)

You: "What rate limits apply to the /users endpoint?"
AI:  The API limits /users to 100 requests per minute per API key...

個人用ナレッジベースを構築する

You: "Ingest my research papers folder"
AI:  Ingested 12 PDFs (2,341 chunks)

You: "What do recent studies say about transformer attention mechanisms?"
AI:  Based on attention-mechanisms-2024.pdf, the key finding is...

正確な技術用語を検索する

RAG Vault のハイブリッド検索は、意味と完全一致の両方を捉えます。

You: "Search for ERR_CONNECTION_REFUSED"
AI:  Found 3 results mentioning ERR_CONNECTION_REFUSED:
     1. troubleshooting.md - "When you see ERR_CONNECTION_REFUSED..."
     2. network-errors.pdf - "Common causes include..."

純粋なセマンティック検索では見つけられません。RAG Vault なら見つけられます。

動作の仕組み

Document → Parse → Chunk by meaning → Embed locally → Store in LanceDB
                         ↓
Query → Embed → Vector search + BM25 → Fusion → Optional reranking → Results

スマートなチャンク分割：文字数ではなく意味に基づいて分割します。コードブロックはそのまま保持します。

ハイブリッド検索：ベクトル類似度と BM25 キーワードマッチングを組み合わせる、2 種類のフュージョンモードがあります。

• ブーストモード（デフォルト）：BM25 によってベクトル検索の距離を乗算的にブーストします。シンプルで予測しやすい方式です。
• RRF モード（RAG_SEARCH_MODE=rrf でオプトイン）：Reciprocal Rank Fusion は、ベクトル検索と BM25 を独立した投票者として扱います。ベクトル検索だけでは見つからないドキュメントが検索結果に表示されることがあります。

クロスエンコーダーによる再ランキング（オプトイン）：最初の検索後、クロスエンコーダーモデル（Xenova/ms-marco-MiniLM-L-6-v2、約 23 MB）が（クエリ、文章）の各ペアをまとめてスコアリングし、関連度の順位付けをさらに精密にします。RAG_RERANKER_ENABLED=true で有効にできます。

クエリ拡張（オプトイン）：検索語が言い換えられている場合や概念的な検索の場合に、再現率を向上させるため、クエリを再構成して生成します。バックエンドは 2 種類あります。ローカルのテンプレートベースの拡張（デフォルト、完全オフライン）と、外部 API を介した LLM ベースの HyDE です。RAG_HYDE_ENABLED=true で有効にできます。

品質フィルタリング：任意の top-K カットオフではなく、関連度の差に基づいて結果をグループ化します。

デフォルトでローカル実行：埋め込みには Transformers.js、ストレージには LanceDB を使用します。ネットワークが必要なのは、初回のモデルダウンロード時、またはリモート URL を明示的に取り込む場合のみです。

MCP ツールを同梱：query_documents、ingest_file、ingest_data、delete_file、list_files、status、feedback_pin、feedback_dismiss、feedback_stats を利用できます。

対応形式

設定

環境変数

Windows ユーザー向け： RAG_EMBEDDING_DEVICE=auto は GPU プロバイダー（DirectML）を試しますが、ONNX Runtime GPU バイナリが利用できない場合、失敗することがあります。埋め込みの初期化エラーが発生した場合は、安定して動作させるため、MCP 設定で RAG_EMBEDDING_DEVICE=cpu に設定してください。詳しくはGPU アクセラレーションに関する FAQを参照してください。

.env を編集せずに、1 つのコマンドで上書き：

# MCP mode
npx github:RobThePCGuy/rag-vault --embedding-device cpu

# Web mode
npx github:RobThePCGuy/rag-vault web --embedding-device dml

# Explicitly force auto detection
npx github:RobThePCGuy/rag-vault --gpu-auto

検索の調整

Cross-Encoder による再順位付け（オプトイン）

クエリ拡張 / HyDE（オプトイン）

プライバシーに関する注意： api バックエンドはクエリテキストを外部の LLM エンドポイントに送信するため、「クラウドを一切使わない」という保証が損なわれます。デフォルトの rule-based バックエンドは完全にローカルで動作します。

セキュリティ（任意）

詳細設定

完全な設定テンプレートは .env.example をコピーしてください。

コードが多いコンテンツの場合は、次をお試しください。

"env": {
  "RAG_HYBRID_WEIGHT": "0.8",
  "RAG_GROUPING": "similar"
}

よくある質問

"env": {
  "RAG_EMBEDDING_DEVICE": "cpu"
}

"MODEL_NAME": "onnx-community/embeddinggemma-300m-ONNX"

開発

git clone https://github.com/RobThePCGuy/rag-vault.git
cd rag-vault
pnpm install
pnpm -C web-ui install

# Install local git hooks (recommended, even for solo dev)
pnpm hooks:install

# Fast local quality gate (backend + web-ui type/lint/format, deps, unused, build, unit tests)
pnpm check:all

# Unit tests only (no model download required)
pnpm test:unit

# Integration/E2E tests (requires model download/network)
pnpm test:integration

# Build
pnpm build

# Run MCP server locally (stdio)
pnpm dev

# Run MCP server locally (remote HTTP + SSE)
pnpm dev:remote

# Run web server locally
pnpm web:dev

# Release to npm (local, guarded)
pnpm release          # patch
pnpm release:minor
pnpm release:major
pnpm release:dry

テスト階層

• pnpm test:unit：ローカル／CI の品質チェック用の決定論的テストです。モデルのダウンロードを伴う統合パスは含まれません。
• pnpm test:integration：埋め込みモデルの初期化を含む、完全な統合および E2E ワークフローです。

ネットワークやモデルに依存するテストスイートを明示的に実行するには、RUN_EMBEDDING_INTEGRATION=1 を使用してください。

リリース戦略

• リリースはローカルで行い、scripts/release-npm.sh を使ってスクリプトで実行します。
• サポートされているバージョン更新は patch、minor、major です。
• このスクリプトはバージョンファイルに変更を加える前に、依存関係のインストール、pnpm check:all、pnpm ui:build を実行します。
• package.json と server.json のバージョンは、チェックが成功した後にのみ更新されます。後続の手順で失敗した場合は自動的に元に戻されます。
• pnpm release:dry はすべてのチェックに加えて npm のドライラン公開を実行し、バージョンファイルを必ず元に戻します。

プロジェクト構成

src/
├── bin/             # CLI subcommands (skills install)
├── chunker/         # Semantic text splitting
├── embedder/        # Transformers.js wrapper
├── errors/          # Error handling utilities
├── explainability/  # Keyword-based result explanations
├── flywheel/        # Feedback loop (pin/dismiss reranking)
├── hyde/            # Query expansion + HyDE (LLM-based)
├── parser/          # PDF, DOCX, HTML parsing
├── query/           # Advanced query syntax parser
├── reranker/        # Cross-encoder reranking (Transformers.js)
├── server/          # MCP tool handlers + remote transport
├── utils/           # Config, file helpers, process handlers
├── vectordb/        # LanceDB + hybrid search (boost + RRF)
└── web/             # Express server + REST API

web-ui/              # React frontend (Vite + Tailwind)

ドキュメント

• SECURITY.md：セキュリティ設定とベストプラクティス
• .env.example：環境変数の完全なテンプレート

ライセンス

MIT：個人利用および商用利用は無料です。

謝辞

Model Context Protocol、LanceDB、Transformers.js を使用して構築されています。

Shinsuke Kagawa による mcp-local-rag のフォークとして始まりました。今では独自のプロジェクトです。 基盤を築いてくれた上流のコントリビューターに心から感謝します。そこから精力的に改良を重ねてきました。 ローカルファーストの開発ツールを、これからもずっと。