open-memex 0.8.0-alpha.2 → 0.8.0

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",
   "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/server.json

@@ -3,7 +3,7 @@
   "name": "io.github.stoneskin/open-memex",
   "title": "open-memex",
   "description": "Local-first memory for AI coding agents — Markdown + SQLite FTS5, shared across editors via MCP.",
-  "version": "0.7.3",
+  "version": "0.8.0",
   "repository": {
     "url": "https://github.com/stoneskin/open-memex",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "open-memex",
-      "version": "0.7.3",
+      "version": "0.8.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {

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)
@@ -133,8 +133,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`,
@@ -1008,7 +1012,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 +1025,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 +1090,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

@@ -893,26 +893,20 @@ 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: Record<string, unknown> = {};
-    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(

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),