quillrag

---

quillrag を選ぶ理由

準備完了まで約20 ms	モデルが読み込まれる前に MCP ハンドシェイクが完了します
実行時依存関係ゼロ	Node、Python、pip/npm、モデルのダウンロードは一切不要です
ハイブリッド検索	密ベクトルのコサイン類似度 ⊕ BM25 を Reciprocal Rank Fusion で統合します
設計上、プライベート	インストール後にネットワークへ接続するコードパスはありません
1つのファイル、3つの OS	約105 MB（モデルを内蔵）。CI で Linux/macOS/Windows 向けにビルドされます

クイックスタート

# 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 の初期化	約20 ms（実測値：ストアのオープン + ツールの登録のみ）
初回の rag_search / rag_index 呼び出し	+約300 ms（1回のみ。safetensors を mmap し、BERT グラフを構築）
2回目以降の検索	クエリあたり 約25 ms（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

Linux の要件： v0.1.6 のバイナリは Ubuntu 24.04 ランナーでビルドされ、glibc 2.39（pidfd_spawnp/pidfd_getpid）にリンクされています。古いディストリビューション（glibc < 2.39、例：Ubuntu 22.04）では、代わりにローカルのツールチェーンでソースからビルドしてください：cargo install --path .。

または、ソースからビルドします：

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 クライアントを接続してください。

ツール

ツール	機能
rag_index	ディレクトリまたはファイルを増分インデックスします。変更のないファイルはスキップし、差分のみを再埋め込みします。削除対象の絞り込みは指定したディレクトリ内に限定されるため、他のルートからインデックスされたドキュメントには影響しません。シンボリックリンク先のファイル／ディレクトリも対象になります。
rag_search	ハイブリッド検索：MiniLM の密ベクトルコサイン類似度と BM25 キーワード検索を Reciprocal Rank Fusion で統合します。ソースパス付きの、順位付けされたチャンクを返します。
rag_status	ドキュメント／チャンク数、インデックス済みバイト数、ファイルタイプ別の内訳を表示します。
rag_clear	すべてを消去します。

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 サイドカー インデックスは、インデックス作成のたびに再構築されます（小規模なデータなら低コストです）。
• 統合：逆順位融合（Σ 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。

オプションの形式（ライブラリ機能）

エンジンを組み込むアプリケーション（default-features = false）では、 IndexHooks エクストラクターを使って、さらに多くの形式をインデックスできます。

機能	追加されるもの
pdf	PdfExtractor：テキストレイヤーを持つ PDF を対象に、ページごとに 1 つのセクションを作成します。検索結果には page が含まれます。
ocr	Ocr、ImageExtractor（png/jpg/webp/bmp/gif）、および PdfExtractor::with_ocr によるスキャン済み PDF ページの OCR。ocrs モデル（約 12 MB、CC BY-SA 4.0、assets/ocr/NOTICE.md を参照）を同梱します。英語／基本ラテン文字のテキストのみが対象です。

読み取り可能でもテキストを含まないファイルは、空のドキュメントとして記録されるため、 変更されていないファイルはインデックス作成のたびに再度 OCR されません（IndexOptions::retry_empty を使うと再確認されます）。

インデックス作成の動作

quillrag index ~/notes              # incremental walk of one root
quillrag index ~/notes --no-prune   # add/update without deleting anything
quillrag index ~/notes --force      # re-embed this root, preserve other roots

• プルーニングの対象はインデックスルート内に限定されます。 ~/work-docs からインデックスされたドキュメントは、 同じデータディレクトリに対して後から quillrag index ~/personal-notes を実行しても 残ります。削除対象になるのは、走査対象のディレクトリ内にあったファイルのうち、その後消失したものだけです。 拡張子やサイズによって除外された既存ファイルは、インデックスに残ります。--no-prune を指定すると、 MCP の no_prune を含め、削除が無効になります。--force は選択したソースだけを再埋め込みします。 ストアを消去するには、明示的に clear を使用してください。スキャンが成功しても結果が空の場合は警告が表示され、 そのルートに残る最後のファイルがプルーニングされる可能性があります。
• シンボリックリンクをたどります。 シンボリックリンクされたソースディレクトリから作成したステージングツリーも、 通常どおりインデックスされます。循環、リンク切れ、読み取り不能なディレクトリがあると、 ストアを変更する前に走査が中止されます。パスにはシンボリックリンクの別名が保持されるため、 別名とそのリンク先の両方をインデックスすると、別々のエントリが作成されます。
• 128 チャンクごとの埋め込みバッチ単位で進捗がログに記録されます（stderr）。そのため、 CPU で長時間インデックスを作成している間も処理の継続を確認できます。

