Velocirag

🦖 VelociRAG

AI エージェント向けの超高速 RAG です。

ONNX Runtime を活用した 4 層検索フュージョン。PyTorch 不要です。ウォーム状態で 200ms 未満の検索を実現します。グラフを増分更新できます。MCP 対応です。

---

ほとんどの RAG ソリューションは、2GB 以上の PyTorch を導入するか、単層のベクトル検索に制限されます。VelociRAG は、ベクトル類似度、BM25 キーワードマッチング、ナレッジグラフのトラバーサル、メタデータフィルタリングという 4 つの検索方法を、相互ランク融合とクロスエンコーダーによる再ランキングで統合します。すべて ONNX Runtime 上で動作し、GPU も API キーも不要です。エージェント連携用の MCP サーバー、ウォームクエリ用の Unix ソケットデーモン、すぐに使える CLI が付属しています。

🚀 クイックスタート

MCP サーバー（Claude、Cursor、Windsurf）

pip install "velocirag[mcp]"
velocirag index ./my-docs
velocirag mcp

Claude Code — プロジェクトルートの .mcp.json に追加します：

{
  "mcpServers": {
    "velocirag": {
      "command": "velocirag",
      "args": ["mcp"],
      "env": { "VELOCIRAG_DB": "/path/to/data" }
    }
  }
}

続いて、Claude Code で /mcp を開き、velocirag サーバーを有効にします。仮想環境を使用する場合は、バイナリのフルパス（例：.venv/bin/velocirag）を指定してください。

Claude Desktop — claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "velocirag": {
      "command": "velocirag",
      "args": ["mcp", "--db", "/path/to/data"]
    }
  }
}

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

{
  "mcpServers": {
    "velocirag": {
      "command": "velocirag",
      "args": ["mcp", "--db", "/path/to/data"]
    }
  }
}

Python API

from velocirag import Embedder, VectorStore, Searcher

embedder = Embedder()
store = VectorStore('./my-db', embedder)
store.add_directory('./my-docs')
searcher = Searcher(store, embedder)
results = searcher.search('query', limit=5)

CLI

pip install velocirag
velocirag index ./my-docs
velocirag search "your query here"

検索デーモン（CLI ユーザー向けのウォームエンジン）

velocirag serve --db ./my-data        # start daemon (background)
velocirag search "query"              # auto-routes through daemon
velocirag status                      # check daemon health
velocirag stop                        # stop daemon

デーモンは Unix ソケット経由で ONNX モデルと FAISS インデックスをウォーム状態に保ちます。最初のクエリではエンジンが読み込まれ（約 1 秒）、以降のクエリは 4 層すべてを融合した検索結果を約 180ms で返します。

🎯 VelociRAG を選ぶ理由

• 4 層検索 — ベクトル＋BM25 キーワード＋ナレッジグラフ＋メタデータを RRF で融合
• LLM 不要 — 検索はすべてローカルモデル（MiniLM と TinyBERT、合計約 80MB）で実行
• GPU 不要 — 純粋な ONNX 推論で、どのマシンでも動作
• ウォーム検索約 3ms — デーモンがモデルとインデックスを Unix ソケット経由でウォーム状態に維持
• 増分インデックス作成 — インデックス全体を再構築せずにファイルを追加
• MCP サーバー — Claude、Cursor、Windsurf など、あらゆる MCP クライアントに接続

関連プロジェクト

• Memkoshi — エージェントのメモリシステムです。検索エンジンとして VelociRAG を使用します。
• Stelline — セッションインテリジェンスです。会話ログからメモリを作成します。
• Glyph — MCP セキュリティスキャナーおよびランタイム保護です。

🏗️ 仕組み

4 層パイプライン：

Query → expand (acronyms, variants)
      → [Vector]   FAISS cosine similarity (384d, MiniLM-L6-v2 via ONNX)
      → [Keyword]  BM25 via SQLite FTS5
      → [Graph]    Knowledge graph traversal
      → [Metadata] Structured SQL filters (tags, status, project)
      → RRF Fusion → Cross-encoder rerank → Results

各レイヤーが検出する内容：

クエリの種類	ベクトル	キーワード	グラフ	メタデータ
概念的（「エラー処理を改善する」）	✅	—	—	—
完全一致（「ERR_CONNECTION_REFUSED」）	—	✅	—	—
関連する概念	—	—	✅	—
絞り込み（「#python status:active」）	—	—	—	✅
複合（「React の状態管理」）	✅	✅	✅	✅

✨ 機能

