quillrag

Один файл. Ноль зависимостей. Готов раньше, чем ваш редактор закончит загрузку.

Локальный RAG-движок в одном статическом бинарнике — эмбеддинги MiniLM встроены внутрь, гибридный поиск dense + 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 и позвольте ИИ искать ваши заметки прямо в ходе разговора — конфиг ниже.

$ ./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 — masked mean pooling + L2-нормализация, численно совпадает с sentence-transformers на CPU. Веса встраиваются в бинарник через include_bytes! и отображаются через mmap из материализованного кэша при первой загрузке.

• Хранилище: один файл redb — текст чанков, сырые f32-векторы, метаданные документов. Атомарные коммиты; устойчивость к сбоям.

• Ключевые слова: tantivy BM25 sidecar-индекс, пересобираемый за каждый проход индексации (дёшево при карманных масштабах).

• Слияние: 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": [...].

Игнорируемые директории: все dot-директории (.git .obsidian .vscode …) плюс node_modules target dist build venv __pycache__ vendor.

Приватность и занимаемые ресурсы

Всё работает локально: эмбеддинги, хранилище, поиск. Ничто не покидает машину — после установки в коде вообще нет сетевых путей.

Бинарник ≈ 105 МБ (модель внутри). RAM ≈ 120 МБ резидентной памяти в простое, пик до ~250 МБ при пакетной эмбеддинг-обработке.

Масштабирование и ограничения

quillrag хранит всё в одном файле redb и выполняет dense-поиск как точное, однопоточное линейное сканирование всех векторов — ANN-индекса пока нет. Поэтому релевантное ограничение — задержка запроса, а не объём хранилища. Хранилище масштабируется до миллионов чанков; скорость поиска — O(N) на запрос.

Проверено на корпусе из 1K чанков (5/5 тестов, включая реальный e2e через JSON-RPC-over-stdio); цифры выше 1K экстраполированы из стоимости O(N) dense-сканирования, а не измерены. Синтетический пробник масштабирования (src/bin/quillbench.rs) существует для измерения кривой на вашем оборудовании — запустите cargo build --release && ./target/release/quillbench.

Что это значит на практике:

• Отличное соответствие: личные/локальные базы знаний, документация проектов, заметки, код — до десятков тысяч чанков, где сохраняется задержка от субсекунды до интерактивной.

• Вне зоны комфорта: корпуса в сотни тысяч и более, где нужен интерактивный (<200 мс) поиск — вам понадобится ANN-индекс (см. Roadmap).

Как это соотносится с распространёнными альтернативами по оси релевантности:

• Только эмбеддинги (например, сырой FAISS flat / простой векторный стор): тот же потолок all-MiniLM-L6-v2, что и у dense-пути quillrag, но quillrag добавляет слияние BM25 + RRF, которое выигрывает на запросах с большим числом ключевых слов (коды ошибок, ID, точные токены). У quillrag нет реранкера или фильтрации по метаданным, которые llama-index предлагает сверху.

• Локальные бэкенды llama-index: функционально похожий гибридный поиск (BM25 + вектор + RRF). quillrag обменивает богатые возможности llama-index (реранкинг, parent-child чанкинг, расширение запросов) на один бинарник без зависимостей и мгновенный запуск. Релевантность на стандартных датасетах (BEIR/MS MARCO) ещё не бенчмаркирована — см. открытый issue, отслеживающий ANN и базовый уровень релевантности.

Roadmap

Сегодня quillrag намеренно минималистичен. Главный прорыв — индекс приблизительных ближайших соседей:

• ANN (HNSW / IVF) по dense-векторам — превращает O(N) сканирование в субмиллисекундный ANN-поиск, поднимая интерактивный потолок с ~10K до миллионов чанков на одной машине.

• Квантование (PQ / SQ) — снижает RAM для векторов с 4 байт/размерность до ~1 байта/размерность, так что 1M чанков ≈ 380 МБ вместо 1.5 ГБ.

• Многопоточное сканирование — распараллелить текущий точный путь как временное решение.

• Хук реранкера — опциональный cross-encoder реранкинг объединённого top-k.

• Бенчмарк релевантности — BEIR / MS MARCO nDCG@10 против базовых линий llama-index.

Следите за работой над ANN здесь: issue #1 — "ANN index for <1M chunks."

FAQ

Это действительно один файл? Да. Веса MiniLM + токенизатор встроены через include_bytes!. Ни npm install, ни Python, ни загрузки модели при первом запросе. Бинарник ~105 МБ, потому что модель живёт внутри.

Почему запуск такой быстрый? Модель эмбеддингов ленивая. Рукопожатие MCP и rag_status её не касаются — редакторы видят готовый сервер за ~20 мс. Модель загружается только при первом rag_search / rag_index (~300 мс однократно).

Какой максимальный корпус он обрабатывает? Проверено на 1K чанков (~25 мс/запрос). Архитектура масштабируется до миллионов хранимых чанков; интерактивный поиск держится до десятков тысяч сегодня, а ANN-индекс (Roadmap) расширяет это до 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-инструментов переписаны для ясности, семантики параметров и прозрачности поведения (флаги read-only/destructive, рекомендации по использованию); server.json включён в репозиторий для публикации в MCP Registry.

• v0.1.2 — пропуск всех dot-директорий при индексации (конфиги плагинов .obsidian больше не засоряют результаты); первый полностью автоматизированный CI-релиз для 3 платформ. Примечание по обновлению: один раз запустите 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