Qmd

qmd - Quick Markdown Search

Full-text (BM25) and vector similarity search with query expansion and reranking.

Overview

qmd provides semantic search across collections of text files (markdown, JSONL, etc.) using:

• BM25 full-text search - Fast keyword matching
• Vector embeddings - Semantic similarity (embeddinggemma-300M)
• Reranking - Quality filtering (qwen3-reranker-0.6b)
• Query expansion - Automatic query refinement

Installation:

bun install -g https://github.com/tobi/qmd

Binary location: ~/.bun/bin/qmd

When to Use

Use qmd for:

• Searching conversation history across Claude Code, claudesp, Clawdbot
• Finding discussions about specific topics
• Semantic similarity search (similar concepts, different words)
• Documentation search
• Any large text corpus search

Session Retention Policy:

• Only keep sessions < 2 months old in qmd index
• Older sessions: grep on demand from raw JSONL files
• Keeps index size manageable, search fast

Core Commands

Search Commands

# Combined search (BM25 + vector + reranking) - BEST
qmd query "{text}" -c <collection>

# Full-text search only - FAST
qmd search "{text}" -c <collection>

# Vector similarity only - SEMANTIC
qmd vsearch "{text}" -c <collection>

Collection Management

# Create/index collection
qmd collection add <path> --name <name> --mask <pattern>

# List all collections
qmd collection list

# Remove collection
qmd collection remove <name>

# Rename collection
qmd collection rename <old> <new>

Index Management

# Update index (re-scan for changes)
qmd update

# Update with git pull
qmd update --pull

# Generate embeddings (required for vsearch)
qmd embed -f

# Check index status
qmd status

# Clean up and vacuum
qmd cleanup

File Operations

# Get specific document
qmd get <file>[:line] [-l N] [--from N]

# Get multiple documents by pattern
qmd multi-get <pattern> [-l N] [--max-bytes N]

# List files in collection
qmd ls [collection[/path]]

Context Management

# Add context for path
qmd context add [path] "text"

# List all contexts
qmd context list

# Remove context
qmd context rm <path>

Search Options

# Limit results
-n <num>                   # Number of results (default: 5)

# Scoring thresholds
--min-score <num>          # Minimum similarity score
--all                      # Return all matches

# Output formats
--full                     # Full document instead of snippet
--line-numbers            # Add line numbers
--json                    # JSON output
--csv                     # CSV output
--md                      # Markdown output
--xml                     # XML output
--files                   # Output docid,score,filepath,context

# Collection filtering
-c <name>                 # Filter to specific collection

# Multi-get options
-l <num>                  # Maximum lines per file
--max-bytes <num>         # Skip files larger than N bytes

Common Patterns

Search All Collections

qmd query "authentication" \
  -c claude-sessions \
  -c claudesp-sessions \
  -c clawdbot-sessions \
  --full -n 10

Search with Score Threshold

qmd query "deployment bug" --min-score 0.7 --json

Get Recent Files

qmd ls claude-sessions | head -20

Semantic Search

# Find similar concepts (not just keywords)
qmd vsearch "how do we handle errors in the gateway"

Bulk Retrieval

# Get all files matching pattern
qmd multi-get "2026-01-28*.jsonl" --json

Output Formats

Default (Snippet)

Result 1 (score: 0.85):
File: ~/.claude/sessions/abc123.jsonl:42
Snippet: ...relevant text around match...

Full Document

qmd query "text" --full --line-numbers

JSON

qmd query "text" --json | jq '.results[] | {score, file: .docid}'

Files Only

qmd query "text" --files
# Output: docid,score,filepath,context

MCP Server

qmd includes an MCP server for agent integration:

# Start MCP server
qmd mcp

# Add to claude_desktop_config.json:
{
  "mcpServers": {
    "qmd": {
      "command": "qmd",
      "args": ["mcp"]
    }
  }
}

MCP tools exposed:

• search - Full-text search
• vsearch - Vector search
• query - Combined search
• get - Get document
• multi-get - Get multiple documents
• collection_* - Collection operations