既存のインデックスのアップグレード

以前のバッチ処理によるインデックス作成では、ドキュメントのパスが誤ったチャンクに関連付けられることがありました。 保存済みのインデックスだけからその関連付けを復元することはできません。 ソースファイルから新しいデータディレクトリを作成し、検索結果を確認してから、 クライアントの接続先を切り替えてください。確認に合格するまでは古いディレクトリを残してください。 また、この方法ではレガシーな相対パスのキーも削除されます。新しいインデックス作成機能は、 元の作業ディレクトリを推測せず、そのまま保持します。新しいキーは絶対パスです。 .. を含むパスはファイルシステムを通じて解決されます。シンボリックリンクベースのルートでは、 表記を一定にしてください。再インデックスすると BM25 サイドカーも更新されます。

プライバシーと使用量

埋め込み、ストレージ、検索のすべてがローカルで動作します。マシンの外部に送信されるものはありません。 インストール後にネットワークコードパスは一切ありません。

バイナリ：約 105 MB（モデルを内包）。アイドル時の常駐 RAM：約 120 MB。 バッチ埋め込み中は約 250 MB まで増加します。

スケーリングと制限

quillrag はすべてのデータを単一の redb ファイルに保存し、密ベクトル検索を全ベクトルに対する正確な単一スレッドの線形スキャンで実行します。現時点では ANN インデックスはありません。そのため、関連する制限はストレージではなくクエリレイテンシです。ストレージは数百万チャンクまでスケールしますが、検索速度はクエリごとに O(N) です。

コーパス	ベクトル数	おおよその RAM（f32）	定常状態のクエリ時間
1K チャンク	1K	~1.5 MB	~25 ms（実測）
10K チャンク	10K	~15 MB	~250 ms（外挿値）
100K チャンク	100K	~154 MB	~2–5 s（外挿値）
1M チャンク	1M	~1.5 GB	20–60 s（外挿値 — ANN なしでは実用的ではありません）

1K チャンクのコーパスで検証済み（実際の JSON-RPC over stdio による e2e を含む 5/5 テスト）。上記の 1K を超える数値は、O(N) の密ベクトルスキャンのコストから外挿したものであり、実測値ではありません。 合成スケールプローブ（src/bin/quillbench.rs）を使って、お使いのハードウェアで曲線を測定できます。cargo build --release && ./target/release/quillbench を実行してください。

実際の使用における意味は次のとおりです。

• 最適な用途： 個人用／ローカルのナレッジベース、プロジェクトドキュメント、メモ、コードなど。サブ秒から対話的なレイテンシを維持できる、数万チャンク程度までの規模に適しています。
• 最適な規模を超える用途： 数十万以上のコーパスで、対話的（<200 ms）な検索が必要な場合は、ANN インデックスが必要になります（ロードマップを参照）。

関連性の観点で、一般的な代替手段と比較すると次のとおりです。

• 埋め込みのみ（例：生の FAISS flat／シンプルなベクトルストア）： quillrag の密ベクトル検索と同じ all-MiniLM-L6-v2 の上限がありますが、quillrag は BM25 + RRF フュージョンを追加しており、キーワード中心のクエリ（エラーコード、ID、完全一致トークン）で優位です。quillrag にはリランカーやメタデータフィルタリングはありませんが、llama-index はそれらを提供しています。
• llama-index のローカルバックエンド： 機能面では、ハイブリッド検索（BM25 + ベクトル + RRF）と類似しています。quillrag は llama-index の高度なリランキング、親子チャンク化、クエリ拡張の代わりに、依存関係のない単一バイナリと即時起動を実現しています。標準データセット（BEIR／MS MARCO）における関連性は、まだベンチマークされていません。ANN と関連性ベースラインを追跡する未解決の issue を参照してください。

