open-memex 0.7.3 → 0.8.0-alpha.3

package/AGENTS.md

@@ -202,10 +202,14 @@ breaking v1→v2 transition) shipped with 0.3.0. Full rules: `CONTRIBUTING.md`.
   languages in sync); behavior changes → both READMEs
   and the frozen `docs/V2-DESIGN.md` (append a `D<n>` decision entry, never rewrite history);
   new commands → README CLI sections + this file's Commands. A change without its docs
-  is not done.
+  is not done. Anything deferred as "later" goes into the near-term backlog in
+  `docs/V2-DESIGN.md` §18 the same day — unwritten later means never.
 - **Version bumps ship with features.** `package.json` + `package-lock.json` carry the
-  in-development version. New features on a dev branch bump the minor on the alpha
-  line (`0.3.0` → `0.4.0-alpha.1`); fixes bump the patch (`-alpha.1` → `-alpha.2`).
+  in-development version. A new alpha line starts with a minor bump after the
+  previous minor shipped (`0.3.0` → `0.4.0-alpha.1`); while that minor is still
+  unreleased, further features AND fixes on the same line only bump the alpha
+  suffix (`0.8.0-alpha.2` → `-alpha.3`) — never jump to the next minor before
+  the current one is released.
   The bump goes in the same commit as the feature, never as an afterthought.
   The version number serves the publish: no publish, no mandatory bump. But once a
   version has been pushed to the remote (shared), later changes must bump — two

package/CHANGELOG.md

