ko-qmd 2.8.3-ko.2 → 2.8.3-ko.3

package/CHANGELOG.md

@@ -2,6 +2,130 @@
 
 ## [Unreleased]
 
+## [2.8.3-ko.3] - 2026-09-18
+
+The reranker now decides which document ranks first. The blend's retrieval-position
+term could outweigh the entire reranker score, so the top retrieval hit was
+unreachable; making position a 10% linear decay took recall@1 from .713 to .874 on
+223 name-like queries and from .467 to .867 on 30 paraphrase queries. The HTTP daemon
+gains two operational knobs: `QMD_QUERY_LOG=1` records every search it serves to a
+monthly JSONL, and `QMD_LLM_IDLE_TIMEOUT_MS=0` keeps models resident, which takes the
+first search after an idle spell from ~1.8s to ~0.07s.
+
+### Changes
+
+- `qmd query`'s reranker can now change which document comes first. The score
+  that orders results blended the reranker against a retrieval-position term of
+  `1 / rrfRank` under rank-gated weights, and that term falls 0.375 between rank
+  1 and rank 2 — more than the 0.25 the entire reranker term could contribute.
+  The top retrieval hit was therefore unreachable: a document the reranker scored
+  0.03 stayed ahead of one it scored 1.00. Position is now a linear decay across
+  the candidate window worth 10% of the blend, so it separates documents the
+  reranker scores alike instead of overruling it. Measured over a fixed candidate
+  dump per goldset, so every formula saw identical retrieval: recall@1 went .713
+  to .874 on 223 alias queries and .467 to .867 on 30 paraphrase queries. On both
+  goldsets the old blend's recall@1 equalled retrieval-only recall@1 to three
+  decimals, which is what an inert reranker looks like as a number.
+- New bench tooling: `scripts/bench-vault-summarize.ts` writes a plain-language
+  summary per document with a local model, and `bench-vault-summary-apply.mjs`
+  builds the summary-augmented copy of a vault that the bench then indexes. This
+  measures whether the vocabulary gap the paraphrase goldset is made of closes at
+  index time. On 16 such queries, giving each document three everyday-language
+  lines took `search` (BM25, no LLM) from .250 to .562 recall@5 and the unreranked
+  hybrid path from .625 to .812. The reranked path did not move (.875 both ways,
+  the same two queries missed): it was already covering the gap, so the summaries
+  buy the cheap backends most of what the expensive one had. The BM25 number
+  carries no confound — that backend never calls query expansion. Summary lines
+  are filtered by document frequency, because a model that emits "이 도구는 뭘 하는
+  건데?" would otherwise give every vague query a weak match on an unrelated
+  document.
+- New bench tooling: `scripts/bench-dump-candidates.ts` records the RRF rank and
+  reranker score of every candidate for each goldset query, and
+  `scripts/bench-blend-sweep.mjs` re-scores that dump under different blend
+  formulas. Comparing two formulas used to mean two bench runs, which vary in
+  their retrieval and take about an hour each; it now costs one dump and a
+  millisecond per formula, and the variants are compared against the same
+  candidates.
+
+- `bench-vault-goldset.mjs` adds two buckets that cost no model call: `alias`,
+  the display text of a `[[target|alias]]` wikilink, and `fmalias`, an entry of
+  the target's own `aliases:` frontmatter list. Both are human-written other
+  names for a document. First measurement on a 232-document vault (223 queries):
+  `full` scored 0.924 r@5 against `hybrid` 0.978 and `vector` 0.982 — of the 17
+  queries `full` missed, `hybrid` had 14 in its top five. The reranker demotes
+  short name-like queries that retrieval already found.
+- `bench-vault-paraphrase.ts` writes its output after every document, so a run
+  killed from outside keeps what it had done.
+
+- `QMD_LLM_IDLE_TIMEOUT_MS` sets how long loaded models stay idle before they
+  are unloaded (`0` = never), overriding the 5 minutes `createStore()` passes.
+  On a long-running HTTP daemon the first search after a quiet spell no longer
+  pays for reloading the models.
+- `QMD_QUERY_LOG=1` makes the HTTP daemon append every `POST /query` /
+  `/search` search to `queries-YYYY-MM.jsonl` in the qmd cache directory: the
+  qmd version and commit, an index fingerprint, the searches, and each result's
+  path, score and rank — never snippets. Clients tag rows with `X-QMD-Tag`,
+  `X-QMD-Qid` and `X-QMD-Role`, and skip them with `X-QMD-No-Log: 1`. Writes
+  never fail a search; `qmd status` shows the newest log file and the MCP
+  `status` tool shows the daemon's flag and last write error.
+- `scripts/dogfood.sh` builds the checkout, stops if bench-ko `bm25_r5` falls
+  below the newest BASELINE.md line, installs the packed tarball globally,
+  restarts the launchd daemon and smoke-tests it; `--restore` reinstalls the
+  published package.
+
+- `develop` is the working branch; `main` only receives merges from it and is
+  where `/release` tags. `publish.yml` authenticates with the `NPM_TOKEN`
+  repository secret and skips a version that is already on the registry, so a
+  manually published version or a re-pushed tag still gets its GitHub release.
+  CI runs for `develop` pushes and pull requests too.
+
+### Fixes
+
+- `bench-vault-report.mjs` writes its miss list next to the input, never on top
+  of it. The path came from `replace('bench.json', 'misses.json')`, a no-op for
+  any other file name, so reporting on a copied result overwrote that result.
+- Query expansion drops sub-queries that have nothing to do with the query again.
+  The drift filter kept an expansion only if it shared a word with the query, but
+  it read the query as `[a-z0-9]` words, so a Korean query produced an empty word
+  list and the filter passed everything. Measured over 151 expansions of 30
+  Korean queries it rejected none, including 22 that were generic English
+  boilerplate ("Proper implementation follows established patterns and best
+  practices.") with no relation to the query — each one an embedding call and a
+  vector search spent on noise. A shared Hangul syllable bigram now counts as the
+  same kind of anchor: it drops those 22 and keeps 127 of the 129 Korean
+  expansions. A query with no anchor of either kind still keeps everything.
+- Query expansion strips thinking tags from a sub-query before searching for it.
+  The grammar forbids newlines inside a line, so a `</think>` arrives welded to
+  the sub-query text rather than on a line of its own that parsing would skip; 20
+  of 46 hyde expansions in the same measurement carried one, and the tag was
+  embedded along with the text that mattered.
+- Query expansion no longer runs the same sub-query twice on the same backend.
+- `limit` no longer decides how wide a search looks, only how many results come
+  back. Both searches over-fetch by a multiple of `limit` — the FTS index by 10x
+  because the collection filter runs after the match, vectors by 3x or 30x
+  because chunks of one document collapse into one result — so a small `limit`
+  left a pool that post-filtering could exhaust, and `-n 5` was not the first five
+  of `-n 20`. The CLI made it visible: its default limit is 20 for `--json` and
+  `--files` and 5 otherwise, so the output format changed which documents were
+  found. Retrieval now looks at 20 documents at minimum whatever `limit` says,
+  which is the breadth `qmd query` already used internally.
+- `bench-vault.sh` refuses to run when the vault it was given sits inside the
+  work directory it is about to `rm -rf`. The work directory is named after the
+  vault, so a vault under `tmp/real-bench/` resolved to the same path and the
+  corpus was deleted before it could be indexed, which showed up as a bench over
+  zero documents rather than as an error.
+- `bench-vault-report.mjs` prints every backend that ran under each bucket, and
+  takes its miss list from the best backend rather than from BM25. The bucket
+  lines were BM25-only under a bare bucket name, so a run's `sem: 9/16` read as
+  the result of the pipeline the run was measuring.
+
+- The Windows git-install probe failed on every push with `Permission denied
+  (publickey)`: npm and pnpm resolve any github.com dependency over SSH first
+  and do not retry an auth failure over https, the runner has no key, and the
+  repository is private so anonymous https fails as well. The job now rewrites
+  every github.com URL to https with the job token via git `insteadOf` before
+  installing.
+
 ## [2.8.3-ko.2] - 2026-09-17
 
 ### Changes

package/README.ko.md

@@ -4,7 +4,7 @@
 
 - 패키지 이름: `ko-qmd` (npm 발행 — `v*` 태그 push 가 `publish.yml` 로 발행)
 - 버전 규칙: `<업스트림 버전>-ko.N` (예: `2.8.3-ko.0`)
-- 브랜치: `main` = 배포 브랜치(업스트림 릴리스 + 한국어 패치 스택). 업스트림은 `upstream` 원격으로만 따라간다 — 포크가 아니다.
+- 브랜치: `develop` = 작업 브랜치(PR 은 여기로), `main` = 배포 브랜치(develop 을 머지한 뒤 `/release` 로 태그 → `publish.yml` 이 `NPM_TOKEN` 시크릿으로 발행). 업스트림은 `upstream` 원격으로만 따라간다 — 포크가 아니다.
 
 ## 업스트림과 다른 점
 
@@ -13,9 +13,12 @@
    - 질의: 따옴표 없는 한글 단어는 끝 조사 하나 또는 `기`를 뗀 어간도 매칭한다(`검색을` → `검색`, 어간 2음절 이상). 따옴표 구문·한자·가나는 그대로.
    - 색인: 한글 구간의 음절 bigram을 필드 끝에 덧붙인다. `FTS_CJK_NORMALIZED_VERSION`이 `"2"`라 기존 인덱스는 처음 열 때 FTS를 한 번 다시 만든다.
 3. 한국어 기본값
-   - 기본 임베딩 모델: `hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf`(업스트림은 embeddinggemma-300M). 리랭커·질의 확장 모델은 업스트림 기본값 그대로. 업스트림 [README.md](README.md)의 모델 표·"Custom Embedding Model" 절은 업스트림 기본값 기준이다.
+   - 기본 임베딩 모델: `hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf`(업스트림은 embeddinggemma-300M). [README.md](README.md)의 모델 표·"Custom Embedding Model"·"Model Configuration" 절도 이 기본값 기준으로 고쳐 뒀다. 리랭커·질의 확장 모델은 업스트림 기본값 그대로.
    - 스킬 `skills/qmd/SKILL.md`에 "Korean queries" 절(`lex:`에 어간·alias·영문 용어, `vec:`에 한국어 패러프레이즈).
 
+4. 데몬 질의 로그 (`src/query-log.ts`, `server.ts` 접점 = REST 핸들러·`status` 툴): `QMD_QUERY_LOG=1` 로 띄운 HTTP 데몬이 REST 검색마다 `queries-YYYY-MM.jsonl` 에 한 줄을 남긴다(결과 경로·점수, 스니펫 없음). 헤더 `X-QMD-Tag`·`X-QMD-Qid`·`X-QMD-Role`·`X-QMD-No-Log`. 계약은 [README.md § Query log](README.md#query-log-ko-qmd). 업스트림 PR 대상 아님.
+5. 모델 idle 타임아웃 env (`src/llm.ts` `LlamaCpp` 생성자): `QMD_LLM_IDLE_TIMEOUT_MS` 가 `createStore()` 의 5분 고정값보다 우선한다. `0` 이면 모델을 내리지 않는다 — 상주 데몬의 첫 검색이 모델을 다시 올리지 않게 하는 용도다.
+
 ### 기본 임베딩 변경 후 재임베딩
 
 벡터는 모델 사이에 호환되지 않는다. embeddinggemma로 만든 기존 인덱스는 다시 임베딩해야 한다.
@@ -26,6 +29,19 @@ qmd embed -f
 
 embeddinggemma를 계속 쓰려면 `index.yml`의 `models: embed:` 또는 `QMD_EMBED_MODEL`로 지정한다.
 
+### dogfood — 작업 트리 빌드를 이 머신 데몬에 올리기
+
+```sh
+bash scripts/dogfood.sh              # build → bench-ko 게이트 → npm pack → npm i -g → 데몬 재시작 → 스모크
+bash scripts/dogfood.sh --restore    # 발행본(DOGFOOD_PIN_FILE 의 ko-qmd@<버전>, 없으면 latest)으로 되돌림
+bash scripts/dogfood.sh --check "RESULT bm25_r5=…"   # 게이트 판정만
+```
+
+- 게이트: `bench-ko.sh` 의 `bm25_r5` 가 [BASELINE.md](test/fixtures/ko-vault/BASELINE.md) 의 마지막 bench-ko `RESULT` 줄보다 낮으면 설치 전에 멈춘다(exit 3). bench 는 소스를 tsx 로 돌리므로, 설치된 `dist/` 는 스모크(설치된 `qmd --version` 의 커밋 · `POST /query`)가 확인한다.
+- `npm link` 가 아니라 pack 설치다 — 링크하면 데몬이 작업 트리의 `dist/` 를 서빙해 빌드 중에 깨질 수 있다.
+- 머신 배선은 env: `DOGFOOD_LABEL`(launchd 라벨, 기본 `com.lemoncloud.qmd-daemon`) · `DOGFOOD_URL`(기본 `http://127.0.0.1:8181`) · `DOGFOOD_SMOKE`(추가 스모크 명령 — `"status":"hit"` JSON 을 내야 함) · `DOGFOOD_PIN_FILE`.
+- 성공하면 `~/.cache/qmd/dogfood-deployed` 에 `<시각> <커밋>` 을 쓴다(`--restore` 가 지운다). 배치 중에는 설치된 바이너리가 발행본 핀과 다르다 — `qmd --version` 의 커밋이 구분자.
+
 ### ko-vault 벤치
 
 `bash scripts/bench-ko.sh` (픽스처 `test/fixtures/ko-vault/`, 문서 28·질의 36, 임베딩은 픽스처 `models.yml`의 embeddinggemma로 고정). 표와 run별 수치는 [BASELINE.md](test/fixtures/ko-vault/BASELINE.md).
@@ -48,6 +64,8 @@ npm install -g ko-qmd@<version>
 "ko-qmd": "<version>"
 ```
 
+버전은 `<업스트림 버전>-ko.N` 형태의 prerelease 라, `^`·`~` 범위는 같은 `major.minor.patch` 의 `-ko.*` 안에서만 움직인다(`^2.8.3-ko.0` 은 `2.8.4-ko.0` 을 안 집는다). 정확한 버전으로 핀한다.
+
 업스트림 `@tobilu/qmd` 와 bin 이름이 같아 둘을 함께 둘 수 없다 — `npm uninstall -g @tobilu/qmd` 뒤 설치한다. 미발행 커밋은 GitHub 에서 직접(`npm i github:tak-bro/ko-qmd#<sha>`) 받을 수 있고, 그때는 `prepare`가 `scripts/build.mjs`(= `tsc -p tsconfig.build.json`)로 `dist/`를 만든다. **설치에는 node + tsc만 필요하고 bun은 필요 없다.** 개발용 `npm run test:unit`은 vitest와 `bun test`를 둘 다 돌리므로 bun이 필요하다.
 
 설치 스모크(빈 디렉터리):

package/README.md

@@ -1,7 +1,8 @@
 > **ko-qmd** (`npm i -g ko-qmd`) — a Korean-language distribution of [tobi/qmd](https://github.com/tobi/qmd) (MIT).
 > Hangul particle stripping and syllable-bigram FTS in the lex path, Qwen3-Embedding-0.6B as the
 > default embedding model. Everything below is upstream's README and still applies: the CLI, the MCP
-> server and the package binary are all called `qmd`.
+> server and the package binary are all called `qmd`. Where it says `@tobilu/qmd` — install commands,
+> SDK `import`s — use `ko-qmd`; the upstream name installs upstream, with none of the Hangul patches.
 > Korean notes, install and release process: [README.ko.md](README.ko.md).
 
 # QMD - Query Markup Documents
@@ -118,7 +119,7 @@ Although the tool works perfectly fine when you just tell your agent to use it o
 **Claude Code** — Install the plugin (recommended):
 
 ```bash
-claude plugin marketplace add tobi/qmd
+claude plugin marketplace add tak-bro/ko-qmd
 claude plugin install qmd@qmd
 ```
 
@@ -160,6 +161,30 @@ The HTTP server exposes two endpoints:
 - `POST /query` (alias `/search`) — structured search without the MCP protocol
 - `GET /health` — liveness check with uptime
 
+##### Query log (ko-qmd)
+
+Start the daemon with `QMD_QUERY_LOG=1` (`true`/`yes` also work; anything else
+is off) and every search served by `POST /query` or `/search` is appended as
+one JSON line to `$XDG_CACHE_HOME/qmd/queries-YYYY-MM.jsonl` (default
+`~/.cache/qmd`, one file per local month, mode `0600`, never pruned). CLI
+searches and MCP tool calls are not logged.
+
+A row records the qmd version and commit, an index fingerprint (document count
+and last update), the searches, collections, limit, rerank flag, each result's
+`<collection>/<path>`, score and rank, and the elapsed milliseconds — no
+snippets or document text. Clients can annotate rows with request headers:
+
+| Header | Row field |
+|--------|-----------|
+| `X-QMD-Tag` | `client.tag` (first 32 characters) |
+| `X-QMD-Qid` | `client.qid` (first 64 characters) — groups the requests of one lookup |
+| `X-QMD-Role` | `client.role` — `primary`, `probe`, `canary` or `replay`; anything else is `null` |
+| `X-QMD-No-Log` | `1` skips the row (tests, evaluation runs) |
+
+Writes happen after the response and never fail a search. `qmd status` shows
+the newest log file; the daemon's MCP `status` tool also shows whether logging
+is on and the last write error.
+
 
 ##### Origin and Host validation
 
@@ -563,29 +588,29 @@ QMD uses three local GGUF models (auto-downloaded on first use):
 
 | Model | Purpose | Size |
 |-------|---------|------|
-| `embeddinggemma-300M-Q8_0` | Vector embeddings (default) | ~300MB |
+| `Qwen3-Embedding-0.6B-Q8_0` | Vector embeddings (default) | ~640MB |
 | `qwen3-reranker-0.6b-q8_0` | Re-ranking | ~640MB |
-| `qmd-query-expansion-1.7B-q4_k_m` | Query expansion (fine-tuned) | ~1.1GB |
+| `qmd-query-expansion-1.7B-q4_k_m` | Query expansion (fine-tuned) | ~1.3GB |
 
 Models are downloaded from HuggingFace and cached in `~/.cache/qmd/models/`.
 
 ### Custom Embedding Model
 
-Override the default embedding model via the `QMD_EMBED_MODEL` environment variable.
-This is useful for multilingual corpora (e.g. Chinese, Japanese, Korean) where
-`embeddinggemma-300M` has limited coverage.
+The default is Qwen3-Embedding-0.6B — multilingual (119 languages including CJK),
+MTEB top-ranked. Override it via the `QMD_EMBED_MODEL` environment variable, for
+example to fall back to embeddinggemma-300M's smaller footprint on an English-only
+corpus:
 
 ```sh
-# Use Qwen3-Embedding-0.6B for better multilingual (CJK) support
-export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
+export QMD_EMBED_MODEL="hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf"
 
 # After changing the model, re-embed all collections:
 qmd embed -f
 ```
 
 Supported model families:
-- **embeddinggemma** (default) — English-optimized, small footprint
-- **Qwen3-Embedding** — Multilingual (119 languages including CJK), MTEB top-ranked
+- **Qwen3-Embedding** (default) — Multilingual (119 languages including CJK), MTEB top-ranked
+- **embeddinggemma** — English-optimized, small footprint
 
 > **Note:** When switching embedding models, you must re-index with `qmd embed -f`
 > since vectors are not cross-compatible between models. The prompt format is
@@ -602,8 +627,8 @@ bun install -g @tobilu/qmd
 ### Development
 
 ```sh
-git clone https://github.com/tobi/qmd
-cd qmd
+git clone https://github.com/tak-bro/ko-qmd
+cd ko-qmd
 npm install
 npm link
 ```
@@ -732,7 +757,7 @@ editor_uri: "vscode://file{path}:{line}:{col}"
 # built-in defaults. `qmd init` writes this block pre-filled with the
 # resolved defaults. See "Model Configuration" for the default URIs.
 models:
-  embed: "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf"
+  embed: "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
   rerank: "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf"
   generate: "hf:tobil/qmd-query-expansion-1.7B-gguf/qmd-query-expansion-1.7B-q4_k_m.gguf"
 
@@ -1155,6 +1180,8 @@ llm_cache       -- Cached LLM responses (query expansion, rerank scores)
 | `QMD_CONFIG_DIR` | unset | Override the config directory outright (takes precedence over `XDG_CONFIG_HOME`) |
 | `QMD_LLAMA_GPU` | `auto` | Force llama.cpp GPU backend (`metal`, `vulkan`, `cuda`) or disable GPU with `false` |
 | `QMD_FORCE_CPU` | unset | Set to `1`/`true` to force CPU mode before any CUDA/Vulkan/Metal probing. Equivalent CLI flag: `--no-gpu`. |
+| `QMD_QUERY_LOG` | unset | ko-qmd: set to `1`/`true`/`yes` on the HTTP daemon to append each search to `$XDG_CACHE_HOME/qmd/queries-YYYY-MM.jsonl` (see [Query log](#query-log-ko-qmd)) |
+| `QMD_LLM_IDLE_TIMEOUT_MS` | `300000` | ko-qmd: idle time in ms before loaded models and contexts are unloaded; `0` never unloads. Overrides the SDK's `createStore()` timeout, so a long-running HTTP daemon can skip the model reload on its first search after a quiet spell, at the cost of keeping that memory in use. |
 | `QMD_EMBED_PARALLELISM` | automatic | Override embedding/reranking context parallelism (1-8). Windows CUDA defaults to `1` because parallel CUDA contexts can crash with `ggml-cuda.cu:98`; use Vulkan or raise this only if your driver is stable. |
 
 ## How It Works
@@ -1275,14 +1302,16 @@ Query ──► LLM Expansion ──► [Original, Variant 1, Variant 2]
 The default models are defined in `src/llm.ts` as HuggingFace URIs:
 
 ```typescript
-const DEFAULT_EMBED_MODEL = "hf:ggml-org/embeddinggemma-300M-GGUF/embeddinggemma-300M-Q8_0.gguf";
+const DEFAULT_EMBED_MODEL = "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf";
 const DEFAULT_RERANK_MODEL = "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf";
 const DEFAULT_GENERATE_MODEL = "hf:tobil/qmd-query-expansion-1.7B-gguf/qmd-query-expansion-1.7B-q4_k_m.gguf";
 ```
 
 Override them per-role without touching source via the `models:` block in
 `index.yml` (see [Configuring `index.yml`](#configuring-indexyml)) or the
-`QMD_EMBED_MODEL` env var. Re-run `qmd embed` after changing the embedding model.
+`QMD_EMBED_MODEL` / `QMD_RERANK_MODEL` / `QMD_GENERATE_MODEL` env vars. The
+config block wins over the env var, which wins over the built-in default.
+Re-run `qmd embed` after changing the embedding model.
 
 ### EmbeddingGemma Prompt Format
 

package/dist/cli/build-info.json

@@ -1,4 +1,4 @@
 {
-  "commit": "3b53262",
-  "builtAt": "2026-09-17T02:43:15.469Z"
+  "commit": "d4da081",
+  "builtAt": "2026-09-18T03:59:04.070Z"
 }

package/dist/cli/qmd.js

@@ -13,6 +13,7 @@ import { getPwd, getRealPath, isPathInsideDir, homedir, resolve, enableProductio
 import { disposeDefaultLlamaCpp, getDefaultLlamaCpp, setDefaultLlamaCpp, LlamaCpp, withLLMSession, pullModels, DEFAULT_MODEL_CACHE_DIR, resolveEmbedModel, resolveGenerateModel, resolveRerankModel, resolveModels, inspectGgufFile, isDarwinMetalMitigationActive } from "../llm.js";
 import { formatSearchResults, formatDocuments, escapeXml, escapeCSV, } from "./formatter.js";
 import { resolveCommit } from "./version.js";
+import { latestQueryLogFile } from "../query-log.js";
 import { getCollection as getCollectionFromYaml, listCollections as yamlListCollections, getDefaultCollectionNames, addContext as yamlAddContext, removeContext as yamlRemoveContext, removeCollection as yamlRemoveCollectionFn, renameCollection as yamlRenameCollectionFn, setGlobalContext, listAllContexts, setConfigIndexName, loadConfig, saveConfig, setConfigSource, findLocalConfigPath, getLocalDbPath, getConfigPath, configExists, } from "../collections.js";
 import { decideLocalConfigGate, gatedItems, hasGatedItems, isCollectionPathInsideProject, isLocalConfigPath, isLocalConfigTrustOptedIn, isTrusted, listTrusted, recordTrust, revokeTrust, sensitiveDigest, } from "../trust.js";
 // NOTE: enableProductionMode() is intentionally NOT called at module scope here.
@@ -384,6 +385,19 @@ async function showStatus() {
             // Stale / recycled PID file cleaned up silently
         }
     }
+    // ko-qmd: the daemon's query log. This process cannot see the daemon's env,
+    // so report what is on disk; the daemon's own `status` tool shows its flag and errors.
+    const queryLogFile = latestQueryLogFile();
+    if (queryLogFile.kind === "file") {
+        // File name only: status keeps filesystem paths out of its output (the Index line aside).
+        console.log(`Query log: ${basename(queryLogFile.path)} (last write ${formatTimeAgo(queryLogFile.modified)})`);
+    }
+    else if (queryLogFile.kind === "error") {
+        console.log(`Query log: ${c.yellow}unreadable — ${queryLogFile.message}${c.reset}`);
+    }
+    else {
+        console.log(`Query log: ${c.dim}none (daemon writes it when started with QMD_QUERY_LOG=1)${c.reset}`);
+    }
     console.log("");
     const orphanedVectors = countOrphanedVectors(db);
     console.log(`${c.bold}Documents${c.reset}`);
@@ -3333,7 +3347,8 @@ function collectEnvironmentOverrides(activeModels, configModels = {}) {
     add("INDEX_PATH", "overrides the SQLite index path; QMD reads/writes a different database");
     add("QMD_CONFIG_DIR", "overrides the QMD config directory and takes precedence over XDG_CONFIG_HOME");
     add("XDG_CONFIG_HOME", "moves QMD config to $XDG_CONFIG_HOME/qmd when QMD_CONFIG_DIR is not set");
-    add("XDG_CACHE_HOME", "moves the default index cache, model cache, and MCP daemon PID files");
+    add("XDG_CACHE_HOME", "moves the default index cache, model cache, MCP daemon PID files, and query logs");
+    add("QMD_QUERY_LOG", "1/true/yes makes the HTTP daemon append each search to queries-YYYY-MM.jsonl in the cache dir");
     addModel("QMD_EMBED_MODEL", "embed", activeModels.embed);
     addModel("QMD_GENERATE_MODEL", "generate", activeModels.generate);
     addModel("QMD_RERANK_MODEL", "rerank", activeModels.rerank);
@@ -3341,6 +3356,7 @@ function collectEnvironmentOverrides(activeModels, configModels = {}) {
     add("QMD_LLAMA_GPU", "selects llama.cpp GPU backend (metal/cuda/vulkan) or disables GPU when set to false/off/0");
     add("QMD_DOCTOR_DEVICE_PROBE", "controls qmd doctor native device probing; 0/off skips GPU probing");
     add("QMD_EMBED_PARALLELISM", "overrides embedding parallel context count; too high can exhaust RAM/VRAM");
+    add("QMD_LLM_IDLE_TIMEOUT_MS", "ms of idle before models unload (0 = never); keeping them loaded holds their memory");
     add("QMD_EXPAND_CONTEXT_SIZE", "overrides query expansion context size; larger values use more memory");
     add("QMD_RERANK_CONTEXT_SIZE", "overrides reranker context size; larger values use more memory");
     add("QMD_EMBED_CONTEXT_SIZE", "overrides embed context size; larger values use more memory");

package/dist/hangul.d.ts

@@ -12,6 +12,15 @@
  * one run stay contiguous.
  */
 export declare function hangulBigramTail(text: string): string;
+/**
+ * Whether two texts share a Hangul syllable bigram (`검색을 고치기` and `문서 검색`
+ * share `검색`). Two Korean sentences about the same thing overlap in syllables long
+ * before they overlap in whole words, because the words carry different particles and
+ * endings, so a bigram is the smallest unit that says "these are about the same thing"
+ * without stemming both sides. Returns false when either side has no Hangul run of two
+ * or more syllables.
+ */
+export declare function sharesHangulBigram(a: string, b: string): boolean;
 /**
  * Strip one trailing particle (or 기) from a pure-Hangul word when the stem
  * keeps at least two syllables (`검색을` → `검색`, `책을` stays). Returns null

package/dist/hangul.js

@@ -36,6 +36,25 @@ export function hangulBigramTail(text) {
     const runs = text.match(HANGUL_RUN_PATTERN) ?? [];
     return runs.flatMap(syllableBigrams).join(" ");
 }
+/**
+ * Whether two texts share a Hangul syllable bigram (`검색을 고치기` and `문서 검색`
+ * share `검색`). Two Korean sentences about the same thing overlap in syllables long
+ * before they overlap in whole words, because the words carry different particles and
+ * endings, so a bigram is the smallest unit that says "these are about the same thing"
+ * without stemming both sides. Returns false when either side has no Hangul run of two
+ * or more syllables.
+ */
+export function sharesHangulBigram(a, b) {
+    const left = new Set((a.match(HANGUL_RUN_PATTERN) ?? []).flatMap(syllableBigrams));
+    if (left.size === 0)
+        return false;
+    for (const run of b.match(HANGUL_RUN_PATTERN) ?? []) {
+        for (const gram of syllableBigrams(run))
+            if (left.has(gram))
+                return true;
+    }
+    return false;
+}
 /**
  * Strip one trailing particle (or 기) from a pure-Hangul word when the stem
  * keeps at least two syllables (`검색을` → `검색`, `책을` stays). Returns null

package/dist/index.js

@@ -78,7 +78,7 @@ export async function createStore(options) {
     }
     // else: DB-only mode — no external config, use existing store_collections
     // Create a per-store LlamaCpp instance — lazy-loads models on first use,
-    // auto-unloads after 5 min inactivity to free VRAM.
+    // auto-unloads after 5 min inactivity to free VRAM (QMD_LLM_IDLE_TIMEOUT_MS overrides).
     const llm = new LlamaCpp({
         embedModel: config?.models?.embed,
         generateModel: config?.models?.generate,

package/dist/llm.d.ts

@@ -157,6 +157,26 @@ export type Queryable = {
     type: QueryType;
     text: string;
 };
+/**
+ * Parse the expansion model's "type: text" lines into sub-queries, dropping the ones
+ * that would cost a search and return nothing useful.
+ *
+ * Three rejections, in order: a line whose text is empty once thinking tags are removed;
+ * a line that drifted off the query; and a line repeating a sub-query already kept for
+ * the same backend, which is the same search run twice.
+ *
+ * The drift rule needs an anchor shared with the query. Upstream reads [a-z0-9] words,
+ * so for a Hangul query the anchor list came out empty and the rule passed everything —
+ * measured 2026-09-18 over 151 expansions of 30 Korean queries it rejected none, keeping
+ * 22 that were generic English boilerplate ("Proper implementation follows established
+ * patterns and best practices.") unrelated to the query. Accepting a shared Hangul
+ * syllable bigram as an anchor drops those 22 and 2 of the 129 Korean expansions, both
+ * sentence fragments with no content word.
+ *
+ * A query with no anchor of either kind (a lone syllable, a symbol) keeps every line, as
+ * before: there is nothing to compare against.
+ */
+export declare function parseExpansionLines(query: string, raw: string): Queryable[];
 /**
  * Document to rerank
  */
@@ -264,6 +284,13 @@ export type LlamaCppConfig = {
      */
     disposeModelsOnInactivity?: boolean;
 };
+/**
+ * ko-qmd: QMD_LLM_IDLE_TIMEOUT_MS overrides the idle unload timeout, including
+ * the 5 minutes createStore() passes. A long-lived daemon sets it to keep the
+ * first search after a quiet spell from reloading models (0 = never unload).
+ * Returns undefined when unset or invalid (with a warning).
+ */
+export declare function resolveIdleTimeoutOverride(envValue?: string | undefined): number | undefined;
 export type LlamaGpuMode = "auto" | "metal" | "vulkan" | "cuda" | false;
 type ParallelismOptions = {
     gpu: string | false;

package/dist/llm.js

@@ -48,6 +48,7 @@ import { homedir } from "os";
 import { dirname, join } from "path";
 import { accessSync, constants, existsSync, mkdirSync, statSync, unlinkSync, readdirSync, readFileSync, writeFileSync, openSync, readSync, closeSync } from "fs";
 import { createRequire } from "node:module";
+import { hangulBigramTail, sharesHangulBigram } from "./hangul.js";
 // =============================================================================
 // Embedding Formatting Functions
 // =============================================================================
@@ -105,6 +106,76 @@ export function canWriteLlamaDir(pkgDir) {
         return false;
     }
 }
+/**
+ * Thinking tags welded onto an expansion line.
+ *
+ * The model is prompted with /no_think and the grammar forbids newlines inside a line,
+ * so a thinking block cannot arrive as a line of its own — it arrives attached to a
+ * sub-query, usually as a trailing "</think>" the grammar had no reason to reject.
+ * Measured 2026-09-18 on 30 Korean queries, 20 of 46 hyde expansions carried one; left
+ * in, the tag is embedded and searched for along with the text that matters.
+ */
+function stripThinkTags(text) {
+    return text
+        .replace(/<think>[\s\S]*?<\/think>/g, " ")
+        .replace(/<\/?think>/g, " ")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+/**
+ * Parse the expansion model's "type: text" lines into sub-queries, dropping the ones
+ * that would cost a search and return nothing useful.
+ *
+ * Three rejections, in order: a line whose text is empty once thinking tags are removed;
+ * a line that drifted off the query; and a line repeating a sub-query already kept for
+ * the same backend, which is the same search run twice.
+ *
+ * The drift rule needs an anchor shared with the query. Upstream reads [a-z0-9] words,
+ * so for a Hangul query the anchor list came out empty and the rule passed everything —
+ * measured 2026-09-18 over 151 expansions of 30 Korean queries it rejected none, keeping
+ * 22 that were generic English boilerplate ("Proper implementation follows established
+ * patterns and best practices.") unrelated to the query. Accepting a shared Hangul
+ * syllable bigram as an anchor drops those 22 and 2 of the 129 Korean expansions, both
+ * sentence fragments with no content word.
+ *
+ * A query with no anchor of either kind (a lone syllable, a symbol) keeps every line, as
+ * before: there is nothing to compare against.
+ */
+export function parseExpansionLines(query, raw) {
+    // Single characters are not anchors: a query containing "1:1" would otherwise keep
+    // every expansion with a digit in it, which is most of them.
+    const queryTerms = query.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter(t => t.length >= 2);
+    const queryHasHangul = hangulBigramTail(query).length > 0;
+    const onQuery = (text) => {
+        if (queryTerms.length === 0 && !queryHasHangul)
+            return true;
+        const lower = text.toLowerCase();
+        if (queryTerms.some(term => lower.includes(term)))
+            return true;
+        return queryHasHangul && sharesHangulBigram(query, text);
+    };
+    const seen = new Set();
+    const queryables = [];
+    for (const line of raw.trim().split("\n")) {
+        const colonIdx = line.indexOf(":");
+        if (colonIdx === -1)
+            continue;
+        const type = line.slice(0, colonIdx).trim();
+        if (type !== "lex" && type !== "vec" && type !== "hyde")
+            continue;
+        const text = stripThinkTags(line.slice(colonIdx + 1));
+        if (!text)
+            continue;
+        if (!onQuery(text))
+            continue;
+        const key = `${type}\n${text.toLowerCase()}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        queryables.push({ type, text });
+    }
+    return queryables;
+}
 // =============================================================================
 // Model Configuration
 // =============================================================================
@@ -338,6 +409,22 @@ export async function pullModels(models, options = {}) {
  */
 // Default inactivity timeout: 5 minutes (keep models warm during typical search sessions)
 const DEFAULT_INACTIVITY_TIMEOUT_MS = 5 * 60 * 1000;
+/**
+ * ko-qmd: QMD_LLM_IDLE_TIMEOUT_MS overrides the idle unload timeout, including
+ * the 5 minutes createStore() passes. A long-lived daemon sets it to keep the
+ * first search after a quiet spell from reloading models (0 = never unload).
+ * Returns undefined when unset or invalid (with a warning).
+ */
+export function resolveIdleTimeoutOverride(envValue = process.env.QMD_LLM_IDLE_TIMEOUT_MS) {
+    const normalized = envValue?.trim() ?? "";
+    if (!normalized)
+        return undefined;
+    if (!/^\d+$/.test(normalized)) {
+        process.stderr.write(`QMD Warning: invalid QMD_LLM_IDLE_TIMEOUT_MS="${envValue}", using the default idle timeout.\n`);
+        return undefined;
+    }
+    return Number(normalized);
+}
 const DEFAULT_EXPAND_CONTEXT_SIZE = 2048;
 export function resolveParallelismOverride(envValue = process.env.QMD_EMBED_PARALLELISM) {
     const normalized = envValue?.trim() ?? "";
@@ -509,7 +596,8 @@ export class LlamaCpp {
         this.rerankModelUri = resolveRerankModel({ rerank: config.rerankModel });
         this.modelCacheDir = config.modelCacheDir || MODEL_CACHE_DIR;
         this.expandContextSize = resolveExpandContextSize(config.expandContextSize);
-        this.inactivityTimeoutMs = config.inactivityTimeoutMs ?? DEFAULT_INACTIVITY_TIMEOUT_MS;
+        this.inactivityTimeoutMs = resolveIdleTimeoutOverride()
+            ?? config.inactivityTimeoutMs ?? DEFAULT_INACTIVITY_TIMEOUT_MS;
         this.disposeModelsOnInactivity = config.disposeModelsOnInactivity ?? false;
     }
     get embedModelName() {
@@ -1244,27 +1332,7 @@ export class LlamaCpp {
                     presencePenalty: 0.5,
                 },
             });
-            const lines = result.trim().split("\n");
-            const queryLower = query.toLowerCase();
-            const queryTerms = queryLower.replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter(Boolean);
-            const hasQueryTerm = (text) => {
-                const lower = text.toLowerCase();
-                if (queryTerms.length === 0)
-                    return true;
-                return queryTerms.some(term => lower.includes(term));
-            };
-            const queryables = lines.map(line => {
-                const colonIdx = line.indexOf(":");
-                if (colonIdx === -1)
-                    return null;
-                const type = line.slice(0, colonIdx).trim();
-                if (type !== 'lex' && type !== 'vec' && type !== 'hyde')
-                    return null;
-                const text = line.slice(colonIdx + 1).trim();
-                if (!hasQueryTerm(text))
-                    return null;
-                return { type: type, text };
-            }).filter((q) => q !== null);
+            const queryables = parseExpansionLines(query, result);
             // Filter out lex entries if not requested
             const filtered = includeLexical ? queryables : queryables.filter(q => q.type !== 'lex');
             if (filtered.length > 0)

package/dist/mcp/server.js

@@ -19,6 +19,7 @@ import { createStore, extractSnippet, addLineNumbers, getDefaultDbPath, DEFAULT_
 import { getConfigPath } from "../collections.js";
 import { enableProductionMode } from "../store.js";
 import { checkRequestOrigin, resolveOriginGuard } from "./origin-guard.js";
+import { entryFromRest, logQuery, queryLogStatus } from "../query-log.js";
 // =============================================================================
 // Helper functions
 // =============================================================================
@@ -457,9 +458,12 @@ Intent-aware lex (C++ performance, not sports):
         for (const col of status.collections) {
             summary.push(`    - ${col.name}: ${col.path} (${col.documents} docs)`);
         }
+        // ko-qmd: daemon query log state (only this process knows its env and write errors).
+        const queryLog = queryLogStatus();
+        summary.push(`  Query log (REST /query only): ${queryLog.enabled ? queryLog.path : "off"} (last write: ${queryLog.lastWrite ?? "none"}${queryLog.lastError ? `, last error: ${queryLog.lastError}` : ""})`);
         return {
             content: [{ type: "text", text: summary.join('\n') }],
-            structuredContent: status,
+            structuredContent: { ...status, queryLog },
         };
     }));
     return server;
@@ -803,6 +807,8 @@ export async function startMcpHttpServer(port, options = {}) {
                 });
                 nodeRes.writeHead(200, { "Content-Type": "application/json" });
                 nodeRes.end(JSON.stringify({ results: formatted }));
+                // ko-qmd: opt-in query log (QMD_QUERY_LOG), written after the response.
+                logQuery(entryFromRest({ path: pathname, headers: nodeReq.headers, searches: queries, params, collections: effectiveCollections, results: formatted, ms: Date.now() - reqStart }), store);
                 log(`${ts()} POST /query ${params.searches.length} queries (${Date.now() - reqStart}ms)`);
                 return;
             }

package/dist/query-log.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Daemon query log — an opt-in JSONL record of searches served by the HTTP
+ * daemon's REST `/query`·`/search` endpoints, so a user dogfooding a build can
+ * mine their real queries for misses. MCP tool calls are not logged yet.
+ *
+ * - Off unless `QMD_QUERY_LOG` is `1`, `true` or `yes` (case-insensitive).
+ *   CLI searches never call this module.
+ * - One file per local month: `$XDG_CACHE_HOME/qmd/queries-YYYY-MM.jsonl`
+ *   (default `~/.cache/qmd`), created 0600. Nothing is ever deleted.
+ * - Rows hold queries, result paths and scores — never snippets or bodies.
+ * - Fail-open: callers do not await and nothing here throws; a failure never
+ *   reaches the search response. The first failure per process prints one
+ *   stderr line; `queryLogStatus()` keeps the latest failure until the next
+ *   successful write.
+ * - Clients annotate rows with `X-QMD-Tag` / `X-QMD-Qid` / `X-QMD-Role`, and
+ *   skip logging with `X-QMD-No-Log: 1`. Header values are untrusted.
+ *
+ * Env and paths are read at call time so tests can redirect XDG_CACHE_HOME.
+ */
+import type { IncomingHttpHeaders } from "node:http";
+import type { IndexStatus } from "./store.js";
+export declare const QUERY_LOG_SCHEMA_VERSION = 1;
+type HeaderSource = Headers | IncomingHttpHeaders;
+type StatusSource = {
+    getStatus(): Promise<IndexStatus>;
+};
+export type QueryLogEntry = {
+    via: "rest" | "mcp";
+    tool: string;
+    headers: HeaderSource;
+    searches: {
+        type: string;
+        query: string;
+    }[];
+    collections: string[] | null;
+    limit: number;
+    /** null = the request left reranking to the daemon default */
+    rerank: boolean | null;
+    results: {
+        file: string;
+        score: number;
+    }[];
+    ms: number;
+    /** Injectable clock for tests; defaults to the time of the call. */
+    now?: Date;
+};
+export type QueryLogStatus = {
+    enabled: boolean;
+    path: string;
+    lastWrite: string | null;
+    lastError: string | null;
+};
+/** Path of the log file for the local month containing `date`. */
+export declare const queryLogPath: (date?: Date) => string;
+/**
+ * Queue one row. Returns immediately; the write happens after the response.
+ * No-op unless the flag is on and the request did not ask to be skipped.
+ * Never throws — the REST handler calls this after the response has ended.
+ */
+export declare const logQuery: (entry: QueryLogEntry, store: StatusSource) => void;
+/** Resolves once every queued row has been written or has failed. */
+export declare const flushQueryLog: () => Promise<void>;
+/** In-process view (the daemon's own `status` tool). */
+export declare const queryLogStatus: () => QueryLogStatus;
+export type QueryLogFileState = {
+    kind: "none";
+} | {
+    kind: "file";
+    path: string;
+    modified: Date;
+} | {
+    kind: "error";
+    message: string;
+};
+/**
+ * Newest log file on disk, for `qmd status` — which runs in a different
+ * process than the daemon and so cannot see the daemon's env or state.
+ * A missing cache dir is "none"; any other failure yields kind "error" with
+ * the error code only (status output carries no filesystem paths).
+ */
+export declare const latestQueryLogFile: () => QueryLogFileState;
+/** Map a REST `/query` request the same way the handler does. */
+export declare const entryFromRest: (input: {
+    path: string;
+    headers: IncomingHttpHeaders;
+    /** The handler's already-mapped searches. */
+    searches: {
+        type: string;
+        query: string;
+    }[];
+    /** Raw JSON body fields the handler reads with typeof checks. */
+    params: {
+        limit?: unknown;
+        rerank?: unknown;
+    };
+    /** The collections actually searched (the handler's defaults applied). */
+    collections: string[];
+    results: {
+        file: string;
+        score: number;
+    }[];
+    ms: number;
+}) => QueryLogEntry;
+export declare const _resetQueryLogForTesting: () => void;
+export {};

package/dist/query-log.js

@@ -0,0 +1,223 @@
+/**
+ * Daemon query log — an opt-in JSONL record of searches served by the HTTP
+ * daemon's REST `/query`·`/search` endpoints, so a user dogfooding a build can
+ * mine their real queries for misses. MCP tool calls are not logged yet.
+ *
+ * - Off unless `QMD_QUERY_LOG` is `1`, `true` or `yes` (case-insensitive).
+ *   CLI searches never call this module.
+ * - One file per local month: `$XDG_CACHE_HOME/qmd/queries-YYYY-MM.jsonl`
+ *   (default `~/.cache/qmd`), created 0600. Nothing is ever deleted.
+ * - Rows hold queries, result paths and scores — never snippets or bodies.
+ * - Fail-open: callers do not await and nothing here throws; a failure never
+ *   reaches the search response. The first failure per process prints one
+ *   stderr line; `queryLogStatus()` keeps the latest failure until the next
+ *   successful write.
+ * - Clients annotate rows with `X-QMD-Tag` / `X-QMD-Qid` / `X-QMD-Role`, and
+ *   skip logging with `X-QMD-No-Log: 1`. Header values are untrusted.
+ *
+ * Env and paths are read at call time so tests can redirect XDG_CACHE_HOME.
+ */
+import { appendFile, mkdir } from "node:fs/promises";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { qmdHomedir } from "./paths.js";
+import { resolveCommit } from "./cli/version.js";
+export const QUERY_LOG_SCHEMA_VERSION = 1;
+const ROLES = ["primary", "probe", "canary", "replay"];
+const TAG_MAX = 32;
+const QID_MAX = 64;
+const FINGERPRINT_TTL_MS = 60_000;
+const isTruthyFlag = (value) => value !== undefined && ["1", "true", "yes"].includes(value.trim().toLowerCase());
+const isQueryLogEnabled = () => isTruthyFlag(process.env.QMD_QUERY_LOG);
+const queryLogDir = () => join(process.env.XDG_CACHE_HOME || join(qmdHomedir(), ".cache"), "qmd");
+const pad2 = (n) => String(n).padStart(2, "0");
+/** Path of the log file for the local month containing `date`. */
+export const queryLogPath = (date = new Date()) => join(queryLogDir(), `queries-${date.getFullYear()}-${pad2(date.getMonth() + 1)}.jsonl`);
+/** ISO-8601 in local time with the UTC offset, e.g. 2026-09-17T16:05:03.123+09:00. */
+const isoWithOffset = (date) => {
+    const offsetMin = -date.getTimezoneOffset();
+    const sign = offsetMin >= 0 ? "+" : "-";
+    const abs = Math.abs(offsetMin);
+    const ms = String(date.getMilliseconds()).padStart(3, "0");
+    return `${date.getFullYear()}-${pad2(date.getMonth() + 1)}-${pad2(date.getDate())}`
+        + `T${pad2(date.getHours())}:${pad2(date.getMinutes())}:${pad2(date.getSeconds())}.${ms}`
+        + `${sign}${pad2(Math.floor(abs / 60))}:${pad2(abs % 60)}`;
+};
+const readHeader = (headers, name) => {
+    if (headers instanceof Headers)
+        return headers.get(name);
+    const raw = headers[name.toLowerCase()];
+    const value = Array.isArray(raw) ? raw[0] : raw;
+    return value ?? null;
+};
+const clip = (value, max) => value === null || value === "" ? null : value.slice(0, max);
+const parseRole = (value) => ROLES.find((role) => role === value) ?? null;
+/** REST emits `qmd://<collection>/<percent-encoded path>`; MCP emits the plain display path. */
+const normalizeResultFile = (file) => {
+    const bare = file.startsWith("qmd://") ? file.slice("qmd://".length) : file;
+    return bare.split("/").map((segment) => {
+        try {
+            return decodeURIComponent(segment);
+        }
+        catch {
+            return segment;
+        }
+    }).join("/");
+};
+let packageVersion;
+const qmdVersion = () => {
+    if (packageVersion !== undefined)
+        return packageVersion;
+    // This file sits one level below the package root both as src/ and dist/.
+    const here = dirname(fileURLToPath(import.meta.url));
+    const root = join(here, "..");
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf-8"));
+        // The commit tells a dogfood build apart from the published package of the same version.
+        const commit = resolveCommit(join(here, "cli"), root);
+        packageVersion = commit ? `${pkg.version ?? "unknown"} (${commit})` : (pkg.version ?? "unknown");
+    }
+    catch {
+        packageVersion = "unknown";
+    }
+    return packageVersion;
+};
+let fingerprintCache = null;
+const indexFingerprint = async (store) => {
+    const now = Date.now();
+    if (fingerprintCache && fingerprintCache.store === store && now - fingerprintCache.at < FINGERPRINT_TTL_MS) {
+        return fingerprintCache.value;
+    }
+    let value;
+    try {
+        const status = await store.getStatus();
+        const updated = status.collections
+            .map((c) => c.lastUpdated)
+            .filter(Boolean)
+            .sort()
+            .at(-1) ?? null;
+        value = { docs: status.totalDocuments, updated };
+    }
+    catch {
+        // A missing fingerprint must not cost the query row.
+        value = { docs: null, updated: null };
+    }
+    fingerprintCache = { store, at: now, value };
+    return value;
+};
+let writeChain = Promise.resolve();
+let lastWrite = null;
+let lastError = null;
+let reportedFailure = false;
+const recordFailure = (path, message) => {
+    lastError = message;
+    if (reportedFailure)
+        return;
+    reportedFailure = true;
+    console.error(`qmd: query log write failed (${path}): ${message} — searches are unaffected`);
+};
+/**
+ * Queue one row. Returns immediately; the write happens after the response.
+ * No-op unless the flag is on and the request did not ask to be skipped.
+ * Never throws — the REST handler calls this after the response has ended.
+ */
+export const logQuery = (entry, store) => {
+    try {
+        queueRow(entry, store);
+    }
+    catch (err) {
+        recordFailure(queryLogPath(), err instanceof Error ? err.message : String(err));
+    }
+};
+const queueRow = (entry, store) => {
+    if (!isQueryLogEnabled())
+        return;
+    if (isTruthyFlag(readHeader(entry.headers, "x-qmd-no-log") ?? undefined))
+        return;
+    const now = entry.now ?? new Date();
+    const path = queryLogPath(now);
+    const partial = {
+        v: QUERY_LOG_SCHEMA_VERSION,
+        ts: isoWithOffset(now),
+        qmd: qmdVersion(),
+        via: entry.via,
+        tool: entry.tool,
+        searches: entry.searches.map(({ type, query }) => ({ type, query })),
+        collections: entry.collections,
+        limit: entry.limit,
+        rerank: entry.rerank,
+        results: entry.results.map((r, i) => ({ file: normalizeResultFile(r.file), score: r.score, rank: i + 1 })),
+        ms: entry.ms,
+        client: {
+            tag: clip(readHeader(entry.headers, "x-qmd-tag"), TAG_MAX),
+            qid: clip(readHeader(entry.headers, "x-qmd-qid"), QID_MAX),
+            role: parseRole(readHeader(entry.headers, "x-qmd-role")),
+        },
+    };
+    writeChain = writeChain.then(async () => {
+        try {
+            const line = JSON.stringify({ ...partial, index: await indexFingerprint(store) }) + "\n";
+            await mkdir(dirname(path), { recursive: true });
+            await appendFile(path, line, { mode: 0o600 });
+            lastWrite = new Date().toISOString();
+            lastError = null;
+        }
+        catch (err) {
+            recordFailure(path, err instanceof Error ? err.message : String(err));
+        }
+    });
+};
+/** Resolves once every queued row has been written or has failed. */
+export const flushQueryLog = () => writeChain;
+/** In-process view (the daemon's own `status` tool). */
+export const queryLogStatus = () => ({
+    enabled: isQueryLogEnabled(),
+    path: queryLogPath(),
+    lastWrite,
+    lastError,
+});
+const errorCode = (err) => err.code ?? err.message;
+/**
+ * Newest log file on disk, for `qmd status` — which runs in a different
+ * process than the daemon and so cannot see the daemon's env or state.
+ * A missing cache dir is "none"; any other failure yields kind "error" with
+ * the error code only (status output carries no filesystem paths).
+ */
+export const latestQueryLogFile = () => {
+    const dir = queryLogDir();
+    try {
+        const newest = readdirSync(dir)
+            .filter((n) => /^queries-\d{4}-\d{2}\.jsonl$/.test(n))
+            .sort()
+            .at(-1);
+        if (!newest)
+            return { kind: "none" };
+        const path = join(dir, newest);
+        return { kind: "file", path, modified: statSync(path).mtime };
+    }
+    catch (err) {
+        const code = errorCode(err); // fs errors are ErrnoException
+        return code === "ENOENT" ? { kind: "none" } : { kind: "error", message: code };
+    }
+};
+/** Map a REST `/query` request the same way the handler does. */
+export const entryFromRest = (input) => ({
+    via: "rest",
+    tool: input.path,
+    headers: input.headers,
+    searches: input.searches,
+    collections: input.collections.length > 0 ? input.collections : null,
+    // Same default as the REST handler in src/mcp/server.ts.
+    limit: typeof input.params.limit === "number" ? input.params.limit : 10,
+    rerank: typeof input.params.rerank === "boolean" ? input.params.rerank : null,
+    results: input.results,
+    ms: input.ms,
+});
+export const _resetQueryLogForTesting = () => {
+    writeChain = Promise.resolve();
+    lastWrite = null;
+    lastError = null;
+    reportedFailure = false;
+    fingerprintCache = null;
+};

package/dist/store.d.ts

@@ -1022,6 +1022,28 @@ export type RankedListMeta = {
  * original vector boost.
  */
 export declare function getHybridRrfWeights(rankedListMeta: RankedListMeta[]): number[];
+/**
+ * Blend a reranker score with a linear retrieval-position tiebreak.
+ *
+ * The position term used to be 1/rrfRank under rank-gated weights (0.75/0.60/0.40).
+ * That score drops 50% between rank 1 and rank 2 — a gap of 0.375 at weight 0.75,
+ * larger than the 0.25 the whole reranker term could ever contribute — so no
+ * reranker score could displace the top retrieval hit, and the reranker was inert
+ * exactly where it decided the answer. A linear decay over the candidate window
+ * separates adjacent ranks by a constant the reranker can overcome.
+ *
+ * Measured 2026-09-18 on one fixed candidate dump per goldset, so every formula was
+ * scored against identical retrieval (scripts/bench-dump-candidates.ts feeding
+ * scripts/bench-blend-sweep.mjs):
+ *
+ *                 alias (n=223)         paraphrase (n=30)
+ *   1/rrfRank     r@1 .713  mrr .808    r@1 .467  mrr .664
+ *   this          r@1 .874  mrr .927    r@1 .867  mrr .903
+ *
+ * On both goldsets the old blend's r@1 equalled retrieval-only r@1 to three
+ * decimals, which is what "the reranker cannot move rank 1" looks like as a number.
+ */
+export declare function blendRerankScore(rrfRank: number, rerankScore: number, candidateLimit: number): number;
 /**
  * Hybrid search: BM25 + vector + query expansion + RRF + chunked reranking.
  *

package/dist/store.js

@@ -3185,6 +3185,22 @@ function mergeSearchResultsByScore(lists, limit) {
         .sort((a, b) => b.score - a.score)
         .slice(0, limit);
 }
+/**
+ * Fewest documents a retrieval pass looks at, whatever `limit` the caller asked for.
+ *
+ * Both searches over-fetch by a multiple of `limit` — FTS by 10x when the collection
+ * filter runs after the match, vectors by 3x or 30x because several chunks of one
+ * document collapse into one result. Those multiples are of a number the caller picked
+ * for display, so a small `limit` leaves a pool that post-filtering can exhaust, and
+ * `-n 5` was not the first five of `-n 20`. The CLI makes that visible: its default
+ * limit is 20 for `--json`/`--files` and 5 otherwise (src/cli/qmd.ts), so the output
+ * format changed which documents came back. README documents `limit` as "Max results"
+ * and `candidateLimit` as the candidate knob; the floor is what makes that true.
+ *
+ * 20 is the breadth hybridQuery already passes explicitly on every one of its own
+ * retrieval calls.
+ */
+const MIN_RETRIEVAL_BREADTH = 20;
 export function searchFTS(db, query, limit = 20, collectionName) {
     const names = scopedCollectionNames(collectionName);
     // Search each requested collection before merging/truncating so a large
@@ -3206,7 +3222,8 @@ export function searchFTS(db, query, limit = 20, collectionName) {
         // When filtering by collection, fetch extra candidates from the FTS index
         // since some will be filtered out. Without a collection filter we can
         // fetch exactly the requested limit.
-        const ftsLimit = collectionFilter ? limit * 10 : limit;
+        const breadth = Math.max(limit, MIN_RETRIEVAL_BREADTH);
+        const ftsLimit = collectionFilter ? breadth * 10 : breadth;
         let sql = `
       WITH fts_matches AS (
         SELECT rowid, bm25(documents_fts, 1.5, 4.0, 1.0) as bm25_score
@@ -3326,6 +3343,7 @@ export async function searchVec(db, query, model, limit = 20, collectionName, se
         return mergeSearchResultsByScore(lists, limit);
     }
     const collectionFilter = names?.[0];
+    const breadth = Math.max(limit, MIN_RETRIEVAL_BREADTH);
     // IMPORTANT: We use a two-step query approach here because sqlite-vec virtual tables
     // hang indefinitely when combined with JOINs in the same query. Do NOT try to
     // "optimize" this by combining into a single query with JOINs - it will break.
@@ -3349,15 +3367,15 @@ export async function searchVec(db, query, model, limit = 20, collectionName, se
         if (collectionHashSeqs.length === 0)
             return [];
         if (collectionHashSeqs.length <= COLLECTION_VEC_EXACT_SCAN_MAX) {
-            vecResults = exactVecScanByHashSeq(db, embedding, collectionHashSeqs, limit);
+            vecResults = exactVecScanByHashSeq(db, embedding, collectionHashSeqs, breadth);
         }
         else {
             // Large collection: ANN with over-fetch, hard-capped at sqlite-vec's max k.
-            vecResults = annVecScan(db, embedding, Math.max(limit * 30, limit * 3));
+            vecResults = annVecScan(db, embedding, breadth * 30);
         }
     }
     else {
-        vecResults = annVecScan(db, embedding, limit * 3);
+        vecResults = annVecScan(db, embedding, breadth * 3);
     }
     if (vecResults.length === 0)
         return [];
@@ -4347,6 +4365,36 @@ export function getHybridRrfWeights(rankedListMeta) {
         return meta.relaxed ? weight * RELAXED_LIST_WEIGHT : weight;
     });
 }
+/**
+ * How much of the blended score the retrieval position is worth. The reranker
+ * decides; position only separates documents it scores alike.
+ */
+const POSITION_TIEBREAK_WEIGHT = 0.1;
+/**
+ * Blend a reranker score with a linear retrieval-position tiebreak.
+ *
+ * The position term used to be 1/rrfRank under rank-gated weights (0.75/0.60/0.40).
+ * That score drops 50% between rank 1 and rank 2 — a gap of 0.375 at weight 0.75,
+ * larger than the 0.25 the whole reranker term could ever contribute — so no
+ * reranker score could displace the top retrieval hit, and the reranker was inert
+ * exactly where it decided the answer. A linear decay over the candidate window
+ * separates adjacent ranks by a constant the reranker can overcome.
+ *
+ * Measured 2026-09-18 on one fixed candidate dump per goldset, so every formula was
+ * scored against identical retrieval (scripts/bench-dump-candidates.ts feeding
+ * scripts/bench-blend-sweep.mjs):
+ *
+ *                 alias (n=223)         paraphrase (n=30)
+ *   1/rrfRank     r@1 .713  mrr .808    r@1 .467  mrr .664
+ *   this          r@1 .874  mrr .927    r@1 .867  mrr .903
+ *
+ * On both goldsets the old blend's r@1 equalled retrieval-only r@1 to three
+ * decimals, which is what "the reranker cannot move rank 1" looks like as a number.
+ */
+export function blendRerankScore(rrfRank, rerankScore, candidateLimit) {
+    const positionScore = 1 - (rrfRank - 1) / candidateLimit;
+    return (1 - POSITION_TIEBREAK_WEIGHT) * rerankScore + POSITION_TIEBREAK_WEIGHT * positionScore;
+}
 /**
  * Hybrid search: BM25 + vector + query expansion + RRF + chunked reranking.
  *
@@ -4586,15 +4634,8 @@ export async function hybridQuery(store, query, options) {
     const rrfRankMap = new Map(candidates.map((c, i) => [c.file, i + 1]));
     const blended = reranked.map(r => {
         const rrfRank = rrfRankMap.get(r.file) || candidateLimit;
-        let rrfWeight;
-        if (rrfRank <= 3)
-            rrfWeight = 0.75;
-        else if (rrfRank <= 10)
-            rrfWeight = 0.60;
-        else
-            rrfWeight = 0.40;
-        const rrfScore = 1 / rrfRank;
-        const blendedScore = rrfWeight * rrfScore + (1 - rrfWeight) * r.score;
+        const rrfScore = 1 - (rrfRank - 1) / candidateLimit;
+        const blendedScore = blendRerankScore(rrfRank, r.score, candidateLimit);
         const candidate = candidateMap.get(r.file);
         const chunkInfo = docChunkMap.get(r.file);
         const bestIdx = chunkInfo?.bestIdx ?? 0;
@@ -4607,7 +4648,7 @@ export async function hybridQuery(store, query, options) {
             rrf: {
                 rank: rrfRank,
                 positionScore: rrfScore,
-                weight: rrfWeight,
+                weight: POSITION_TIEBREAK_WEIGHT,
                 baseScore: trace?.baseScore ?? 0,
                 topRankBonus: trace?.topRankBonus ?? 0,
                 totalScore: trace?.totalScore ?? 0,
@@ -4908,15 +4949,8 @@ export async function structuredSearch(store, searches, options) {
     const rrfRankMap = new Map(candidates.map((c, i) => [c.file, i + 1]));
     const blended = reranked.map(r => {
         const rrfRank = rrfRankMap.get(r.file) || candidateLimit;
-        let rrfWeight;
-        if (rrfRank <= 3)
-            rrfWeight = 0.75;
-        else if (rrfRank <= 10)
-            rrfWeight = 0.60;
-        else
-            rrfWeight = 0.40;
-        const rrfScore = 1 / rrfRank;
-        const blendedScore = rrfWeight * rrfScore + (1 - rrfWeight) * r.score;
+        const rrfScore = 1 - (rrfRank - 1) / candidateLimit;
+        const blendedScore = blendRerankScore(rrfRank, r.score, candidateLimit);
         const candidate = candidateMap.get(r.file);
         const chunkInfo = docChunkMap.get(r.file);
         const bestIdx = chunkInfo?.bestIdx ?? 0;
@@ -4929,7 +4963,7 @@ export async function structuredSearch(store, searches, options) {
             rrf: {
                 rank: rrfRank,
                 positionScore: rrfScore,
-                weight: rrfWeight,
+                weight: POSITION_TIEBREAK_WEIGHT,
                 baseScore: trace?.baseScore ?? 0,
                 topRankBonus: trace?.topRankBonus ?? 0,
                 totalScore: trace?.totalScore ?? 0,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ko-qmd",
-  "version": "2.8.3-ko.2",
+  "version": "2.8.3-ko.3",
   "description": "Query Markup Documents - On-device hybrid search for markdown files with BM25, vector search, and LLM reranking",
   "type": "module",
   "main": "dist/index.js",