tobi/qmd v2.8.3

on GitHub

[2.8.3] - 2026-08-16

Security

• qmd update no longer runs a project-local .qmd/index.yml's update:
  commands without approval (#886). That file arrives with a git clone and is
  adopted automatically for any command run inside the tree, so cloning a
  repository and running qmd update executed shell commands chosen by whoever
  wrote it. On a terminal QMD now lists the commands and asks; with nobody to
  ask it skips them and keeps indexing. Approvals are recorded per config file
  and per command set in <config dir>/trusted.json, so editing a command — or
  a git pull that rewrites one — asks again. New qmd trust,
  qmd trust list and qmd trust revoke manage approvals, and
  QMD_TRUST_UPDATE_HOOKS=1 opts unattended runs back in. Commands in your own
  ~/.config/qmd/*.yml, including anything qmd collection update-cmd writes,
  are unaffected.

• The same project-local trust gate now covers collection path values that
  resolve outside the project and non-default models.embed / models.rerank
  / models.generate URIs (#889). In-project paths still index unattended;
  out-of-project directories are skipped until qmd trust, and custom model
  URIs are not loaded or downloaded. QMD_TRUST_LOCAL_CONFIG=1 opts unattended
  runs back in (and QMD_TRUST_UPDATE_HOOKS=1 still does). qmd collection add records trust as it writes, the same way update-cmd does.

• Indexing no longer follows file symlinks or glob ../ / absolute patterns
  out of the collection directory. fast-glob already skipped symlinked
  directories, but a file symlink (or a mask like ../**/*.md) still resolved
  via realpath and ingested the target. qmd:// filesystem resolution uses
  the same containment check, so qmd://collection/../../../etc/passwd no
  longer produces a path outside the collection.

