quillrag

単一ファイル。依存関係ゼロ。エディタの読み込みが終わる前に準備完了。

単一の静的バイナリに収められたローカルRAGエンジン — MiniLM埋め込みを内蔵し、 ハイブリッド密ベクトル + BM25検索、MCPネイティブ。NodeもPythonも不要、 初回クエリ時のモデルダウンロードも不要。

quillragが選ばれる理由

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ハンドシェイクと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クライアントから接続するだけです。

ツール

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)です。

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