ko-qmd 2.8.3-ko.5 → 2.8.3-ko.7

package/CHANGELOG.md

@@ -2,6 +2,159 @@
 
 ## [Unreleased]
 
+## [2.8.3-ko.7] - 2026-10-02
+
+The query path is now observable and bounded. Every query-log row breaks its latency into
+stages, the daemon logs its heap once an hour, and expansion and rerank stop waiting past a
+deadline instead of holding a query for 85 s. The reranker also sees a note's first chunk by default.
+
+- `qmd mcp` (stdio and HTTP) no longer waits on a slow LLM stage without bound. Past
+  `QMD_EXPAND_DEADLINE_MS` (default 5 s) a query searches its original text alone, and past
+  `QMD_RERANK_DEADLINE_MS` (default 10 s) it answers in RRF order; `0` restores waiting. The clock
+  starts once the model is loaded, so a cold start or a reload after the idle unload is not a timeout;
+  the query log records that wait as a `load` stage. One MCP `query` with expansion and rerank took
+  85 s. The REST `/query` response and the MCP `query` tool say which stage timed out (`timeouts`),
+  the query log row lists it the same way, and a timed-out rerank reads `rerank: "timeout"` there.
+  A fallback does not apply `minScore` to its 1/rank scores. An abandoned expansion or rerank keeps
+  running and fills its cache; until it finishes, later queries skip that stage (logged once) instead
+  of queueing behind it. The CLI search commands and the SDK (`rerankDeadlineMs`, `expandDeadlineMs`
+  options) never set a deadline on their own.
+
+- The daemon's query log row now carries `stages`, the milliseconds spent in each stage of the
+  search: `refresh` (the pre-query re-index check), `expand`, `fts`, `embed`, `vec`, `chunk`,
+  `rerank` and `serialize`; a stage that did not run is absent. REST `rerank:false` queries had a p95 of 2.9–5.3 s
+  against a p50 of 0.2–0.5 s with no rerank in the path, and the single `ms` could not say which
+  stage the tail came from. Daemon log lines now start with a dated local ISO timestamp instead of
+  a UTC `HH:mm:ss.SSS`, so a slow line can be matched to its row.
+
+- The HTTP daemon logs a `health` line every hour: heap used and total, rss, and how many
+  `subscriptions/listen` and other `/mcp` requests have a handler still waiting on its response. A daemon that ran ten days died with
+  "Reached heap limit" after its heap crept to 3.8 GB under idle discover/cancelled traffic, and
+  nothing in the log showed the slope or what was holding memory. `QMD_HEALTH_LOG_INTERVAL_MS`
+  changes the interval; `0` turns it off.
+
+- `scripts/autoresearch/prepare.sh` builds the goldset from more than the collection folder and over
+  several runs. `AR_EXTRA_DIRS="outputs docs"` copies sibling folders of the collection into the corpus
+  (names only, so no vault path lands in git), `AR_RUN=N` writes `generated-N.json` from documents no
+  earlier run answered (`bench-vault-paraphrase.ts --dirs`, `--skip`), and `split` merges every run,
+  drops the query ids listed in `dropped.txt`, and splits only each run's new documents, so an earlier
+  train/held-out assignment never moves.
+
+- The reranker now gets a note's first chunk, its title and summary: the first chunk starts 16
+  points ahead in chunk selection (8 when an intent is given, so intent words can still pick a later
+  chunk). A later chunk needs 17 more points, about nine English words or seventeen Hangul syllable
+  pairs, so for a typical short query the first chunk is always sent. A second autoresearch loop found
+  this on a goldset of 320 train and 71 held-out queries drawn from four vault folders. Held-out full
+  MRR goes 0.7291 → 0.7459, ko-vault seam and hard lines are unchanged, and bm25, vector and hybrid
+  results are identical (`BASELINE.md` 2026-09-29).
+
+## [2.8.3-ko.6] - 2026-09-29
+
+Korean queries are handled better before and during reranking. A query written
+as "X 말고 Y" now searches for Y alone, and a Hangul query skips LLM expansion,
+which steadies hard-query results and cuts hybrid latency from about 1s to tens
+of ms per query. The reranker is now shown the chunk that best matches the
+query's Hangul syllable bigrams, led by the note title: held-out full MRR goes
+0.6589 → 0.7260 on a goldset generated from a real vault. Scoped vector search on
+small indexes runs one KNN (vector stage 250–1300ms → about 25ms). The README
+gains an English edition and an FAQ.
+
+- `QMD_RERANK_CACHE=<path>` keeps rerank scores in their own sqlite file instead of the index's
+  `llm_cache`, so a store over a rebuilt index reuses them. The key carries the query, the rerank
+  model, the doc-token cap and the chunk text, not the scoring code in `src/llm.ts`, so the file is
+  safe across index rebuilds with the same reranker code. It is not trimmed to 1000 rows. With it
+  set, a second `scripts/bench-ko.sh` run on ko-vault gives the same lines and its `full` backend
+  spends 3.7 s reranking instead of 300 s (the whole run drops from 5:17 to 0:56). Unset, nothing
+  changes. A fallback result (no rerank context could be created, every score 0.5) is no longer
+  cached in either place.
+
+- The reranker now sees a better chunk of a long Korean note. The chunk is chosen by the
+  two-syllable pairs of the query's Hangul words of three or more syllables, instead of whole
+  words, so `임베딩은` still finds a chunk about `임베딩`. Generic two-syllable words such as 방법
+  and 경우 no longer steer the choice. A query word with no Hangul (an English term, say) counts double. When the chosen chunk
+  does not contain the note title, `# <title>` is put in front of it. An autonomous loop
+  (`scripts/autoresearch/`) found this over 28 experiments on a goldset generated from a private
+  vault. The goldset's held-out split, which the loop never saw, goes from full MRR 0.6589 to
+  0.7260 (32 queries). ko-vault seam and hard lines are unchanged. The bm25, vector and hybrid
+  results do not read the rerank input and are identical on both sets (`BASELINE.md`
+  2026-09-28). An intent word now counts 1 point in chunk selection (was 0.5), keeping it at half a
+  query word now that a non-Hangul query word counts 2; no goldset carries intent, so no bench
+  number moves.
+
+- The reranker's input (the query string, which chunk of each candidate is sent and the document
+  text) is now built in `src/rerank-input.ts` for both `hybridQuery` and `structuredSearch`, which
+  had copied the chunk-scoring loop. Results are unchanged.
+
+- A Korean query of the form "X 말고 Y" now searches for Y alone. `hybridQuery` (CLI `qmd query`,
+  plain MCP `query`) and the `lex`/`vec` lines of `structuredSearch` (MCP `searches`, typed lines)
+  drop everything up to the last whitespace-separated 말고, 빼고, 제외하고 or 제외한. The rerank
+  query follows. `hyde` lines, `intent` and `qmd search`/`vsearch` stay as written. Before this
+  change every list also searched for X, the concept the user ruled out, so a note about X often
+  took rank 1. `아닌` and bare `제외` are not markers, because they also state conditions or act as
+  nouns. On the ko-vault seam form, the `neg` queries' full MRR goes 0.4500 → 0.6944. Hard
+  `full_r1` goes 0.5111 → 0.6111 and hard `full_mrr` 0.7472 → 0.8287. No query outside `neg`
+  changed its results, and that run is the gate's new reference (`BASELINE.md` 2026-09-27,
+  "a Korean negation clause is stripped before search").
+
+- `structuredSearch` (MCP `searches`, SDK `search({ queries })`, typed `lex:`/`vec:` lines) now
+  counts a relaxed lex list, one that matched only through the any-word retry, at half its slot's
+  weight, as `hybridQuery` already did. At a flat 2.0 for the first list, a lex line that matched
+  some of a Korean question's words outranked the vector list, and a decoy sharing those words took
+  rank 1. This one weight was the whole gap between the two paths on the Korean ko-vault queries:
+  re-fusing each path's lists with the other's weights reproduced its top 10 for 85 of 85 queries.
+  On the seam form, hard `hybrid_r1` goes 0.3111 → 0.3778 and `hybrid_r5` 0.8996 → 0.9211, with
+  `full_r1` unchanged at 0.5111, and that run is the gate's new reference (`BASELINE.md` 2026-09-27).
+
+- A query with any Hangul is no longer expanded by the LLM on the hybrid path (`hybridQuery`). That
+  path serves CLI `qmd query`, including an explicit `expand:` line, as well as a plain MCP `query`
+  and SDK `search({ query })`; `qmd vsearch` still expands. On the ko-vault goldset the
+  expansion model wrapped Korean questions in English sentence templates and stray Chinese, and its
+  sampling alone moved hard rank 1 by up to five of 30 queries between runs. Without it, hard
+  `hybrid_r1` reads 0.3778 (0.2611–0.3611 with expansion), `full_r1` holds at 0.5111, the easy
+  queries lose nothing, and the median hybrid query drops from about 1 s to 20 ms. The Korean
+  queries now return the same results on every run. English-only queries are still expanded, and a
+  caller who wants variants for a Korean question can pass its own `searches`
+  (`BASELINE.md` 2026-09-26).
+
+- `scripts/bench-ko.sh` benches the seam form by default. Every one-line goldset query reaches
+  `qmd bench` as `lex: <q>` + `vec: <q>`, the shape REST/MCP callers send, which skips LLM query
+  expansion. `KO_FORM=plain` keeps the old path, and the `RESULT-HARD` line now ends with
+  `form=<seam|plain>`. The `dogfood.sh` gate refuses a bench whose form differs from its baseline
+  line's form. On the seam form it gates hard `hybrid_r1` as well as `full_r1`, against a reference
+  line with `tol=0`, since the seam form gave the same lines in every run. The reason is the plain
+  form's hard wobble, which turned out to be the expansion sampler alone. Replaying recorded
+  expansions reproduces every query's top 10, and every query that moved between same-commit runs
+  had drawn a different expansion. The draw moved `hybrid_r1` by up to five of 30 queries and once
+  put `full_r1` 0.0007 above the old gate's floor (`BASELINE.md` 2026-09-26). The gate also runs
+  the bench with any exported `KO_BENCH`/`KO_CORPUS`/`KO_FORM` removed, and `bench-ko.sh` refuses a
+  `KO_BENCH` inside `tmp/bench-ko/`, where the run clears its outputs.
+
+- `scripts/bench-ko.sh` takes `KO_CORPUS` (a corpus directory holding `wiki/` and
+  `distractors/`) and `KO_BENCH` (a goldset) so an A/B runs through the same isolated harness
+  and stdout lines. Overrides resolve against the caller's cwd and are checked before the
+  previous run's output is removed. The first use settled a question: three everyday-language
+  question lines per document, decoys included, did not move hard rank 1 on the REST-shaped
+  goldset (hybrid_r1 0.3111 → 0.2778, full_r1 flat at 0.5111; hard hit@5 up 2 of 30). Index-time
+  summaries are therefore not being built. The same runs point the `hybrid_r1` wobble at LLM
+  query expansion rather than re-embedding (`BASELINE.md` 2026-09-25).
+- ko-vault goldset: 69 near-topic distractor documents and 30 hard queries (`sem-hard` /
+  `multi` / `neg`) join the fixture; `bench-ko.sh` indexes both directories (97 files) and
+  prints a `RESULT-HARD hybrid_r1=… full_r1=… n=30` line next to `RESULT`. The `dogfood.sh`
+  gate now also fails when the hard `full_r1` falls below the baseline minus the `tol=` recorded
+  on that baseline line, and fails closed when `RESULT-HARD` or its `tol=` goes missing.
+  `full_r1` is gated rather than `hybrid_r1` because it held one value across eight same-commit
+  runs, while `hybrid_r1` moved by about 3.5 queries of 30.
+  Fixture invariants (no title-term leakage, no excluded concept among expected files, no basename
+  collisions) are enforced by `test/ko-bench-fixture.test.ts`.
+
+- Collection- or filter-scoped vector search is faster on indexes of up to
+  4096 vectors. It now post-filters one sqlite-vec KNN over the whole table,
+  which is exact because vec0 KNN is a brute-force scan, instead of computing
+  `vec_distance_cosine` row by row. On the KB goldset (1047 of 3389 vectors,
+  M3 Max) the vector stage dropped from 250–1300ms to about 25ms, and a cold
+  capped query (cap 128, candidateLimit 15) went from p90 2000ms to 906ms with
+  identical rankings. Larger indexes keep the exact scan.
+
 ## [2.8.3-ko.5] - 2026-09-24
 
 Rerank gets an input cap. Truncating each document to 128 tokens keeps KB
