Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
name
qmd
description
Search personal knowledge bases, notes, docs, and meeting transcripts locally using qmd — a hybrid retrieval engine with BM25, vector search, and LLM reranking. Supports CLI and MCP integration.
Local, on-device search engine for personal knowledge bases. Indexes markdown
notes, meeting transcripts, documentation, and any text-based files, then
provides hybrid search combining keyword matching, semantic understanding, and
LLM-powered reranking — all running locally with no cloud dependencies.
User asks to search their notes, docs, knowledge base, or meeting transcripts
User wants to find something across a large collection of markdown/text files
User wants semantic search ("find notes about X concept") not just keyword grep
User has already set up qmd collections and wants to query them
User asks to set up a local knowledge base or document search system
Keywords: "search my notes", "find in my docs", "knowledge base", "qmd"
Prerequisites
Node.js >= 22 (required)
# Check version
node --version # must be >= 22# macOS — install or upgrade via Homebrew
brew install node@22
# Linux — use NodeSource or nvm
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# or with nvm:
nvm install 22 && nvm use 22
SQLite with Extension Support (macOS only)
macOS system SQLite lacks extension loading. Install via Homebrew:
brew install sqlite
Install qmd
npm install -g @tobilu/qmd
# or with Bun:
bun install -g @tobilu/qmd
First run auto-downloads 3 local GGUF models (~2GB total):
Model
Purpose
Size
embeddinggemma-300M-Q8_0
Vector embeddings
~300MB
qwen3-reranker-0.6b-q8_0
Result reranking
~640MB
qmd-query-expansion-1.7B
Query expansion
~1.1GB
Verify Installation
qmd --version
qmd status
Quick Reference
Command
What It Does
Speed
qmd search "query"
BM25 keyword search (no models)
~0.2s
qmd vsearch "query"
Semantic vector search (1 model)
~3s
qmd query "query"
Hybrid + reranking (all 3 models)
~2-3s warm, ~19s cold
qmd get <docid>
Retrieve full document content
instant
qmd multi-get "glob"
Retrieve multiple files
instant
qmd collection add <path> --name <n>
Add a directory as a collection
instant
qmd context add <path> "description"
Add context metadata to improve retrieval
instant
qmd embed
Generate/update vector embeddings
varies
qmd status
Show index health and collection info
instant
qmd mcp
Start MCP server (stdio)
persistent
qmd mcp --http --daemon
Start MCP server (HTTP, warm models)
persistent
Setup Workflow
1. Add Collections
Point qmd at directories containing your documents:
# Add a notes directory
qmd collection add ~/notes --name notes
# Add project docs
qmd collection add ~/projects/myproject/docs --name project-docs
# Add meeting transcripts
qmd collection add ~/meetings --name meetings
# List all collections
qmd collection list
2. Add Context Descriptions
Context metadata helps the search engine understand what each collection
contains. This significantly improves retrieval quality:
qmd context add qmd://notes "Personal notes, ideas, and journal entries"
qmd context add qmd://project-docs "Technical documentation for the main project"
qmd context add qmd://meetings "Meeting transcripts and action items from team syncs"
3. Generate Embeddings
qmd embed
This processes all documents in all collections and generates vector
embeddings. Re-run after adding new documents or collections.
4. Verify
qmd status # shows index health, collection stats, model info
Search Patterns
Fast Keyword Search (BM25)
Best for: exact terms, code identifiers, names, known phrases.
No models loaded — near-instant results.
Best for: natural language questions, conceptual queries.
Loads embedding model (~3s first query).
qmd vsearch "how does the rate limiter handle burst traffic"
qmd vsearch "ideas for improving onboarding flow"
Hybrid Search with Reranking (Best Quality)
Best for: important queries where quality matters most.
Uses all 3 models — query expansion, parallel BM25+vector, reranking.
qmd query "what decisions were made about the database migration"
Structured Multi-Mode Queries
Combine different search types in a single query for precision:
# BM25 for exact term + vector for concept
qmd query $'lex: rate limiter\nvec: how does throttling work under load'# With query expansion
qmd query $'expand: database migration plan\nlex: "schema change"'
Query Syntax (lex/BM25 mode)
Syntax
Effect
Example
term
Prefix match
perf matches "performance"
"phrase"
Exact phrase
"rate limiter"
-term
Exclude term
performance -sports
HyDE (Hypothetical Document Embeddings)
For complex topics, write what you expect the answer to look like:
qmd query $'hyde: The migration plan involves three phases. First, we add the new columns without dropping the old ones. Then we backfill data. Finally we cut over and remove legacy columns.'
qmd search "query" --json # JSON output (best for parsing)
qmd search "query" --limit 5 # Limit results
qmd get "#abc123"# Get by document ID
qmd get "path/to/file.md"# Get by file path
qmd get "file.md:50" -l 100 # Get specific line range
qmd multi-get "journals/*.md" --json # Batch retrieve by glob
MCP Integration (Recommended)
qmd exposes an MCP server that provides search tools directly to
Zeus Agent via the native MCP client. This is the preferred
integration — once configured, the agent gets qmd tools automatically
without needing to load this skill.
Once connected, these tools are available as mcp_qmd_*:
MCP Tool
Maps To
Description
mcp_qmd_search
qmd search
BM25 keyword search
mcp_qmd_vsearch
qmd vsearch
Semantic vector search
mcp_qmd_deep_search
qmd query
Hybrid search + reranking
mcp_qmd_get
qmd get
Retrieve document by ID or path
mcp_qmd_status
qmd status
Index health and stats
The MCP tools accept structured JSON queries for multi-mode search:
{"searches":[{"type":"lex","query":"authentication middleware"},{"type":"vec","query":"how user login is verified"}],"collections":["project-docs"],"limit":10}
CLI Usage (Without MCP)
When MCP is not configured, use qmd directly via terminal:
terminal(command="qmd query 'what was decided about the API redesign' --json", timeout=30)
For setup and management tasks, always use terminal:
terminal(command="qmd collection add ~/Documents/notes --name notes")
terminal(command="qmd context add qmd://notes 'Personal research notes and ideas'")
terminal(command="qmd embed")
terminal(command="qmd status")
How the Search Pipeline Works
Understanding the internals helps choose the right search mode:
Query Expansion — A fine-tuned 1.7B model generates 2 alternative
queries. The original gets 2x weight in fusion.
Parallel Retrieval — BM25 (SQLite FTS5) and vector search run
simultaneously across all query variants.
