---
name: qmd
description: Search markdown knowledge bases, notes, and documentation using the qmd CLI. Use when searching notes, finding documents, or looking up information in the knowledge base.
license: MIT
compatibility: Requires qmd CLI. Install via `npm install -g @tobilu/qmd`.
metadata:
  author: tobi
  version: "2.0.0"
allowed-tools: Bash(qmd:*)
---

# QMD - Quick Markdown Search

Local search engine for markdown content. Use via the `qmd` CLI (bash).

## Status

!`qmd status 2>/dev/null || echo "Not installed: npm install -g @tobilu/qmd"`

## CLI Usage

```bash
qmd query "question"                        # Auto-expand + rerank (recommended)
qmd query $'lex: X\nvec: Y'                 # Structured query document
qmd query $'expand: question'              # Explicit expand
qmd search "keywords"                       # BM25 only (no LLM)
qmd get "path/to/file.md"                   # Retrieve a document by path
qmd get "#abc123"                           # Retrieve by docid
qmd get "path/to/file.md:100" -l 50         # Retrieve starting at line 100, 50 lines
qmd multi-get "journals/2026-*.md" -l 40    # Batch fetch by glob
qmd multi-get notes/foo.md,notes/bar.md     # Comma-separated list
```

## Query Types

| Type | Method | Input |
|------|--------|-------|
| `lex` | BM25 | Keywords — exact terms, names, code |
| `vec` | Vector | Question — natural language |
| `hyde` | Vector | Answer — hypothetical result (50-100 words) |

## Writing Good Queries

**lex (keyword)**
- 2-5 terms, no filler words
- Exact phrase: `"connection pool"` (quoted)
- Exclude terms: `performance -sports` (minus prefix)
- Code identifiers work: `handleError async`

**vec (semantic)**
- Full natural language question
- Be specific: `"how does the rate limiter handle burst traffic"`

**hyde (hypothetical document)**
- Write 50-100 words of what the *answer* looks like
- Use the vocabulary you expect in the result

**expand (auto-expand)**
- Single-line query (implicit) or `expand: question`
- Lets a local LLM generate lex/vec/hyde variations
- Do not mix with other typed lines

## Combining Types

| Goal | Approach |
|------|----------|
| Know exact terms | `lex` only |
| Don't know vocabulary | Single-line (implicit expand) or `vec` |
| Best recall | `lex` + `vec` |
| Complex topic | `lex` + `vec` + `hyde` |

First query gets 2x weight — put your strongest signal first.

## Lex Syntax

| Syntax | Meaning | Example |
|--------|---------|---------|
| `term` | Prefix match | `perf` matches "performance" |
| `"phrase"` | Exact phrase | `"rate limiter"` |
| `-term` | Exclude | `performance -sports` |

## Collection Filtering

```bash
qmd query --collections docs "question"
qmd query --collections docs,notes "question"
```

Omit to search all collections.