sem-search-a

name	sem-search-a
type	action
description	This skill should be used when the user asks to "search notes", "find similar notes", "semantic search", "reindex vault", "rebuild index", "query vault", or needs to find notes by meaning rather than keywords.
argument-hint	<query text> or --reindex

Action skill — Semantic search operations: BM25, vector search, hybrid search, reindexing.

Semantic Search — qmd

Search the vault by meaning using qmd, a local semantic search engine for markdown. BM25 + vector search + LLM re-ranking, all local. No cloud APIs.

Setup (One-Time)

If qmd is not installed:

brew install oven-sh/bun/bun        # Bun runtime (if not installed)
bun install -g github:tobi/qmd      # qmd itself

Register the vault as a collection:

qmd collection add "<vault-path>" --name vault

Build initial embeddings (~2GB models downloaded on first run):

qmd embed

Index stored at ~/.cache/qmd/index.sqlite — outside vault, no gitignore needed.

Commands

Reindex

When invoked with --reindex or after batch changes to the vault:

qmd update    # Re-index all collections (picks up new/changed/deleted files)
qmd embed     # Rebuild vector embeddings (needed after first install or model change)

Use qmd update for routine reindexing. Use qmd embed only for initial setup or embedding model changes.

Quick Search (BM25)

Fast keyword search. Good for finding notes that mention specific terms.

qmd search "prediction market pricing"

Semantic Search (Vector)

Vector similarity search. Finds conceptually related content even without keyword overlap.

qmd vsearch "how do agents maintain context across sessions"

This is the most useful search mode for finding related notes, confirming filing destinations, and discovering connections.

Best Quality (Hybrid + LLM Re-ranking)

Combines BM25 + vector search + LLM re-ranking with 6 parallel searches. Highest quality but slower.

qmd query "what patterns emerge in agentic development workflows"

Use for thorough exploration. Overkill for quick lookups.

Get Document

Retrieve the content of a specific document by path:

qmd get "2-Areas/ai-dev-ecosystem/2025-01-21_agentic-learnings.md"

Output Formats

Append format flags for programmatic use:

• --json — JSON output (for parsing results)
• --csv — CSV output
• --md — Markdown formatted
• --files — File paths only (one per line, useful for piping)

Example: qmd vsearch "agentic development" --files returns just paths.

When to Use Which

Need	Command	Speed
Find notes mentioning a term	qmd search	Fast
Find conceptually similar notes	qmd vsearch	Medium
Thorough exploration of a topic	qmd query	Slower
Confirm filing destination	qmd vsearch	Medium
Discover cross-area connections	qmd query	Slower

Integration with Other Skills

• auto-process-a: Uses qmd vsearch to confirm filing destinations
• backlinks-a: Uses qmd vsearch or qmd query to find semantically similar notes
• find-connections-a: Uses qmd query for thorough connection discovery
• librarian agent: Runs qmd update after batch processing

Troubleshooting

• "No collections": Run qmd collection add "<vault-path>" --name vault
• "No embeddings": Run qmd embed (first time takes a few minutes)
• Stale results: Run qmd update to re-index
• Check collections: qmd collection list shows registered collections