PicoQMD: a lightweight QMD alternative for low-resource computers
A fully local search engine and MCP server in a single ~16MB Go binary (~11MB stripped). PicoQMD is a from-scratch Go reimplementation of tobi's QMD built for machines where QMD's Node.js/Bun stack is too heavy: Raspberry Pi (including Pi Zero), old laptops, small VPSes, air-gapped boxes, and dev machines that just don't want another Node runtime.
Lightweight QMD alternative: fully local hybrid search engine (BM25 + vector + rerank) and MCP server in a single ~15MB Go binary. No Node.js. Runs on Raspberry Pi.
Estrellas
7
Herramientas
—
Disponibilidad
—
It runs the same search pipeline as QMD (SQLite FTS5 BM25, semantic vector search, hybrid query expansion + Reciprocal Rank Fusion + cross-encoder reranking, the same GGUF models) without Node.js, Bun, Python, or native-module ABI headaches. One static binary and a SQLite file.
Point Claude Code, OpenClaw, PicoClaw, MiniClaw, or any other MCP agent at it for instant local search over code, docs, configs, and notes. No cloud, no telemetry, works offline.
PicoQMD vs QMD
If you're looking for "QMD but for a lower-spec computer", this is the trade-off table:
PicoQMD is not a fork. It's an independent Go implementation that tracks QMD's retrieval design and ports the fixes that apply (v0.4.0 covered QMD v2.1 to v2.6.3; v0.5.0 covers the v2.8.x round). If you have a fast dev machine and live in the Node ecosystem, use QMD. If you want the same local search quality in a fraction of the footprint, or on hardware QMD can't run at all, use PicoQMD.
Why PicoQMD?
Most search tools assume fast hardware. PicoQMD is built for everything else:
~16MB binary (~11MB with -ldflags="-s -w"), smaller than most npm installs
~15× smaller index than QMD. The 10,800-doc corpus that filled an 11.9GB QMD index fits in 0.78GB, measured on the same machine and models
3× smaller, 3× faster vectors. Embeddings are Matryoshka-truncated to 256 dims by default (EmbeddingGemma is MRL-trained; ~97.6% of full quality). PICOQMD_EMBED_DIM overrides
Minimal RAM. BM25 mode runs in tens of MB and fits alongside an agent on $10 hardware
Zero dependencies. No runtime, no interpreters, no containers, no C toolchain (pure-Go SQLite)
MCP native. stdio and HTTP transports, works with any MCP-compatible agent
Cross-compiles anywhere Go does: ARM32, ARM64, RISC-V, x86 in one command
Scales up. Add semantic vector search and hybrid re-ranking when your hardware allows
Degrades gracefully. Without models, vector/hybrid tools are hidden from the agent; BM25, get, and observations still work
Safe under launchd/cron/systemd. Progress output auto-quiets when stdout is not a TTY, so captured logs stay bounded
What's New in v0.6.x
v0.6.1: reranker fixed. The v0.5.0 bench exposed the hybrid pipeline scoring worse than plain vector search; five compounding defects in the rerank stage (KV-cache contamination between candidates, an out-of-distribution prompt instead of Qwen3-Reranker's documented template, title-only candidate text, an RRF/rerank score-scale mismatch, and a too-small decode batch) are fixed. Measured: hybrid hit@10 60% → 100%, MRR 0.50 → 1.00 on the reference fixture, now the strongest pipeline.
v0.6.0: Matryoshka-256 vectors (full details in CHANGELOG.md):
Embeddings are truncated to 256 dims (from EmbeddingGemma's 768) and L2-renormalized, at both document and query time. 3× smaller vector storage, 3× faster brute-force scans, ~97.6% of full-dimension quality. Measured on a 10,800-doc corpus: index 853MB → 743MB, vector search 0.5s → 0.3s, bench quality within noise of 768-dim (hit@10 unchanged at 100%, MRR 1.0 → 0.9 on a 5-query fixture).
picoqmd migrate-vectors converts an existing index in place in seconds. MRL training means truncate+renormalize produces exactly what embedding at 256 dims would; no re-embed needed. Includes a VACUUM to reclaim the space.
PICOQMD_EMBED_DIM overrides the target (0 = full model dimension). The dimension is part of the embedding fingerprint, so mixed-dimension search is impossible; doctor flags mismatches.
Ports of the applicable QMD v2.8.x improvements plus hardening from a real-world failure:
Model-hash embedding fingerprints. The fingerprint now includes a sha256 of the model file's bytes, not just its name. A re-downloaded model with the same filename used to invalidate every stored vector silently; now it just triggers a re-embed.
picoqmd doctor reports model identity, per-fingerprint vector distribution, and stale or orphaned vectors, and exits non-zero on problems so cron jobs can gate on it.
picoqmd cleanup [--dry-run] deletes stale and orphaned vectors so the next sync regenerates them.
picoqmd bench <fixture.json> measures search quality (hit@k, precision, recall, MRR) per pipeline against a fixture of known-good queries. See example-bench.json.
Multi-collection scope.collection accepts a comma-separated list everywhere; each collection is searched separately and the results merged, so a big collection can't crowd a small one out of the top-k.
Intent-aware expansion. A dominant keyword match no longer skips LLM query expansion when the caller supplied an intent hint.
New -c/--collection flag on search, vsearch, and query.
Robust FTS5 queries. Version strings (v3.9.7), hyphenated terms (real-time), and operator words (AND/OR/NOT) can no longer produce FTS5 syntax errors; every term is emitted as a quoted phrase with prefix matching.
Real document retrieval.get/multi_get return content from disk with line-numbered output, qmd:// + #docid headers, and line-range refs: get notes.md:120:40 reads 40 lines from line 120. --full-path swaps in the on-disk path for piping into editors and file tools.
BM25 snippets with line citations. Snippets are extracted from the source file (>>>term<<< highlighting, path:L<n>), which also feeds the reranker real text instead of bare titles.
Embedding fingerprints. Vectors are stamped with the model + chunker identity; changing either marks documents pending for re-embed instead of silently searching stale vectors.
Honest embed tracking. A document only counts as embedded when every chunk has a current vector; interrupted embed runs resume instead of being forgotten.
Concurrency-safe SQLite. 120s busy timeout (override: PICOQMD_SQLITE_BUSY_TIMEOUT, ms) so a scheduled sync racing the MCP daemon queues instead of throwing database is locked.
Scoped embedding.picoqmd embed -c <collection> embeds one collection without re-indexing, so huge collections are opt-in.
--no-rerank skips the cross-encoder for faster hybrid results on constrained hardware.
First test suite.go test ./... covers query sanitization, retrieval, and embed tracking against a real store.
Quick Start
# Install (or grab a prebuilt binary from Releases)
go install github.com/altSeneca/picoqmd@latest
# Index markdown docs (default)
picoqmd add ~/docs --no-embed
# Index a codebase: Go, Python, TypeScript, and markdown
picoqmd add ~/myproject --glob "**/*.{go,py,ts,md}" --no-embed
# Search, with prefix matching built in
picoqmd search "kubernetes deployment"
picoqmd search "deploy" # matches "deployment", "deployed", "deploying"
# Retrieve with line ranges
picoqmd get notes.md:120:40 # 40 lines starting at line 120
MCP Server
PicoQMD is an MCP server first. Point your agent at it and you get search, get, multi_get, and status, plus vector_search, deep_search, and research when models are available.
Any agent that speaks Model Context Protocol can connect. The MCP server exposes the same search tools whether you're on a Mac Studio or a Pi Zero.
MCP Tools Reference
Tool
Description
Requires Models
search
BM25 keyword search via SQLite FTS5 with prefix matching, disk-extracted snippets, line citations
No
vector_search
Semantic similarity using embeddings
Yes
deep_search
Query expansion + fan-out + RRF + re-ranking (noExpand, noRerank to trim stages)
Yes
research
Composite: BM25 + vector in parallel, deduplicated via RRF, one call
Yes
get
Retrieve a document by path, #docid, or qmd:// URI, with :from:count line ranges, line-numbered
No
multi_get
Batch retrieve by glob or comma-separated list; oversized files reported as skipped, never silently dropped
No
status
Index health, embedding fingerprint, pending counts, stale observation count
No
Maintenance runs from the CLI: doctor diagnoses the index, cleanup [--dry-run] removes stale or orphaned vectors, and bench <fixture.json> scores search quality per pipeline.
Common parameters across search tools:
Parameter
Type
Description
query
string
Search query (required)
intent
string
Optional disambiguation hint threaded through expansion, reranking, and snippets
limit
int
Max results, default 10
collection
string
Collection name, or a comma-separated list; each is searched separately and the results merged
minScore
float
Minimum relevance score 0 to 1
maxChars
int
Truncate response to this many characters (server-side token budget)
No models, no llama.cpp, no downloads. Just Go + SQLite FTS5 with prefix matching. This is the mode for Pi-Zero-class devices where every megabyte counts: keyword search over ~10,000 documents runs in under 30MB of RAM.
Vector + hybrid, for capable hardware
picoqmd add ~/notes # downloads embedding model (~300MB)
picoqmd model download embedding # or: reranker, expansion
picoqmd "semantic search query" # auto-selects best pipeline
picoqmd embed -c big-collection # embed one collection at a time
When you have the RAM, add semantic search with query expansion, RRF fusion, and cross-encoder re-ranking. Still local, still offline. Same models QMD uses:
All three accept -c collection or -c colA,colB to scope the search.
Platform Support
Platform
BM25
Vector/Hybrid
Binary
Linux arm32 (Pi Zero, Pi 1)
yes
no
~11MB
Linux riscv64
yes
no
~10MB
Linux arm64 (Pi 3/4/5, SBCs)
yes
yes
~11MB
Linux amd64
yes
yes
~11MB
macOS arm64 (Apple Silicon)
yes
yes
~11MB
macOS amd64 (Intel)
yes
yes
~12MB
Cross-compile for your target in one line:
GOOS=linux GOARCH=arm GOARM=7 go build -ldflags="-s -w" -o picoqmd .
Export / Import: index once, search anywhere
Build a full index (with embeddings) on a capable machine, then transfer it to a tiny device:
# On your workstation
picoqmd add ~/docs && picoqmd export -o docs.tar.gz
# On a Pi Zero / edge device
picoqmd import docs.tar.gz
picoqmd search "deployment guide" # BM25 + precomputed embeddings, no models needed
The exported bundle contains the SQLite database with all embeddings baked in. The edge device gets semantic-quality ranking without downloading a single model.
Remote Search
Don't want to run search on the edge device at all? Forward to a remote instance:
PicoQMD automatically skips binary files, files over 1MB, and common noise directories (.git, node_modules, vendor, __pycache__, build, dist, target, etc.).
Use Cases
QMD alternative on low-spec hardware: the same local hybrid search without the Node.js runtime, on machines from a Pi Zero up
Claude Code MCP server: fast, token-efficient search over large codebases without spinning up Elasticsearch
PicoClaw / MiniClaw search tool: give your $10 AI agent fast local search over project docs, wikis, and codebases
OpenClaw on Raspberry Pi: add document search to your self-hosted AI assistant without eating its RAM budget
Edge AI knowledge base: deploy searchable documentation to field devices, kiosks, or air-gapped environments
Offline dev search: index API docs, READMEs, and notes for airplane-mode development
Token-efficient MCP pipelines: use research to cut context window usage by ~50% vs separate search calls
Roadmap
See ROADMAP.md. Matryoshka 768→256 truncation shipped in v0.6.0. Next up: chunk-level incremental re-embedding, recency-aware ranking, binary quantization with two-phase rescoring for very large corpora, and tree-sitter AST chunking for code.
Acknowledgments
PicoQMD is a Go reimplementation of QMD by @tobi, which provides the architecture, hybrid search pipeline, models, and design. Built with yzma (pure-Go llama.cpp bindings) and llama.cpp.
See GUIDE.md for the full user guide, output formats, and configuration.
Lightweight QMD alternative: fully local hybrid search engine (BM25 + vector + rerank) and MCP server in a single ~15MB Go binary. No Node.js. Runs on Raspberry Pi.
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Preguntas
¿Cómo instalo Picoqmd?
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
¿Picoqmd necesita una clave de API?
Este registro no indica ninguna variable de entorno obligatoria.
¿Qué transporte usa Picoqmd?
Picoqmd se ejecuta localmente por stdio.
¿Cuándo se comprobó Picoqmd por última vez?
Última comprobación: 2026-10-27. Lightweight QMD alternative: fully local hybrid search engine (BM25 + vector + rerank) and MCP server in a single ~15MB Go binary. No Node.js. Runs on Raspberry Pi.