• ONNX Runtime — コールドスタート 184ms、キャッシュ時 3ms。PyTorch も GPU も不要
• 4 層フュージョン — FAISS のベクトル類似度＋SQLite FTS5（BM25）＋ナレッジグラフ＋メタデータフィルタリングを、相互ランク融合で統合
• クロスエンコーダーによる再ランキング — ONNX Runtime 経由の TinyBERT 再ランキングモデルを基本インストールに同梱。PyTorch は不要です。初回使用時に約 17MB のモデルをダウンロードします
• グラフの増分更新 — ファイル中心の来歴追跡で変更点を検出し、影響を受けたノード／エッジのみを再構築します。連鎖削除により、すべてのストア（ベクトル、グラフ、メタデータ）の一貫性を維持します。ソースごとに来歴を分離したマルチソースに対応します
• MCP サーバー — Claude、Cursor、Windsurf 向けの 5 つのツール（search、index、add_document、health、list_sources）
• 検索デーモン — Unix ソケットサーバーが、クエリ間で ONNX モデルと FAISS インデックスをウォーム状態に維持
• ナレッジグラフ — アナライザーが Markdown からエンティティ、時間、トピック、明示的リンクのエッジを構築します。GLiNER NER はオプションです。418 ファイルを 2.1 秒で処理
• スマートチャンク化 — ヘッダーを考慮した分割により、ドキュメント構造と親コンテキストを保持
• クエリ拡張 — 略語レジストリ、大文字小文字／スペースのバリエーション、アンダースコアを考慮したトークン化
• どこでも動作 — CPU のみ、8GB の RAM、API キー不要、外部サービス不要

🤖 MCP サーバー

VelociRAG は、エージェントとシームレスに統合するための Model Context Protocol サーバーを公開します。

利用可能なツール：

• search — 4 層の融合検索と再ランキング
• index — ナレッジベースにドキュメントを追加
• add_document — 単一のドキュメントを挿入
• health — システム診断
• list_sources — インデックス済みドキュメントのソースを表示

MCP サーバーのプロセスはクエリ間も起動したままなので、モデルは一度だけ読み込まれ、以降の検索はすべてウォーム状態で実行されます。MCP 互換のあらゆるクライアントで動作します。

🐍 Python API

4 層の統合検索：

from velocirag import (
    Embedder, VectorStore, Searcher,
    GraphStore, MetadataStore, UnifiedSearch,
    GraphPipeline
)

# Build the full stack
embedder = Embedder()
store = VectorStore('./search-db', embedder)
graph_store = GraphStore('./search-db/graph.db')
metadata_store = MetadataStore('./search-db/metadata.db')

# Index with graph + metadata
store.add_directory('./docs')
pipeline = GraphPipeline(graph_store, embedder, metadata_store)
pipeline.build('./docs', source_name='my-docs')

# Unified search across all layers
searcher = Searcher(store, embedder)
unified = UnifiedSearch(searcher, graph_store, metadata_store)
results = unified.search(
    'machine learning algorithms',
    limit=5,
    enrich_graph=True,
    filters={'tags': ['python'], 'status': 'active'}
)

クイックセマンティック検索：

from velocirag import Embedder, VectorStore, Searcher

embedder = Embedder()
store = VectorStore('./db', embedder)
store.add_directory('./docs')
searcher = Searcher(store, embedder)
results = searcher.search('neural networks', limit=10)

グラフの増分更新：

from velocirag import Embedder, GraphStore, GraphPipeline

# First run — full build, populates provenance
gs = GraphStore('./db/graph.db')
pipeline = GraphPipeline(gs, embedder=Embedder())
pipeline.build('./docs', source_name='my-docs')  # full build

# Subsequent runs — only changed files get reprocessed
pipeline.build('./docs', source_name='my-docs')  # incremental (automatic)

# Force full rebuild
pipeline.build('./docs', source_name='my-docs', force_rebuild=True)

# Multi-source graphs
pipeline.build('./project-a', source_name='project-a')
pipeline.build('./project-b', source_name='project-b')  # isolated provenance

# Deleted files automatically cascade across all stores
# (vector, FTS5, graph, metadata) on next build

💻 CLI リファレンス

# Index documents (graph + metadata built by default)
velocirag index <path> [--no-graph] [--no-metadata] [--gliner] [--full-graph] [--force]
                       [--source NAME] [--db PATH]

# Search across all layers (auto-routes through daemon if running)
velocirag search <query> [--limit N] [--threshold F] [--format text|json]

# Search daemon
velocirag serve [--db PATH] [-f]         # start daemon (-f for foreground)
velocirag stop                            # stop daemon
velocirag status                          # check daemon health

# Metadata queries
velocirag query [--tags TAG] [--status S] [--project P] [--recent N]

# System health and status
velocirag health [--format text|json]

# Start MCP server
velocirag mcp [--db PATH] [--transport stdio|sse]

オプション：

• --no-graph — ナレッジグラフの構築をスキップ
• --no-metadata — メタデータの抽出をスキップ
• --full-graph — 意味的類似性エッジを含むグラフを構築（追加で約 2GB の RAM が必要）
• --source NAME — 複数ソースのプロベナンス分離に使用するラベル
• --force — すべてクリアして最初から再構築
• --gliner — エンティティ抽出に GLiNER を使用（pip install "velocirag[ner]" が必要）