• qmd mcp --http now validates the Origin and Host headers on every
  request and answers 403 when they name anything but a loopback address
  (#881). Binding to localhost is no defence against the user's own browser:
  a page can re-point its hostname at 127.0.0.1 (DNS rebinding) and read
  the indexed corpus through POST /query or POST /mcp. Requests with no
  Origin (curl, MCP clients, editors) are unaffected. Extend the allowlists
  with QMD_ALLOWED_ORIGINS / QMD_ALLOWED_HOSTS, or set
  QMD_ALLOWED_ORIGINS=* behind your own authenticating proxy. A wildcard
  bind (--host 0.0.0.0) skips the host check and warns at startup.

Changed

• Dependencies: node-llama-cpp 3.18.1 → 3.20.0 (llama.cpp b8390 → b10361, 2026-08-11). Also safe patch/minors: picomatch 4.0.4 → 4.0.5, web-tree-sitter 0.26.8 → 0.26.12, tsx 4.21.0 → 4.23.12, vitest 3.2.4 → 3.2.7. No zod/vitest major; @modelcontextprotocol/server stays 2.0.0 (no 2.x patch). flake.nix FOD hashes are not updated here.

• generate and query expansion now await LlamaContextSequence.dispose() before disposing the parent context. node-llama-cpp 3.20 made sequence dispose async; the library's context-onDispose path does not wait.

• MCP server now speaks protocol revision 2026-07-28 via the official
  TypeScript SDK 2.x (@modelcontextprotocol/server). HTTP is sessionless
  (no Mcp-Session-Id, no initialize handshake, no idle-session TTL / #816
  reaper). Clients send version and capabilities in _meta; server/discover
  is implemented; Streamable HTTP POST requires Mcp-Method / Mcp-Name
  (mismatch → -32020); tools/list is deterministic and carries ttlMs /
  cacheScope. 2025-era stdio clients still work (serveStdio dual-speak);
  2025-era HTTP initialize is answered per-request without minting a
  session. Existing tools (query / get / multi_get / status), stdio
  EOF shutdown, and named-index daemon PIDs are unchanged. No release.

• qmd pull (and implicit model downloads in embed/query) no longer print
  node-llama-cpp's download progress bar. The bar redraws every few kilobytes
  and flooded agent transcripts with thousands of tokens (#776). Pass
  qmd pull --progress to show it on an interactive terminal.

• --full-path no longer degrades silently when a result cannot be resolved on
  disk (#785). A fallback there means the file moved or was deleted since the
  last index, so search, query, get and multi-get now print a notice to
  stderr naming how many results fell back and suggesting qmd update; stdout
  stays machine-readable.

• search/query now decide per result whether to show the docid under
  --full-path, matching multi-get and get: a result that resolved shows
  its on-disk path and no docid, one that did not keeps its qmd:// URI and
  its docid, so it is still addressable. Previously the docid was dropped for
  every row whenever the flag was set, leaving unresolved rows with neither a
  usable path nor an identifier.

• search --format csv always emits the docid column, empty for rows that
  resolved to an on-disk path. Under --full-path the header previously
  dropped the column entirely — which also disagreed with the empty-result
  header, always printed with docid. Column positions are now stable across
  runs and formats.

Fixed

• Concurrent first-open of a cold index no longer fails with
  table documents_fts already exists on Bun/macOS. FTS5
  CREATE VIRTUAL TABLE IF NOT EXISTS is not atomic across WAL
  connections: two processes can both see a missing table on their
  schema snapshot and the loser throws. Table create and legacy-schema
  repair now use the same BEGIN IMMEDIATE + double-check as the FTS
  sync triggers, and treat a concurrent "already exists" as success
  when the table is present.

• Nix flake qmd-node-modules FOD hashes updated for x86_64-linux and
  aarch64-darwin after the MCP SDK 2.0 bump. nix build / Nix GHA was
  failing with a fixed-output hash mismatch.

• CJK FTS rebuild no longer skips leftover fts5(name, body, content='documents')
  tables when fts_cjk_normalized_version is already stamped, and schema
  repair now checks live FTS columns (PRAGMA table_info) as well as
  sqlite_master.sql. The MCP HTTP test helper still seeds that legacy
  table; startMcpHttpServer / createStore on it must not throw
  no such column: T.name (#792 regression).

• qmd collection add --glob is no longer silently ignored. parseArgs ran
  with strict: false, so OpenClaw's --glob memory.md (and any other
  --glob) fell through, the default **/*.md was used, and a second
  collection on the same path collided as a duplicate instead of indexing
  the requested mask (#536). --glob is now an alias for --mask.

• The bin/qmd trampoline now execs process.execPath instead of
  re-resolving node from PATH. Native addons (better-sqlite3) are
  compiled for the Node that installed qmd; a version manager (nvm, fnm,
  mise) selecting a different major in the working directory used to spawn
  that other binary and fail with NODE_MODULE_VERSION / ERR_DLOPEN_FAILED
  (#577 leftover; #319). bun bin/qmd still resolves node from PATH so
  Node-ABI addons are not loaded into bun.

• qmd update / qmd collection add no longer swallow unreadable files
  silently (#460). readFileSync failures (ETIMEDOUT on APFS compressed
  files, EAGAIN, EACCES, …) still skip the file so the rest of the collection
  indexes, but the CLI now warns with the path and error code and reports
  the skip count. The SDK update() result includes skipped.

• The architecture diagram no longer draws Vec expansions into BM25 search
  (#680). lex expansions are FTS-only; vec and hyde expansions are
  vector-only. The original query still goes to both backends.

• qmd bench no longer runs to a wall of 0.00 when the fixture collection is
  missing or empty (#716). It errors up front with the same "Collection not
  found" / index hint as qmd search -c, and if every backend still scores
  zero it warns on stderr to check qmd ls.

• qmd cleanup now reclaims the content and FTS space left behind after a
  wrong-directory qmd update. Deactivating files (the next update in the
  right directory) only tombstoned the documents rows; cleanup deleted those
  rows and vacuumed, but never dropped the unreferenced content hashes and
  never ran FTS5 optimize, so documents_fts_data kept the old bodies
  (#550). Cleanup now deletes inactive docs, then orphaned content, then
  compact FTS, then vacuum. --dry-run reports the content hashes too.

• Concurrent query calls with rerank: true on a cold MCP server no longer
  race ensureRerankContexts(). Embed already serialized context creation;
  rerank did not, so two overlapping first queries both saw an empty pool,
  both created ranking contexts, and the inactivity timer disposed the loser
  (Object is disposed, #682). Callers now await the in-flight create.

• Embedding-context pool size no longer assumes every GGUF costs 150 MB of
  VRAM (the nomic-embed figure). Larger models such as Qwen3-Embedding-0.6B
  are ~1190 MB per 2048-token context; opening 8 of those exhausted an 8 GB
  card so qmd query failed with Failed to create any rerank context even
  though the reranker itself was fine. The pool is now sized from the weight
  file, and 1 GB is reserved for the reranker (#799). Default
  embeddinggemma/nomic throughput is unchanged. QMD_EMBED_PARALLELISM still
  overrides.

• Multi-collection -c A -c B (and SDK/MCP collections: [A, B]) no longer
  searches globally then post-filters. A large unrelated collection could fill
  the FTS/ANN top-k so the requested collections vanished, yielding false-empty
  results even though each collection matched on its own. searchFTS /
  searchVec now search each requested collection, then merge by score
  (#775). Single-collection exact-scan (#791, #803) is unchanged.

• Query expansion no longer consumes caller intent, and a cached expansion
  whose sub-queries all miss is dropped instead of replaying forever (#818).
  Intent still steers reranking and snippet/chunk selection; it just no longer
  enters the expansion prompt or cache key, where the model copied meta-language
  ("so I can compare spend settings") into lex/vec terms that matched nothing.

• Files whose names differ only in the characters the legacy slug collapsed to
  - (spaces, underscores) no longer evict each other from the index (#717).
  The handalized-path migration now skips any row whose path is still owned by
  a file in the current scan, so it only adopts genuinely stale pre-2.6 rows.
  qmd get and qmd ls <prefix> also match _ and % in paths literally
  instead of as SQL LIKE wildcards, so qmd get 2026_06_16.md no longer
  returns a sibling 2026-06-16.md.

• CLI multi-get and SDK/MCP multi_get now share one comma-list resolver.
  Collection-prefixed paths (qmd/docs/SYNTAX.md) work in both transports,
  unanchored LIKE '%name' no longer silently fetches a different document
  for a filename fragment (NTAX.md ≠ SYNTAX.md), and ambiguous names
  across collections error with the candidate list instead of LIMIT 1 (#759).

• The Nix flake wrapper now seeds the same pre-import env as bin/qmd.
  Nix installs exec bun src/cli/qmd.ts directly, so they previously skipped
  the launcher: qmd mcp could leak llama/ggml native logs onto JSON-RPC
  stdio, and Darwin CLI exits dumped a ggml Metal residency-set stack trace
  after an otherwise successful query. The wrapper now quiets those logs for
  mcp and sets GGML_METAL_NO_RESIDENCY=1 on Darwin unless
  QMD_METAL_KEEP_RESIDENCY=1 (#723).

• Rerank context creation no longer swallows the real failure. A VRAM OOM or
  corrupt model previously produced only Reranker unavailable — skipping reranking (and a dead identical retry whose comment claimed it disabled
  flash attention, which ranking contexts never supported). The warning now
  includes the underlying message so the two cases are distinguishable (#782).

• The Nix flake package now ships skills/ next to src/ in $out/lib/qmd/.
  findPackageRoot() walks up from the wrapped src/cli/qmd.ts looking for a
  sibling skills/ directory; without it, qmd skill show and qmd skills list
  always failed with "QMD skill not found" on Nix-installed binaries (#722).

• /release step 1 no longer points at a missing script. skills/release/scripts/release-context.sh
  now exists: it silently installs git hooks and prints version info, working-tree
  status, commits and files since the last tag, [Unreleased], and the previous
  changelog entry. The skill's process list also drops the duplicate step 7 and
  checks dependency updates before cutting the release (#796).

• store.searchVec() (and SDK searchVector()) now embed the query with the
  store's pinned embed model instead of the global QMD_EMBED_MODEL. A store
  created with a non-default models.embed previously failed with
  Dimension mismatch ... Expected N ... received M and loaded the wrong
  (often much larger) model at query time. Hybrid/precomputed/session search
  paths were unaffected and stay unchanged (#690).

• qmd collection add --mask "a.md,*.txt" now indexes the union of each
  pattern. The comma-separated form was documented and commonly guessed, but
  the joined string was passed to fast-glob as one literal glob, so it
  matched zero files with no error. Brace form {a.md,*.txt} is unchanged.
  The same split applies on qmd update for stored comma-list masks (#557).

• NixOS / immutable-root installs no longer crash qmd embed with EACCES
  when node-llama-cpp tries to compile llama.cpp into a read-only
  node_modules. The flake wrapper puts Nix's glibc and libstdc++ on
  LD_LIBRARY_PATH so prebuilt binaries can dlopen them, and
  getLlama() uses build: "never" when the llama directory is not
  writable (#574).

• CJK FTS rebuild no longer raises "database is busy" when flushing insert
  batches. The streaming .iterate() cursor stayed open across
  BEGIN on the same connection; the scan now uses keyset-paginated
  LIMIT batches so each SELECT finalizes before the insert transaction
  starts (#797).

• Quoted FTS phrases containing dotted tokens (e.g. "1.0.21") now match the
  indexed document. The porter unicode61 tokenizer stores dotted strings as
  adjacent parts, but phrase sanitization stripped the dots into a single
  token (1021) that could never hit. Dotted tokens inside quotes are split
  into adjacent phrase terms, matching the bare-term rewrite from #563 (#757).

• scripts/build.mjs no longer passes shell: true to spawnSync on Windows.
  With the default Node install path (C:\Program Files\nodejs\node.exe),
  cmd.exe split the unquoted process.execPath at the space, the tsc
  spawn failed, and prepare could still report success with no dist/ —
  leaving bin/qmd at "not built". The helper always receives a real binary
  path plus an args array, so no shell is needed. A spawn error now prints
  the missing binary path instead of failing silently. (#681)

• Case-sensitive collections no longer collapse distinct document identities that
  differ only by path casing. The implicit COLLATE NOCASE legacy migration was
  unsafe for filesystems that contain both README.md and readme.md; case-only
  legacy migrations must now be explicit and operator-reviewed (#801).

• cleanupOrphanedVectors now runs its orphan count and both DELETEs in a
  single immediate transaction. An interruption between the two DELETEs
  (crash, SQLITE_BUSY) could desync vectors_vec from content_vectors,
  leaving stale metadata rows that make a later reactivation of the same
  content hash look already-embedded — so qmd embed skips it and the
  document becomes silently unsearchable by vector, with no orphan left to
  clean up (#766).

• qmd embed no longer splits a UTF-16 surrogate pair (emoji, etc.) across a
  chunk boundary. A chunk ending or starting mid-pair produced an unpaired
  surrogate in the chunk text, which some remote embedding APIs reject as
  invalid JSON — permanently failing that chunk on every retry, since the
  boundary calculation is deterministic. This covers both the character-based
  chunker and chunkDocumentByTokens's recursive re-splitting for
  astral-plane-dense content, which could previously drive the char budget
  low enough to reproduce the same split (#777).

• insertContext looks up store_collections by name. #754 retargeted the
  query from the dropped collections table but left WHERE id = ?, and
  store_collections has name TEXT PRIMARY KEY with no id column — the
  call threw no such column: id. Matches deleteContext /
  updateStoreContext (#853).

• qmd collection add with no path argument now errors with usage instead of
  silently indexing the current working directory (#684). Pass . to index
  CWD, matching the documented examples.

• qmd status reports orphaned embedding chunks, qmd update hints when they
  exceed 10% of vectors, and qmd cleanup --dry-run previews what would be
  removed. Incremental update still does not auto-prune vectors (a transient
  empty mount would otherwise force a full re-embed) (#768).

• qmd --index <name> mcp --http --daemon now scopes PID/log files per index
  (mcp-<name>.pid) and passes the resolved database path to the child, so a
  named-index daemon no longer collides with the default mcp.pid or opens
  the default store (#772).

• Opening a store no longer throws SQLiteError: no such column: T.name when
  documents_fts is still the legacy fts5(name, body, content='documents')
  schema. CREATE VIRTUAL TABLE IF NOT EXISTS left that table in place, and
  the CJK FTS rebuild's DELETE FROM documents_fts compiled against
  documents.name, which does not exist (#792).

• Rerank cache keys now include the resolved models.rerank URI, so swapping
  the configured reranker no longer serves the previous model's cached scores
  (#764).

• vsearch -c <collection> no longer returns empty results for small
  collections crowded out of the global ANN candidate pool. searchVec now
  exact-scans the collection's vectors with vec_distance_cosine when the
  set is within 20k rows (ANN + post-filter cannot see collections that never
  enter global top-k, and sqlite-vec caps k at 4096 so a larger multiplier
  alone is not enough). Larger collections still use capped ANN over-fetch
  (#791, #803).

• multi-get --format files now emits the docid as its own CSV field
  (#docid,path,...) instead of prepending it into the path field with a
  space (#docid path,...), matching search --format files and keeping
  naive comma-splitting usable (#760).

• qmd embed now takes an exclusive process lock (.qmd-embed.lock next to
  the index DB) so concurrent invocations no longer race on vectors_vec
  and fail with UNIQUE constraint failed: vectors_vec.hash_seq. A second
  embed exits early with Another embed process is already running. Skipping.
  Stale locks from crashed processes are recovered via PID identity checks
  (#825).

• windows prepare fix #778 keeps dist build #824

• qmd mcp (stdio) now shuts down gracefully when stdin reaches EOF instead
  of orphaning to PID 1 when the parent MCP client dies (#751): the server
  closes its transport, gives in-flight request handlers a bounded window to
  settle, closes the store (which disposes its llama.cpp instance), and lets
  the process drain via process.exitCode (no forced process.exit(), which
  has caused exit-time native crashes before).

• qmd --version no longer reports an unrelated repository's commit (#787).
  The commit was discovered at runtime with git -C <installDir> rev-parse,
  and git -C walks up, so any install nested inside another checkout
  reported that checkout's HEAD — a global npm install under a git-managed
  prefix such as Homebrew's /opt/homebrew claimed Homebrew's commit as
  qmd's. Identical tarballs reported different "commits" depending only on
  where they were installed, which is why one issue can collect three distinct
  hashes for the same published build. scripts/build.mjs now stamps the
  commit it built from into dist/cli/build-info.json (suffixed -dirty when
  built from a modified tree), and the runtime prefers that. Source checkouts
  still resolve their own HEAD, but only after confirming the enclosing
  repository is qmd's; anything else reports no commit rather than a
  misleading one. The lookup also no longer interpolates the install path into
  a shell string, so a path containing a space stops silently dropping the
  commit, and --version from a build runs no subprocess at all.

• qmd doctor no longer false-positives .etag HTTP sidecars (written by
  qmd pull next to each download) as invalid GGUF models. The model-cache
  check now only inspects real .gguf files, so a sidecar that happens to
  sort before the blob no longer poisons the report. #812

• qmd mcp stop and qmd mcp --http --daemon now verify that a pidfile PID still belongs to a qmd process before signalling it or refusing to start. Recycled PIDs (common after reboot) are treated as stale: the pidfile is unlinked instead of SIGTERM'ing an unrelated process or blocking daemon start with a false "Already running" error (#806).

• qmd collection add now rejects missing paths and regular files before
  creating collection configuration or index state. The error reports both the
  received and resolved path so malformed shell arguments can be corrected.

• Claude Code plugin: scope the plugin source to ./skills so installs
  copy just the skills (~50 KB) instead of the entire repository. Previously a
  canonical install materialized ~230 MB / 9,000+ items into
  ~/.claude/plugins/cache/ — including a full npm dependency install
  triggered by the repo-root package.json. Both skills (qmd and release)
  still ship, unchanged. (#790)

• Claude Code plugin: releases now bump the plugin version in
  .claude-plugin/marketplace.json in lockstep with package.json. The
  plugin cache is keyed on this version, and it had been stuck at 0.1.0
  since February — so installed plugins never received skill updates
  (users who installed in February are still being served that snapshot
  today, despite the qmd skill nearly tripling in size since). Also bumps
  the plugin to 2.6.3 as a one-time catch-up so existing installs pick
  up the current skill on their next claude plugin update. (#789)

Changed

• --full-path no longer degrades silently when a result cannot be resolved on
  disk (#785). A fallback there means the file moved or was deleted since the
  last index, so search, query, get and multi-get now print a notice to
  stderr naming how many results fell back and suggesting qmd update; stdout
  stays machine-readable.
• search/query now decide per result whether to show the docid under
  --full-path, matching multi-get and get: a result that resolved shows
  its on-disk path and no docid, one that did not keeps its qmd:// URI and
  its docid, so it is still addressable. Previously the docid was dropped for
  every row whenever the flag was set, leaving unresolved rows with neither a
  usable path nor an identifier.
• search --format csv always emits the docid column, empty for rows that
  resolved to an on-disk path. Under --full-path the header previously
  dropped the column entirely — which also disagreed with the empty-result
  header, always printed with docid. Column positions are now stable across
  runs and formats.