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에 직접 연결하여 대화 중에 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

빠른 이유

임베딩 모델은 지연(lazy) 방식입니다: 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": [...]로 확장하세요.

무시되는 디렉터리: 모든 점(dot) 디렉터리 (.git .obsidian .vscode …) 및 node_modules target dist build venv __pycache__ vendor.

개인정보 보호 및 리소스 사용량

모든 것이 로컬에서 실행됩니다: 임베딩, 저장, 검색. 어떤 것도 머신을 떠나지 않습니다 — 설치 후 네트워크 코드 경로가 전혀 없습니다.

바이너리 ≈ 105 MB (모델이 내장됨). 유휴 상태에서 RAM ≈ 120 MB 상주, 배치 임베딩 중 ~250 MB까지 급증.

확장성 및 한계

quillrag는 모든 것을 단일 redb 파일에 저장하고 dense 검색을 모든 벡터에 대한 정확한 단일 스레드 선형 스캔으로 실행합니다 — 아직 ANN 인덱스는 없습니다. 따라서 관련 한계는 쿼리 지연 시간이지 저장소가 아닙니다. 저장소는 수백만 청크까지 확장되지만, 검색 속도는 쿼리당 O(N)입니다.

1K 청크 코퍼스에서 검증됨 (실제 JSON-RPC-over-stdio e2e를 포함한 5/5 테스트); 1K 이상의 수치는 O(N) dense 스캔 비용에서 추정된 것이지 측정된 것이 아닙니다. 자체 하드웨어에서 곡선을 측정하기 위한 합성 스케일 프로브(src/bin/quillbench.rs)가 있습니다 — cargo build --release && ./target/release/quillbench를 실행하세요.

실제로 의미하는 바:

• 적합한 경우: 개인/로컬 지식 베이스, 프로젝트 문서, 노트, 코드 — 서브초에서 인터랙티브 지연 시간이 유지되는 수만 개 이하의 청크.

• 최적 범위를 벗어난 경우: 수십만 개 이상의 코퍼스에서 인터랙티브(<200 ms) 검색이 필요하다면 — ANN 인덱스가 필요합니다 (로드맵 참조).

일반적인 대안과 관련성 측면에서 비교하면:

• 임베딩 전용 (예: raw FAISS flat / 단순 벡터 스토어): quillrag의 dense 경로와 동일한 all-MiniLM-L6-v2 상한이지만, quillrag는 BM25 + RRF 융합을 추가하여 키워드 중심 쿼리(오류 코드, ID, 정확한 토큰)에서 우세합니다. quillrag에는 llama-index가 추가로 제공하는 리랭커나 메타데이터 필터링이 없습니다.

• llama-index 로컬 백엔드: 기능적으로 유사한 하이브리드 검색 (BM25 + vector + RRF). quillrag는 llama-index의 풍부한 리랭킹/부모-자식 청킹/쿼리 확장을 제로 의존성 단일 바이너리와 즉시 시작으로 맞바꿉니다. 표준 데이터셋(BEIR/MS MARCO)에서의 관련성은 아직 벤치마크되지 않았습니다 — ANN 및 관련성 기준선을 추적하는 공개 이슈를 참조하세요.

로드맵

quillrag는 오늘날 의도적으로 최소한입니다. 가장 큰 돌파구는 근사 최근접 이웃 인덱스입니다:

• dense 벡터에 대한 ANN (HNSW / IVF) — O(N) 스캔을 서브밀리초 ANN 조회로 바꾸어 인터랙티브 상한을 단일 머신에서 ~10K에서 수백만 청크로 끌어올립니다.

• 양자화 (PQ / SQ) — 벡터 RAM을 4 bytes/dim에서 ~1 byte/dim으로 줄여 1M 청크가 1.5 GB 대신 ≈ 380 MB가 됩니다.

• 멀티스레드 스캔 — 현재 정확 경로를 임시 방편으로 병렬화.

• 리랭커 훅 — 융합된 top-k에 대한 선택적 크로스 인코더 리랭크.

• 관련성 벤치마크 — BEIR / MS MARCO nDCG@10 vs. llama-index 기준선.

ANN 작업은 여기에서 추적하세요: issue #1 — "1M 청크 미만용 ANN 인덱스."

자주 묻는 질문

정말 하나의 파일인가요? 네. MiniLM 가중치 + 토크나이저가 include_bytes!로 컴파일되어 있습니다. npm install도, Python도, 첫 쿼리 시 모델 다운로드도 없습니다. 바이너리가 ~105 MB인 이유는 모델이 내부에 있기 때문입니다.

왜 시작이 그렇게 빠른가요? 임베딩 모델이 지연(lazy) 방식이기 때문입니다. MCP 핸드셰이크와 rag_status는 모델을 건드리지 않으므로 에디터는 ~20 ms 안에 준비된 서버를 볼 수 있습니다. 모델은 첫 rag_search / rag_index에서만 로드됩니다 (~300 ms 일회성).

처리할 수 있는 최대 코퍼스는? 1K 청크에서 검증되었습니다 (~25 ms/쿼리). 아키텍처는 수백만 개의 저장된 청크로 확장되며, 현재 인터랙티브 검색은 수만 개 이하에서 유지되고, 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 도구 설명을 명확성, 매개변수 의미, 동작 투명성(읽기 전용/파괴적 플래그, 사용 지침)을 위해 재작성; 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