{
  "markdown": "<div align=\"center\">\n\n# quillrag\n\n**One file. Zero dependencies. Ready before your editor finishes loading.**\n\nA local RAG engine in a single static binary — MiniLM embeddings compiled\ninside, hybrid dense + BM25 retrieval, MCP-native. No Node, no Python,\nno model download on first query.\n\n[![release](https://img.shields.io/github/v/release/Ayush-yadav11/quillrag)](https://github.com/Ayush-yadav11/quillrag/releases/latest)\n[![platforms](https://img.shields.io/badge/platform-linux%20%7C%20macOS%20%7C%20Windows-blue)](https://github.com/Ayush-yadav11/quillrag/releases/latest)\n[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)\n\n<img src=\"assets/demo.gif\" alt=\"quillrag terminal demo: serve, index, search\" width=\"720\"/>\n\n</div>\n\n---\n\n## Why quillrag\n\n| | |\n|---|---|\n| **~20 ms to ready** | MCP handshake completes before the model even loads |\n| **Zero runtime deps** | no Node, no Python, no pip/npm, no model downloads — ever |\n| **Hybrid retrieval** | dense cosine ⊕ BM25 fused with Reciprocal Rank Fusion |\n| **Private by construction** | no network code path after installation |\n| **One file, three OSes** | ~105 MB (the model lives inside), CI-built for linux/macOS/Windows |\n\n## Quick start\n\n```sh\n# 1. grab a prebuilt binary (or cargo install --path .)\ngh release download --repo Ayush-yadav11/quillrag -p '*linux*'\ntar xzf quillrag-x86_64-linux.tar.gz && chmod +x quillrag\n\n# 2. point it at any folder of notes/docs/code\n./quillrag index ~/notes          # incremental walk\n\n# 3. ask it something\n./quillrag search \"how does backpropagation work\"\n```\n\nOr wire it straight into Claude Desktop / Cursor and let the AI search your\nnotes mid-conversation — config below.\n\n```\n$ ./quillrag serve --data-dir ~/.local/share/quillrag\n2026-08-26 INFO quillrag 0.1.2 ready in 41ms      <- handshake-ready before the model loads\n```\n\n## Why it's fast\n\n| Stage | Cost |\n|---|---|\n| Binary start + MCP initialize | **~20 ms** (measured: store open + tool registration only) |\n| First `rag_search` / `rag_index` call | +~300 ms one-time (mmap safetensors, build BERT graph) |\n| Subsequent searches | **~25 ms** per query (2-core CPU, small corpus) |\n| Re-indexing unchanged corpus | near-zero (FNV content hash skip) |\n\nThe embedding model is *lazy*: the MCP handshake and `rag_status` never touch\nit, so editors see an instant server.\n\n## Install\n\nDownload a prebuilt archive from the [latest release](https://github.com/Ayush-yadav11/quillrag/releases/latest)\n— Windows x86_64, macOS Apple Silicon, and Linux x86_64 are all built by CI on\nevery version tag:\n\n```sh\n# linux/macOS example: fetch + extract the latest release\ngh release download --repo Ayush-yadav11/quillrag -p '*linux*' | tar xz\nchmod +x quillrag && ./quillrag --version\n```\n\nOr build from source:\n\n```sh\ncargo install --path .\n```\n\nCross-compile targets used by CI: `x86_64-unknown-linux-gnu`,\n`aarch64-apple-darwin`, `x86_64-pc-windows-msvc`.\n\n## Wire it into your editor\n\nClaude Desktop / Cursor / any MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"quillrag\": {\n      \"command\": \"/usr/local/bin/quillrag\",\n      \"args\": [\"serve\"],\n      \"env\": { \"QUILLRAG_DATA\": \"~/.local/share/quillrag\" }\n    }\n  }\n}\n```\n\nOr just run `./quillrag serve` and point any stdio client at it.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `rag_index`  | Incrementally index a directory/file. Skips unchanged files, prunes deleted ones, re-embeds only diffs. |\n| `rag_search` | Hybrid retrieval: dense MiniLM cosine + BM25 keyword, fused with Reciprocal Rank Fusion. Returns ranked chunks with source paths. |\n| `rag_status` | Document/chunk counts, bytes indexed, file-type breakdown. |\n| `rag_clear`  | Wipe everything. |\n\nCLI equivalents (same engine):\n\n```sh\nquillrag index ~/notes              # incremental walk\nquillrag search \"auth flow\" -k 5    # one-shot search\nquillrag status                     # stats\nquillrag clear                      # wipe\n```\n\n## Design\n\n- **Embeddings**: [candle](https://github.com/huggingface/candle) (pure Rust)\n  running `sentence-transformers/all-MiniLM-L6-v2` — masked mean pooling +\n  L2 norm, numerically matching sentence-transformers on CPU. Weights are\n  `include_bytes!`-ed into the binary and mmap'd from a materialized cache on\n  first load.\n- **Storage**: single [redb](https://github.com/cberner/redb) file — chunk text,\n  raw f32 vectors, document metadata. Atomic commits; crash-safe.\n- **Keywords**: [tantivy](https://github.com/quickwit-inc/tantivy) BM25 sidecar\n  index rebuilt per indexing pass (cheap at pocket scale).\n- **Fusion**: Reciprocal Rank Fusion (`Σ 1/(60+rank)`) — no score-scale tuning,\n  robust to heterogeneous rankings.\n- **Chunking**: paragraph-first with 1000-char cap and 120-char overlap;\n  oversized paragraphs hard-split at sentence boundaries.\n\n### File types indexed by default\n`md markdown txt rst json yaml yml toml csv tsv html htm xml log rs py js jsx ts\ntsx go c h cpp hpp java rb sh bash zsh sql proto graphql dockerfile makefile ini\ncfg conf env` — extend with `-e ext1,ext2` / `\"extensions\": [...]`.\n\nIgnored dirs: **every dot-directory** (`.git .obsidian .vscode …`) plus\n`node_modules target dist build venv __pycache__ vendor`.\n\n## Privacy & footprint\n\nEverything runs locally: embeddings, storage, search. Nothing leaves the\nmachine — there is no network code path at all after installation.\n\nBinary ≈ 105 MB (the model lives inside). RAM ≈ 120 MB resident while idle,\nspiking to ~250 MB during batch embedding.\n\n## Scaling & limits\n\nquillrag stores everything in a single `redb` file and runs dense retrieval as\nan **exact, single-threaded linear scan over all vectors** — no ANN index yet.\nThat makes the relevant limit *query latency*, not storage. Storage scales to\nmillions of chunks; retrieval speed is O(N) per query.\n\n| Corpus | Vectors | Approx. RAM (f32) | Steady-state query |\n|---|---|---|---|\n| 1K chunks | 1K | ~1.5 MB | **~25 ms** (measured) |\n| 10K chunks | 10K | ~15 MB | ~250 ms (extrapolated) |\n| 100K chunks | 100K | ~154 MB | ~2–5 s (extrapolated) |\n| 1M chunks | 1M | ~1.5 GB | 20–60 s (extrapolated — not viable without ANN) |\n\n**Verified on a corpus of 1K chunks (5/5 tests including real JSON-RPC-over-stdio\ne2e); figures above 1K are extrapolated from the O(N) dense-scan cost, not\nmeasured.** A synthetic scale probe (`src/bin/quillbench.rs`) exists to measure\nthe curve on your own hardware — run `cargo build --release && ./target/release/quillbench`.\n\nWhat this means in practice:\n\n- **Great fit:** personal/local knowledge bases, project docs, notes, code —\n  up to low-tens-of-thousands of chunks where sub-second-to-interactive latency\n  holds.\n- **Away from the sweet spot:** corpora in the hundreds of thousands+ where you\n  need interactive (<200 ms) retrieval — you'll want an ANN index (see Roadmap).\n\nHow it compares to common alternatives on the *relevance* axis:\n\n- **Embedding-only (e.g. raw FAISS flat / simple vector store):** same\n  `all-MiniLM-L6-v2` ceiling as quillrag's dense path, but quillrag adds BM25 +\n  RRF fusion, which wins on keyword-heavy queries (error codes, IDs, exact\n  tokens). quillrag has no reranker or metadata filtering, which llama-index\n  offers on top.\n- **llama-index local backends:** functionally similar hybrid retrieval\n  (BM25 + vector + RRF). quillrag trades llama-index's rich reranking/parent-child\n  chunking/query-expansion for a zero-dependency single binary and instant\n  startup. Relevance on a standard dataset (BEIR/MS MARCO) is **not yet\n  benchmarked** — see the open issue tracking ANN + a relevance baseline.\n\n## Roadmap\n\nquillrag is deliberately minimal today. The big unlock is an **approximate\nnearest-neighbor index**:\n\n- **ANN (HNSW / IVF) over the dense vectors** — turns O(N) scan into\n  sub-millisecond ANN lookup, pushing the interactive ceiling from ~10K to\n  millions of chunks on a single machine.\n- **Quantization (PQ / SQ)** — drops vector RAM from 4 bytes/dim to ~1 byte/dim,\n  so 1M chunks ≈ 380 MB instead of 1.5 GB.\n- **Multi-threaded scan** — parallelize the current exact path as a stopgap.\n- **Reranker hook** — optional cross-encoder rerank of the fused top-k.\n- **Relevance benchmark** — BEIR / MS MARCO nDCG@10 vs. llama-index baselines.\n\nTrack the ANN work here: **issue #1 — \"ANN index for <1M chunks.\"**\n\n## FAQ\n\n**Is it really one file?** Yes. The MiniLM weights + tokenizer are compiled in\nvia `include_bytes!`. No `npm install`, no Python, no model download on first\nquery. The binary is ~105 MB because the model lives inside it.\n\n**Why is startup so fast?** The embedding model is *lazy*. The MCP handshake and\n`rag_status` never touch it — editors see a ready server in ~20 ms. The model\nonly loads on the first `rag_search` / `rag_index` (~300 ms one-time).\n\n**What's the largest corpus it handles?** Verified at 1K chunks (~25 ms/query).\nThe architecture scales to millions of stored chunks; interactive retrieval\nholds up to low-tens-of-thousands today, and an ANN index (Roadmap) extends that\nto 1M+.\n\n**How is this different from llama-index?** Similar hybrid retrieval quality, but\nquillrag is a single static binary with no runtime/dependency footprint and\ninstant startup. llama-index adds rerankers, sophisticated chunking, and query\nexpansion that quillrag doesn't have yet.\n\n**What file types are indexed?** `md markdown txt rst json yaml yml toml csv\ntsv html htm xml log rs py js jsx ts tsx go c h cpp hpp java rb sh bash zsh sql\nproto graphql dockerfile makefile ini cfg conf env` — extend with `-e`.\n\n**Does it phone home?** No. There is no network code path after installation.\n\n## Changelog\n\n- **v0.1.3** — MCP tool descriptions rewritten for clarity, parameter semantics,\n  and behavioral transparency (read-only/destructive flags, usage guidance);\n  server.json shipped in-repo for MCP Registry publishing.\n- **v0.1.2** — skip all dot-directories when indexing (`.obsidian` plugin configs\n  no longer pollute results); first fully automated 3-platform CI release.\n  *Upgrade note:* run `quillrag clear` once and re-index.\n- **v0.1.1** — CI-built release artifacts for linux/macos/windows with checksums.\n- **v0.1.0** — initial public release; renamed from pocketrag.\n\n## Development\n\n```sh\ncargo test                    # unit + end-to-end (spawns real stdio servers)\ncargo run -- serve            # dev server\nRUST_LOG=debug cargo run ...  # verbose logs (stderr only)\n```\n\nLicense: MIT\n",
  "bytes": 10399,
  "sha": "1d9f4a9668ddf36b3882509286cd0116dc951dd55d4f3db0817b78f1b0d7a359",
  "repo_slug": "ayush-yadav11/quillrag",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ayush_yadav11_quillrag_7cb6a472/readme"
}