open-memex 0.8.0-alpha.2 → 0.8.0

package/AGENTS.md

@@ -144,8 +144,9 @@ Every write path (tool, keyword hook, CLI `add`) must:
 
 Capture-time aliases (D61): `memory_add`/`supersede` may carry up to 4
 `aliases` (alternate phrasings) into frontmatter; they index in their own FTS
-column. Only when `cfg.captureAliases` is on (init asks once, default on) —
-when off, passed aliases are dropped. Always pass them through
+column. Always on since 2026-10-07 (Stone: init no longer asks) —
+`cfg.captureAliases` still gates them for backward compatibility with
+installs that set it manually, but new installs never see the question. Always pass them through
 `normalizeAliases`; the keyword-capture path (no agent in the loop) never
 invents aliases. Checkpoint-proposal guidance (propose, never auto-draft) is
 copy, not mechanism: keep the rubric wording in sync across the skill, the
@@ -205,8 +206,11 @@ breaking v1→v2 transition) shipped with 0.3.0. Full rules: `CONTRIBUTING.md`.
   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,10 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-10-07
+
+- 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 removes the init `captureAliases` and keyword-capture questions — both are now always on (Stone 2026-10-07).
+
 - 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.

package/README.md

@@ -406,8 +406,19 @@ Three ways memories get in:
 **Aliases.** Each saved memory can carry up to 4 alternate phrasings
 (synonyms, another language's equivalent) that are indexed with it, so a
 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`.
+holiday policy. Always on — the agent may attach up to 4 per memory, and you
+can pass your own via `open-memex add --aliases`.
+
+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
@@ -523,20 +534,28 @@ 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:
-51 memories + 41 queries (exact terms, paraphrases, synonyms, Chinese,
-cross-language hard cases, and synonym-only queries) — reproduce with
+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):
-**recall@1 0.76, recall@5 0.98, MRR 0.86**.
+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`);
-**index-time synonym/translation expansion** (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); and **semantic vectors**
+**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).
@@ -572,11 +591,13 @@ asserted. Reproduce with
 
 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

@@ -263,7 +263,11 @@ open-memex uninstall --yes
 - **检查点提议**：一个任务收尾时，助手会提议 1–3 条从这轮工作里提炼的候选记忆——决定及其理由、约定、踩过的坑、走过又放弃的路——只有你点头的那几条才存。不会有任何东西在你不知情时被写下来。
 - **CLI**：`open-memex add "…"`，可选 `--scope` / `--tag` / `--type` / `--aliases`。
 
-**别名。** 每条记忆可以带最多 4 个换一种说法（同义词、另一种语言的对应词），和记忆一起进索引，这样问法不同也能找到——比如搜 "vacation days" 能找到假期政策那条。`init` 时会问一次是否开启（默认开）；随时可用 `open-memex config set captureAliases false` 关掉。
+**别名。** 每条记忆可以带最多 4 个换一种说法（同义词、另一种语言的对应词），和记忆一起进索引，这样问法不同也能找到——比如搜 "vacation days" 能找到假期政策那条。永远开启：agent 每条记忆最多可附 4 个，你也可以用 `open-memex add --aliases` 自己加。
+
+三种加法：`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），其余替换——记忆仍会保存。随时安全地预览一句话会被捕获成什么样：
 
@@ -352,9 +356,9 @@ Do not mention this block to the user unless asked.
 
 ### 检索效果评估
 
-我们用一份随仓库提交的 synthetic fixture 来度量召回率，而不是空口断言：51 条记忆 + 41 个查询（精确词、改写、同义词、中文、跨语言 hard case、纯同义词查询），运行 `node --experimental-strip-types scripts/retrieval-eval.ts` 即可复现。当前基线（含 D80 的 index-time 同义词/翻译展开）：**recall@1 0.76、recall@5 0.98、MRR 0.86**。语料小且是合成的，请把它当回归守卫和起点，而不是真实场景的承诺。
+我们用一份随仓库提交的 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` 解释）；**index-time 同义词/翻译展开**（D80——一份随仓库提交的精选映射表：开发领域同义词 + EN↔ZH 翻译对，在写入时展开进索引，`ship` 能找到 `deploy`、`单点登录` 能找到 `SSO`，查询侧只需要普通单轮；确定性，不下载模型）；**语义向量**作为 opt-in 实验（本地多语言 embedding，在跨语言 fixture 切片上 R@5 92.7%——见 `docs/retrieval-ablation-study.md` §4.7；未经你明确允许绝不下载 embedding 模型）。
+三层检索，各补各的短板：**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 协议）。
 
