johncarpenter/kb-search

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:

| Mode | Command | When to use | |---|---|---| | Keyword | qmd search "term" | Fast exact-match, known terminology | | Semantic | qmd vsearch "concept" | Conceptual/fuzzy queries | | Hybrid | qmd query "question" | Best overall quality (default choice) |

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

| Range | Meaning | |---|---| | 0.8–1.0 | Highly relevant | | 0.5–0.8 | Moderately relevant | | 0.2–0.5 | Somewhat relevant | | < 0.2 | Low relevance — consider filtering |

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.