90 lines
2.7 KiB
Markdown
90 lines
2.7 KiB
Markdown
---
|
|
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.
|