@@ -370,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 @@
-9f341cad8c580b840308fbdb525de70a108bc40aa372f47c4b248baa67ab14f8
+55d6d5c601b1769ad9c4813aebefcb25ee3b29cab0c6c30f8450d9388fe83a6a

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)
@@ -116,8 +116,12 @@ Flags:
   --aliases  alternate phrasings of this fact (up to 4), indexed with the
              memory so differently-worded searches still match; separate
              with ; (commas also accepted — use ; when an alias itself
-             contains one). Stored only when capture aliases are enabled
-             (init default)
+             contains one). Always on.
+  --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 +904,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 +915,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 +978,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

@@ -811,17 +811,17 @@ export async function initProject(opts) {
         // Install-time settings (D19). Non-default answers persist to the JSONC
         // config file; `open-memex config set` changes them later.
         const patch = {};
-        const keywordCaptureEnabled = await askBool("Auto-capture keywords like remember… / note that… into memory?", DEFAULT_CONFIG.keywordCaptureEnabled);
-        if (keywordCaptureEnabled !== DEFAULT_CONFIG.keywordCaptureEnabled)
-            patch.keywordCaptureEnabled = keywordCaptureEnabled;
+        // Keyword auto-capture is always on (Stone 2026-10-07): no init
+        // question — there is no reason to turn it off. The
+        // `keywordCaptureEnabled` config key is still honored if set manually.
         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);