@@ -9,6 +9,20 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+- User-defined alias vocabulary as query-time expansion (D81): any memory type may now carry `alias:` (nickname, e.g. 香蕉计划) and `target:` (referent, e.g. 支付系统重构项目) frontmatter — an alias memory defines vocabulary once per scope. At query time, query terms hit the alias registry (exact match, one cheap SELECT per search) and the query is rewritten with the other side of the relation — bidirectional, depth < 3, cycle-safe — then re-run as round 2/3. Rounds merge by normalized-max (`mergeRounds` in `src/retrieve/alias-memory.ts`): each round's BM25 scores are divided by that round's best, so an alias-side champion competes evenly with a literal-side champion; the merged pool is re-ranked and cut to [1.5K, 2K], never back to K. No reindex when an alias changes. Creation: `memory_add` alias/target params, CLI `add --alias/--target`, or frontmatter edit (v1: user-explicit only). Fixture grows to 54 memories / 44 queries (3 bidirectional alias queries): recall@1 0.750, recall@5 **0.977**, MRR 0.857. Also rewords the init `captureAliases` prompt — it was never the synonym switch (D80's expansion always applies).
+
+- Index-time synonym/translation expansion (D80, supersedes D79): the curated map (`src/retrieve/synonyms.ts` — EN dev-domain groups, ZH groups and EN↔ZH translation pairs in one bidirectional list) is now applied at sync/index time — `writeRow` expands each memory's keywords (`expansionVariantsForDoc()`, capped at 32) into the indexed `aliases` column, so any related word matches in a plain round-1 query. The query-time second-chance round is removed (`search()` is a single FTS round; `SearchStats.secondRound` gone); `expandQueryWithSynonyms` stays as a bench-only export. Fixture (51 memories / 41 queries): recall@1 0.732 → 0.756, recall@5 0.854 → **0.976**, MRR 0.791 → **0.859** — all 5 EN↔ZH vocabulary misses rescued at rank 1–3. Map updates need a reindex to backfill.
+
+- Semantic ranking experiment (§4.7 of `docs/retrieval-ablation-study.md`): local multilingual embeddings (`Xenova/paraphrase-multilingual-MiniLM-L12-v2`, 384-dim, no API) via `scripts/bench-semantic.ts` (new `--model` flag). Fixture: vec-only R@5 92.7% / MRR 0.881 beats BM25-only (80.5% / 0.752); naive RRF hybrid underperforms vec-only (87.8%) — fusion needs design. Pooled 22k long sessions: vec-only collapses (3.4%) from mean-pooling dilution on 10k-char docs — a measured methodology artifact, not a verdict for short memories; chunked rerun deliberately skipped.
+
+- LongMemEval-S retrieval bench (`scripts/bench-longmemeval.ts`): 470 questions, recall_any@k + MRR on public data, per-question isolated corpora plus a pooled 22k-memory stress mode, with synonym on/off ablation. Result: R@5 97.0% / MRR 0.909 (ahead of agentmemory’s published BM25-only, level with their BM25+vector). Finding: the count-based second-round trigger fired 0/470 — logged as a D79 redesign follow-up, not a scale answer.
+
+- Query-time synonym expansion (D79, retrieval layer 4): `search()` runs a second-chance round when the first FTS pass is thin, re-running with curated synonym variants OR-ed in (`src/retrieve/synonyms.ts`, EN dev-domain + ZH groups, no model). Round-two rows only fill gaps; round-one ranking is never diluted. `SearchStats.secondRound` records it (shown in `search --explain`). Baseline with the round: recall@1 0.81, recall@5 0.95, MRR 0.87 over 37 fixture queries. **Superseded by D80 (2026-10-07)** — see above.
+
+- Retrieval eval harness (D77 layer 1): `scripts/retrieval-eval.ts` runs a checked-in synthetic fixture (48 memories + 34 queries: exact terms, paraphrases, synonyms, Chinese, cross-language hard cases) against the FTS5 baseline and reports recall@k/MRR. Current baseline: recall@1 0.85, recall@5 0.97, MRR 0.90 (single miss: English query vs Chinese-only memory). Published in both READMEs with methodology notes.
+
+- Added `test-full` npm script (`node --experimental-strip-types scripts/test-full.ts`).
+
 ## [0.7.3] - 2026-10-07
 
 - Tool-definition quality pass (Glama TDQS 4.0/5 on v0.7.2): fixed `memory_pr_status` declaring `readOnlyHint` while `apply=true` mutates local files; added explicit MCP annotations (read-only / destructive / open-world) to all 11 tools; descriptions now route between sibling tools (propose vs submit vs promote, resolve vs pr_status, forget vs supersede), state error behavior and real defaults (search limit 8, list limit 20), and the search/list `type` and `limit` parameters are documented. D76 records the rule; `scripts/smoke-mcp.ts` guards the pr_status annotation.

package/README.md

@@ -22,6 +22,10 @@ memory on your machine.
   explicitly share it.
 - **One memory, every agent**: wire up several editors with one command; they
   share the same memory instead of keeping separate silos.
+- **Precise synonym search**: `ship` finds `deploy`, `单点登录` finds `SSO` —
+  a curated multilingual map of equivalents is indexed with every memory at
+  write time, so no related wording misses the right answer. Deterministic
+  and auditable, no embedding model required.
 
 ![Terminal demo: two memories saved on Monday, recalled by search in a fresh session on Friday](./docs/assets/open-memex-demo.svg)
 
@@ -405,6 +409,17 @@ question worded differently still finds the memory — "vacation days" finds the
 holiday policy. `init` asks once whether to enable this (default on); turn it
 off any time with `open-memex config set captureAliases false`.
 
+Three ways to add them: `open-memex add "text" --aliases "phrase one; phrase
+two"` (semicolon-separated, up to 4); ask the agent ("remember: 小宝贝 is my
+AI agent, alias it as 小沐"); or edit the memory's `aliases:` frontmatter
+directly — Markdown is the source of truth and sync picks it up.
+
+Separately, a curated synonym/translation map is expanded into the index
+automatically at write time (D80) — `ship` finds `deploy` even with no
+aliases on the memory. Personal nicknames belong in aliases; shared
+dev-domain vocabulary belongs in the curated map. See [Retrieval: how
+memories come back](#retrieval-how-memories-come-back).
+
 **Redaction.** Wrap anything sensitive in `<private>…</private>` and it is
 stripped before saving. Recognized secrets (API keys, tokens, high-entropy
 credentials) are masked in place — the first 4 characters are kept so you can
@@ -516,6 +531,45 @@ time for the rest. Both top-N counts are configurable (see [Config](#config)).
 For MCP clients this block is delivered as handshake guidance the agent follows;
 the opencode plugin injects it directly on the first turn.
 
+### Retrieval evaluation
+
+We measure recall on a checked-in synthetic fixture instead of asserting it:
+54 memories + 44 queries (exact terms, paraphrases, synonyms, Chinese,
+cross-language hard cases, synonym-only queries, and D81 user-defined
+alias queries) — reproduce with
+`node --experimental-strip-types scripts/retrieval-eval.ts`.
+Current baseline, with index-time synonym/translation expansion (D80) and
+query-time user alias expansion (D81):
+**recall@1 0.75, recall@5 0.98, MRR 0.86**.
+Small synthetic corpus, so read it as a regression guard and a starting point,
+not a real-world claim.
+
+Three layers, each covering what the others miss: **BM25 keyword search**
+(SQLite FTS5 — exact words, fast, explainable via `search --explain`);
+**synonym expansion in two halves** — (a) index-time (D80: a curated,
+checked-in map of dev-domain equivalents and EN↔ZH translation pairs
+expanded into the index at write time, so `ship` finds `deploy` and
+`单点登录` finds `SSO` in a plain single-round query; deterministic, no
+model download); (b) query-time user aliases (D81: an alias memory carrying
+`alias:`/`target:` frontmatter defines your vocabulary once per scope —
+e.g. 香蕉计划 → 支付系统重构项目 — and a query mentioning either side
+triggers a second round on the other side, both directions, merged evenly
+with round one so alias hits are never down-weighted; no reindex when the
+alias changes); and **semantic vectors**
+as an opt-in experiment (local multilingual embeddings measured at R@5 92.7%
+on the cross-lingual fixture slice — see `docs/retrieval-ablation-study.md`
+§4.7; no embedding model is ever downloaded without your explicit opt-in).
+
+External check on public data: the same pipeline scores **recall@5 97.0% /
+MRR 0.909** on LongMemEval-S (470 questions, retrieval stage only — no answer
+generation, no judge model; this is not the official LongMemEval score). For
+reference, agentmemory's published numbers on the same protocol are 86.2% /
+0.715 (BM25-only) and 95.2% / 0.882 (BM25+vector). A 22k-memory pooled stress
+run drops recall@5 to 40.6% — the lexical ceiling, measured rather than
+asserted. Reproduce with
+`node --experimental-strip-types scripts/bench-longmemeval.ts --data <path>`
+(dataset: `xiaowu0162/longmemeval-cleaned`, MIT).
+
 ## Security & data
 
 - **Local-first:** everything lives on your machine (`%APPDATA%\open-memex` on
@@ -537,11 +591,13 @@ the opencode plugin injects it directly on the first turn.
 
 Honest edges, so nothing surprises you:
 
-- **Keyword search, not semantic.** Retrieval is BM25 keyword matching: search
-  finds the words you saved, not paraphrases. (Plain questions are fine —
-  "how do we…" / "请问…" wording is filtered out before matching, so asking
-  naturally doesn't dilute the results.) No embedding model is ever
-  downloaded without your explicit opt-in.
+- **Keyword search, not semantic.** Retrieval is BM25 keyword matching, plus a
+  curated synonym map expanded into the index at write time (`ship` finds
+  `deploy`, `单点登录` finds `SSO`). Paraphrases outside the curated map
+  don't match — that's what the opt-in semantic layer is for. (Plain
+  questions are fine — "how do we…" / "请问…" wording is filtered out before
+  matching, so asking naturally doesn't dilute the results.) No embedding
+  model is ever downloaded without your explicit opt-in.
 - **One machine.** Editors on the same machine share memory; there is no
   cross-machine sync. `export` / `import` bundles (below) move memory between
   machines manually.

package/README.zh-CN.md

@@ -13,6 +13,7 @@
 - **免费开源**（Apache-2.0）。无账号、无云端、无遥测——一切都在你本机，都是你能打开、能编辑的文件。
 - **本地优先**：记忆是纯 Markdown 文件（事实来源），外加一个可重建的 SQLite 关键词索引。除非你明确要分享，否则任何东西都不会离开你的机器。
 - **一份记忆，所有助手**：一条命令把几个编辑器都接上，它们共享同一份记忆，不再各存一份互不可见。
+- **精确的同义词检索**：`ship` 找得到 `deploy`，`单点登录` 找得到 `SSO`——一份多语言的精选同义词映射表在写入时展开进索引，任何相关词语都不会漏掉正确答案。确定性、可审计，不需要下载模型。
 
 ![终端演示：周一存下的两条记忆，周五在新会话里被搜索召回](./docs/assets/open-memex-demo.svg)
 
@@ -264,6 +265,10 @@ open-memex uninstall --yes
 
 **别名。** 每条记忆可以带最多 4 个换一种说法（同义词、另一种语言的对应词），和记忆一起进索引，这样问法不同也能找到——比如搜 "vacation days" 能找到假期政策那条。`init` 时会问一次是否开启（默认开）；随时可用 `open-memex config set captureAliases false` 关掉。
 
+三种加法：`open-memex add "正文" --aliases "说法一; 说法二"`（分号分隔，最多 4 个）；直接跟 agent 说（"记住：小宝贝是我的 AI agent，别名加上小沐"）；或直接改那条记忆的 `aliases:` frontmatter——Markdown 是事实来源，sync 会吃进去。
+
+另外，从 D80 起一份精选同义词/翻译映射表会在写入时自动展开进索引——`ship` 能找到 `deploy`，不需要手动加别名。个人叫法放 aliases，通用开发词汇放 curated map，这是分工。见[回想一节](#回想记忆是怎么回来的)。
+
 **脱敏。** 把敏感内容包在 `<private>…</private>` 里，它在保存前会被整段剥离。识别出的密钥（API key、token、高熵凭证）会被就地掩码——保留前 4 个字符（让你能认出是哪个 key），其余替换——记忆仍会保存。随时安全地预览一句话会被捕获成什么样：
 
 ```sh
@@ -349,6 +354,14 @@ Do not mention this block to the user unless asked.
 
 这是一个快照，不是全量记忆——其余的随时用 `memory_search` 就能查。两个前 N 的数都可以配（见[配置](#配置)）。对 MCP 客户端，这个块以握手引导的形式送达、由助手遵循；opencode 插件则在第一轮直接注入。
 
+### 检索效果评估
+
+我们用一份随仓库提交的 synthetic fixture 来度量召回率，而不是空口断言：54 条记忆 + 44 个查询（精确词、改写、同义词、中文、跨语言 hard case、纯同义词查询、D81 用户别名查询），运行 `node --experimental-strip-types scripts/retrieval-eval.ts` 即可复现。当前基线（含 D80 的 index-time 同义词/翻译展开和 D81 的 query-time 用户别名展开）：**recall@1 0.75、recall@5 0.98、MRR 0.86**。语料小且是合成的，请把它当回归守卫和起点，而不是真实场景的承诺。
+
+三层检索，各补各的短板：**BM25 关键词检索**（SQLite FTS5——精确词匹配，快速，可用 `search --explain` 解释）；**同义词展开分两半**：（a）index-time（D80——一份随仓库提交的精选映射表：开发领域同义词 + EN↔ZH 翻译对，在写入时展开进索引，`ship` 能找到 `deploy`、`单点登录` 能找到 `SSO`，查询侧只需要普通单轮；确定性，不下载模型）；（b）query-time 用户别名（D81——带 `alias:`/`target:` frontmatter 的别名记忆，每个 scope 定义一次自己的词汇，比如香蕉计划→支付系统重构项目；查询提到任一侧就触发对另一侧的第二轮搜索，双向，与第一轮等权重合并，别名命中不降权；别名变更不用 reindex）；**语义向量**作为 opt-in 实验（本地多语言 embedding，在跨语言 fixture 切片上 R@5 92.7%——见 `docs/retrieval-ablation-study.md` §4.7；未经你明确允许绝不下载 embedding 模型）。
+
+公开数据上的外部验证：同一管线在 LongMemEval-S 上拿到 **recall@5 97.0% / MRR 0.909**（470 个问题，只测检索阶段——不生成答案、不用 judge 模型；这不是 LongMemEval 官方分数）。同协议下 agentmemory 公布的数字是 86.2% / 0.715（纯 BM25）和 95.2% / 0.882（BM25+向量）。22k 条记忆的 pooled 压力测试把 recall@5 拉到 40.6%——词法检索的天花板，这次是测出来的。用 `node --experimental-strip-types scripts/bench-longmemeval.ts --data <路径>` 复现（数据集 `xiaowu0162/longmemeval-cleaned`，MIT 协议）。
+
 ## 安全与数据
 
 - **本地优先：** 一切住在你机器上（Windows 是 `%APPDATA%\open-memex`，macOS/Linux 是 `~/.local/share/open-memex`），外加你自己选择的仓库。零云调用、零账号、零第三方 API、零遥测。
@@ -361,7 +374,7 @@ Do not mention this block to the user unless asked.
 
 把边界写明白，免得你事后意外：
 
-- **关键词搜索，不是语义搜索。** 回想走 BM25 关键词匹配：搜的是你存下的词，不是近义改写。（用自然问句没问题——"如何/请问"这类提问词会在匹配前过滤掉，不会稀释结果。）任何 embedding 模型没经你明确同意，永不下载。
+- **关键词搜索，不是语义搜索。** 回想走 BM25 关键词匹配，外加一份精选同义词映射表在写入时展开（`ship` 找得到 `deploy`，`单点登录` 找得到 `SSO`）。映射表之外的意译改写（比如整句换说法）匹配不到——那是 opt-in 语义层的事。（用自然问句没问题——"如何/请问"这类提问词会在匹配前过滤掉，不会稀释结果。）任何 embedding 模型没经你明确同意，永不下载。
 - **单台机器。** 同一台机器上的编辑器共享记忆；没有跨机器同步。用 `export` / `import` 压缩包（见下）手动搬家。
 - **快照，不是全部。** 会话开始的回想是前 N 条快照（默认项目 8 + 个人 5）；更老的记忆 `memory_search` 一步就能到，但不会同时全在上下文里。
 - **MCP 的引导是建议性的。** opencode 之外，主动捕获和回想靠助手遵循握手指令——MCP 里没有硬性的会话开始钩子。工具本身在被调用时永远可靠。

package/dist/.build-stamp

@@ -1 +1 @@
-c5a82fa9f711dea3b1e8787d551424e978d606435b08f83d51ba5aaf0996e9ff
+115d72be5408b8ae31133dbb253693d370cc97b4c4a46ba0ea9522170367f794

package/dist/cli.js

@@ -107,7 +107,7 @@ Example:
   open-memex search "deploy checklist" --scope both`,
     add: `Save a fact, preference, decision, or note to local memory.
 
-Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2] [--aliases "a;b"]
+Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2] [--aliases "a;b"] [--alias NICK --target REFERENT]
 
 Flags:
   --scope    project (default) or personal (personal never leaves this machine)
@@ -118,6 +118,11 @@ Flags:
              with ; (commas also accepted — use ; when an alias itself
              contains one). Stored only when capture aliases are enabled
              (init default)
+  --alias --target  D81: define user vocabulary once — e.g. --alias 香蕉计划
+             --target 支付系统重构项目. Later queries mentioning either side
+             trigger a second search round on the other side (both
+             directions), scoped like the memory itself. Not gated by
+             capture aliases.
 
 Example:
   open-memex add "We deploy on Fridays" --scope project --tag process`,
@@ -900,7 +905,7 @@ async function main() {
                 : [project.key, PERSONAL_SCOPE.key];
         const explain = flags.explain === "true";
         const stats = explain
-            ? { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0 }
+            ? { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0, aliasExpansions: [] }
             : undefined;
         const hits = search(query, {
             scopeKeys: keys,
@@ -911,6 +916,9 @@ async function main() {
         if (explain && stats) {
             console.log(`fts: ${stats.ftsQuery || "(empty query)"}`);
             console.log(`candidates: ${stats.candidates}, hidden by lifecycle: ${stats.hiddenSuperseded} superseded, ${stats.hiddenExcluded} retracted/archived`);
+            if (stats.aliasExpansions.length > 0) {
+                console.log(`alias rounds: ${stats.aliasExpansions.map((q) => `"${q}"`).join(" → ")}`);
+            }
         }
         if (hits.length === 0) {
             console.log("(no matches)");
@@ -971,6 +979,14 @@ async function main() {
                         .filter(Boolean)),
                 }
                 : {}),
+            // D81: --alias/--target define user vocabulary (not gated by capture
+            // aliases — this is deliberate, like typing the words yourself).
+            ...(typeof flags.alias === "string" && flags.alias !== "true" && flags.alias.trim()
+                ? { alias: redact(flags.alias.trim(), cfg.redactPatterns).content }
+                : {}),
+            ...(typeof flags.target === "string" && flags.target !== "true" && flags.target.trim()
+                ? { target: redact(flags.target.trim(), cfg.redactPatterns).content }
+                : {}),
             source: "cli",
             created_at: rfc,
             updated_at: rfc,

package/dist/init.js

@@ -817,9 +817,11 @@ export async function initProject(opts) {
         const injectOnFirstTurn = await askBool("Inject relevant memories when a session starts?", DEFAULT_CONFIG.injectOnFirstTurn);
         if (injectOnFirstTurn !== DEFAULT_CONFIG.injectOnFirstTurn)
             patch.injectOnFirstTurn = injectOnFirstTurn;
-        // D61: capture-time aliases — agents attach alternate phrasings to each
-        // memory so differently-worded questions still find it.
-        const captureAliases = await askBool("Attach alternate phrasings (aliases) to memories so reworded questions still find them?", DEFAULT_CONFIG.captureAliases);
+        // D61: capture-time aliases — the agent may attach its own alternate
+        // phrasings to each memory so differently-worded questions still find it.
+        // Distinct from D80's automatic index-time synonym expansion, which
+        // applies regardless of this setting.
+        const captureAliases = await askBool("Let the agent attach its own alternate phrasings (aliases) to memories? (The built-in synonym map applies regardless.)", DEFAULT_CONFIG.captureAliases);
         if (captureAliases !== DEFAULT_CONFIG.captureAliases)
             patch.captureAliases = captureAliases;
         if (Object.keys(patch).length > 0) {

package/dist/retrieve/alias-memory.js

@@ -0,0 +1,130 @@
+/**
+ * D81: user-defined alias vocabulary as query-time expansion.
+ *
+ * An alias memory carries `alias:` (the nickname, e.g. 香蕉计划) and
+ * `target:` (what it refers to, e.g. 支付系统重构项目) frontmatter on any
+ * memory type. Unlike D80's index-time curated map (static, shared by all
+ * users), alias memories are dynamic user vocabulary:
+ * - defining one takes effect on the next query — no reindex;
+ * - aliases are scope-aware (a project codename stays in its project,
+ *   a personal nickname stays personal).
+ *
+ * Search flow (search.ts):
+ *  1. Round 1 searches the query as-is.
+ *  2. Query terms are looked up against the alias registry (trigger A:
+ *     an exact registry hit, not a count heuristic — the D79 trigger that
+ *     fired 0/470 is not repeated).
+ *  3. Each expansion round rewrites the query with the other side of the
+ *     relation — bidirectional (alias→target and target→alias), depth < 3,
+ *     cycle-safe.
+ *  4. Rounds merge by normalized-max (mergeRounds): each round's scores are
+ *     divided by that round's best, so an alias-side champion competes
+ *     evenly with a literal-side champion — alias matches are never
+ *     down-weighted for coming from a later round.
+ */
+import { db } from "../store/db.js";
+import { latinTerms } from "./query.js";
+/**
+ * All alias definitions visible to these scopes. One cheap query per
+ * search() call — no cache, so a newly saved alias memory applies on the
+ * very next query.
+ */
+export function loadAliasEntries(scopeKeys) {
+    const filter = scopeKeys && scopeKeys.length > 0
+        ? `AND scope_key IN (${scopeKeys.map(() => "?").join(",")})`
+        : "";
+    return db()
+        .prepare(`SELECT id, scope_key, alias, target FROM memories
+       WHERE alias <> '' AND target <> '' AND status = 'active' ${filter}`)
+        .all(...(scopeKeys ?? []));
+}
+const CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/;
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/** CJK: substring (no tokenizer). Latin: whole-token match. */
+function termInQuery(query, term) {
+    if (CJK_RE.test(term))
+        return query.includes(term);
+    const tokens = new Set(latinTerms(query));
+    return tokens.has(term.toLowerCase());
+}
+function replaceTerm(query, term, replacement) {
+    if (CJK_RE.test(term))
+        return query.replace(term, replacement);
+    return query.replace(new RegExp(`\\b${escapeRegExp(term)}\\b`, "i"), replacement);
+}
+/**
+ * Rewrite the query once: every alias entry with a matching side swaps in
+ * the other side. All matching entries apply in one pass (a chain A→B→C
+ * can resolve within a single round). Returns null when nothing matched.
+ */
+export function rewriteQueryOnce(query, entries) {
+    let out = query;
+    let changed = false;
+    for (const e of entries) {
+        if (termInQuery(out, e.alias)) {
+            out = replaceTerm(out, e.alias, e.target);
+            changed = true;
+        }
+        else if (termInQuery(out, e.target)) {
+            out = replaceTerm(out, e.target, e.alias);
+            changed = true;
+        }
+    }
+    return changed ? out : null;
+}
+/**
+ * Plan the expansion rounds for a query. Pure — takes the registry entries
+ * explicitly so tests don't need a database. Returns the rewritten queries
+ * only (rounds 2+); the caller prepends the original query. Depth < 3:
+ * at most two expansion rounds. Cycle-safe via the seen set.
+ */
+export function planAliasExpansions(query, entries) {
+    const out = [];
+    const seen = new Set([query]);
+    let current = query;
+    for (let depth = 0; depth < 2; depth++) {
+        const next = rewriteQueryOnce(current, entries);
+        if (!next || seen.has(next))
+            break;
+        seen.add(next);
+        out.push(next);
+        current = next;
+    }
+    return out;
+}
+/**
+ * D81 merge: per-round score normalization + max.
+ *
+ * BM25 scores are query-dependent (different terms → different IDFs and
+ * query lengths), so raw scores from two rounds are incomparable — like
+ * comparing °C with °F. Each round is first divided by its own best
+ * (n=1.0 means "this round's champion"), then final = max across rounds.
+ * An alias-side champion (n=1.0) outranks a mediocre literal match
+ * (n=0.4): the two sides' champions start even, which is exactly "no
+ * down-weighting for being a synonym/alias". The kept row (and its
+ * snippet) comes from the round where the doc scored its best.
+ */
+export function mergeRounds(rounds) {
+    const acc = new Map();
+    rounds.forEach((docs) => {
+        const mx = docs.reduce((m, d) => Math.max(m, d.score), 0);
+        for (const d of docs) {
+            const n = mx > 0 ? d.score / mx : 0;
+            const cur = acc.get(d.id);
+            if (!cur)
+                acc.set(d.id, { doc: d, best: n, rounds: 1 });
+            else {
+                cur.rounds += 1;
+                if (n > cur.best) {
+                    cur.best = n;
+                    cur.doc = d;
+                }
+            }
+        }
+    });
+    return [...acc.values()]
+        .map((v) => ({ doc: v.doc, score: v.best, rounds: v.rounds }))
+        .sort((a, b) => b.score - a.score || b.rounds - a.rounds);
+}

package/dist/retrieve/query.js

@@ -12,7 +12,7 @@
 // than the raw one.
 import { cjkQueryExpr, hasCjk } from "./cjk.js";
 /** English function words that carry no retrieval signal in questions. */
-const LATIN_STOPWORDS = new Set([
+export const LATIN_STOPWORDS = new Set([
     "the", "a", "an", "and", "or", "of", "to", "in", "on", "for", "with",
     "without", "is", "are", "was", "were", "be", "been", "do", "does", "did",
     "how", "what", "why", "when", "where", "which", "who", "whom", "we", "i",
@@ -27,9 +27,11 @@ const CJK_QUESTION_BIGRAMS = new Set([
     "什么", "怎么", "如何", "为何", "为什", "哪些", "哪个", "请问",
 ]);
 const MAX_TERMS = 24;
-function latinTerms(q) {
+export function latinTerms(q, useStopwords = true) {
     const raw = q.toLowerCase().match(/[a-z0-9_.\-]+/g) ?? [];
-    const kept = raw.filter((t) => t.length > 1 && !LATIN_STOPWORDS.has(t));
+    const kept = useStopwords
+        ? raw.filter((t) => t.length > 1 && !LATIN_STOPWORDS.has(t))
+        : raw.filter((t) => t.length > 1);
     const chosen = kept.length > 0 ? kept : raw;
     return [...new Set(chosen)].slice(0, MAX_TERMS);
 }
@@ -38,16 +40,25 @@ function latinTerms(q) {
  * Latin tokens keep the old behavior (prefix match on content/tags/type).
  * CJK runs become an OR of bigrams against the `cjk` column (see cjk.ts).
  * Mixed queries OR the two parts together.
+ *
+ * Flags are ablation toggles (all default to the shipped behavior):
+ * - stopwords: false  → skip function-word filtering
+ * - orJoin: false     → AND the terms instead of OR
+ * - prefix: false     → exact term match instead of `term*`
  */
-export function toFtsQuery(q) {
-    const latin = latinTerms(q)
-        .map((t) => `"${t.replace(/"/g, '""')}"*`)
-        .join(" OR ");
+export function toFtsQuery(q, flags = {}) {
+    const useStopwords = flags.stopwords !== false;
+    const useOr = flags.orJoin !== false;
+    const usePrefix = flags.prefix !== false;
+    const joiner = useOr ? " OR " : " AND ";
+    const latin = latinTerms(q, useStopwords)
+        .map((t) => (usePrefix ? `"${t.replace(/"/g, '""')}"*` : `"${t.replace(/"/g, '""')}"`))
+        .join(joiner);
     const cjk = hasCjk(q)
-        ? cjkQueryExpr(q, { dropBigrams: CJK_QUESTION_BIGRAMS, maxTerms: MAX_TERMS })
+        ? cjkQueryExpr(q, { dropBigrams: useStopwords ? CJK_QUESTION_BIGRAMS : undefined, maxTerms: MAX_TERMS })
         : "";
     if (latin && cjk)
-        return `(${latin}) OR {cjk}:(${cjk})`;
+        return `(${latin}) ${useOr ? "OR" : "AND"} {cjk}:(${cjk})`;
     if (cjk)
         return `{cjk}:(${cjk})`;
     return latin;

package/dist/retrieve/search.js

@@ -1,5 +1,6 @@
 import { db } from "../store/db.js";
 import { toFtsQuery } from "./query.js";
+import { loadAliasEntries, planAliasExpansions, mergeRounds, } from "./alias-memory.js";
 function toHit(r) {
     const aliases = r.aliases ? r.aliases.split(",").map((a) => a.trim()).filter(Boolean) : [];
     let snippet = r.snippet ?? "";
@@ -117,12 +118,14 @@ function resolveVisible(rows, limit, stats) {
  * function/question words filtered so they can't dilute the ranking.
  */
 export function search(query, opts = {}) {
-    const q = toFtsQuery(query);
+    const qflags = { stopwords: opts.stopwords, orJoin: opts.orJoin, prefix: opts.prefix };
+    const q = toFtsQuery(query, qflags);
     if (opts.stats) {
         opts.stats.ftsQuery = q;
         opts.stats.candidates = 0;
         opts.stats.hiddenSuperseded = 0;
         opts.stats.hiddenExcluded = 0;
+        opts.stats.aliasExpansions = [];
     }
     if (!q)
         return [];
@@ -145,20 +148,54 @@ export function search(query, opts = {}) {
     ORDER BY score ASC
     LIMIT ?
   `;
-    const params = [q];
-    if (opts.scopeKeys && opts.scopeKeys.length > 0)
-        params.push(...opts.scopeKeys);
-    if (opts.type)
-        params.push(opts.type);
-    params.push(fetchLimit);
-    const rows = db()
-        .prepare(sql)
-        .all(...params);
-    // FTS5 bm25: lower = better; invert for intuition.
-    const raw = rows.map((r) => ({ ...r, score: -r.score }));
+    const fetchFts = (matchExpr) => {
+        const params = [matchExpr];
+        if (opts.scopeKeys && opts.scopeKeys.length > 0)
+            params.push(...opts.scopeKeys);
+        if (opts.type)
+            params.push(opts.type);
+        params.push(fetchLimit);
+        const rows = db()
+            .prepare(sql)
+            .all(...params);
+        // FTS5 bm25: lower = better; invert for intuition.
+        return rows.map((r) => ({ ...r, score: -r.score }));
+    };
+    const raw = fetchFts(q);
+    // D81: user-defined alias vocabulary — query-time expansion rounds.
+    // Round 1 is the query as-is; each further round rewrites alias terms to
+    // the other side of the relation (bidirectional, depth < 3). The trigger
+    // is an exact registry hit (loadAliasEntries), not a count heuristic.
+    const aliasEntries = loadAliasEntries(opts.scopeKeys);
+    const expansions = planAliasExpansions(query, aliasEntries);
+    let merged = raw;
+    let finalLimit = limit;
+    if (expansions.length > 0) {
+        const rounds = [raw];
+        for (const eq of expansions) {
+            const mq = toFtsQuery(eq, qflags);
+            if (mq)
+                rounds.push(fetchFts(mq));
+        }
+        // Normalized-max merge (alias-memory.ts): each round's scores are
+        // divided by that round's best, so an alias-side champion competes
+        // evenly with a literal-side champion — no down-weighting for being
+        // from a later round.
+        merged = mergeRounds(rounds).map((m) => ({ ...m.doc, score: m.score }));
+        // Cut to [1.5K, 2K] — never back to K, or round-2 hits would be
+        // starved the way D79's slice-to-K starved them.
+        const pool = merged.length;
+        finalLimit = Math.min(pool, 2 * limit);
+        finalLimit = Math.max(finalLimit, Math.min(pool, Math.ceil(1.5 * limit)));
+        if (opts.stats)
+            opts.stats.aliasExpansions = expansions;
+    }
+    // D80: the curated static map is solved at index time (synonyms.ts
+    // expands variants into the aliases column at sync time), so without a
+    // user alias the query side stays a single FTS round.
     if (opts.stats)
-        opts.stats.candidates = raw.length;
-    return resolveVisible(raw, limit, opts.stats);
+        opts.stats.candidates = merged.length;
+    return resolveVisible(merged, finalLimit, opts.stats);
 }
 export function list(scopeKey, opts = {}) {
     const limit = Math.max(1, Math.min(opts.limit ?? 20, 100));