open-memex 0.8.0-alpha.2 → 0.8.0-alpha.3

package/AGENTS.md

@@ -205,8 +205,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,8 @@ 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.

package/README.md

@@ -409,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
@@ -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

@@ -265,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
@@ -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
+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

@@ -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

@@ -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,
@@ -228,6 +249,14 @@ export async function addMemory(getScope, cfg, args) {
         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);

package/docs/V2-DESIGN.md

@@ -1602,6 +1602,8 @@ requirement: personal data never touches third-party services). Benchmarks to tr
 
 - **D79 — query-time synonym expansion with a second-chance round (2026-10-07).** Fourth retrieval layer after D56 (query construction) and D61 (agent-side expansion guidance, capture-time aliases): a curated, checked-in synonym map (`src/retrieve/synonyms.ts` — EN dev-domain groups plus ZH groups, bidirectional) applied at query time. `search()` runs round one unchanged; when it returns fewer candidates than requested, round two re-runs with synonym variants OR-ed in and fills only the gaps — round-one ids and scores are never diluted by the expansion. Deliberately not embeddings and not an LLM call: deterministic, auditable, zero dependencies; a bad synonym is a visible line in the file, not a silent vector. `SearchStats.secondRound` records whether the round ran (surfaced in `search --explain`). Eval proof: 3 synonym-only fixture queries are unanswerable in round one by construction (their words appear in no memory); round two answers 2 of 3 at rank –2. Baseline with the round: recall@1 0.81, recall@5 0.95, MRR 0.87 over 37 queries. Follow-ups, not in this change: feedback-weighted ranking once D77 counters land; the embeddings gate decision against these numbers; reranker evaluation. **Update (2026-10-07, LongMemEval-S):** measured on 470 questions (recall_any@k protocol, per-question isolated corpora): R@1 86.0% / R@5 97.0% / R@10 98.3% / MRR 0.909 — ahead of agentmemory’s published BM25-only (86.2% / 94.6% / 0.715) and level with their BM25+vector (95.2% / 98.6% / 0.882). But the second round fired on **0 of 470** queries: the `raw.length < limit` trigger never trips once the corpus fills the page — the round as designed is a thin-corpus fallback, not a scale answer. A pooled 22k-memory stress run drops R@5 to 40.6% (the lexical ceiling, now measured instead of asserted). Consequence: the trigger needs a redesign (score/coverage-based, or always-expand-with-fusion) before the round can claim the scale story; the pooled number is the baseline an embedding layer must beat. **Ablation (2026-10-07, same bench):** OFAT over the lexical factors, limit=10, effect on MRR: OR semantics **+0.652** (AND collapses to 0.257 — the load-bearing wall); prefix matching **-0.010** (disabling it lifts R@1 86.0%→87.9% — mildly harmful, needs a second dataset before acting); stopword filtering **+0.005** (keep: cheap, principled); synonym round **0.000** at every limit and scale tested. Limit sweep: R@1 is invariant to limit (86.0% at 1–50); returns flatten at limit 5 (R@5 97.0%, +1.3pp to go to 50); round-2 fired 10/470 at limit=50 and rescued nothing (identical to no-synonyms). Pooled 22k at limit=50: R@5 still 40.6%, round-2 fired 0. Reading: the lexical lemon is squeezed — OR does the work, the rest is ±0.01. The next gains must come from ranking under distractors (embedding/reranker layer), not more lexical tweaks. Rescue experiment (same day): fallback-append vs always-expand+RRF-fusion, 470q, stratified by query–gold overlap — **zero rescues** under either design, at either scale; not one question changes outcome. The 8 residual misses are reasoning problems (preference/multi-hop/temporal), not vocabulary gaps. The round’s value lives in a mismatch slice the public data barely contains (proven on constructed queries: 2 of 3 rescued). Keep the curated map; stop spending design budget on the trigger. (Superseded same day: index-time expansion, see backlog.)
 - **D80 — index-time synonym/translation expansion (2026-10-07).** Supersedes D79's query-time second round (removed from `search()`; `SearchStats.secondRound` gone): the curated map (`src/retrieve/synonyms.ts` — EN dev-domain groups, ZH groups and EN↔ZH translation pairs merged into one bidirectional group list) is applied at sync/index time. `writeRow` expands each memory's keywords via `expansionVariantsForDoc()` and appends the variants to the indexed `aliases` column (FTS and CJK-bigram columns both pick them up), so any related word matches in a plain round-1 query. Query side: single FTS round, no trigger, no second chance. Keyword-centric per Stone ("重要的是关键词"): Latin content terms (same stopword filter as the query builder, so both sides agree on what a keyword is) + CJK substring matching + multi-word Latin phrases (`regression test`); variants already present in the text are skipped; capped at 32 per memory to bound index growth. Derived at sync time — the Markdown file stays the source of truth; a map update needs a reindex to backfill. *Rationale: the precise slice (exact EN↔ZH pairs like 单点登录/SSO) must never be missed, and embeddings are fuzzy where the map is exact; paying the cost once at write time keeps every query simple and trigger-free.* Eval on the 41-query cross-lingual fixture: 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. Known trade-off: a single-keyword query can rank an aliases-only hit below shorter docs sharing the variant (`how do we ship`: rank 2 → 8 — its hit is 1 of 15 variants on a long aliases field); accepted, the old rank depended on the fragile thin-corpus trigger. `expandQueryWithSynonyms` kept as a bench-only export.
