Skip to main content
Glama

quillrag

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

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

release platforms license


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(実測: ストアオープン + ツール登録のみ)

最初のrag_search / rag_index呼び出し

+約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クライアントから接続するだけです。

ツール

ツール

機能

rag_index

ディレクトリ/ファイルをインクリメンタルにインデックス。変更のないファイルはスキップ、削除されたファイルは除去、差分のみ再埋め込み。

rag_search

ハイブリッド検索: 密ベクトルMiniLM cosine + 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サイドカー インデックスをインデックスパスごとに再構築(ポケット規模では低コスト)。

  • 融合: 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 tools
rag_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_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

    A4.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Local-first RAG indexing and semantic search MCP server. Enables document retrieval and context-aware queries using local embedding models.
      3
      8 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Drop-in MCP server template with SQLite FTS5 search backend. ~300 lines, no vector DB, no embedding API, runs on a Pi.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP server for local RAG over personal notes, PDFs, and documents, enabling plain-English querying and hybrid search with multi-hop context expansion.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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