QMD - Local Wiki Search Engine
On-device hybrid search engine for the wiki. BM25 + vector + LLM reranking, all local via GGUF models. The tool that makes the wiki a brain, not just a folder of files.
Why qmd
At ~100 pages, _index.md is enough for navigation. At 178+ pages and growing, agents
need real search - keyword for exact names, semantic for conceptual questions, and
re-ranking to surface the best results. qmd provides all three without external APIs,
cloud services, or API keys. Source: https://github.com/tobi/qmd; AGENTS.md
The wiki is the single source of truth across all agents. qmd is the retrieval layer that makes it queryable. Together they implement the brain-agent loop: every agent session can search the wiki before responding, and every answer that adds value gets filed back.
Architecture
┌──────────────────┐ ┌───────────────┐ ┌──────────────────┐
│ Wiki (git) │ │ qmd │ │ AI Agent │
│ │ │ (retrieval) │ │ │
│ markdown files │───>│ SQLite + │<──>│ search before │
│ = source of │ │ BM25 + vec │ │ answering │
│ truth │ │ │ │ │
│ human can │<───│ hybrid │ │ write back │
│ always read │ │ search │ │ valuable answers│
│ & edit │ │ (all local) │ │ │
└──────────────────┘ └───────────────┘ └──────────────────┘
Setup
npm install -g @tobilu/qmd
qmd collection add ~/Documents/GitHub/kevin-wiki/wiki --name wiki
qmd context add qmd://wiki "Kevin Liu's personal LLM wiki..."
qmd embed
Models auto-download on first use (~2GB total):
- embeddinggemma-300M - vector embeddings (300MB)
- qwen3-reranker-0.6b - re-ranking (640MB)
- qmd-query-expansion-1.7B - query expansion (1.1GB)
All cached in ~/.cache/qmd/models/. Index lives at ~/.cache/qmd/index.sqlite.
Search Modes
| Mode | Command | Speed | Best for |
|---|---|---|---|
| Keyword (BM25) | qmd search "term" |
Fastest | Known names, exact matches |
| Semantic (vector) | qmd vsearch "concept" |
Fast | Fuzzy meaning, conceptual queries |
| Hybrid + rerank | qmd query "question" |
Best quality | Complex questions, synthesis |
Agent Integration
MCP Server (recommended)
Configured in .cursor/mcp.json:
{ "mcpServers": { "qmd": { "command": "qmd", "args": ["mcp"] } } }
Exposes 4 tools: query, get, multi_get, status.
CLI with structured output
qmd search "authentication" --json -n 10
qmd query "error handling" --all --files --min-score 0.4
qmd get "skills/agent-browser.md" --full
Keeping the Index Current
After adding or modifying wiki pages:
qmd update && qmd embed
The qmd update command re-indexes changed files (by content hash). qmd embed generates
vectors for new chunks only. Both are incremental and fast.
Context System
Context metadata improves search relevance. Attached to collections and paths:
qmd context add qmd://wiki "Personal LLM wiki covering skills, tools, design..."
qmd context add qmd://wiki/skills "Agent skill documentation and best practices"
qmd context add qmd://wiki/architecture "System architecture and design decisions"
Context strings are returned alongside search results, helping agents understand what they're looking at before reading the full document.
Compared To
- gbrain - Postgres + pgvector, designed for 10K+ file people/company CRMs. Requires Supabase ($25/mo) + OpenAI key. Overkill for a technical knowledge base; ideal for a CEO tracking 3,000+ people.
- grep/ripgrep - Works at small scale but misses conceptual matches. "How should I structure animations" won't find a page titled "Motion 3D Playbook."
_index.mdscan - The current approach. Works but requires reading the full index into context on every query. qmd is more token-efficient and finds better matches.- RAG (cloud) - Requires API calls, chunking pipeline, vector DB hosting. qmd does all of this locally in one binary.
Timeline
- 2026-07-13 | Reinstalled
@tobilu/qmd2.5.3 under Node 24, recreated the canonicalwikicollection and Kevin-specific root context, rebuilt lexical and semantic indexes, and restored QMD to the globally projected Cursor MCP configuration. Source: User request, 2026-07-13; localqmd status; https://github.com/tobi/qmd - 2026-06-17 | Added provenance and tied qmd to the brain-first lookup rule in AGENTS and the operations hub. Source: AGENTS.md; Agent Operations Hub
- 2026-04-10 | Created local wiki search-engine page for qmd setup and agent integration. Source: https://github.com/tobi/qmd