+- **D81 — user-defined alias vocabulary as query-time expansion (2026-10-07).** Stone: an alias should be a *kind of memory* — defined once, remembered forever. Any memory type may carry `alias:` (the nickname, e.g. 香蕉计划) and `target:` (what it refers to, e.g. 支付系统重构项目) frontmatter; the alias memory defines vocabulary once per scope. At query time (`src/retrieve/alias-memory.ts`), query terms are looked up against the alias registry — one cheap `SELECT` per `search()` call over rows with non-empty alias+target (trigger A: exact registry hit, never a count heuristic; the D79 0/470 trigger is not repeated). On a hit the query is rewritten with the other side of the relation — bidirectional (alias→target and target→alias), depth < 3, cycle-safe — and re-run as round 2 (round 3 for chains). Rounds merge by normalized-max (`mergeRounds`): each round's BM25 scores are divided by that round's best (raw cross-round scores are incomparable — °C vs °F), then final = max, so an alias-side champion competes evenly with a literal-side champion — alias hits are never down-weighted for coming from a later round. Merged pool is re-ranked then cut to [1.5K, 2K] (Stone) — never back to K, or round-2 hits would be starved the way D79's slice-to-K starved them. No reindex when an alias changes (query-time). Scope-aware: a project codename stays in its project. *Rationale: D80's curated map is static and shared — personal vocabulary (小宝贝, 香蕉计划) doesn't belong in it; per-memory D61 aliases don't propagate to new memories. Alias memories close the gap: user-defined, scope-aware, effective immediately.* v1: user-explicit creation only (`memory_add` alias/target params, CLI `--alias`/`--target`, frontmatter edit); agent-proposed aliases deferred. D81 also rewords the init `captureAliases` prompt (it is not the synonym switch — D80's expansion always applies). Eval: 3 new fixture queries (香蕉计划↔支付系统重构项目 both directions + the alias memory itself), 44 queries total: recall@1 0.750, recall@5 **0.977** (43/44), MRR 0.857 — the single miss remains `how do we ship` (known D80 trade-off).
+
 
 ## Open Questions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.8.0-alpha.2",
+  "version": "0.8.0-alpha.3",
   "mcpName": "io.github.stoneskin/open-memex",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "keywords": [

package/scripts/bench-longmemeval.ts

@@ -147,7 +147,7 @@ function rankOf(
   q: LMEItem,
   isGold: (id: string) => boolean,
 ): number {
-  const stats = { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0 };
+  const stats = { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0, aliasExpansions: [] as string[] };
   const hits = search(q.question, {
     scopeKeys: ["personal"],
     limit: K,

package/scripts/retrieval-eval/fixture.ts

@@ -1,11 +1,13 @@
 /**
  * Synthetic retrieval-eval fixture (D77).
  *
- * 48 personal-scope memories + 36 queries with gold ids. Written BEFORE
+ * 54 personal-scope memories + 44 queries with gold ids. Written BEFORE
  * running the eval — the fixture is the test, not tuned to the results.
  * All memories share one scope/tier so the measured ranking is pure BM25.
  * Mixed EN/ZH; includes paraphrase and synonym queries (the hard cases
- * from the retrieval-robustness question) and near-duplicate distractors.
+ * from the retrieval-robustness question), near-duplicate distractors,
+ * and D81 user-defined alias vocabulary (bidirectional query-time
+ * expansion: 香蕉计划 ↔ 支付系统重构项目).
  */
 
 export interface FixtureMemory {
@@ -13,6 +15,9 @@ export interface FixtureMemory {
   type: string;
   tags: string[];
   aliases?: string[];
+  /** D81: user-defined alias vocabulary (nickname → referent). */
+  alias?: string;
+  target?: string;
   body: string;
 }
 
@@ -103,6 +108,11 @@ export const MEMORIES: FixtureMemory[] = [
   { id: "mem-049", type: "fact", tags: ["备份", "数据库"], body: "数据库备份每天凌晨两点执行，全量保留三十天，恢复演练每个季度做一次。" },
   { id: "mem-050", type: "decision", tags: ["发布", "测试"], body: "上线前必须跑完全量回归测试，测试报告要贴到发布群里，TL 确认后才能发。" },
   { id: "mem-051", type: "gotcha", tags: ["staging"], body: "The staging environment wipes itself every night at midnight. Never leave test data there overnight — it will be gone by morning." },
+
+  // ---- D81 user-defined alias vocabulary (query-time expansion) ----
+  { id: "mem-052", type: "fact", tags: ["alias"], alias: "香蕉计划", target: "支付系统重构项目", body: "香蕉计划是支付系统重构项目的内部代号，团队日常用香蕉计划指代这个项目。" },
+  { id: "mem-053", type: "decision", tags: ["backend"], body: "支付系统重构项目决定用 Go 重写网关层，Q4 启动。" },
+  { id: "mem-054", type: "fact", tags: ["planning"], body: "香蕉计划下周一启动评审，材料周五前提交。" },
 ];
 
 export const QUERIES: FixtureQuery[] = [
@@ -164,4 +174,9 @@ export const QUERIES: FixtureQuery[] = [
   { query: "how do we ship", gold: ["mem-001"], note: "synonym-only: ship→deploy/release" },
   { query: "pager schedule", gold: ["mem-042"], note: "synonym-only: pager→oncall" },
   { query: "my token got exposed", gold: ["mem-017"], note: "synonym-only: token→secret" },
+
+  // ---- D81 alias-memory queries (bidirectional query-time expansion) ----
+  { query: "香蕉计划用什么语言重写网关", gold: ["mem-053"], note: "alias→target: round 2 must find mem-053 via 支付系统重构项目" },
+  { query: "支付系统重构项目什么时候启动评审", gold: ["mem-054"], note: "target→alias: round 2 must find mem-054 via 香蕉计划" },
+  { query: "香蕉计划是哪个项目的代号", gold: ["mem-052"], note: "alias memory itself, round 1" },
 ];

package/scripts/retrieval-eval.ts

@@ -37,6 +37,8 @@ for (const m of MEMORIES) {
     type: m.type,
     tags: m.tags,
     aliases: m.aliases,
+    alias: m.alias,
+    target: m.target,
     source: "retrieval-eval fixture",
   });
   fs.writeFileSync(path.join(dir, `${m.id}.md`), serialize(fm, m.body), "utf8");
@@ -51,7 +53,7 @@ let mrr = 0;
 const misses: string[] = [];
 
 for (const q of QUERIES) {
-  const stats = { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0 };
+  const stats = { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0, aliasExpansions: [] as string[] };
   const hits = search(q.query, { scopeKeys: ["personal"], limit: 50, stats });
   const ids = hits.map((h) => h.id);
   let rank = -1;

package/scripts/smoke-pure.ts

@@ -9,6 +9,12 @@ import { resolveProjectScope, resolveCwdScope, pickScopeRoot, PERSONAL_SCOPE } f
 import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
 import { toFtsQuery } from "../src/retrieve/query.ts";
 import { expansionVariantsForDoc, MAX_AUTO_VARIANTS } from "../src/retrieve/synonyms.ts";
+import {
+  planAliasExpansions,
+  rewriteQueryOnce,
+  mergeRounds,
+  type AliasEntry,
+} from "../src/retrieve/alias-memory.ts";
 import { contentHash, similarity, NEAR_DUP_THRESHOLD } from "../src/store/lifecycle.ts";
 import {
   MIN_NODE_VERSION,
@@ -894,5 +900,54 @@ console.log("== D80 index-time expansion ==");
   ok("no curated terms → no variants", expansionVariantsForDoc("hello world").length === 0);
 }
 
+console.log("== D81 alias-memory query-time expansion ==");
+{
+  const entries: AliasEntry[] = [
+    { id: "a1", scope_key: "personal", alias: "香蕉计划", target: "支付系统重构项目" },
+    { id: "a2", scope_key: "personal", alias: "小宝贝", target: "AI agent" },
+  ];
+  // alias → target.
+  const r1 = rewriteQueryOnce("香蕉计划进展如何", entries);
+  ok("alias rewrites to target", r1 === "支付系统重构项目进展如何", String(r1));
+  // target → alias (bidirectional).
+  const r2 = rewriteQueryOnce("支付系统重构项目什么时候评审", entries);
+  ok("target rewrites to alias", r2 === "香蕉计划什么时候评审", String(r2));
+  // Latin token match (whole token, not substring).
+  const r3 = rewriteQueryOnce("ask 小宝贝 for help", entries);
+  ok("latin alias rewrites", r3 === "ask AI agent for help", String(r3));
+  ok("latin substring does not match", rewriteQueryOnce("association meeting", [{ id: "x", scope_key: "p", alias: "sso", target: "单点登录" }]) === null);
+  // No match → null.
+  ok("no alias term → null", rewriteQueryOnce("今天天气不错", entries) === null);
+  // Depth < 3: at most two expansion rounds.
+  const chained: AliasEntry[] = [
+    { id: "c1", scope_key: "p", alias: "alpha", target: "beta" },
+    { id: "c2", scope_key: "p", alias: "beta", target: "gamma" },
+    { id: "c3", scope_key: "p", alias: "gamma", target: "delta" },
+  ];
+  const plan = planAliasExpansions("alpha status", chained);
+  ok("depth capped below 3", plan.length === 2, JSON.stringify(plan));
+  // Cycle-safe: alpha↔beta oscillates back to the seen query and stops.
+  const cyclic: AliasEntry[] = [
+    { id: "x1", scope_key: "p", alias: "alpha", target: "beta" },
+    { id: "x2", scope_key: "p", alias: "beta", target: "alpha" },
+  ];
+  ok("cycle stops", planAliasExpansions("alpha status", cyclic).length <= 1);
+
+  // Normalized-max merge: an alias-side champion (n=1.0) outranks a mediocre
+  // literal match (n=0.4) — no down-weighting for being from a later round.
+  const merged = mergeRounds([
+    [{ id: "lit-best", score: 10 }, { id: "lit-mid", score: 4 }],
+    [{ id: "alias-best", score: 5 }, { id: "lit-best", score: 2 }],
+  ]);
+  const order = merged.map((m) => m.doc.id);
+  ok("alias champion ties literal champion", merged[0].score === 1 && merged[1].score === 1, JSON.stringify(merged.map((m) => [m.doc.id, m.score]))),
+  ok("multi-round doc wins ties", order[0] === "lit-best", order.join(","));
+  ok("alias-only doc keeps full weight", order[1] === "alias-best", order.join(","));
+  ok("mediocre literal ranks last", order[2] === "lit-mid", order.join(","));
+  // Single round degrades to plain ordering.
+  const single = mergeRounds([[{ id: "a", score: 3 }, { id: "b", score: 9 }]]);
+  ok("single round orders by score", single[0].doc.id === "b" && single[0].score === 1, JSON.stringify(single.map((m) => [m.doc.id, m.score])));
+}
+
 console.log(fails === 0 ? "\nALL PASS" : `\n${fails} FAILURES`);
 process.exit(fails === 0 ? 0 : 1);

package/src/cli.ts

@@ -124,7 +124,7 @@ Example:
 
   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)
@@ -135,6 +135,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`,
@@ -1008,7 +1013,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: [] as string[] }
       : undefined;
     const hits = search(query, {
       scopeKeys: keys,
@@ -1021,6 +1026,9 @@ async function main() {
       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)");
@@ -1083,6 +1091,14 @@ async function main() {
             ),
           }
         : {}),
+      // 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/src/init.ts

@@ -905,10 +905,12 @@ export async function initProject(opts: {
     );
     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.
+    // 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(
-      "Attach alternate phrasings (aliases) to memories so reworded questions still find them?",
+      "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)

package/src/retrieve/alias-memory.ts

@@ -0,0 +1,154 @@
+/**
+ * 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.ts";
+import { latinTerms } from "./query.ts";
+
+export interface AliasEntry {
+  id: string;
+  scope_key: string;
+  alias: string;
+  target: string;
+}
+
+/**
+ * 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?: string[]): AliasEntry[] {
+  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 ?? []) as unknown[])) as AliasEntry[];
+}
+
+const CJK_RE = /[\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff]/;
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** CJK: substring (no tokenizer). Latin: whole-token match. */
+function termInQuery(query: string, term: string): boolean {
+  if (CJK_RE.test(term)) return query.includes(term);
+  const tokens = new Set(latinTerms(query));
+  return tokens.has(term.toLowerCase());
+}
+
+function replaceTerm(query: string, term: string, replacement: string): string {
+  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: string,
+  entries: AliasEntry[],
+): string | null {
+  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: string,
+  entries: AliasEntry[],
+): string[] {
+  const out: string[] = [];
+  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<T extends { id: string; score: number }>(
+  rounds: T[][],
+): Array<{ doc: T; score: number; rounds: number }> {
+  const acc = new Map<string, { doc: T; best: number; rounds: number }>();
+  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/src/retrieve/query.ts

@@ -32,7 +32,7 @@ const CJK_QUESTION_BIGRAMS = new Set([
 
 const MAX_TERMS = 24;
 
-function latinTerms(q: string, useStopwords = true): string[] {
+export function latinTerms(q: string, useStopwords = true): string[] {
   const raw = q.toLowerCase().match(/[a-z0-9_.\-]+/g) ?? [];
   const kept = useStopwords
     ? raw.filter((t) => t.length > 1 && !LATIN_STOPWORDS.has(t))

package/src/retrieve/search.ts

@@ -1,5 +1,10 @@
 import { db } from "../store/db.ts";
 import { toFtsQuery } from "./query.ts";
+import {
+  loadAliasEntries,
+  planAliasExpansions,
+  mergeRounds,
+} from "./alias-memory.ts";
 
 export interface SearchHit {
   id: string;
@@ -88,6 +93,8 @@ export interface SearchStats {
   candidates: number;
   hiddenSuperseded: number;
   hiddenExcluded: number;
+  /** D81: query-time alias expansions actually run (rounds 2+, raw text). */
+  aliasExpansions: string[];
 }
 
 /**
@@ -176,6 +183,7 @@ export function search(
     opts.stats.candidates = 0;
     opts.stats.hiddenSuperseded = 0;
     opts.stats.hiddenExcluded = 0;
+    opts.stats.aliasExpansions = [];
   }
   if (!q) return [];
   const limit = Math.max(1, Math.min(opts.limit ?? 8, 50));
@@ -229,11 +237,38 @@ export function search(
 
   const raw: RawRow[] = 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.
-  if (opts.stats) opts.stats.candidates = raw.length;
-  return resolveVisible(raw, limit, opts.stats);
+  // 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: RawRow[] = raw;
+  let finalLimit = limit;
+  if (expansions.length > 0) {
+    const rounds: RawRow[][] = [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 = merged.length;
+  return resolveVisible(merged, finalLimit, opts.stats);
 }
 
 export function list(

package/src/store/db.ts

@@ -48,6 +48,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 '',
@@ -103,7 +105,7 @@ END;
 `;
 
 /** Current index schema version. Bump when TABLE_SCHEMA/FTS_SCHEMA change. */
-const SCHEMA_VERSION = 7;
+const SCHEMA_VERSION = 8;
 
 function userVersion(d: AnyDatabase): number {
   const row = d.prepare("PRAGMA user_version").get() as { user_version: number };

package/src/store/lifecycle.ts

@@ -260,6 +260,9 @@ export interface SupersedeInput {
   type?: string;
   tags?: string[];
   aliases?: string[];
+  /** D81: undefined = inherit the old memory's pair. */
+  alias?: string;
+  target?: string;
   source?: string;
 }
 
@@ -288,6 +291,9 @@ export function supersede(
     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/src/store/markdown.ts

@@ -60,6 +60,17 @@ export interface Frontmatter {
    * Optional and additive: files without it parse unchanged.
    */
   aliases?: string[];
+  /**
+   * D81: user-defined alias vocabulary — `alias` is the nickname
+   * (e.g. 香蕉计划), `target` is what it refers to
+   * (e.g. 支付系统重构项目). Unlike D61 per-memory aliases (alternate
+   * phrasings of one memory), an alias memory defines vocabulary once and
+   * the query-time expansion (retrieve/alias-memory.ts) applies it to every
+   * search in its scope — no reindex when the alias changes. Optional;
+   * files without it parse unchanged.
+   */
+  alias?: string;
+  target?: string;
   source: string;
   created_at: string; // RFC 3339, never bare epoch (§3)
   updated_at: string; // RFC 3339
@@ -247,6 +258,13 @@ export function normalizeFrontmatter(
           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/src/store/sync.ts

@@ -15,8 +15,8 @@ import { projectRoot, paths } from "../paths.ts";
 import { loadConfig } from "../config.ts";
 
 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,
@@ -28,6 +28,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,
@@ -74,6 +76,7 @@ function writeRow(mf: MemoryFile, mtimeMs: number): void {
     (a) => !have.has(a.toLowerCase()),
   );
   const aliases = [...supplied, ...auto].join(",");
+  // D81: user-defined alias vocabulary (single nickname → referent pair).
   db().prepare(UPSERT_SQL).run(
     fm.id,
     fm.scope_key,
@@ -86,6 +89,8 @@ function writeRow(mf: MemoryFile, mtimeMs: number): void {
     fm.status,
     tags,
     aliases,
+    fm.alias ?? "",
+    fm.target ?? "",
     body,
     cjkIndexText(body + "\n" + tags + "\n" + aliases),
     contentHash(body),

package/src/tools/ops.ts

@@ -113,6 +113,18 @@ 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()
@@ -163,6 +175,18 @@ 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 type MemorySupersedeArgs = z.infer<z.ZodObject<typeof memorySupersedeArgs>>;
 
@@ -242,6 +266,8 @@ function buildFrontmatter(
     type: Frontmatter["type"];
     tags: string[];
     aliases?: string[];
+    alias?: string;
+    target?: string;
     source: Frontmatter["source"];
   },
 ): Frontmatter {
@@ -259,6 +285,11 @@ function buildFrontmatter(
     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,
@@ -328,6 +359,14 @@ export async function addMemory(
           (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);
@@ -447,6 +486,16 @@ export async function supersedeMemory(
               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);