ロードマップ

quillrag は現在、意図的に最小限の機能にとどめています。大きな進展の鍵となるのは、近似最近傍インデックスです。

• 密ベクトルに対する ANN（HNSW／IVF） — O(N) スキャンをサブミリ秒の ANN 検索に変え、単一マシンで対話的に扱える上限を約 10K から数百万チャンクへ引き上げます。
• 量子化（PQ／SQ） — ベクトルの RAM 使用量を次元あたり 4 バイトから約 1 バイトに削減するため、1M チャンクで約 1.5 GB ではなく約 380 MB になります。
• マルチスレッドスキャン — 暫定措置として、現在の正確な検索処理を並列化します。
• リランカーフック — フュージョン後の top-k を、任意のクロスエンコーダーでリランキングします。
• 関連性ベンチマーク — llama-index のベースラインと比較した BEIR／MS MARCO の nDCG@10。

ANN の作業はこちらで追跡できます：issue #1 — "1M チャンク未満向けの ANN インデックス。"

FAQ

本当に1つのファイルだけですか？ はい。MiniLMの重みとトークナイザーはinclude_bytes!でコンパイル時に組み込まれます。npm installもPythonも、初回クエリ時のモデルのダウンロードも不要です。モデルがバイナリに含まれているため、サイズは約105 MBです。

起動がとても速いのはなぜですか？ 埋め込みモデルは遅延読み込みされます。MCPのハンドシェイクとrag_statusではモデルにアクセスしないため、エディターには約20 msで準備完了のサーバーが表示されます。モデルが読み込まれるのは、初回のrag_search／rag_index実行時のみです（1回限りで約300 ms）。

処理できるコーパスの最大サイズは？ 1Kチャンク（クエリあたり約25 ms）での動作を確認済みです。このアーキテクチャは数百万件の保存済みチャンクに対応できるよう拡張可能です。現時点でインタラクティブな検索に対応するのは数万件程度までで、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.6：ルートスコープの刈り込み、正常に動作する--no-prune、ソーススコープの--force、失敗時にも安全な検出処理を伴うシンボリックリンクの走査、絶対ソースキー、正確な部分バッチの進捗表示を追加しました。バッチ書き込みでドキュメントとチャンクの関連付けがシャッフルされる問題、およびBM25の結果パスが欠落する問題を修正しました。前述の手順に従って、古いインデックスを新しいディレクトリに再構築してください。
• v0.1.5：公開を取り下げたドラフトです。初期の安全性修正が不完全なため、このタグは本番環境では使用しないでください。
• v0.1.4 — マルチスレッド推論とバッチインデックス作成。
• v0.1.3 — MCPツールの説明を、明確さ、パラメーターの意味、動作の透明性（読み取り専用／破壊的操作のフラグ、使用方法のガイダンス）のために書き直しました。MCPレジストリへの公開に向けて、server.jsonをリポジトリ内に同梱しました。
• v0.1.2 — インデックス作成時にすべてのドットディレクトリをスキップするようにしました（.obsidianのプラグイン設定が検索結果に混入しなくなりました）。3プラットフォームすべてに対応した、初の完全自動CIリリースです。 アップグレード時の注意： quillrag clearを1回実行してから、インデックスを再作成してください。
• v0.1.1 — チェックサム付きの、linux／macos／windows向けCIビルドリリース成果物。
• v0.1.0 — 初回の一般公開リリース。pocketragから名称を変更しました。

開発

cargo test --release          # unit + end-to-end with real model inference
cargo run -- serve            # dev server
RUST_LOG=debug cargo run ...  # verbose logs (stderr only)

ライセンス：MIT。assets/ocr/内のオプションのOCRモデルはCC BY-SA 4.0です。assets/ocr/NOTICE.mdを参照してください。