Index Details

Location: ~/.cache/qmd/index.sqlite

Models (auto-downloaded from HuggingFace):

• Embedding: embeddinggemma-300M-Q8_0
• Reranking: qwen3-reranker-0.6b-q8_0
• Generation: Qwen3-0.6B-Q8_0

Collection structure:

CREATE TABLE collections (
  name TEXT PRIMARY KEY,
  path TEXT,
  mask TEXT
);

CREATE TABLE documents (
  docid TEXT PRIMARY KEY,
  collection TEXT,
  path TEXT,
  hash TEXT,
  content TEXT
);

CREATE TABLE embeddings (
  hash TEXT PRIMARY KEY,
  embedding BLOB
);

Troubleshooting

"Collection not found"

qmd collection list  # Check what exists
qmd collection add <path> --name <name> --mask "*.md"

"No embeddings found"

qmd embed -f  # Generate embeddings

No results

# Try broader search
qmd search "keyword" --all --min-score 0.3

# Check collection has files
qmd ls <collection>

# Re-index
qmd update

Large index

qmd cleanup  # Vacuum DB

Examples

Example 1: Find Authentication Discussions

qmd query "authentication jwt middleware" \
  -c claude-sessions \
  -c clawdbot-sessions \
  --full --line-numbers -n 5

Example 2: Search Clawdbot Only

qmd search "gateway bug" -c clawdbot-sessions --files

Example 3: Semantic Search

# Find conceptually similar content
qmd vsearch "deploying containers to production" \
  --full -n 3

Example 4: Get Session by ID

# If you know the session ID
qmd get ~/.clawdbot/agents/main/sessions/abc-123.jsonl --full

Example 5: Search Recent Sessions

# Find files, then search within them
find ~/.clawdbot/agents/main/sessions -name "*.jsonl" -mtime -7 | \
  xargs qmd multi-get --json | \
  jq -r '.[] | select(.content | contains("voice"))'

Related Search Tools

qmd specializes in local markdown/JSONL search. For external search:

QMD's unique capabilities:

• ✅ Local-only (no external API calls)
• ✅ BM25 full-text + vector embeddings + reranking
• ✅ Conversation history across Claude Code/claudesp/Clawdbot
• ✅ Fast markdown collection search
• ✅ MCP server for agent integration
• ❌ External web search (use brave/tavily/exa)
• ❌ Multi-perspective (use lev-research)

Integration pattern:

# 1. Search local history
qmd query "authentication discussion" -c claude-sessions --full

# 2. If not found locally, search external
valyu research "authentication patterns 2026" --turns 5

# 3. Or use unified search
lev get "authentication" --scope=all  # Searches both local + external

Integration with Other Skills

lev-clwd

lev-clwd uses qmd for conversation history search across all 3 session stores.

lev-find

Future: lev-find will abstract qmd collections with unified interface.

See skill://lev-research for comprehensive research workflows.

Claudesp Variant (~/dcs)

The claudesp variant lives at ~/.claude-sneakpeek/claudesp/config/ with shortcut:

~/dcs → ~/.claude-sneakpeek/claudesp/config/

Directory Structure

~/.claude-sneakpeek/
└── claudesp/
    └── config/              # ← ~/dcs points here
        ├── CLAUDE.md        # Variant-specific instructions
        ├── .claude.json     # Variant settings + hooks
        ├── settings.json    # Variant hook configuration
        ├── commands/        # Commands (copies, allow variant edits)
        ├── skills/          # Skills (symlinked from ~/.claude/skills/)
        ├── hooks/           # Same hooks as ~/.claude/hooks/
        ├── plans/           # Session plans
        ├── history.jsonl    # Claudesp-specific command history
        ├── projects/        # Project session indexes
        └── session-env/     # Session environments

Session Collections

Searching Claudesp History

# Search claudesp sessions specifically
qmd query "entity dashboard" -c claudesp-sessions --full -n 5

# Cross-variant search (all 3 session stores)
qmd query "lev cms" -c claude-sessions -c claudesp-sessions -c clawdbot-sessions -n 10

