rqmd

Rust-based mini CLI search engine for your docs, knowledge bases, meeting notes, whatever. Tracking current SOTA approaches while being all local.

Hybrid local document search in a single static binary. No Node. No Bun. No native-module rebuild per platform. Build once, run anywhere.

Built on the search pipeline and ideas of tobi/qmd. Coming from qmd? See Migrating from qmd.

Documentation

This README covers the essentials. Everything else lives in docs/:

Also: CONTRIBUTING.md · SECURITY.md · DISCLAIMER.md

---

Why Rust

rqmd ships as a ~60MB self-contained binary with no runtime dependencies:

• SQLite bundled via rusqlite — no system SQLite dependency
• BM25 via Tantivy (pure Rust) — no FTS5 extension
• Vector search via usearch (HNSW, C++ header-only, statically linked)
• Inference via llama-cpp-2 (Metal on macOS, CPU on Linux/Windows)

---

Features

Plain-text queries are auto-expanded by a local Qwen3-1.7B model into lex/vec/hyde sub-queries fused with the original via RRF. Details: docs/CLI.md and docs/SYNTAX.md.

---

Installation

# Homebrew (macOS / Linux — prebuilt, no compile)
brew tap tylern91/rqmd
brew trust tylern91/rqmd  # required on Homebrew ≥4.5
brew install rqmd

# cargo (source build, cross-platform — requires Rust ≥1.78, cmake ≥3.14)
cargo install --git https://github.com/tylern91/rqmd --locked rqmd-cli

Prebuilt binary downloads, building from source, the ONNX Runtime backend, and Linux/MUSL static builds: docs/INSTALL.md.

---

Quick start

# Index a directory
rqmd collection add ~/notes --name notes
rqmd context add rqmd://notes/ "Personal notes and ideas"
rqmd embed                          # downloads GGUF models on first run (~900MB)

# Search
rqmd search "project timeline"      # BM25 keyword
rqmd vsearch "deployment process"   # vector similarity
rqmd query "quarterly planning"     # hybrid BM25 + vector + rerank + LLM expansion (best quality)
rqmd similar notes/project-plan.md  # find documents most similar to an already-indexed one

# MCP server (for Claude, Cursor, etc.)
rqmd mcp                            # stdio transport
rqmd mcp --http --port 8181         # Streamable HTTP transport

---

CLI reference

Full command table, global flags, and query flags (--intent, --format, candidate-pool sizing): docs/CLI.md.

---

Query syntax and expansion

rqmd query auto-expands plain-text queries into lex/vec/hyde sub-queries via a local LLM, fused with RRF. rqmd search/rqmd vsearch run a single mode directly, with no expansion. Typed multi-line queries, the --intent flag, and the full grammar (phrase/negation operators, MCP searches array) are documented in docs/SYNTAX.md and docs/CLI.md.

---

Contributing

See CONTRIBUTING.md for the full guide — GPG-signing requirement, commit/branch conventions, the CHANGELOG + semver-label convention, and what not to rely on yet.

The non-obvious part is the search-quality gate, rqmd eval — run it before any change that touches the search path:

# BM25 quality (no model, fast — run this always)
cargo run -p rqmd-cli -- eval --mode bm25 --verbose

# Full hybrid quality (requires models — run before search-path changes)
RQMD_INFERENCE_BACKEND=llama cargo run -p rqmd-cli -- eval --mode hybrid

# Embed throughput (compare backends)
cargo run -p rqmd-cli -- bench -n 5

The BM25 eval also runs in CI on every push.

See also: SECURITY.md for vulnerability reporting and the known MCP-listener authentication boundary, and DISCLAIMER.md for license, warranty, and no-telemetry terms.

---

Acknowledgements

rqmd is a Rust port of tobi/qmd — the original TypeScript hybrid-search CLI by @tobi. The search pipeline design, RRF fusion formula, BM25 field weights, chunking parameters, docid scheme, and MCP tool surface are all derived from that project. See BENCHMARK.md for the de-risking spike results that validated the Rust technology choices.

Coming from qmd? The quickest path:

# macOS / Linux — prebuilt binary, no compiler needed
brew tap tylern91/rqmd && brew trust tylern91/rqmd && brew install rqmd

# or build from source
git clone https://github.com/tylern91/rqmd && cd rqmd
./scripts/install.sh          # builds + installs rqmd to ~/.cargo/bin/

rqmd collection add ~/notes   # same pattern as qmd
rqmd embed                    # downloads models on first run (~900 MB)

Your existing collections need to be re-added (rqmd uses its own index at ~/.cache/rqmd/ on Linux, ~/Library/Caches/rqmd/ on macOS), but the search commands and MCP surface work the same way. See Migrating from qmd for the full env-var mapping.