@@ -88,7 +241,7 @@ it to `scope`.
 - Plain Hangul lex terms that spell a common technical loanword (`서치`, `웹`,
   `코어`, `마이그레이션`, about 80 entries in a built-in table) also match the
   Latin spelling, so `하이브리드 서치` finds a note that only says
-  `hybrid-search` and `레몬 웹 코어` reaches `lemon-web-core`. The lookup runs
+  `hybrid-search` and `리액트 웹 코어` reaches `react-web-core`. The lookup runs
   on particle-stripped stems too (`서치를`), single-syllable entries (`웹`, `훅`)
   are bridged when they stand alone (not `웹을`), and terms with no entry produce the same FTS5 query as before.
   Query-side only; no re-index. On the ko-vault bench the eleven new loanword

package/README.en.md

@@ -0,0 +1,184 @@
+# ko-qmd — local hybrid search for Korean Markdown notes
+
+[![npm](https://img.shields.io/npm/v/ko-qmd?label=npm%20ko-qmd)](https://www.npmjs.com/package/ko-qmd)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+[한국어](README.md) · **English**
+
+**ko-qmd is an on-device search engine for Korean Markdown notes — Obsidian vaults, wikis, meeting
+notes and docs folders — that finds them by keyword or by natural-language question.**
+It combines BM25 full-text search, vector search and LLM reranking, and matches Korean query words
+by their stem even when a particle or verb ending is attached. Every model runs locally through
+[node-llama-cpp](https://github.com/withcatai/node-llama-cpp) (GGUF, no network calls), so your notes
+never leave the machine. AI agents such as Claude Code and Claude Desktop use it through the CLI, an
+MCP server, a REST endpoint or the TypeScript SDK.
+It is the Korean distribution of [tobi/qmd](https://github.com/tobi/qmd) (MIT).
+
+- Package: `ko-qmd` on npm. The binary and MCP server keep the upstream name, `qmd`
+- Version: `<upstream version>-ko.N` (e.g. `2.8.3-ko.5`)
+- Full reference (every CLI option, MCP tool parameters, SDK API, scoring): [docs/REFERENCE.md](docs/REFERENCE.md)
+- Changes: [CHANGELOG.md](CHANGELOG.md) · [FAQ](#faq)
+
+```mermaid
+flowchart LR
+  Q[Query] --> H[Korean handling<br/>particle/ending strip · loanword bridge]
+  H --> FTS[BM25<br/>FTS5 + syllable bigrams]
+  Q --> VS[Vector search<br/>Qwen3-Embedding]
+  FTS --> RRF[RRF fusion]
+  VS --> RRF
+  RRF --> RR[Rerank<br/>Qwen3-Reranker]
+  RR --> OUT[Results]
+```
+
+## What differs from upstream qmd
+
+### Korean keyword search (lex)
+
+- **Particle and ending stripping** — an unquoted Hangul word also matches its stem: one trailing particle
+  (`검색을` → `검색`), a two-particle chain (`청킹에서의` → `청킹`), verb and nominalizing endings
+  (`토큰화하는` → `토큰화`, `검색하기` → `검색`), `한`/`된` endings (`필요한` → `필요`) and the 하↔해
+  contraction. Quoted phrases, Hanja and kana are left as written.
+- **Loanword bridge** — about 80 built-in Hangul spellings of technical terms (`서치`, `웹`, `코어`,
+  `마이그레이션`, …) also search their English spelling, so `하이브리드 서치` finds a `hybrid-search` note.
+  Only the query changes; no re-index is needed.
+- **Mixed-script token split** — `SKILL.md계약의핵심` becomes `skill` AND `md` AND `계약의핵심`.
+- **Long-query relaxation** — a query of three or more words that matches nothing with AND is retried with
+  OR, so a natural-language sentence never returns zero hits.
+- **Syllable-bigram index** — Hangul runs are indexed as syllable bigrams too, so a word inside a
+  compound written without spaces still matches.
+- **Negation strip** — "X 말고 Y" ("Y, not X") searches for Y alone.
+
+### Models and chunking
+
+| Role | Default model | Upstream |
+|---|---|---|
+| Embedding | `Qwen3-Embedding-0.6B` (Q8_0) | embeddinggemma-300M |
+| Rerank | `Qwen3-Reranker-0.6B` (Q8_0) | same |
+| Query expansion | `qmd-query-expansion-1.7B` | same |
+
+- Korean documents are chunked by their real token budget: Hangul costs far more tokens per character
+  than English (measured on Qwen3-Embedding: 1.64 chars/token for Korean, 6.08 for English). English
+  chunk boundaries match upstream.
+- Hybrid RRF weights are tuned for Korean, and a query containing Hangul skips LLM query expansion on
+  the hybrid path (English queries are still expanded).
+- The rerank blend lets the reranker actually change the top result, and the reranker is shown the
+  chunk that best matches the query's Hangul syllable bigrams, led by the note title.
+
+### Scope, tools and daemon
+
+- **Path and time scope** — CLI `--path` / `--since` / `--until`, the same fields over REST and MCP,
+  `scope` in the SDK. Ranking happens inside the filtered corpus.
+- **`qmd grep`** — exact string or regex match over indexed bodies, for spellings the tokenizer never
+  produced.
+- **Daemon** — re-indexes changed files before a search (once per collection every 30 s), optional query
+  log (`QMD_QUERY_LOG=1`), raw `vec_score` / `fts_score` with `rerank:false`, and a per-document
+  rerank token cap (`QMD_RERANK_MAX_DOC_TOKENS`, or `rerankMaxDocTokens` per request).
+
+## Install
+
+```sh
+npm install -g ko-qmd            # or pin: ko-qmd@2.8.3-ko.5
+```
+
+- It cannot sit beside upstream `@tobilu/qmd` (same binary name): `npm uninstall -g @tobilu/qmd` first.
+- Requires Node.js 22+ or Bun; on macOS, Homebrew SQLite (for extension loading). Models download to
+  `~/.cache/qmd/models/` on first use.
+
+## Quick start
+
+```sh
+qmd collection add ~/notes --name notes          # register and index a folder
+qmd context add qmd://notes "Personal dev notes" # description returned with results
+qmd embed                                         # vector embeddings (first time, then changes only)
+
+qmd query "하이브리드 서치 설계 결정"               # fusion + rerank (recommended)
+qmd search "리랭크"                               # BM25 only (fast, no model)
+qmd vsearch "검색 지연을 줄인 방법"                 # vector only
+qmd grep "QMD_QUERY_LOG"                          # exact body match
+qmd get "#abc123"                                 # fetch by docid
+```
+
+Common options: `-c <collection>` · `-n <count>` · `--min-score <score>` · `--full` ·
+`--intent "<what you are after>"` · `--no-rerank` · `--format json|csv|md|xml|files`.
+
+## Use from AI agents
+
+```sh
+qmd mcp                          # stdio MCP server (Claude Desktop, Claude Code, …)
+qmd mcp --http                   # HTTP on port 8181 — models load once, sessions share them
+qmd mcp --http --daemon          # background; stop with qmd mcp stop
+```
+
+The HTTP daemon serves `POST /mcp` (MCP Streamable HTTP), `POST /query` (REST) and `GET /health`.
+
+```sh
+curl -s http://127.0.0.1:8181/query -H 'Content-Type: application/json' -d '{
+  "searches": [{"type": "vec", "query": "리랭크 지연"}, {"type": "lex", "query": "리랭크 지연"}],
+  "collections": ["notes"], "limit": 10
+}'
+```
+
+```ts
+const { createStore } = await import('ko-qmd')   // ESM only — require() does not work
+
+const store = await createStore({ dbPath: './index.sqlite', configPath: `${process.env.HOME}/.config/qmd/index.yml` })
+const results = await store.search({
+  queries: [{ type: 'vec', query: '리랭크 지연' }, { type: 'lex', query: '리랭크 지연' }],
+  collection: 'notes', limit: 10,
+})
+await store.close()
+```
+
+Tool list, request fields and SDK API: [docs/REFERENCE.md](docs/REFERENCE.md). Search guidance for
+agents, including a section on Korean queries: [skills/qmd/SKILL.md](skills/qmd/SKILL.md).
+
+## Benchmark
+
+`bash scripts/bench-ko.sh` runs the `test/fixtures/ko-vault/` fixture (97 documents, 93 queries).
+On its first 52 queries, bm25 recall@5 went from 0.6250 on upstream 2.8.3 to 0.9519 in this
+distribution. Every run's numbers are in [BASELINE.md](test/fixtures/ko-vault/BASELINE.md).
+
+## FAQ
+
+### What is ko-qmd?
+A CLI, MCP server and SDK that search Korean Markdown notes on your own machine. It adds Korean
+particle and ending handling, a Hangul syllable-bigram index, a Korean-friendly default embedding
+model (Qwen3-Embedding) and tuned fusion weights on top of upstream qmd.
+
+### Why not use upstream qmd for Korean?
+Upstream BM25 treats a word with a particle attached (`검색을`, `청킹에서의`) as a different token from
+its stem, so it misses notes that say `검색`. On the ko-vault benchmark (52 queries) bm25 recall@5 is
+0.6250 upstream and 0.9519 here.
+
+### Can it search an Obsidian vault?
+Yes. Register the vault folder with `qmd collection add <vault path> --name <name>` and it indexes the
+`*.md` files inside. It only reads your files.
+
+### Does it need internet access or an API key?
+No. The embedding, rerank and query-expansion models download once on first use and run offline after
+that.
+
+### How do I connect it to Claude Code or another agent?
+Start the MCP server with `qmd mcp` (stdio) or `qmd mcp --http --daemon` (HTTP, shared models). See
+[Use from AI agents](#use-from-ai-agents).
+
+### Does it work for English notes too?
+Yes. English queries and documents behave as upstream: same chunk boundaries, same query expansion.
+Korean and English notes can live in one index.
+
+## Development
+
+```sh
+bun install
+bun src/cli/qmd.ts <command>     # run from source
+bun run lint && bun run test:types
+npx vitest run --reporter=verbose test/
+npm run build                    # dist/ — never `bun build --compile` (it breaks sqlite-vec)
+```
+
+`develop` is the working branch (PRs go there); `main` is the release branch. Release, dogfood and
+upstream-sync procedures are documented in Korean in [README.md](README.md#개발).
+
+## License
+
+MIT. Original copyright Tobi Lutke ([LICENSE](LICENSE)); this distribution uses the same license.

package/README.md

@@ -1,13 +1,20 @@
-# ko-qmd
+# ko-qmd — 한국어 마크다운 노트를 위한 로컬 하이브리드 검색 엔진
 
-한국어 마크다운 노트를 위한 로컬 검색 엔진. [tobi/qmd](https://github.com/tobi/qmd)(MIT)의 한국어 배포판이다.
-노트·회의록·문서를 색인해 키워드로도 자연어로도 찾고, 에이전트가 CLI·MCP·REST·SDK 로 쓴다.
-모든 모델은 [node-llama-cpp](https://github.com/withcatai/node-llama-cpp) 로 로컬에서 돈다(GGUF, 네트워크 호출 없음).
+[![npm](https://img.shields.io/npm/v/ko-qmd?label=npm%20ko-qmd)](https://www.npmjs.com/package/ko-qmd)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+**한국어** · [English](README.en.md)
+
+**ko-qmd 는 한국어 마크다운 노트(Obsidian 볼트·위키·회의록·문서 폴더)를 키워드와 자연어로 찾는 로컬 검색 엔진이다.**
+BM25 전문 검색, 벡터 검색, LLM 리랭크를 섞어 쓰고, 조사·어미가 붙은 한국어 질의도 어간으로 찾는다.
+모든 모델이 [node-llama-cpp](https://github.com/withcatai/node-llama-cpp) 로 내 컴퓨터에서 돌아 노트가 밖으로 나가지 않는다(GGUF, 네트워크 호출 없음).
+AI 에이전트(Claude Code·Claude Desktop 등)는 CLI·MCP 서버·REST·TypeScript SDK 로 쓴다.
+[tobi/qmd](https://github.com/tobi/qmd)(MIT)의 한국어 배포판이다.
 
 - 패키지: `ko-qmd` (npm). 실행 파일과 MCP 서버 이름은 업스트림과 같은 `qmd`
-- 버전: `<업스트림 버전>-ko.N` (예: `2.8.3-ko.4`)
+- 버전: `<업스트림 버전>-ko.N` (예: `2.8.3-ko.5`)
 - 영어 레퍼런스(전체 CLI 옵션·MCP 툴 파라미터·SDK API·점수 계산): [docs/REFERENCE.md](docs/REFERENCE.md)
-- 변경 이력: [CHANGELOG.md](CHANGELOG.md)
+- 변경 이력: [CHANGELOG.md](CHANGELOG.md) · 자주 묻는 질문: [FAQ](#자주-묻는-질문)
 
 ```mermaid
 flowchart LR
@@ -28,11 +35,12 @@ flowchart LR
   동사·명사화 어미(`토큰화하는` → `토큰화`, `검색하기` → `검색`), `한`/`된` 어미(`필요한` → `필요`), 하↔해 축약(`더하` ↔ `더해`).
   따옴표 구문·한자·가나는 그대로 둔다.
 - **외래어 다리** — 기술 용어의 한글 표기(`서치`·`웹`·`코어`·`마이그레이션` 등 약 80개 내장 표)는 영문 표기도 함께 찾는다.
-  `하이브리드 서치`가 `hybrid-search` 노트를, `레몬 웹 코어`가 `lemon-web-core`를 찾는다. 질의 쪽만 바뀌므로 재색인은 필요 없다.
+  `하이브리드 서치`가 `hybrid-search` 노트를, `리액트 웹 코어`가 `react-web-core`를 찾는다. 질의 쪽만 바뀌므로 재색인은 필요 없다.
 - **문자 체계가 섞인 토큰 분리** — `SKILL.md계약의핵심`은 `skill` AND `md` AND `계약의핵심`으로 나눈다.
 - **긴 질의 완화** — 세 단어 이상 질의가 AND 로 한 건도 안 맞으면 같은 단어를 OR 로 다시 찾는다. 자연어 문장 질의가 0건이 되지 않는다.
 - **음절 bigram 색인** — 한글 구간의 음절 bigram 을 FTS 필드에 덧붙인다. 붙여 쓴 복합어 안의 단어도 걸린다.
   기존 인덱스는 처음 열 때 FTS 를 한 번 다시 만든다.
+- **부정 절 제거** — "X 말고 Y" 꼴 질의는 Y 만 찾는다(`말고`·`빼고`·`제외하고`·`제외한`).
 
 ### 기본 모델과 청킹
 
@@ -45,8 +53,13 @@ flowchart LR
 - 한국어 문서는 실제 토큰 예산으로 청킹한다. 한글은 글자당 토큰이 영어보다 훨씬 많다(Qwen3-Embedding 실측 ko 1.64 / en 6.08 chars/token).
   그래서 청크 크기는 한글·기타 문자의 조화 평균으로 잡는다. 영어 문서의 청크 경계는 업스트림과 같다.
 - 하이브리드 RRF 가중치를 한국어에 맞게 조정했다. 벡터 목록은 절반, OR 로 완화한 lex 목록은 다시 절반, 확장 질의 목록은 0.75 로 센다.
+- `qmd query`·MCP plain `query`·SDK `search({ query })` 의 하이브리드 경로에서 한글이 한 글자라도 든 질의는 LLM 질의
+  확장을 하지 않는다(명시적 `expand:` 포함, `qmd vsearch` 는 아직 확장한다). 확장 모델은 한국어 질문에 영어 문장 틀과 중국어를 섞어 썼고,
+  그 샘플링만으로 어려운 질의 1위가 실행마다 30개 중 5개까지 바뀌었다. 끄자 어려운 질의 1위는 줄지 않았고 hybrid 지연은
+  질의당 약 1초에서 수십 ms 로 줄었다(BASELINE.md 2026-09-26). 영어 질의는 그대로 확장한다.
 - 리랭커가 실제로 1위를 바꿀 수 있게 점수 블렌드를 고쳤다. 검색 순위 항은 블렌드의 10% 인 선형 감쇠다.
   이전 블렌드에서는 리랭크 점수와 상관없이 검색 1위가 그대로 남았다.
+- 리랭커에는 질의의 한글 음절 bigram 이 가장 많이 겹치는 청크를 보내고, 청크에 노트 제목이 없으면 제목을 앞에 붙인다.
 
 ### 검색 범위와 도구
 
@@ -72,7 +85,7 @@ flowchart LR
 ## 설치
 
 ```sh
-npm install -g ko-qmd            # 또는 버전 핀: ko-qmd@2.8.3-ko.4
+npm install -g ko-qmd            # 또는 버전 핀: ko-qmd@2.8.3-ko.5
 ```
 
 - 업스트림 `@tobilu/qmd` 와 실행 파일 이름이 같아 함께 둘 수 없다. `npm uninstall -g @tobilu/qmd` 뒤 설치한다.
@@ -87,7 +100,7 @@ qmd collection add ~/notes --name notes          # 컬렉션 등록 + 색인
 qmd context add qmd://notes "개인 개발 노트"       # 검색 결과와 함께 돌려줄 설명
 qmd embed                                         # 벡터 임베딩 (처음 한 번, 이후 변경분만)
 
-qmd query "하이브리드 서치 설계 결정"               # 확장 + 융합 + 리랭크 (권장)
+qmd query "하이브리드 서치 설계 결정"               # 융합 + 리랭크 (권장, 한글 질의는 확장하지 않는다)
 qmd search "리랭크"                               # BM25 만 (빠름, 모델 없음)
 qmd vsearch "검색 지연을 줄인 방법"                 # 벡터만
 qmd grep "QMD_QUERY_LOG"                          # 본문 정확 일치
@@ -197,16 +210,23 @@ bash scripts/dogfood.sh --check "RESULT bm25_r5=…"   # 게이트 판정만
 ```
 
 - 게이트: `bench-ko.sh` 의 `bm25_r5` 가 [BASELINE.md](test/fixtures/ko-vault/BASELINE.md) 의 마지막 `RESULT` 줄보다 낮으면 설치 전에 멈춘다(exit 3).
+  베이스라인에 `RESULT-HARD` 줄이 있으면 어려운 유형 게이트도 돈다: 벤치를 돌린 form(`form=`, 없으면 plain)이
+  그 줄과 같아야 하고, `full_r1` 이 그 줄의 값에서 그 줄의 `tol=` 을 뺀 값보다 낮으면 마찬가지로 멈춘다.
+  seam form(`bench-ko.sh` 기본값 — 질의마다 `lex:`·`vec:` 두 줄, LLM 질의 확장 없음)이면 `hybrid_r1` 도 같은 식으로 본다.
+  seam form 은 같은 커밋에서 매번 같은 값이 나와 기준줄이 `tol=0` 이다. plain form 의 `hybrid_r1` 은 확장 샘플링만으로
+  질의 5개만큼 흔들려서 게이트하지 않는다(BASELINE.md 2026-09-26).
 - `npm link` 가 아니라 pack 설치다. 링크하면 데몬이 작업 트리의 `dist/` 를 서빙해 빌드 중에 깨질 수 있다.
-- 머신 배선 env: `DOGFOOD_LABEL`(launchd 라벨, 기본 `com.lemoncloud.qmd-daemon`) · `DOGFOOD_URL`(기본 `http://127.0.0.1:8181`) ·
+- 머신 배선 env: `DOGFOOD_LABEL`(launchd 라벨, 기본 `io.github.ko-qmd.daemon`) · `DOGFOOD_URL`(기본 `http://127.0.0.1:8181`) ·
   `DOGFOOD_SMOKE` · `DOGFOOD_PIN_FILE`. 성공하면 `~/.cache/qmd/dogfood-deployed` 에 `<시각> <커밋>` 을 쓴다.
 
 ### ko-vault 벤치
 
-`bash scripts/bench-ko.sh` — 픽스처 `test/fixtures/ko-vault/`(문서 28·질의 63), 임베딩은 Qwen3-Embedding-0.6B-Q8_0 고정.
+`bash scripts/bench-ko.sh` — 픽스처 `test/fixtures/ko-vault/`(문서 97: 위키 28·디스트랙터 69·질의 93), 임베딩은 Qwen3-Embedding-0.6B-Q8_0 고정.
+기본은 seam form(REST/MCP 호출과 같은 `lex:`+`vec:` 모양, 확장 없음)이고 `KO_FORM=plain` 이면 질의를 그대로 넘겨 확장 경로를 잰다.
 run별 수치는 [BASELINE.md](test/fixtures/ko-vault/BASELINE.md). 업스트림 2.8.3 의 bm25_r5 0.6250 에서 시작해,
 Qwen3-Embedding 기본값·질의 52 에서 bm25_r5 0.9519 · vector_r5 1.0000 · full_r5 1.0000 이다.
-질의 63 은 외래어 표기 질의 11건을 더한 셋이고, 그 11건의 수치는 BASELINE.md 2026-09-23 절에 있다.
+질의 63 은 외래어 표기 질의 11건을 더한 셋이고, 그 11건의 수치는 BASELINE.md 2026-09-23 절에 있다. 질의 93 은 어려운 유형
+(sem-hard 12·multi 8·neg 10) 30건을 더한 셋이고, 첫 수치는 BASELINE.md 2026-09-24 절에 있다.
 
 ### Electron 내장
 
@@ -234,12 +254,35 @@ pnpm install --lockfile-only                              # package.json 이 바
 bun run lint && bun run test:types && bun run test:unit && bash scripts/bench-ko.sh
 ```
 
-- 벤치는 bm25 recall@5·MRR 을 질의별로 머지 전과 비교한다(hybrid 는 실행마다 한 질의쯤 흔들린다).
+- 벤치는 bm25 recall@5·MRR 을 질의별로 머지 전과 비교한다. 기본 seam form 은 실행마다 같은 값이 나와서, 움직였다면
+  동기화가 바꾼 것이다. `KO_FORM=plain` 의 hybrid 는 질의 확장 샘플링만으로도 흔들린다.
 - PR 은 squash 가 아니라 **머지 커밋**으로 들인다. 업스트림 커밋이 조상으로 남아야 다음 동기화가 새 커밋만 본다.
   같은 이유로 이 브랜치는 squash·rebase 하지 않고, `develop`·`main` 을 upstream 위로 rebase 하지 않는다.
 - `pnpm install --frozen-lockfile --lockfile-only` 가 통과해야 한다. 낡은 `pnpm-lock.yaml` 은 GitHub 설치(`prepare`)와 릴리스 태그의 pre-push 검사를 막는다.
 - 업스트림 태그 위에 있을 때만 `v<업스트림 버전>-ko.N` 태그를 쓴다. `main` 스냅샷이면 버전은 마지막 태그 기준이다.
 
+## 자주 묻는 질문
+
+### ko-qmd 는 무엇인가?
+한국어 마크다운 노트를 로컬에서 검색하는 CLI·MCP 서버·SDK 다. 업스트림 qmd 에 한국어 조사·어미 처리, 한글 음절 bigram 색인,
+한국어에 맞춘 기본 임베딩(Qwen3-Embedding)과 융합 가중치를 더했다.
+
+### 업스트림 qmd 로 한국어를 검색하면 무엇이 안 되나?
+업스트림의 BM25 는 `검색을`·`청킹에서의` 처럼 조사가 붙은 단어를 다른 토큰으로 본다. 그래서 `검색` 이라고 적은 노트를 놓친다.
+ko-vault 벤치(질의 52)에서 bm25 recall@5 는 업스트림 2.8.3 의 0.6250 에서 이 배포판의 0.9519 로 올랐다([BASELINE.md](test/fixtures/ko-vault/BASELINE.md)).
+
+### Obsidian 볼트를 그대로 검색할 수 있나?
+그렇다. 볼트 폴더를 `qmd collection add <볼트 경로> --name <이름>` 으로 등록하면 그 안의 `*.md` 를 색인한다. 볼트 파일은 읽기만 한다.
+
+### 인터넷 연결이나 API 키가 필요한가?
+아니다. 임베딩·리랭크·질의 확장 모델은 처음 쓸 때 한 번 내려받고(`~/.cache/qmd/models/`), 그 뒤로는 오프라인에서 돈다.
+
+### Claude Code 같은 AI 에이전트에 붙이려면?
+`qmd mcp`(stdio) 또는 `qmd mcp --http --daemon`(HTTP, 여러 세션이 모델 공유)으로 MCP 서버를 띄운다. [에이전트에서 쓰기](#에이전트에서-쓰기) 참고.
+
+### 영어 노트도 되나?
+된다. 영어 질의와 영어 문서의 청크 경계·질의 확장은 업스트림과 같게 동작한다. 한국어와 영어가 섞인 노트도 한 인덱스에서 찾는다.
+
 ## 라이선스
 
 MIT. 원저작권은 Tobi Lutke([LICENSE](LICENSE))에게 있고, 이 배포판도 같은 라이선스를 따른다.

package/dist/bench/bench.d.ts

@@ -13,7 +13,13 @@
  *   - hybrid: BM25 + vector RRF fusion without reranking
  *   - full: Full hybrid pipeline with LLM reranking
  */
-import type { BenchmarkResult } from "./types.js";
+import type { BackendSummaryByType, HardSummary, QueryResult, BenchmarkResult } from "./types.js";
+/** Per-type summary built from the existing computeSummary on each type's slice of results.
+ *  A type with zero queries gets no entry — pooling must skip it, never divide by zero. */
+export declare const computeSummaryByType: (results: QueryResult[]) => BackendSummaryByType;
+/** Count-weighted pool of the hard query types over the per-type summary — the numbers behind
+ *  the `RESULT-HARD` line bench-ko.sh prints and dogfood.sh gates. Nulls when empty. */
+export declare const computeHardSummary: (byType: BackendSummaryByType) => HardSummary;
 export type BenchCollectionInfo = {
     name: string;
     active_count: number;

package/dist/bench/bench.js

@@ -17,6 +17,7 @@ import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { createStore, getDefaultDbPath, } from "../index.js";
 import { scoreResults } from "./score.js";
+import { HARD_QUERY_TYPES } from "./types.js";
 function parseStructuredQuery(query) {
     const lines = query.split("\n").map((line, idx) => ({
         trimmed: line.trim(),
@@ -219,6 +220,46 @@ function computeSummary(results) {
     }
     return summary;
 }
+/** Per-type summary built from the existing computeSummary on each type's slice of results.
+ *  A type with zero queries gets no entry — pooling must skip it, never divide by zero. */
+export const computeSummaryByType = (results) => {
+    const byType = {};
+    const types = Array.from(new Set(results.map(r => r.type))).sort();
+    for (const type of types) {
+        const slice = results.filter(r => r.type === type);
+        byType[type] = {};
+        for (const [name, s] of Object.entries(computeSummary(slice))) {
+            byType[type][name] = { ...s, count: slice.length };
+        }
+    }
+    return byType;
+};
+/** Count-weighted pool of the hard query types over the per-type summary — the numbers behind
+ *  the `RESULT-HARD` line bench-ko.sh prints and dogfood.sh gates. Nulls when empty. */
+export const computeHardSummary = (byType) => {
+    const METRICS = [
+        ["hybrid_r1", "hybrid", "avg_recall_at_1"],
+        ["hybrid_mrr", "hybrid", "avg_mrr"],
+        ["full_r1", "full", "avg_recall_at_1"],
+        ["full_mrr", "full", "avg_mrr"],
+    ];
+    const out = { hybrid_r1: null, hybrid_mrr: null, full_r1: null, full_mrr: null, n: 0 };
+    for (const type of HARD_QUERY_TYPES) {
+        out.n += Object.values(byType[type] ?? {})[0]?.count ?? 0;
+    }
+    for (const [key, backend, metric] of METRICS) {
+        let num = 0, den = 0;
+        for (const type of HARD_QUERY_TYPES) {
+            const entry = byType[type]?.[backend];
+            if (!entry)
+                continue;
+            num += entry[metric] * entry.count;
+            den += entry.count;
+        }
+        out[key] = den > 0 ? num / den : null;
+    }
+    return out;
+};
 /**
  * Fail fast when the fixture's collection is missing or empty so `qmd bench`
  * does not spend minutes printing a wall of 0.00 (#716).
@@ -300,11 +341,14 @@ export async function runBenchmark(fixturePath, options = {}) {
     }
     const summary = computeSummary(results);
     const timestamp = new Date().toISOString().replace(/[:.]/g, "").slice(0, 15);
+    const summaryByType = computeSummaryByType(results);
     const benchResult = {
         timestamp,
         fixture: fixturePath,
         results,
         summary,
+        summary_by_type: summaryByType,
+        summary_hard: computeHardSummary(summaryByType),
     };
     // Output
     if (benchSummaryAllZero(summary)) {

package/dist/bench/types.d.ts

@@ -5,19 +5,24 @@
  * The harness runs each query through multiple search backends
  * and measures precision, recall, MRR, and latency.
  */
+export type BenchmarkQueryType = "exact" | "semantic" | "topical" | "cross-domain" | "alias" | "sem-hard" | "multi" | "neg";
+/** Query types pooled into the hard `RESULT-HARD` gate line (bench-ko.sh / dogfood.sh). */
+export declare const HARD_QUERY_TYPES: readonly BenchmarkQueryType[];
 export interface BenchmarkQuery {
     /** Unique identifier for the query */
     id: string;
     /** The search query text */
     query: string;
     /** Query difficulty/type for grouping results */
-    type: "exact" | "semantic" | "topical" | "cross-domain" | "alias";
+    type: BenchmarkQueryType;
     /** Human-readable description of what this tests */
     description: string;
     /** File paths (relative to collection) that should appear in results */
     expected_files: string[];
     /** How many of expected_files should appear in top-k results */
     expected_in_top_k?: number;
+    /** For `neg` queries: the named-but-excluded concept's path (fixture-test invariant only) */
+    excluded?: string;
 }
 export interface BenchmarkFixture {
     /** Description of the benchmark */
@@ -63,18 +68,34 @@ export interface QueryResult {
     type: string;
     backends: Record<string, BackendResult>;
 }
+/** Per-backend averages over a group of queries (the shape of summary[backend]). */
+export interface BackendSummary {
+    avg_precision: number;
+    avg_recall: number;
+    avg_recall_at_1: number;
+    avg_recall_at_3: number;
+    avg_recall_at_5: number;
+    avg_mrr: number;
+    avg_f1: number;
+    avg_latency_ms: number;
+}
+/** Per-backend averages over one query type; count = queries of that type (the same for every backend). */
+export type BackendSummaryByType = Record<string, Record<string, BackendSummary & {
+    count: number;
+}>>;
+/** Count-weighted pool over the hard query types; nulls when no hard queries ran (printed as nan). */
+export interface HardSummary {
+    hybrid_r1: number | null;
+    hybrid_mrr: number | null;
+    full_r1: number | null;
+    full_mrr: number | null;
+    n: number;
+}
 export interface BenchmarkResult {
     timestamp: string;
     fixture: string;
     results: QueryResult[];
-    summary: Record<string, {
-        avg_precision: number;
-        avg_recall: number;
-        avg_recall_at_1: number;
-        avg_recall_at_3: number;
-        avg_recall_at_5: number;
-        avg_mrr: number;
-        avg_f1: number;
-        avg_latency_ms: number;
-    }>;
+    summary: Record<string, BackendSummary>;
+    summary_by_type: BackendSummaryByType;
+    summary_hard: HardSummary;
 }