Auto-Refresh (Staleness Detection)

How qmd Handles Incremental Updates

qmd tracks file hashes in the index. On qmd update:

• New files → indexed and added
• Changed files (hash differs) → re-indexed
• Unchanged files → skipped (fast)
• Deleted files → removed from index

This means qmd update is always safe and incremental.

XDG Cache Staleness Check

Index lives at ~/.cache/qmd/index.sqlite (XDG-compliant).

Auto-refresh pattern for hooks/session start:

#!/bin/bash
# qmd-auto-refresh.sh - Run on SessionStart or as needed
# Checks if index is stale and refreshes incrementally

QMD_INDEX="$HOME/.cache/qmd/index.sqlite"
STALENESS_THRESHOLD=86400  # 1 day in seconds

if [ ! -f "$QMD_INDEX" ]; then
  echo "qmd index missing, creating..."
  qmd update
  exit 0
fi

# Check last modified time
INDEX_MTIME=$(stat -f %m "$QMD_INDEX" 2>/dev/null || stat -c %Y "$QMD_INDEX" 2>/dev/null)
NOW=$(date +%s)
AGE=$(( NOW - INDEX_MTIME ))

if [ "$AGE" -gt "$STALENESS_THRESHOLD" ]; then
  echo "qmd index stale (${AGE}s old), refreshing..."
  qmd update  # Incremental: skips unchanged files via hash
else
  echo "qmd index fresh (${AGE}s old)"
fi

Hook Integration

Add to ~/.claude/settings.json SessionStart hooks:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/qmd-auto-refresh.sh"
          }
        ]
      }
    ]
  }
}

Session Retention Policy

• < 2 months old: Keep in qmd index (fast semantic search)
• > 2 months old: Grep on demand from raw JSONL files
• Cleanup: qmd cleanup removes orphaned data, vacuums DB

Collection-Level Staleness

# Check which collections need refresh
qmd status | grep "updated" | awk '{print $1, $NF}'

# Force refresh specific collection
qmd update -c claude-sessions
qmd update -c claudesp-sessions

# Refresh all (incremental, safe)
qmd update

Maintenance

Daily Update

Add to jared cron or SessionStart hook:

# Incremental update (skips unchanged files)
qmd update

# Generate embeddings for new files
qmd embed -f

Weekly Cleanup

qmd cleanup  # Remove orphaned data, vacuum DB

Reference

Repository: https://github.com/tobi/qmd Models: HuggingFace (auto-downloaded) Index: ~/.cache/qmd/index.sqlite Binary: ~/.bun/bin/qmd Shortcut: ~/dcs → ~/.claude-sneakpeek/claudesp/config/

Technique Map

• Role definition - Clarifies operating scope and prevents ambiguous execution.
• Context enrichment - Captures required inputs before actions.
• Output structuring - Standardizes deliverables for consistent reuse.
• Step-by-step workflow - Reduces errors by making execution order explicit.
• Edge-case handling - Documents safe fallbacks when assumptions fail.

Technique Notes

These techniques improve reliability by making intent, inputs, outputs, and fallback paths explicit. Keep this section concise and additive so existing domain guidance remains primary.

Prompt Architect Overlay

Role Definition

You are the prompt-architect-enhanced specialist for lev-find-qmd, responsible for deterministic execution of this skill's guidance while preserving existing workflow and constraints.

Input Contract

• Required: clear user intent and relevant context for this skill.
• Preferred: repository/project constraints, existing artifacts, and success criteria.
• If context is missing, ask focused questions before proceeding.

Output Contract

• Provide structured, actionable outputs aligned to this skill's existing format.
• Include assumptions and next steps when appropriate.
• Preserve compatibility with existing sections and related skills.

Edge Cases & Fallbacks

• If prerequisites are missing, provide a minimal safe path and request missing inputs.
• If scope is ambiguous, narrow to the highest-confidence sub-task.
• If a requested action conflicts with existing constraints, explain and offer compliant alternatives.