quillrag
quillrag
Eine Datei. Null Abhängigkeiten. Bereit, bevor dein Editor fertig geladen hat.
Eine lokale RAG-Engine in einer einzigen statischen Binärdatei – MiniLM-Embeddings einkompiliert, hybrides Dense- + BM25-Retrieval, MCP-nativ. Kein Node, kein Python, kein Modell-Download bei der ersten Abfrage.
Warum quillrag
~20 ms bis bereit | Der MCP-Handshake ist abgeschlossen, bevor das Modell überhaupt lädt |
Keine Laufzeitabhängigkeiten | kein Node, kein Python, kein pip/npm, keine Modell-Downloads – niemals |
Hybrid-Retrieval | Dense-Cosine ⊕ BM25, fusioniert mit Reciprocal Rank Fusion |
Privat durch Konstruktion | kein Netzwerk-Codepfad nach der Installation |
Eine Datei, drei Betriebssysteme | ~105 MB (das Modell lebt darin), CI-gebaut für linux/macOS/Windows |
Related MCP server: mcp-fts5-starter
Schnellstart
# 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"Oder binde es direkt in Claude Desktop / Cursor ein und lass die KI deine Notizen mitten im Gespräch durchsuchen – Konfiguration unten.
$ ./quillrag serve --data-dir ~/.local/share/quillrag
2026-08-26 INFO quillrag 0.1.2 ready in 41ms <- handshake-ready before the model loadsWarum es schnell ist
Phase | Aufwand |
Binärstart + MCP-Initialisierung | ~20 ms (gemessen: nur Store-Öffnung + Tool-Registrierung) |
Erster | +~300 ms einmalig (mmap safetensors, BERT-Graph aufbauen) |
Nachfolgende Suchen | ~25 ms pro Abfrage (2-Kern-CPU, kleiner Korpus) |
Neuindizierung unveränderten Korpus | nahezu null (Überspringen per FNV-Inhaltshash) |
Das Embedding-Modell ist lazy: Der MCP-Handshake und rag_status berühren es nie, daher sehen Editoren einen sofort bereiten Server.
Installation
Lade ein vorgefertigtes Archiv aus dem neuesten Release herunter – Windows x86_64, macOS Apple Silicon und Linux x86_64 werden von CI bei jedem Versions-Tag gebaut:
# linux/macOS example: fetch + extract the latest release
gh release download --repo Ayush-yadav11/quillrag -p '*linux*' | tar xz
chmod +x quillrag && ./quillrag --versionOder aus dem Quellcode bauen:
cargo install --path .Von CI verwendete Cross-Compile-Ziele: x86_64-unknown-linux-gnu, aarch64-apple-darwin, x86_64-pc-windows-msvc.
In deinen Editor einbinden
Claude Desktop / Cursor / jeder MCP-Client:
{
"mcpServers": {
"quillrag": {
"command": "/usr/local/bin/quillrag",
"args": ["serve"],
"env": { "QUILLRAG_DATA": "~/.local/share/quillrag" }
}
}
}Oder führe einfach ./quillrag serve aus und richte einen beliebigen stdio-Client darauf aus.
Tools
Tool | Funktion |
| Indiziert inkrementell ein Verzeichnis/eine Datei. Überspringt unveränderte Dateien, entfernt gelöschte, bettet nur Änderungen neu ein. |
| Hybride Suche: Dense-MiniLM-Cosine + BM25-Keywords, fusioniert mit Reciprocal Rank Fusion. Liefert gerankte Chunks mit Quellpfaden. |
| Dokument-/Chunk-Anzahl, indizierte Bytes, Dateityp-Aufschlüsselung. |
| Alles löschen. |
CLI-Äquivalente (gleiche Engine):
quillrag index ~/notes # incremental walk
quillrag search "auth flow" -k 5 # one-shot search
quillrag status # stats
quillrag clear # wipeDesign
Embeddings: candle (reines Rust) mit
sentence-transformers/all-MiniLM-L6-v2– maskiertes Mean-Pooling + L2-Norm, numerisch übereinstimmend mit sentence-transformers auf der CPU. Die Gewichte werden perinclude_bytes!in die Binärdatei eingebettet und beim ersten Laden aus einem materialisierten Cache gemappt (mmap).Speicher: eine einzige redb-Datei – Chunk-Text, rohe f32-Vektoren, Dokument-Metadaten. Atomare Commits; absturzsicher.
Keywords: tantivy BM25-Sidecar-Index, der bei jedem Indizierungslauf neu aufgebaut wird (günstig bei kleinen Datenmengen).
Fusion: Reciprocal Rank Fusion (
Σ 1/(60+rank)) – keine Score-Skalierungs-Anpassung, robust gegenüber heterogenen Rankings.Chunking: absatzbasiert mit 1000-Zeichen-Limit und 120-Zeichen-Überlappung; überlange Absätze werden an Satzgrenzen hart geteilt.
Standardmäßig indizierte Dateitypen
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 – erweitern mit -e ext1,ext2 / "extensions": [...].
Ignorierte Verzeichnisse: jedes Dot-Verzeichnis (.git .obsidian .vscode …) sowie node_modules target dist build venv __pycache__ vendor.
Datenschutz & Ressourcenbedarf
Alles läuft lokal: Embeddings, Speicher, Suche. Nichts verlässt die Maschine – es gibt nach der Installation überhaupt keinen Netzwerk-Codepfad.
Binärdatei ≈ 105 MB (das Modell lebt darin). RAM ≈ 120 MB resident im Leerlauf, mit Spitzen von ~250 MB während des Batch-Embeddings.
Skalierung & Grenzen
quillrag speichert alles in einer einzigen redb-Datei und führt das Dense-Retrieval als exakten, single-threaded linearen Scan über alle Vektoren aus – noch kein ANN-Index. Dadurch ist die relevante Grenze Abfragelatenz, nicht Speicher. Der Speicher skaliert auf Millionen von Chunks; die Abrufgeschwindigkeit ist O(N) pro Abfrage.
Korpus | Vektoren | Ca. RAM (f32) | Abfrage im Dauerbetrieb |
1K Chunks | 1K | ~1.5 MB | ~25 ms (gemessen) |
10K Chunks | 10K | ~15 MB | ~250 ms (hochgerechnet) |
100K Chunks | 100K | ~154 MB | ~2–5 s (hochgerechnet) |
1M Chunks | 1M | ~1.5 GB | 20–60 s (hochgerechnet — ohne ANN nicht praktikabel) |
Verifiziert an einem Korpus von 1K Chunks (5/5 Tests inklusive echtem JSON-RPC-over-stdio-E2E); Werte über 1K sind aus den O(N)-Kosten des Dense-Scans hochgerechnet, nicht gemessen. Eine synthetische Skalierungssonde (src/bin/quillbench.rs) existiert, um die Kurve auf deiner eigenen Hardware zu messen – führe cargo build --release && ./target/release/quillbench aus.
Was das in der Praxis bedeutet:
Sehr gut geeignet: persönliche/lokale Wissensdatenbanken, Projektdokumentationen, Notizen, Code – bis zu einigen Zehntausend Chunks, wo Latenzen von unter einer Sekunde bis interaktiv gelten.
Außerhalb des Optimalbereichs: Korpora mit mehreren hunderttausend Chunks und mehr, wo du interaktive (<200 ms) Suche benötigst – dann brauchst du einen ANN-Index (siehe Roadmap).
So schneidet es im Vergleich zu gängigen Alternativen auf der Relevanz-Achse ab:
Nur-Embedding (z. B. rohes FAISS-Flat / einfacher Vektor-Store): gleiche
all-MiniLM-L6-v2-Obergrenze wie quillrags Dense-Pfad, aber quillrag fügt BM25 + RRF-Fusion hinzu, die bei keyword-lastigen Abfragen (Fehlercodes, IDs, exakte Tokens) gewinnt. quillrag hat keinen Reranker und keine Metadatenfilterung, die llama-index zusätzlich bietet.llama-index lokale Backends: funktional ähnliches Hybrid-Retrieval (BM25 + Vektor + RRF). quillrag tauscht llama-index' umfangreiches Reranking/Parent-Child-Chunking/Query-Expansion gegen eine einzige Binärdatei ohne Abhängigkeiten und sofortigen Start. Die Relevanz auf einem Standarddatensatz (BEIR/MS MARCO) ist noch nicht benchmarkt – siehe das offene Issue, das ANN + eine Relevanz-Baseline verfolgt.
Roadmap
quillrag ist heute bewusst minimal. Der große Durchbruch ist ein Approximate-Nearest-Neighbor-Index:
ANN (HNSW / IVF) über die Dense-Vektoren – verwandelt den O(N)-Scan in eine ANN-Suche im Sub-Millisekundenbereich und hebt die interaktive Grenze von ~10K auf Millionen von Chunks auf einer einzigen Maschine.
Quantisierung (PQ / SQ) – reduziert den Vektor-RAM von 4 Bytes/Dim auf ~1 Byte/Dim, sodass 1M Chunks ≈ 380 MB statt 1,5 GB benötigen.
Multithreaded-Scan – parallelisiert den aktuellen exakten Pfad als Übergangslösung.
Reranker-Hook – optionales Cross-Encoder-Reranking der fusionierten Top-k.
Relevanz-Benchmark – BEIR / MS MARCO nDCG@10 vs. llama-index-Baselines.
Verfolge die ANN-Arbeit hier: issue #1 — "ANN index for <1M chunks."
FAQ
Ist es wirklich eine Datei? Ja. Die MiniLM-Gewichte + Tokenizer sind per include_bytes! einkompiliert. Kein npm install, kein Python, kein Modell-Download bei der ersten Abfrage. Die Binärdatei ist ~105 MB groß, weil das Modell darin lebt.
Warum ist der Start so schnell? Das Embedding-Modell ist lazy. Der MCP-Handshake und rag_status berühren es nie – Editoren sehen einen bereiten Server in ~20 ms. Das Modell lädt nur beim ersten rag_search / rag_index (~300 ms einmalig).
Was ist der größte Korpus, den es verarbeitet? Verifiziert bei 1K Chunks (~25 ms/Abfrage). Die Architektur skaliert auf Millionen gespeicherter Chunks; interaktive Suche gilt heute bis zu einigen Zehntausend, und ein ANN-Index (Roadmap) erweitert das auf 1M+.
Wie unterscheidet sich das von llama-index? Ähnliche Qualität der hybriden Suche, aber quillrag ist eine einzige statische Binärdatei ohne Laufzeit-/Abhängigkeits-Fußabdruck und mit sofortigem Start. llama-index bietet Reranker, ausgefeiltes Chunking und Query-Expansion, die quillrag noch nicht hat.
Welche Dateitypen werden indiziert? 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 – erweitern mit -e.
Sendet es Daten nach Hause? Nein. Es gibt nach der Installation keinen Netzwerk-Codepfad.
Changelog
v0.1.3 – MCP-Toolbeschreibungen für Klarheit, Parametersemantik und Verhaltenstransparenz neu geschrieben (Read-only/destruktive Flags, Nutzungshinweise); server.json im Repo für die MCP-Registry-Veröffentlichung enthalten.
v0.1.2 – überspringt beim Indizieren alle Dot-Verzeichnisse (
.obsidian-Plugin-Konfigurationen verschmutzen die Ergebnisse nicht mehr); erstes vollautomatisiertes CI-Release für 3 Plattformen. Hinweis zum Upgrade:quillrag cleareinmal ausführen und neu indizieren.v0.1.1 – CI-gebauten Release-Artefakte für linux/macos/windows mit Prüfsummen.
v0.1.0 – erste öffentliche Veröffentlichung; umbenannt von pocketrag.
Entwicklung
cargo test # unit + end-to-end (spawns real stdio servers)
cargo run -- serve # dev server
RUST_LOG=debug cargo run ... # verbose logs (stderr only)Lizenz: 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.36 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