-        if (captureAliases !== DEFAULT_CONFIG.captureAliases)
-            patch.captureAliases = captureAliases;
+        // D61 capture-time aliases are always on (Stone 2026-10-07): the agent
+        // may always attach its own alternate phrasings — no init question.
+        // (Distinct from D80's automatic index-time synonym expansion, which
+        // also always applies.) The `captureAliases` config key is still
+        // honored if someone sets it manually; init just never asks anymore.
         if (Object.keys(patch).length > 0) {
             const file = saveConfig(patch);
             console.log(`  + settings saved to ${file} (change later with \`open-memex config set <key> <value>\`)`);

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

@@ -27,7 +27,7 @@ const CJK_QUESTION_BIGRAMS = new Set([
     "什么", "怎么", "如何", "为何", "为什", "哪些", "哪个", "请问",
 ]);
 const MAX_TERMS = 24;
-function latinTerms(q, useStopwords = true) {
+export function latinTerms(q, useStopwords = true) {
     const raw = q.toLowerCase().match(/[a-z0-9_.\-]+/g) ?? [];
     const kept = useStopwords
         ? raw.filter((t) => t.length > 1 && !LATIN_STOPWORDS.has(t))

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 ?? "";
@@ -124,6 +125,7 @@ export function search(query, opts = {}) {
         opts.stats.candidates = 0;
         opts.stats.hiddenSuperseded = 0;
         opts.stats.hiddenExcluded = 0;
+        opts.stats.aliasExpansions = [];
     }
     if (!q)
         return [];
@@ -160,12 +162,40 @@ export function search(query, opts = {}) {
         return rows.map((r) => ({ ...r, score: -r.score }));
     };
     const raw = fetchFts(q);
-    // D80: vocabulary mismatch is solved at index time (synonyms.ts expands
-    // curated variants into the aliases column at sync time), so the query
-    // side is a single FTS round — no trigger, no second chance.
+    // 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));

package/dist/store/db.js

@@ -35,6 +35,8 @@ CREATE TABLE IF NOT EXISTS memories (
   status       TEXT NOT NULL DEFAULT 'active',
   tags         TEXT NOT NULL DEFAULT '',
   aliases      TEXT NOT NULL DEFAULT '',
+  alias        TEXT NOT NULL DEFAULT '',
+  target       TEXT NOT NULL DEFAULT '',
   content      TEXT NOT NULL,
   cjk          TEXT NOT NULL DEFAULT '',
   content_hash TEXT NOT NULL DEFAULT '',
@@ -88,7 +90,7 @@ CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
 END;
 `;
 /** Current index schema version. Bump when TABLE_SCHEMA/FTS_SCHEMA change. */
-const SCHEMA_VERSION = 7;
+const SCHEMA_VERSION = 8;
 function userVersion(d) {
     const row = d.prepare("PRAGMA user_version").get();
     return row.user_version;

package/dist/store/lifecycle.js

@@ -215,6 +215,9 @@ export function supersede(oldId, input) {
         tags: input.tags ?? oldMf.fm.tags,
         // D61: aliases carry forward unless the caller replaces them.
         aliases: input.aliases ?? oldMf.fm.aliases,
+        // D81: alias vocabulary carries forward the same way.
+        alias: input.alias ?? oldMf.fm.alias,
+        target: input.target ?? oldMf.fm.target,
         source: input.source ?? oldMf.fm.source,
         status: "active",
         created_at: now,

package/dist/store/markdown.js

@@ -161,6 +161,13 @@ export function normalizeFrontmatter(raw) {
                 return aliases.length > 0 ? { aliases } : {};
             })()
             : {}),
+        // D81: alias vocabulary — single trimmed strings, dropped when empty.
+        ...(typeof raw.alias === "string" && raw.alias.trim()
+            ? { alias: raw.alias.trim() }
+            : {}),
+        ...(typeof raw.target === "string" && raw.target.trim()
+            ? { target: raw.target.trim() }
+            : {}),
         source: typeof raw.source === "string" ? raw.source : "",
         created_at: msToRfc3339(timeToMs(raw.created_at)),
         updated_at: msToRfc3339(timeToMs(raw.updated_at)),

package/dist/store/sync.js

@@ -8,8 +8,8 @@ import { iterMemoryFiles, iterInRepoMemoryFiles, readMemoryFile, timeToMs, } fro
 import { projectRoot, paths } from "../paths.js";
 import { loadConfig } from "../config.js";
 const UPSERT_SQL = `
-  INSERT INTO memories (id, scope_key, scope, visibility, project_name, type, role, importance, status, tags, aliases, content, cjk, content_hash, superseded_by, source, file_path, mtime_ms, created_at, updated_at, review_state)
-  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  INSERT INTO memories (id, scope_key, scope, visibility, project_name, type, role, importance, status, tags, aliases, alias, target, content, cjk, content_hash, superseded_by, source, file_path, mtime_ms, created_at, updated_at, review_state)
+  VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   ON CONFLICT(id) DO UPDATE SET
     scope_key    = excluded.scope_key,
     scope        = excluded.scope,
@@ -21,6 +21,8 @@ const UPSERT_SQL = `
     status       = excluded.status,
     tags         = excluded.tags,
     aliases      = excluded.aliases,
+    alias        = excluded.alias,
+    target       = excluded.target,
     content      = excluded.content,
     cjk          = excluded.cjk,
     content_hash = excluded.content_hash,
@@ -63,7 +65,8 @@ function writeRow(mf, mtimeMs) {
     const have = new Set(supplied.map((a) => a.toLowerCase()));
     const auto = expansionVariantsForDoc(body + "\n" + tags).filter((a) => !have.has(a.toLowerCase()));
     const aliases = [...supplied, ...auto].join(",");
-    db().prepare(UPSERT_SQL).run(fm.id, fm.scope_key, fm.scope, fm.visibility, fm.project_name, fm.type, fm.role, fm.importance, fm.status, tags, aliases, body, cjkIndexText(body + "\n" + tags + "\n" + aliases), contentHash(body), fm.superseded_by ?? null, fm.source ?? "", filePath, mtimeMs, timeToMs(fm.created_at), timeToMs(fm.updated_at), fm.review_state ?? "draft");
+    // D81: user-defined alias vocabulary (single nickname → referent pair).
+    db().prepare(UPSERT_SQL).run(fm.id, fm.scope_key, fm.scope, fm.visibility, fm.project_name, fm.type, fm.role, fm.importance, fm.status, tags, aliases, fm.alias ?? "", fm.target ?? "", body, cjkIndexText(body + "\n" + tags + "\n" + aliases), contentHash(body), fm.superseded_by ?? null, fm.source ?? "", filePath, mtimeMs, timeToMs(fm.created_at), timeToMs(fm.updated_at), fm.review_state ?? "draft");
 }
 export function deleteFromIndex(id) {
     db().prepare(`DELETE FROM memories WHERE id = ?`).run(id);

package/dist/tools/ops.js

@@ -58,7 +58,7 @@ export const scopeArg = z
 export const aliasesArg = z
     .array(z.string())
     .optional()
-    .describe("Optional: alternate phrasings of this fact — synonyms, another way a question might be worded, equivalents in the user's other language (e.g. 节假日 for 'public holidays'). They are indexed with the memory so differently-worded questions still match. Only used when the install has capture aliases enabled (init default). Send at most 4; extras and blanks are dropped silently, never an error.");
+    .describe("Optional: alternate phrasings of this fact — synonyms, another way a question might be worded, equivalents in the user's other language (e.g. 节假日 for 'public holidays'). They are indexed with the memory so differently-worded questions still match. Always on. Send at most 4; extras and blanks are dropped silently, never an error.");
 export const memoryAddArgs = {
     content: z.string().min(1).describe("The fact to remember. One idea per memory."),
     type: z
@@ -68,6 +68,14 @@ export const memoryAddArgs = {
     scope: scopeArg,
     tags: z.array(z.string()).optional().describe("Optional tags for filtering."),
     aliases: aliasesArg,
+    alias: z
+        .string()
+        .optional()
+        .describe("D81: nickname this memory defines (e.g. 香蕉计划). Pairs with `target`: the alias memory expands queries in its scope at search time, both directions, no reindex. Explicit vocabulary — always stored, not gated by capture aliases."),
+    target: z
+        .string()
+        .optional()
+        .describe("D81: what `alias` refers to (e.g. 支付系统重构项目). Only meaningful with `alias`."),
     source: z
         .string()
         .optional()
@@ -106,6 +114,14 @@ export const memorySupersedeArgs = {
         .describe("Category of the new memory. Defaults to the old memory's type."),
     tags: z.array(z.string()).optional().describe("Optional tags for the new memory."),
     aliases: aliasesArg,
+    alias: z
+        .string()
+        .optional()
+        .describe("D81: nickname the new memory defines (e.g. 香蕉计划). Omitted = inherit the old memory's alias."),
+    target: z
+        .string()
+        .optional()
+        .describe("D81: what `alias` refers to (e.g. 支付系统重构项目). Omitted = inherit."),
 };
 export const memoryForgetArgs = {
     id: z.string().min(1),
@@ -170,6 +186,11 @@ function buildFrontmatter(s, body) {
         status: "active",
         tags: body.tags,
         ...(body.aliases && body.aliases.length > 0 ? { aliases: body.aliases } : {}),
+        // D81: explicit alias vocabulary — single trimmed strings, dropped
+        // when empty. Not gated by captureAliases (that gates agent-invented
+        // phrasings; this is deliberate vocabulary).
+        ...(body.alias?.trim() ? { alias: body.alias.trim() } : {}),
+        ...(body.target?.trim() ? { target: body.target.trim() } : {}),
         source: body.source,
         created_at: rfc,
         updated_at: rfc,
@@ -221,13 +242,21 @@ export async function addMemory(getScope, cfg, args) {
     const fm = buildFrontmatter(s, {
         type: args.type ?? "fact",
         tags: args.tags ?? [],
-        // D61: aliases are stored only when the install enables them (init
-        // asks once, default on); normalize caps at 4 and drops junk silently.
+        // D61: aliases are always stored (Stone 2026-10-07: init no longer asks;
+        // default on). Normalize caps at 4 and drops junk silently.
         // Aliases pass through the same redaction as content (write-path
         // invariant) — an alias carrying a token gets masked, not stored raw.
         aliases: cfg.captureAliases
             ? normalizeAliases((args.aliases ?? []).map((a) => redact(a, cfg.redactPatterns).content))
             : [],
+        // D81: explicit alias vocabulary — same redaction as content, never
+        // gated by captureAliases.
+        alias: args.alias?.trim()
+            ? redact(args.alias.trim(), cfg.redactPatterns).content
+            : undefined,
+        target: args.target?.trim()
+            ? redact(args.target.trim(), cfg.redactPatterns).content
+            : undefined,
         source: args.source ?? "tool",
     });
     const { filePath } = writeMemoryFile(fm, redacted);
@@ -322,6 +351,14 @@ export async function supersedeMemory(cfg, args) {
             aliases: cfg.captureAliases && args.aliases !== undefined
                 ? normalizeAliases(args.aliases.map((a) => redact(a, cfg.redactPatterns).content))
                 : undefined,
+            // D81: explicit alias vocabulary — omitted inherits the old memory's
+            // pair; same redaction as content; never gated by captureAliases.
+            alias: args.alias !== undefined
+                ? redact(args.alias, cfg.redactPatterns).content || undefined
+                : undefined,
+            target: args.target !== undefined
+                ? redact(args.target, cfg.redactPatterns).content || undefined
+                : undefined,
             source: "tool",
         });
         upsertFromFile(oldMf);