/enable-semantic-search

name: enable-semantic-search
description: "Turn on local AI-powered semantic (meaning-based) search over the vault, with smart collection discovery. Use when the user says 'enable semantic search', 'search by meaning', 'set up QMD', or search keeps missing obvious matches. Not for scraping the web; use `scrape`."

Enable Semantic Search

Set up local AI-powered semantic search for your vault. This is a **concierge experience** — it analyzes your vault, discovers what collections make sense, and creates a tailored search setup.

What You're Enabling

Semantic search finds content by **meaning**, not just keywords:

• Search "product-led growth" → finds notes saying "PLG", "self-serve motion", "freemium adoption"
• Search "customer churn" → finds notes about "retention problems", "users leaving", "cancellation patterns"

Your skills (`/daily-plan`, `/meeting-prep`, `/triage`, etc.) automatically use semantic search when available, finding more relevant context than keyword matching alone.

Pre-Flight Checks

Run these checks before proceeding:

# Check if qmd is already installed
which qmd

# Check if Bun is available (required)
which bun

# macOS only: Check SQLite via Homebrew
brew list sqlite 2>/dev/null && echo "SQLite OK" || echo "Need: brew install sqlite"

# Check available disk space (need ~2.5GB)
df -h ~ | tail -1

**If qmd is already installed**, run `qmd status` to check existing setup. If collections already exist, skip to the **Collection Health Check** section at the bottom.

Step 1: Explain What We're Installing

Present this to the user:

═══════════════════════════════════════════════════════════════════════
                    SEMANTIC SEARCH FOR YOUR VAULT
═══════════════════════════════════════════════════════════════════════

What is this?
─────────────
Right now, finding notes requires knowing the exact words used.
Search "product-led growth" — won't find notes saying "PLG" or
"self-serve motion".

Semantic search understands meaning, not just keywords. It finds
conceptually related content even when terminology differs.


How does it work?
─────────────────
Your notes get converted to "embeddings" — mathematical
representations of meaning. When you search, your query becomes
an embedding too. The system finds notes whose meaning is close
to your query's meaning.

Think of it like: instead of matching letters, we're matching ideas.


What gets installed?
────────────────────
Three small AI models run locally on your machine:

  MODEL                      PURPOSE                    SIZE
  ─────────────────────────────────────────────────────────────
  EmbeddingGemma-300M        Converts text to meaning   ~300MB
                             vectors. The core
                             "understanding" model.

  Qwen3-Reranker-0.6b       Re-orders results by       ~640MB
                             true relevance. Improves
                             result quality.

  QMD-Query-Expansion-1.7B   Expands your search to     ~1.1GB
                             include related terms.
                             "PLG" → also searches
                             "product-led", "freemium"

  Total: ~2GB one-time download


Privacy & Security
──────────────────
- Everything runs locally — your notes never leave your machine
- No API keys required
- No cloud services
- Models downloaded from HuggingFace (open source)
- Index stored in ~/.cache/qmd/ (not in your vault)


What changes in your workflow?
──────────────────────────────
Enabling semantic search silently upgrades these skills:

  /daily-plan    — Enriches meeting prep with thematically
                   related past discussions

  /meeting-prep  — Discovers past discussions related by
                   meaning, not just name matching

  /triage        — Matches inbox items to goals by meaning,
                   catches semantic duplicates

  Person Lookup  — Finds "the VP of Sales mentioned..." even
                   without a name

  Search & Recall — All vault searches use hybrid retrieval
                    (BM25 + vectors + LLM reranking)


System Requirements
───────────────────
  ~2.5GB disk space (for models + index)
  macOS: Homebrew SQLite required (brew install sqlite)
  Bun runtime (will install if missing)

Step 2: Get User Consent

Ask: **"Ready to enable semantic search? This will download ~2GB of models. [Y/n]"**

If no, exit gracefully: "No problem. Run `/enable-semantic-search` anytime."

Step 3: Install Dependencies

# Install Bun if missing
if ! command -v bun &> /dev/null; then
    echo "Installing Bun runtime..."
    curl -fsSL https://bun.sh/install | bash
fi

# macOS: Install SQLite if missing
if [[ "$OSTYPE" == "darwin"* ]]; then
    if ! brew list sqlite &> /dev/null; then
        echo "Installing SQLite via Homebrew..."
        brew install sqlite
    fi
fi

# Install qmd globally
echo "Installing qmd..."
bun install -g github:tobi/qmd

Step 4: Download Models

echo "Downloading AI models (~2GB)..."
echo "This happens once. Future searches are instant."
echo ""
echo "Models downloading:"
echo "  EmbeddingGemma-300M  — Converts text to meaning vectors"
echo "  Qwen3-Reranker-0.6b  — Improves result relevance"
echo "  QMD-Query-Expansion   — Expands searches with related terms"
echo ""

# Trigger model download with a simple embed operation
cd "$VAULT_PATH" && qmd embed --help 2>/dev/null || true

Step 4.5: Register the QMD MCP Server

qmd is intentionally NOT pre-registered in `.mcp.json` — a registered server whose binary is missing shows the user a failing MCP server every session. Now that qmd is installed, add the registration to the vault's `.mcp.json`:

python3 - <<'EOF'
import json, pathlib
p = pathlib.Path(".mcp.json")
cfg = json.loads(p.read_text()) if p.exists() else {"mcpServers": {}}
cfg.setdefault("mcpServers", {})["qmd"] = {"command": "qmd", "args": ["mcp"]}
p.write_text(json.dumps(cfg, inde