qmd
- Repo stars 39
- Author repo awesome-omni-skill
- Domain
- AI
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @diegosouzapw · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- macOS · Linux · Windows
- Runtime requirements
- Bun
- Detected file/system behavior
-
- Read-only
- Write / modify
- Env read
- Network behavior
- Local-only
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# qmd - Local Markdown Search
Local search engine for Markdown notes, docs, and knowledge bases. Index once, search fast. Use instead of `find` for file discovery across large directories.
## Installation
```bash
bun install -g https://github.com/tobi/qmd
```
## Setup
```bash
# Add a collection
qmd collection add /path/to/your/notes --name notes --mask "**/*.md"
# Generate embeddings (required for vsearch/query)
qmd embed
# List your collections
qmd collection list
```
## When to Use
- "search my notes / docs / knowledge base"
- "find related notes"
- "find files matching [pattern]" — use instead of `find` to avoid hangs on large directories
- "what did we decide about X?"
## Default Behavior (important)
- Prefer `qmd search` (BM25) — it's instant and should be the default.
- Use `qmd vsearch` only when keyword search fails and you need semantic similarity.
- Avoid `qmd query` unless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes.
- **Always use `--json` flag** for structured output when invoking from an agent.
## Search Commands
```bash
# Fast keyword search (default)
qmd search "authentication flow" --json
qmd search "config" --json -c notes
# Semantic search (slower, for conceptual queries)
qmd vsearch "how does login work" --json
qmd vsearch "best practices for error handling" --json -n 20
# Combined with reranking (best quality, slowest)
qmd query "implementing user auth" --json
qmd query "deployment process" --json --min-score 0.5
```
### Search Mode Selection
| Mode | Speed | Quality | Best For |
|------|-------|---------|----------|
| `search` | Fast | Good | Exact keywords, known terms |
| `vsearch` | Medium | Better | Conceptual queries, synonyms |
| `query` | Slow | Best | Complex questions, uncertain terms |
### Search Options
| Option | Description |
|--------|-------------|
| `-n NUM` | Number of results (default: 5, 20 with --json) |
| `-c, --collection` | Scope to specific collection |
| `--min-score NUM` | Minimum score threshold |
| `--full` | Return complete document content |
| `--json` | Structured JSON output (agent-friendly) |
| `--files` | File paths only (fast discovery) |
| `--all` | Return all matches |
## Retrieve Documents
```bash
# Get full file
qmd get docs/guide.md --json
# Get by document hash ID
qmd get "#a1b2c3" --json
# Get specific lines
qmd get notes/meeting.md:50 -l 30 --json
# Get multiple files by glob
qmd multi-get "docs/*.md" --json
qmd multi-get "*.yaml" -l 50 --max-bytes 10240
```
## Output Formats
- `--files` — paths + scores (for file discovery)
- `--json` — structured with snippets
- `--md` — markdown formatted
- `-n 10` — limit results
## Maintenance
```bash
qmd update # Re-index changed files
qmd status # Check index health
qmd collection list # List all collections
```
## Keeping Index Fresh
```bash
# Hourly incremental updates (BM25):
0 * * * * export PATH="$HOME/.bun/bin:$PATH" && qmd update
# Optional: nightly embedding refresh:
0 5 * * * export PATH="$HOME/.bun/bin:$PATH" && qmd embed
```
## MCP Server
qmd can run as an MCP server for direct agent integration:
```bash
qmd mcp
```
Exposes tools: `qmd_search`, `qmd_vsearch`, `qmd_query`, `qmd_get`, `qmd_multi_get`, `qmd_status`
## Performance
- `qmd search` is typically instant.
- `qmd vsearch` can take ~1 minute on first run (loads local LLM).
- `qmd query` adds LLM reranking — can be slow, avoid for interactive use.
## Models (auto-downloaded)
All run locally — no API keys needed.
- Embedding: embeddinggemma-300M
- Reranking: qwen3-reranker-0.6b
- Generation: Qwen3-0.6B
- Cache location: `~/.cache/qmd/models/`
- Override with `XDG_CACHE_HOME` environment variable.
Sections and files
Listed in source order.
sections -> Installation → Setup → When to Use → Default Behavior (important) → Search Commands → Search Mode Selection
terms -> Always use --json flag · Local search engine for Markdown notes, docs, and knowledge bases. · - Prefer qmd search (BM25) — it's instant and should be the default. · - qmd search is typically instant. · All run locally — no API keys needed.
files/cmd -> find · qmd search · qmd vsearch · qmd query · --json · search · vsearch · query
body sha256 -> 73d8b9cc9658
When to Use
"search my notes / docs / knowledge base" "find related notes" "find files matching [pattern]" — use instead of
findto avoid hangs on large directories "what did we decide about X?"Default Behavior (important)
Prefer
qmd search(BM25) — it's instant and should be the default. Useqmd vsearchonly when keyword search fails and you need semantic similarity. Avoidqmd queryunless the user explicitly wants the highest quality hybrid results and can tolerate long runtimes. Always use--jsonflag for structured output when invoking from an agent.Search Mode Selection
Mode · Speed · Quality · Best For
search· Fast · Good · Exact keywords, known termsvsearch· Medium · Better · Conceptual queries, synonymsquery· Slow · Best · Complex questions, uncertain termsSearch Options
Option · Description
-n NUM· Number of results (default: 5, 20 with --json)-c, --collection· Scope to specific collection--min-score NUM· Minimum score threshold--full· Return complete document contentOutput Formats
--files— paths + scores (for file discovery)--json— structured with snippets--md— markdown formatted-n 10— limit results