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。

隐私与占用

一切都在本地运行：嵌入、存储、搜索。没有任何内容离开机器——安装后完全没有网络代码路径。

二进制约 105 MB（模型内置）。空闲时 RAM 约 120 MB 常驻，批量嵌入时峰值约 250 MB。

扩展性与限制

quillrag 将所有内容存储在单个 redb 文件中，并将稠密检索作为精确、单线程线性扫描所有向量执行——目前没有 ANN 索引。因此相关限制是查询延迟，而不是存储。存储可扩展到数百万个分块；检索速度为每次查询 O(N)。

已在 1K 分块语料库上验证（5/5 测试，包括真实的 JSON-RPC-over-stdio 端到端测试）；1K 以上的数据是从 O(N) 稠密扫描成本外推的，而非实测。 存在一个合成规模探针（src/bin/quillbench.rs）用于在您自己的硬件上测量曲线——运行 cargo build --release && ./target/release/quillbench。

这在实践中意味着什么：

• 非常适合： 个人/本地知识库、项目文档、笔记、代码——最多数万低量级分块，此时亚秒到交互式延迟可保持。

• 远离最佳点： 数十万以上的语料库，需要交互式（<200 毫秒）检索——您需要 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 和相关性基线的开放问题。

路线图

quillrag 目前刻意保持极简。最大的解锁是近似最近邻索引：

• 对稠密向量进行 ANN（HNSW / IVF）——将 O(N) 扫描变为亚毫秒级 ANN 查找，将交互式上限从约 10K 推高到单机数百万分块。

• 量化（PQ / SQ）——将向量 RAM 从 4 字节/维降至约 1 字节/维，因此 1M 分块约 380 MB 而不是 1.5 GB。

• 多线程扫描——并行化当前精确路径作为临时措施。

• 重排序器钩子——对融合后的 top-k 进行可选的交叉编码器重排序。

• 相关性基准——BEIR / MS MARCO nDCG@10 对比 llama-index 基线。

在此跟踪 ANN 工作：issue #1 — “ANN index for <1M chunks.”

常见问题

它真的只有一个文件吗？ 是的。MiniLM 权重和分词器通过 include_bytes! 编译进去。无需 npm install、无需 Python、首次查询无需下载模型。二进制约 105 MB，因为模型内置其中。

为什么启动这么快？ 嵌入模型是惰性的。MCP 握手和 rag_status 从不触碰它——编辑器在约 20 毫秒内看到就绪的服务器。模型仅在首次 rag_search / rag_index 时加载（约 300 毫秒一次性）。

它能处理的最大语料库是多少？ 已在 1K 分块上验证（约 25 毫秒/查询）。架构可扩展到数百万存储分块；交互式检索目前可保持到数万低量级，ANN 索引（路线图）将其扩展到 1M+。

这与 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 工具描述以提高清晰度、参数语义和行为透明度（只读/破坏性标志、使用指南）；在仓库中提供 server.json 用于 MCP Registry 发布。

• v0.1.2 — 索引时跳过所有点目录（.obsidian 插件配置不再污染结果）；首次全自动 3 平台 CI 发布。升级说明： 运行一次 quillrag clear 并重新索引。

• v0.1.1 — CI 构建的 linux/macos/windows 发布工件，带校验和。

• 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