tobi/qmd v1.1.5

on GitHub

[1.1.5] - 2026-03-07

Ambiguous queries like "performance" now produce dramatically better results
when the caller knows what they mean. The new intent parameter steers all
five pipeline stages — expansion, strong-signal bypass, chunk selection,
reranking, and snippet extraction — without searching on its own. Design and
original implementation by Ilya Grigorik (@vyalamar) in #180.

Changes

• Intent parameter: optional intent string disambiguates queries across
  the entire search pipeline. Available via CLI (--intent flag or intent:
  line in query documents), MCP (intent field on the query tool), and
  programmatic API. Adapted from PR #180 (thanks @vyalamar).
• Query expansion: when intent is provided, the expansion LLM prompt
  includes Query intent: {intent}, matching the finetune training data
  format for better-aligned expansions.
• Reranking: intent is prepended to the rerank query so Qwen3-Reranker
  scores with domain context.
• Chunk selection: intent terms scored at 0.5× weight alongside query
  terms (1.0×) when selecting the best chunk per document for reranking.
• Snippet extraction: intent terms scored at 0.3× weight to nudge
  snippets toward intent-relevant lines without overriding query anchoring.
• Strong-signal bypass disabled with intent: when intent is provided, the
  BM25 strong-signal shortcut is skipped — the obvious keyword match may not
  be what the caller wants.
• MCP instructions: callers are now guided to provide intent on every
  search call for disambiguation.
• Query document syntax: intent: recognized as a line type. At most one
  per document, cannot appear alone. Grammar updated in docs/SYNTAX.md.

[1.1.2] - 2026-03-07

13 community PRs merged. GPU initialization replaced with node-llama-cpp's
built-in autoAttempt — deleting ~220 lines of manual fallback code and
fixing GPU issues reported across 10+ PRs in one shot. Reranking is faster
through chunk deduplication and a parallelism cap that prevents VRAM
exhaustion.

Changes

• GPU init: use node-llama-cpp's build: "autoAttempt" instead of manual
  GPU backend detection. Automatically tries Metal/CUDA/Vulkan and falls back
  gracefully. #310 (thanks @giladgd — the node-llama-cpp author)
• Query --explain: qmd query --explain exposes retrieval score traces
  — backend scores, per-list RRF contributions, top-rank bonus, reranker
  score, and final blended score. Works in JSON and CLI output. #242
  (thanks @vyalamar)
• Collection ignore patterns: ignore: ["Sessions/**", "*.tmp"] in
  collection config to exclude files from indexing. #304 (thanks @sebkouba)
• Multilingual embeddings: QMD_EMBED_MODEL env var lets you swap in
  models like Qwen3-Embedding for non-English collections. #273 (thanks
  @daocoding)
• Configurable expansion context: QMD_EXPAND_CONTEXT_SIZE env var
  (default 2048) — previously used the model's full 40960-token window,
  wasting VRAM. #313 (thanks @0xble)
• candidateLimit exposed: -C / --candidate-limit flag and MCP
  parameter to tune how many candidates reach the reranker. #255 (thanks
  @pandysp)
• MCP multi-session: HTTP transport now supports multiple concurrent
  client sessions, each with its own server instance. #286 (thanks @joelev)

Fixes

• Reranking performance: cap parallel rerank contexts at 4 to prevent
  VRAM exhaustion on high-core machines. Deduplicate identical chunk texts
  before reranking — same content from different files now shares a single
  reranker call. Cache scores by content hash instead of file path.
• Deactivate stale docs when all files are removed from a collection and
  qmd update is run. #312 (thanks @0xble)
• Handle emoji-only filenames (🐘.md → 1f418.md) instead of crashing.
  #308 (thanks @debugerman)
• Skip unreadable files during indexing (e.g. iCloud-evicted files returning
  EAGAIN) instead of crashing. #253 (thanks @jimmynail)
• Suppress progress bar escape sequences when stderr is not a TTY. #230
  (thanks @dgilperez)
• Emit format-appropriate empty output ([] for JSON, CSV header for CSV,
  etc.) instead of plain text "No results." #228 (thanks @amsminn)
• Correct Windows sqlite-vec package name (sqlite-vec-windows-x64) and add
  sqlite-vec-linux-arm64. #225 (thanks @ilepn)
• Fix claude plugin setup CLI commands in README. #311 (thanks @gi11es)

[1.1.1] - 2026-03-06

Fixes

• Reranker: truncate documents exceeding the 2048-token context window
  instead of silently producing garbage scores. Long chunks (e.g. from
  PDF ingestion) now get a fair ranking.
• Nix: add python3 and cctools to build dependencies. #214 (thanks
  @pcasaretto)

[1.1.0] - 2026-02-20

QMD now speaks in query documents — structured multi-line queries where every line is typed (lex:, vec:, hyde:), combining keyword precision with semantic recall. A single plain query still works exactly as before (it's treated as an implicit expand: and auto-expanded by the LLM). Lex now supports quoted phrases and negation ("C++ performance" -sports -athlete), making intent-aware disambiguation practical. The formal query grammar is documented in docs/SYNTAX.md.

The npm package now uses the standard #!/usr/bin/env node bin convention, replacing the custom bash wrapper. This fixes native module ABI mismatches when installed via bun and works on any platform with node >= 22 on PATH.

Changes

• Query document format: multi-line queries with typed sub-queries (lex:, vec:, hyde:). Plain queries remain the default (expand: implicit, but not written inside the document). First sub-query gets 2× fusion weight — put your strongest signal first. Formal grammar in docs/SYNTAX.md.
• Lex syntax: full BM25 operator support. "exact phrase" for verbatim matching; -term and -"phrase" for exclusions. Essential for disambiguation when a term is overloaded across domains (e.g. performance -sports -athlete).
• expand: shortcut: send a single plain query (or start the document with expand: on its only line) to auto-expand via the local LLM. Query documents themselves are limited to lex, vec, and hyde lines.
• MCP query tool (renamed from structured_search): rewrote the tool description to fully teach AI agents the query document format, lex syntax, and combination strategy. Includes worked examples with intent-aware lex.
• HTTP /query endpoint (renamed from /search; /search kept as silent alias).
• collections array filter: filter by multiple collections in a single query (collections: ["notes", "brain"]). Removed the single collection string param — array only.
• Collection include/exclude: includeByDefault: false hides a collection from all queries unless explicitly named via collections. CLI: qmd collection exclude <name> / qmd collection include <name>.
• Collection update-cmd: attach a shell command that runs before every qmd update (e.g. git stash && git pull --rebase --ff-only && git stash pop). CLI: qmd collection update-cmd <name> '<cmd>'.
• qmd status tips: shows actionable tips when collections lack context descriptions or update commands.
• qmd collection subcommands: show, update-cmd, include, exclude. Bare qmd collection now prints help.
• Packaging: replaced custom bash wrapper with standard #!/usr/bin/env node shebang on dist/qmd.js. Fixes native module ABI mismatches when installed via bun, and works on any platform where node >= 22 is on PATH.
• Removed MCP tools search, vector_search, deep_search — all superseded by query.
• Removed qmd context check command.
• CLI timing: each LLM step (expand, embed, rerank) prints elapsed time inline (Expanding query... (4.2s)).

Fixes

• qmd collection list shows [excluded] tag for collections with includeByDefault: false.
• Default searches now respect includeByDefault — excluded collections are skipped unless explicitly named.
• Fix main module detection when installed globally via npm/bun (symlink resolution).