📊 パフォーマンス

ByteByteGo/system-design-101 での実測ベンチマーク（418 ファイル、1,001 チャンク）：

指標	値
インデックス作成（418 ファイル）	13.6 秒
検索（ウォーム状態、5 件）	35～90 ms
グラフ構築（軽量）	2.1 秒 → 2,397 ノード、8,717 エッジ
増分更新（1 ファイル）	1.3 秒
再ランキングモデル	ONNX 経由の Cross-encoder TinyBERT
インストールサイズ	約 80MB（PyTorch なし）
RAM 使用量	すべてのモデルを読み込み済みの状態で 1GB 未満

本番環境でのデプロイ（6,300 件以上のチャンク、3 ソース、950 ファイル）：

指標	値
完全検索（ウォーム状態）	平均 16 ms、最小 2 ms
完全検索（初回実行）	平均 22 ms、最小 4 ms
検索 P50 / P95	17 ms / 55 ms
ヒット率（100 クエリのベンチマーク）	99/100
グラフ	3,125 ノード、132,320 エッジ
再ランキングモデル	ONNX 経由の Cross-encoder TinyBERT
RAM	すべてのモデルを読み込み済みの状態で 1GB 未満

⚙️ 設定

環境変数	デフォルト	説明
VELOCIRAG_DB	./.velocirag	データベースディレクトリ
VELOCIRAG_SOCKET	/tmp/velocirag-daemon.sock	デーモンのソケットパス
NO_COLOR	—	カラー出力を無効化

依存関係（すべて基本インストールに含まれます）：

• onnxruntime — ONNX 推論（埋め込みモデル＋再ランキングモデル）
• tokenizers + huggingface-hub — モデルの読み込み
• faiss-cpu — ベクトル類似性検索
• networkx + scikit-learn — ナレッジグラフ＋トピッククラスタリング
• numpy、click、pyyaml、python-frontmatter

オプションの追加機能：

• pip install "velocirag[mcp]" — MCP サーバー（fastmcp を追加）
• pip install "velocirag[ner]" — GLiNER によるエンティティ抽出（gliner を追加。PyTorch が必要）

📚 参考文献

VelociRAG は、以下の基礎的な研究成果を基盤としています。

コアフュージョンと検索

Reciprocal Rank Fusion — Cormack, G. V., Clarke, C. L. A., & Büttcher, S. (2009). "Reciprocal Rank Fusion outperforms Condorcet and individual Rank Learning Methods." SIGIR '09.
検索レイヤー間で結果を統合するためのコアフュージョンアルゴリズムです。

BM25 — Robertson, S. E., Walker, S., Jones, S., Hancock-Beaulieu, M., & Gatford, M. (1994). "Okapi at TREC-3." TREC-3.
SQLite FTS5 を介したキーワード検索の基盤です。

埋め込みとニューラル情報検索

Sentence-BERT — Reimers, N., & Gurevych, I. (2019). "Sentence-BERT: Sentence Embeddings using Siamese BERT-Networks." EMNLP 2019. paper
all-MiniLM-L6-v2 を使用した高密度埋め込みアーキテクチャです。

MiniLM — Wang, W., Wei, F., Dong, L., Bao, H., Yang, N., & Zhou, M. (2020). "MiniLM: Deep Self-Attention Distillation for Task-Agnostic Compression of Pre-Trained Transformers." NeurIPS 2020. paper
本番環境向け埋め込みモデルのための、効率的な Transformer 蒸留です。

再ランキングとニューラルモデル

Cross-Encoder Reranking — Nogueira, R., & Cho, K. (2019). "Passage Re-ranking with BERT." arXiv:1901.04085. paper
MS MARCO 上で TinyBERT を使用したクロスアテンション再ランキングです。

TinyBERT — Jiao, X., et al. (2020). "TinyBERT: Distilling BERT for Natural Language Understanding." Findings of EMNLP 2020. paper
高速な再ランキング推論を実現する、圧縮された BERT です。

ベクトル検索とシステム

FAISS — Johnson, J., Douze, M., & Jégou, H. (2019). "Billion-scale similarity search with GPUs." IEEE Transactions on Big Data. paper
高性能なベクトル類似性検索エンジンです。

GLiNER — Zaratiana, U., Nzeyimana, A., & Holat, P. (2023). "GLiNER: Generalist Model for Named Entity Recognition using Bidirectional Transformer." arXiv:2311.08526. paper
ナレッジグラフのエンティティ抽出向けの汎用 NER です（オプションの依存関係）。

📄 ライセンス

MIT — どこでも使用でき、何でも構築できます。

エージェント連携についてサポートが必要ですか？ 機械可読なプロジェクトコンテキストについては、AGENTS.md をご確認ください。

---

素早く考え、さらに素早く記憶するエージェントのために構築されました。