# Keywords
$ qmd search "budget Q4"

# Meaning
$ qmd vsearch "spending plans"

# Both + AI reranking
$ qmd query "what did we spend?"

-- Content-addressable storage
CREATE TABLE content (
  hash TEXT PRIMARY KEY,
  doc  TEXT NOT NULL,
  created_at TEXT
);

-- Document index (soft-delete)
CREATE TABLE documents (
  collection TEXT,
  path       TEXT,
  title      TEXT,
  hash       TEXT REFERENCES content,
  active     INTEGER DEFAULT 1,
  UNIQUE(collection, path)
);

-- Full-text search
CREATE VIRTUAL TABLE documents_fts
  USING fts5(
    filepath, title, body,
    tokenize='porter unicode61'
  );

-- Vector embeddings (sqlite-vec)
CREATE VIRTUAL TABLE vectors_vec
  USING vec0(
    hash_seq   TEXT PRIMARY KEY,
    embedding  float[N]
      distance_metric=cosine
  );

-- Chunk metadata
CREATE TABLE content_vectors (
  hash TEXT, seq INTEGER,
  pos  INTEGER, model TEXT,
  PRIMARY KEY(hash, seq)
);

-- LLM response cache
CREATE TABLE llm_cache (
  hash TEXT PRIMARY KEY,
  result TEXT,
  created_at TEXT
);

Input: "what did we decide about pricing?"

Output (3 line types):
lex: pricing decision meeting notes
lex: pricing strategy final
vec: discussions about product pricing
       and strategy decisions
vec: revenue model and price changes
hyde: After reviewing the market data,
  the team decided to move forward
  with the tiered pricing approach
  starting Q2...

Three query types

• lex: Keyword variants for BM25 — short, no filler words
• vec: Natural language phrases for vector search
• hyde: Hypothetical Document Embedding — a ~100-word synthetic answer that the real answer should be near in vector space

Training setup

Results

Scoring dimensions (max 140)

• Format compliance (0–30)
• Diversity of expansions (0–30)
• HyDE quality (0–20)
• Content quality (0–20)
• Entity preservation (–45 to +20)
• Think mode bonus (0–20)

The algorithm

// RRF formula per document:
RRF(d) = Σ for each query q:
  weight(q) / (k + rank(d, q))

// where k = 60 (standard constant)
// weight(q) depends on query type:
//   original query = 2x weight
//   expansion variants = 1x weight

Position-aware blending

// Top ranks: trust retrieval more
rank 1-5:  75% retrieval + 25% reranker
rank 6-15: 65% retrieval + 35% reranker
rank 16+:  40% retrieval + 60% reranker

Why RRF?

• Rank-based, not score-based — no need to normalize across different scoring systems
• Original query gets double weight so user intent stays dominant
• Top-ranking docs get bonus points for appearing in multiple retrievers
• Handles the incommensurability problem: BM25 scores and cosine distances are on totally different scales

Break point scores

Decay function

// Prefer splits near the target size
// but accept earlier good boundaries

normalizedDist = distance / window;
multiplier = 1.0 - (dist**2) * 0.7;
finalScore = bp.score * multiplier;

// At target:  1.00x
// 25% back:   0.96x (gentle)
// 50% back:   0.83x (moderate)
// 75% back:   0.61x (steep)
// Edge:       0.30x

Session lifecycle

// Scoped session pattern
await withLLMSession(llm, async (session) => {
  // session has abort signal
  // and duration limits
  const embeddings = await
    session.embedBatch(texts);
});
// resources freed on exit

// Reference counting tracks active
// sessions per model
class LLMSessionManager {
  refs: Map<model, count>
  canUnload(): boolean
}

Key patterns

• Inactivity timeout: 5-min idle unloads contexts (keeps models warm in memory)
• Promise guards: Prevent concurrent model loads that duplicate VRAM
• No greedy decoding: Prevents generation loops
• Context size bounds: Truncation before inference prevents crashes
• ETag caching: Model downloads check freshness via HTTP ETag, skip re-download
• Deterministic disposal: Cleanup with timeouts, not just GC

Resource: qmd:// URIs

Read-only markdown access via qmd://{+path} resource templates. Discovery is search-only (no directory listing).

Two transports

# Stdio (Claude Code, Cursor)
$ qmd mcp

# HTTP (shared, long-lived)
$ qmd mcp --http --port 8181

# Background daemon
$ qmd mcp --http --daemon
$ qmd mcp stop

Dynamic instructions

On MCP initialize, the server builds a system prompt including:

• Collection inventory with doc counts
• Vector index availability warnings
• Query type examples and strategies
• Retrieval workflow documentation

Collection model

# YAML config (~/.config/qmd/index.yml)
collections:
  meeting-notes:
    path: ~/Documents/meetings
    pattern: "**/*.md"
    ignore:
      - "**/drafts/**"
    context:
      /: "Weekly team meeting notes"
      /2025: "Current year meetings"
      /2025/q1: "Q1 planning sessions"
  docs:
    path: ~/projects/api/docs
    pattern: "**/*.{md,mdx}"

Virtual paths

Universal addressing across collections:

# Full virtual path
qmd://meeting-notes/2025/standup.md

# Context resolution (longest prefix)
qmd://meeting-notes/2025/q1/jan.md
  → matches /2025/q1 context
  → "Q1 planning sessions"

Context hierarchy

• Path-prefix matching (longest wins)
• Global context applies to all collections
• Attached to search results for LLM context
• qmd context check finds missing descriptions

Core commands

# Index your files
$ qmd collection add ~/notes --name notes
$ qmd embed

# Three search modes
$ qmd search "budget Q4"       # BM25
$ qmd vsearch "spending plans"  # vector
$ qmd query "what did we spend" # hybrid

# Retrieve documents
$ qmd get meeting.md:50       # from line 50
$ qmd get "#abc123"           # by docid
$ qmd multi-get "journals/2025*"

# Maintenance
$ qmd update --pull   # git pull + reindex
$ qmd status          # index health
$ qmd cleanup         # vacuum + prune

Output formats

Key flags

• -c collection — restrict to collection
• --min-score 0.5 — filter weak results
• --explain — show full score trace
• --no-rerank — skip LLM reranking
• --full — show full document content