quillrag
quillrag
単一ファイル。依存関係ゼロ。エディタの読み込みが終わる前に準備完了。
単一の静的バイナリに収められたローカルRAGエンジン — MiniLM埋め込みを内蔵し、 ハイブリッド密ベクトル + BM25検索、MCPネイティブ。NodeもPythonも不要、 初回クエリ時のモデルダウンロードも不要。
quillragが選ばれる理由
起動まで約20ms | モデルが読み込まれる前にMCPハンドシェイクが完了 |
実行時依存ゼロ | NodeもPythonもpip/npmもモデルダウンロードも不要 — 一切なし |
ハイブリッド検索 | 密ベクトルcosine ⊕ BM25をReciprocal Rank Fusionで融合 |
設計上プライベート | インストール後のネットワークコードパスなし |
1ファイル、3OS対応 | 約105MB(モデル内蔵)、linux/macOS/Windows向けにCIビルド |
Related MCP server: mcp-fts5-starter
クイックスタート
# 1. grab a prebuilt binary (or cargo install --path .)
gh release download --repo Ayush-yadav11/quillrag -p '*linux*'
tar xzf quillrag-x86_64-linux.tar.gz && chmod +x quillrag
# 2. point it at any folder of notes/docs/code
./quillrag index ~/notes # incremental walk
# 3. ask it something
./quillrag search "how does backpropagation work"またはClaude Desktop / Cursorに直接接続して、会話の途中でAIにノートを検索 させることができます — 設定は以下。
$ ./quillrag serve --data-dir ~/.local/share/quillrag
2026-08-26 INFO quillrag 0.1.2 ready in 41ms <- handshake-ready before the model loads高速な理由
ステージ | コスト |
バイナリ起動 + MCP初期化 | 約20ms(実測: ストアオープン + ツール登録のみ) |
最初の | +約300ms(初回のみ: safetensorsのmmap、BERTグラフ構築) |
以降の検索 | クエリあたり約25ms(2コアCPU、小規模コーパス) |
変更なしコーパスの再インデックス | ほぼゼロ(FNVコンテンツハッシュによるスキップ) |
埋め込みモデルは遅延ロードです: MCPハンドシェイクとrag_statusはモデルに
一切触れないため、エディタには即座にサーバーが準備完了と表示されます。
インストール
最新リリースから ビルド済みアーカイブをダウンロード — Windows x86_64、macOS Apple Silicon、 Linux x86_64はすべて各バージョンタグでCIがビルドします:
# linux/macOS example: fetch + extract the latest release
gh release download --repo Ayush-yadav11/quillrag -p '*linux*' | tar xz
chmod +x quillrag && ./quillrag --versionまたはソースからビルド:
cargo install --path .CIで使用するクロスコンパイルターゲット: x86_64-unknown-linux-gnu、
aarch64-apple-darwin、x86_64-pc-windows-msvc。
エディタに接続する
Claude Desktop / Cursor / 任意のMCPクライアント:
{
"mcpServers": {
"quillrag": {
"command": "/usr/local/bin/quillrag",
"args": ["serve"],
"env": { "QUILLRAG_DATA": "~/.local/share/quillrag" }
}
}
}または./quillrag serveを実行して、任意のstdioクライアントから接続するだけです。
ツール
ツール | 機能 |
| ディレクトリ/ファイルをインクリメンタルにインデックス。変更のないファイルはスキップ、削除されたファイルは除去、差分のみ再埋め込み。 |
| ハイブリッド検索: 密ベクトルMiniLM cosine + BM25キーワードをReciprocal Rank Fusionで融合。ソースパス付きのランク付けされたチャンクを返す。 |
| ドキュメント/チャンク数、インデックス済みバイト数、ファイルタイプ別の内訳。 |
| すべて消去。 |
CLI相当(同じエンジン):
quillrag index ~/notes # incremental walk
quillrag search "auth flow" -k 5 # one-shot search
quillrag status # stats
quillrag clear # wipe設計
埋め込み: candle(純Rust)で
sentence-transformers/all-MiniLM-L6-v2を実行 — マスク平均プーリング + L2正規化、CPU上でsentence-transformersと数値的に一致。重みはinclude_bytes!でバイナリに埋め込まれ、初回ロード時にマテリアライズされた キャッシュからmmapされます。ストレージ: 単一のredbファイル — チャンク テキスト、生のf32ベクトル、ドキュメントメタデータ。アトミックコミット、クラッシュセーフ。
キーワード: tantivy BM25サイドカー インデックスをインデックスパスごとに再構築(ポケット規模では低コスト)。
融合: Reciprocal Rank Fusion(
Σ 1/(60+rank))— スコアスケールの調整不要、 異種ランキングに対して堅牢。チャンキング: 段落優先、1000文字上限、120文字オーバーラップ。巨大な段落は 文の境界でハード分割。
デフォルトでインデックスされるファイルタイプ
md markdown txt rst json yaml yml toml csv tsv html htm xml log rs py js jsx ts tsx go c h cpp hpp java rb sh bash zsh sql proto graphql dockerfile makefile ini cfg conf env — -e ext1,ext2 / "extensions": [...]で拡張可能。
無視されるディレクトリ: すべてのドットディレクトリ(.git .obsidian .vscode など)に加え、
node_modules target dist build venv __pycache__ vendor。
プライバシーとフットプリント
すべてローカルで実行: 埋め込み、ストレージ、検索。マシンの外に出るものは ありません — インストール後のネットワークコードパスは一切ありません。
バイナリ約105MB(モデル内蔵)。RAMはアイドル時約120MB、バッチ埋め込み時に 約250MBまでスパイク。
スケーリングと限界
quillragはすべてを単一のredbファイルに格納し、密ベクトル検索を
全ベクトルに対する正確なシングルスレッド線形スキャンとして実行します —
ANNインデックスはまだありません。つまり、関連する限界はクエリレイテンシであり、
ストレージではありません。ストレージは数百万チャンクまでスケールします。
検索速度はクエリあたりO(N)です。
コーパス | ベクトル数 | おおよそのRAM(f32) | 定常状態のクエリ |
1Kチャンク | 1K | 約1.5MB | 約25ms(実測) |
10Kチャンク | 10K | 約15MB | 約250ms(外挿) |
100Kチャンク | 100K | 約154MB | 約2〜5秒(外挿) |
1Mチャンク | 1M | 約1.5GB | 20〜60秒(外挿 — ANNなしでは現実的でない) |
1Kチャンクのコーパスで検証済み(実JSON-RPC-over-stdioのe2eを含む5/5テスト);
1Kを超える数値はO(N)密スキャンコストからの外挿であり、実測ではありません。
合成スケールプローブ(src/bin/quillbench.rs)が自分のハードウェアで曲線を
測定するために存在します — cargo build --release && ./target/release/quillbenchを実行。
これが実際に意味すること:
最適な用途: 個人/ローカルナレッジベース、プロジェクトドキュメント、ノート、 コード — サブ秒からインタラクティブなレイテンシが維持される数万チャンクまで。
適さない用途: 数十万チャンク以上でインタラクティブ(<200ms)な検索が 必要な場合 — ANNインデックスが必要になります(ロードマップ参照)。
関連性の軸で一般的な代替手段と比較すると:
埋め込みのみ(例: 素のFAISSフラット / 単純なベクトルストア): quillragの 密ベクトルパスと同じ
all-MiniLM-L6-v2の上限ですが、quillragはBM25 + RRF融合を 追加しており、キーワード中心のクエリ(エラーコード、ID、正確なトークン)で 優位に立ちます。quillragにはリランカーやメタデータフィルタリングがなく、 llama-indexはその上にこれらを提供します。llama-indexローカルバックエンド: 機能的に類似したハイブリッド検索 (BM25 + ベクトル + RRF)。quillragはllama-indexの豊富なリランキング/親子 チャンキング/クエリ拡張と引き換えに、依存ゼロの単一バイナリと即時起動を 提供します。標準データセット(BEIR/MS MARCO)での関連性はまだベンチマーク されていません — ANNと関連性ベースラインを追跡するオープンイシューを参照。
ロードマップ
quillragは現在意図的に最小限です。大きな飛躍の鍵は近似最近傍インデックスです:
密ベクトルに対するANN(HNSW / IVF) — O(N)スキャンをサブミリ秒のANN ルックアップに変え、インタラクティブな上限を約1万から単一マシンで数百万 チャンクに押し上げます。
量子化(PQ / SQ) — ベクトルRAMを4バイト/次元から約1バイト/次元に削減し、 1Mチャンクで1.5GBではなく約380MBに。
マルチスレッドスキャン — 現在の正確パスを暫定策として並列化。
リランカーフック — 融合されたtop-kに対するオプションのクロスエンコーダー リランク。
関連性ベンチマーク — llama-indexベースラインに対するBEIR / MS MARCO nDCG@10。
ANNの作業はこちらで追跡: issue #1 — 「<1MチャンクのANNインデックス。」
FAQ
本当に1ファイルですか? はい。MiniLMの重みとトークナイザーは
include_bytes!でコンパイルされています。npm installもPythonも、初回クエリ時の
モデルダウンロードも不要です。モデルが内部にあるためバイナリは約105MBです。
なぜ起動がそんなに速いのですか? 埋め込みモデルは遅延ロードです。MCP
ハンドシェイクとrag_statusはモデルに一切触れません — エディタには約20msで
準備完了のサーバーが見えます。モデルは最初のrag_search / rag_indexでのみ
読み込まれます(初回のみ約300ms)。
扱える最大のコーパスは? 1Kチャンクで検証済み(約25ms/クエリ)。アーキテクチャは 数百万の保存チャンクまでスケールします。インタラクティブ検索は現在数万まで 維持され、ANNインデックス(ロードマップ)で100万以上に拡張されます。
llama-indexとどう違うのですか? ハイブリッド検索の品質は似ていますが、 quillragは実行時/依存フットプリントがなく即時起動の単一静的バイナリです。 llama-indexにはquillragにはまだないリランカー、高度なチャンキング、クエリ拡張が あります。
どのファイルタイプがインデックスされますか? md markdown txt rst json yaml yml toml csv tsv html htm xml log rs py js jsx ts tsx go c h cpp hpp java rb sh bash zsh sql proto graphql dockerfile makefile ini cfg conf env — -eで拡張可能。
外部に通信しますか? いいえ。インストール後のネットワークコードパスは ありません。
チェンジログ
v0.1.3 — MCPツールの説明を明確さ、パラメータの意味論、動作の透明性 (読み取り専用/破壊的フラグ、使用ガイダンス)のために書き直し。MCPレジストリ 公開用のserver.jsonをリポジトリ内に同梱。
v0.1.2 — インデックス時にすべてのドットディレクトリをスキップ (
.obsidianプラグイン設定が結果を汚染しなくなりました)。初の完全自動化 3プラットフォームCIリリース。 アップグレード注意:quillrag clearを一度実行して再インデックスしてください。v0.1.1 — linux/macos/windows向けCIビルドのリリース成果物とチェックサム。
v0.1.0 — 初の公開リリース。pocketragから改名。
開発
cargo test # unit + end-to-end (spawns real stdio servers)
cargo run -- serve # dev server
RUST_LOG=debug cargo run ... # verbose logs (stderr only)ライセンス: MIT
Available Tools
4 toolsrag_clearA
Destructive: permanently deletes ALL indexed documents, chunks, and embeddings from the knowledge base. Cannot be undone — source files on disk are not touched, but re-indexing from scratch is required afterwards. Confirm with the user before calling.
Inputs: no named parameters.
rag_indexA
Index local documents into the knowledge base before searching. Pass an absolute directory path for a recursive incremental walk (skips unchanged files by content hash, prunes entries for deleted files) or a single file path. Idempotent and safe to re-run; only changed content is re-embedded. Supported types: md/txt/code files (see README for the full list); dot-directories like .git and .obsidian are skipped automatically. After indexing completes, use rag_search to query. To remove everything instead, use rag_clear.
Inputs: path (required), extensions.
rag_searchA
Search the local knowledge base using hybrid retrieval (dense MiniLM embeddings + BM25 keyword matching, fused via Reciprocal Rank Fusion). Returns up to top_k ranked chunks with source file paths, chunk indices, and relevance scores. Read-only: never modifies the index. If results are empty, call rag_index first to populate the knowledge base. Prefer this over rag_status when answering a user's question about their documents.
Inputs: query (required), top_k.
rag_statusA
Report knowledge base statistics: document count, chunk count, total indexed bytes, and per-file-type breakdown. Read-only and instant (does not load the embedding model). Use it to check whether anything is indexed before running a search.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a single, clear responsibility: search, status, index, and clear. There is no overlap—even search and status are distinguished by read-only purpose versus metadata reporting. The descriptions explicitly note when to prefer one over the other.
All tools follow the same 'rag_' prefix followed by a lowercase verb or noun, all in snake_case. The pattern is uniform and predictable: rag_search, rag_status, rag_clear, rag_index. No mixed conventions or stylistic deviations.
With 4 tools, the server is well-scoped for a RAG knowledge base service. It covers the core operations without unnecessary bloat or missing essentials. This is within the ideal 3-15 range and each tool earns its place.
The tools cover the full lifecycle: index (create/update), search (read), status (read metadata), and clear (delete). The only minor gap is the lack of a selective document deletion, but incremental indexing and pruning handle updates well, so agents can work around this limitation.
Maintenance
Related MCP Connectors
An MCP server for search and retrieval over a local LanceDB database
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
RAG-as-a-service MCP sunucusu — çok-kiracılı koleksiyon yönetimi, metin ingest (chunk+embed+upsert,…
Related MCP Servers
- AlicenseAqualityDmaintenanceLocal-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.38 npmMIT
- AlicenseNot gradedqualityDmaintenanceDrop-in MCP server template with SQLite FTS5 search backend. ~300 lines, no vector DB, no embedding API, runs on a Pi.MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for local RAG over personal notes, PDFs, and documents, enabling plain-English querying and hybrid search with multi-hop context expansion.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for a self-hosted RAG system that enables AI tools to search and retrieve grounded answers from locally ingested documents via MCP tools, with local embeddings and no API key required.MIT