KB Search — QMD Knowledgebase Tool

Search, retrieve, and index local markdown knowledgebase files via the QMD CLI. QMD is assumed to be installed and available on PATH.

Workflow

1. First-Time Setup (Index a Directory)

When a user points to a new directory of markdown files, register it as a QMD collection and generate embeddings:

qmd collection add /path/to/docs --name <collection-name>
qmd embed

• •Default glob is **/*.md — override with --mask if needed.
• •Run qmd embed -f to force a full re-embed after significant content changes.
• •Use qmd status to verify index health.

2. Searching

Choose the right search mode based on the query:

Always prefer qmd query unless the user needs speed or has a specific keyword.

Key flags:

• •-n <num> — number of results (default 5)
• •-c <collection> — restrict to a specific collection
• •--min-score <float> — filter low-relevance results (0.0–1.0)
• •--json — structured output, ideal for programmatic use
• •--full — show complete document content in results
• •--md — markdown-formatted output

Example — high-quality search with relevance filtering:

qmd query -n 10 --min-score 0.3 --json "user authentication"

3. Retrieving Documents

Fetch specific files or passages after identifying them via search:

qmd get <path-or-docid>                  # Full document
qmd get <path>:<line> -l <count>         # Specific line range
qmd multi-get "<glob-or-csv>"            # Multiple documents

• •Use #docid syntax from search results for precise retrieval.
• •Use --max-bytes with multi-get to skip oversized files.

4. Maintaining the Index

qmd update              # Re-index all collections after file changes
qmd status              # Check index health and stats
qmd cleanup             # Remove orphaned cache data

Run qmd update after any batch of file additions/removals. Follow with qmd embed if new files were added.

5. Working with Multiple Knowledge Bases

Use named indexes to keep separate domains isolated:

qmd --index <name> collection add /path --name <coll>
qmd --index <name> query "search term"

Output Handling

• •For presenting results to the user: use --md for readable output.
• •For programmatic processing: use --json for structured data with snippets and scores.
• •For file listings: use --files for docid,score,filepath,context format.

Score Interpretation

Error Handling

• •If qmd is not found: prompt user to install via bun install -g github:tobi/qmd.
• •If search returns no results: try broadening the query, lowering --min-score, or using qmd vsearch for semantic matching.
• •If embeddings are stale: run qmd embed -f to force refresh.

Full CLI Reference

See references/qmd-cli.md for the complete command reference including all flags and options.