open-memex 0.8.0 → 0.8.1

package/AGENTS.md

@@ -205,6 +205,10 @@ breaking v1→v2 transition) shipped with 0.3.0. Full rules: `CONTRIBUTING.md`.
   new commands → README CLI sections + this file's Commands. A change without its docs
   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.
+- **Measurement before mechanism.** A retrieval change lands its fixture +
+  baseline number in a commit with no retrieval change at all, so the delta is
+  unambiguous. `scripts/retrieval-eval.ts` is the gate: no retrieval PR merges
+  without before/after recall@k + MRR on the checked-in fixture.
 - **Version bumps ship with features.** `package.json` + `package-lock.json` carry the
   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

package/CHANGELOG.md

@@ -9,6 +9,15 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+## [0.8.1] - 2026-10-07
+
+- D83 follow-up: the two D83 clauses that shipped as design but not as code. (1) **BM25 weight for the `expansions` column** — `bm25(memories_fts, …)` now takes an explicit weight vector (`src/retrieve/weights.ts`, order `[content, tags, aliases, expansions, type, cjk]`) instead of the implicit all-1.0. `expansions` is `0.75`: measured on equal-length docs, a direct body match and an expansion-only match score *identically* at weight 1.0 (`-3.983` vs `-3.983`), leaving the order to tiebreaks — any weight below 1.0 breaks that tie in the right direction. `0.75` is the highest value the fixture cannot distinguish from 1.0 (sweep: 1.0/0.9/0.75 all give R@1 0.750 / R@5 0.977 / MRR 0.857; 0.5 costs MRR, below 0.35 R@5 breaks). Exposed as `opts.expansionsWeight` so the sweep stays measurable; `smoke-pure.ts` pins the vector's shape and ordering. (2) **`search --explain` per-column attribution** — reports `matched via: body=N alias=N expansion=N other=N` plus the active weights. Does **not** fix the D80 `how do we ship` rank-8 case: that is per-column length norm, not weighting. Fixture unchanged at R@1 0.750 / R@5 0.977 / MRR 0.857.
+
+- fix: `search()` honours the caller's `limit` again (#53). When a D81 alias round fired, the widened candidate pool leaked out through the return value, so `memory_search` / MCP `memory_search` / `cli search` returned up to **2× `limit`** hits with no signal it happened. The pool is still wider than `limit` for *ranking* (round-2 hits are not starved the way D79's slice-to-K starved them); only the cut changed, to `limit`. Drops the dead `1.5K` line, which could never raise the value. No ranking change — `scripts/retrieval-eval.ts` is unchanged at recall@1 0.750 / recall@5 0.977 / MRR 0.857.
+- perf: partial index on the alias registry (#55): `loadAliasEntries` ran `WHERE alias <> '' AND target <> ''` as a full table scan on **every** search. Added `idx_memories_alias ON memories(scope_key) WHERE alias <> '' AND target <> ''` to `TABLE_SCHEMA`, which runs on every db open — no `SCHEMA_VERSION` bump, no rebuild, existing installs pick it up on next open. Measured at 5k memories: 971ms → 39ms per 2000 lookups (~25×), `EXPLAIN QUERY PLAN` confirms `SEARCH memories USING INDEX idx_memories_alias`. Deliberately not a result cache: a newly saved alias must still apply on the very next query.
+- D83 (implemented, for #56): D80 index-time expansion variants moved out of the `aliases` column into a dedicated `expansions` index column (own FTS column + triggers; `SearchHit.aliases` and `(aka: …)` surface only user-authored aliases; expansion-only matches report `(synonym: …)`; `--explain` shows the same via the snippet). Schema v8 → v9 with rebuild-from-Markdown migration (verified on a scratch DB). `retrieval-eval` unchanged at R@1 0.750 / R@5 0.977 / MRR 0.857 — the `how do we ship` rank stayed 8: expansion-column length-norm dilution is inherent, not caused by the mixing.
+- `memory_search` / `memory_list` `type` is now a closed enum (D82, closes #51): a misspelled type is rejected at the schema (MCP -32602) instead of silently returning zero results. The opencode plugin shares the same args objects, so both surfaces tighten together; `scripts/smoke-mcp.ts` guards the rejection.
+
 ## [0.8.0] - 2026-10-07
 
 - User-defined alias vocabulary as query-time expansion (D81): any memory type may now carry `alias:` (nickname, e.g. 香蕉计划) and `target:` (referent, e.g. 支付系统重构项目) frontmatter — an alias memory defines vocabulary once per scope. At query time, query terms hit the alias registry (exact match, one cheap SELECT per search) and the query is rewritten with the other side of the relation — bidirectional, depth < 3, cycle-safe — then re-run as round 2/3. Rounds merge by normalized-max (`mergeRounds` in `src/retrieve/alias-memory.ts`): each round's BM25 scores are divided by that round's best, so an alias-side champion competes evenly with a literal-side champion; the merged pool is re-ranked and cut to [1.5K, 2K], never back to K. No reindex when an alias changes. Creation: `memory_add` alias/target params, CLI `add --alias/--target`, or frontmatter edit (v1: user-explicit only). Fixture grows to 54 memories / 44 queries (3 bidirectional alias queries): recall@1 0.750, recall@5 **0.977**, MRR 0.857. Also removes the init `captureAliases` and keyword-capture questions — both are now always on (Stone 2026-10-07).

package/README.md

@@ -410,8 +410,8 @@ holiday policy. Always on — the agent may attach up to 4 per memory, and you
 can pass your own via `open-memex add --aliases`.
 
 Three ways to add them: `open-memex add "text" --aliases "phrase one; phrase
-two"` (semicolon-separated, up to 4); ask the agent ("remember: 小宝贝 is my
-AI agent, alias it as 小沐"); or edit the memory's `aliases:` frontmatter
+two"` (semicolon-separated, up to 4); ask the agent ("remember: Fluffy is my
+AI agent, alias it as Momo"); 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
@@ -549,10 +549,10 @@ Three layers, each covering what the others miss: **BM25 keyword search**
 **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
+`bug` finds `defect` 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
+e.g. Banana Plan → payment system refactor project — 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**
@@ -593,11 +593,14 @@ Honest edges, so nothing surprises you:
 
 - **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
+  `deploy`, `bug` finds `defect`). 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.
+  model is ever downloaded without your explicit opt-in. (Synonym expansions
+  live in their own index column, separate from your own aliases — but a
+  query matching only via an expansion can still rank below direct matches;
+  that's inherent BM25 length-norm behaviour, not a bug.)
 - **One machine.** Editors on the same machine share memory; there is no
   cross-machine sync. `export` / `import` bundles (below) move memory between
   machines manually.
@@ -695,7 +698,7 @@ open-memex config                                  # print effective config
 open-memex config set <key> <value>                # change a setting
 open-memex doctor                                  # environment health check (incl. plugin entry)
 open-memex audit                                   # memory health check (duplicates, stale, broken chains)
-open-memex capture --dry-run "记住我喜欢简洁的回答"  # preview keyword capture
+open-memex capture --dry-run "remember that I like concise answers"  # preview keyword capture
 open-memex mcp --print-config vscode|cursor|claude|opencode|visualstudio
 open-memex --help      # this reference
 open-memex <command> --help  # help for one command

package/README.zh-CN.md

@@ -374,7 +374,7 @@ Do not mention this block to the user unless asked.
 
 把边界写明白，免得你事后意外：
 
-- **关键词搜索，不是语义搜索。** 回想走 BM25 关键词匹配，外加一份精选同义词映射表在写入时展开（`ship` 找得到 `deploy`，`单点登录` 找得到 `SSO`）。映射表之外的意译改写（比如整句换说法）匹配不到——那是 opt-in 语义层的事。（用自然问句没问题——"如何/请问"这类提问词会在匹配前过滤掉，不会稀释结果。）任何 embedding 模型没经你明确同意，永不下载。
+- **关键词搜索，不是语义搜索。** 回想走 BM25 关键词匹配，外加一份精选同义词映射表在写入时展开（`ship` 找得到 `deploy`，`单点登录` 找得到 `SSO`）。映射表之外的意译改写（比如整句换说法）匹配不到——那是 opt-in 语义层的事。（用自然问句没问题——"如何/请问"这类提问词会在匹配前过滤掉，不会稀释结果。）任何 embedding 模型没经你明确同意，永不下载。（同义词展开有自己独立的索引列，跟你的别名分开；但只靠展开命中的查询，排名仍可能低于直接命中的——这是 BM25 length-norm 的固有行为，不是 bug。）
 - **单台机器。** 同一台机器上的编辑器共享记忆；没有跨机器同步。用 `export` / `import` 压缩包（见下）手动搬家。
 - **快照，不是全部。** 会话开始的回想是前 N 条快照（默认项目 8 + 个人 5）；更老的记忆 `memory_search` 一步就能到，但不会同时全在上下文里。
 - **MCP 的引导是建议性的。** opencode 之外，主动捕获和回想靠助手遵循握手指令——MCP 里没有硬性的会话开始钩子。工具本身在被调用时永远可靠。

package/dist/.build-stamp

@@ -1 +1 @@
-55d6d5c601b1769ad9c4813aebefcb25ee3b29cab0c6c30f8450d9388fe83a6a
+db188c4af0c070c360ad3e3694172a66d5503a7fdad1ea2321a56b059228e3e6

package/dist/cli.js

@@ -10,6 +10,7 @@ import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatR
 import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.js";
 import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.js";
 import { search, list, countList, hitStateLabel } from "./retrieve/search.js";
+import { DEFAULT_EXPANSIONS_WEIGHT } from "./retrieve/weights.js";
 import { formatInventoryLine, truncationNote } from "./retrieve/display.js";
 import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, normalizeAliases, } from "./store/markdown.js";
 import { loadConfig, configSource } from "./config.js";
@@ -918,6 +919,18 @@ async function main() {
             if (stats.aliasExpansions.length > 0) {
                 console.log(`alias rounds: ${stats.aliasExpansions.map((q) => `"${q}"`).join(" → ")}`);
             }
+            // D83: which indexed column each hit matched on. `expansion` means the
+            // hit only surfaced through a D80 derived variant, so it ranks below an
+            // equal body match by construction (BM25_WEIGHTS) — this is how a
+            // surprising rank gets traced instead of guessed at.
+            if (hits.length > 0) {
+                const via = hits.reduce((acc, h) => {
+                    acc[h.matchedVia] = (acc[h.matchedVia] ?? 0) + 1;
+                    return acc;
+                }, {});
+                console.log(`matched via: ${Object.entries(via).map(([k, n]) => `${k}=${n}`).join(", ")}` +
+                    `   (bm25 weights: content=1 tags=1 aliases=1 expansions=${DEFAULT_EXPANSIONS_WEIGHT} type=1 cjk=1)`);
+            }
         }
         if (hits.length === 0) {
             console.log("(no matches)");

package/dist/retrieve/search.js

@@ -1,13 +1,41 @@
 import { db } from "../store/db.js";
 import { toFtsQuery } from "./query.js";
+import { BM25_WEIGHTS } from "./weights.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 ?? "";
-    // D61: the snippet highlights matches in the body column only. When the
-    // match came through an alias (body shows no highlight), say so — the
-    // hit otherwise looks unrelated to the query.
-    if (aliases.length > 0 && !/\[[^\]]+\]/.test(snippet)) {
+    // D83: attribution is per-column now. The aliases column holds only
+    // user/authored phrasings (D61); the expansions column holds D80 derived
+    // variants. Say which one matched — the hit otherwise looks unrelated to
+    // the query when the body shows no highlight.
+    const hlTerms = (s) => {
+        if (!s)
+            return [];
+        const m = s.match(/\[([^\]]+)\]/g);
+        return m ? [...new Set(m.map((x) => x.slice(1, -1)))] : [];
+    };
+    const aliasTerms = hlTerms(r.alias_hl);
+    const expTerms = hlTerms(r.exp_hl);
+    // D83: attribute the hit to the column that matched, so `--explain` can
+    // trace an unexpected rank. Order matters: a body highlight is the most
+    // direct evidence, then an authored alias, then a derived expansion.
+    const matchedVia = /\[[^\]]+\]/.test(snippet)
+        ? "body"
+        : aliasTerms.length > 0
+            ? "alias"
+            : expTerms.length > 0
+                ? "expansion"
+                : "other";
+    if (aliasTerms.length > 0 && aliases.length > 0) {
+        snippet += ` (aka: ${aliases.join(", ")})`;
+    }
+    else if (expTerms.length > 0) {
+        snippet += ` (synonym: ${expTerms.join(", ")})`;
+    }
+    else if (aliases.length > 0 && !/\[[^\]]+\]/.test(snippet)) {
+        // Match came through another column (tags/type/cjk) — the authored
+        // aliases are still honest context for the hit.
         snippet += ` (aka: ${aliases.join(", ")})`;
     }
     return {
@@ -17,6 +45,7 @@ function toHit(r) {
         type: r.type,
         tags: r.tags ? r.tags.split(",").filter(Boolean) : [],
         aliases,
+        matchedVia,
         snippet,
         score: r.score,
         updated_at: r.updated_at,
@@ -138,18 +167,26 @@ export function search(query, opts = {}) {
         : "";
     const typeFilter = opts.type ? ` AND m.type = ?` : "";
     const sql = `
-    SELECT m.id, m.scope_key, m.project_name, m.type, m.tags, m.aliases, m.updated_at,
+    SELECT m.id, m.scope_key, m.project_name, m.type, m.tags, m.aliases, m.expansions, m.updated_at,
            m.status, m.superseded_by, m.review_state, m.source, m.created_at,
            snippet(memories_fts, 0, '[', ']', ' ... ', 12) AS snippet,
-           bm25(memories_fts) AS score
+           highlight(memories_fts, 2, '[', ']') AS alias_hl,
+           highlight(memories_fts, 3, '[', ']') AS exp_hl,
+           bm25(memories_fts, ?, ?, ?, ?, ?, ?) AS score
     FROM memories_fts
     JOIN memories m ON m.rowid = memories_fts.rowid
     WHERE memories_fts MATCH ?${scopeFilter}${typeFilter}
     ORDER BY score ASC
     LIMIT ?
   `;
+    // D83: the weight vector is bound per statement, so it leads the parameter
+    // list (it appears in the SELECT list, before the WHERE's MATCH).
+    const weights = opts.expansionsWeight === undefined
+        ? BM25_WEIGHTS
+        : BM25_WEIGHTS.map((w, i) => (i === 3 ? opts.expansionsWeight : w));
     const fetchFts = (matchExpr) => {
-        const params = [matchExpr];
+        const params = [...weights];
+        params.push(matchExpr);
         if (opts.scopeKeys && opts.scopeKeys.length > 0)
             params.push(...opts.scopeKeys);
         if (opts.type)
@@ -169,7 +206,6 @@ export function search(query, opts = {}) {
     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) {
@@ -181,21 +217,22 @@ export function search(query, opts = {}) {
         // 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.
+        //
+        // The merged pool is deliberately wider than `limit` (each round already
+        // over-fetches by fetchLimit) so round-2 hits are never starved the way
+        // D79's slice-to-K starved them. #53: that headroom is for RANKING only —
+        // the return is still cut to the caller's `limit`, since `limit` is a cap
+        // on what every caller (tools, MCP, cli) receives, not a hint.
         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.
+    // expands variants into the indexed 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);
+    return resolveVisible(merged, limit, opts.stats);
 }
 export function list(scopeKey, opts = {}) {
     const limit = Math.max(1, Math.min(opts.limit ?? 20, 100));

package/dist/retrieve/weights.js

@@ -0,0 +1,35 @@
+/**
+ * D83: BM25 column weights for the FTS index.
+ *
+ * Split out of `search.ts` deliberately: `smoke-pure.ts` must keep running
+ * with no SQLite dependency (its header says "pure-logic, no
+ * bun:sqlite"), and importing `search.ts` pulls in `store/db.ts` at module
+ * load. This module holds the tunable constant and nothing else, so the
+ * guard test can import it without opening a database.
+ *
+ * `expansions` (D80-derived synonym/translation variants) sits strictly below
+ * `aliases` so the preference is explicit rather than incidental: a body
+ * match outranks an expansion-only match, and a user-authored alias outranks
+ * a derived one. This is not cosmetic — measured on equal-length docs, at
+ * weight 1.0 a direct body match and an expansion-only match score
+ * *identically* (-3.983 vs -3.983), leaving the order to tiebreaks. Any
+ * weight < 1.0 breaks that tie in the right direction.
+ *
+ * The value is the highest one the checked-in fixture cannot distinguish from
+ * 1.0 (`scripts/retrieval-eval.ts`: R@1 0.750 / R@5 0.977 / MRR 0.857 hold
+ * from 1.0 down to 0.75; 0.5 already costs MRR, and below 0.35 R@5 breaks).
+ * So the ordering guarantee is free, and the fixture is the gate that keeps
+ * it honest — retune by re-running the sweep, not by feel.
+ *
+ * Known non-fix: this does NOT repair D80's `how do we ship` rank-8 case.
+ * That is per-column length norm (one variant among many in a long
+ * `expansions` field), not a weighting problem; see D83's update.
+ */
+/** Weight for the D80 `expansions` column. */
+export const DEFAULT_EXPANSIONS_WEIGHT = 0.75;
+/**
+ * Full weight vector for `memories_fts`, in declaration order.
+ * MUST stay in sync with FTS_SCHEMA column order in `store/db.ts`:
+ * `[content, tags, aliases, expansions, type, cjk]`.
+ */
+export const BM25_WEIGHTS = [1, 1, 1, DEFAULT_EXPANSIONS_WEIGHT, 1, 1];

package/dist/store/db.js

@@ -35,6 +35,7 @@ CREATE TABLE IF NOT EXISTS memories (
   status       TEXT NOT NULL DEFAULT 'active',
   tags         TEXT NOT NULL DEFAULT '',
   aliases      TEXT NOT NULL DEFAULT '',
+  expansions   TEXT NOT NULL DEFAULT '',
   alias        TEXT NOT NULL DEFAULT '',
   target       TEXT NOT NULL DEFAULT '',
   content      TEXT NOT NULL,
@@ -53,6 +54,19 @@ CREATE INDEX IF NOT EXISTS idx_memories_scope_updated
   ON memories(scope_key, updated_at DESC);
 CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
 CREATE INDEX IF NOT EXISTS idx_memories_status ON memories(status);
+-- D81: the alias registry (retrieve/alias-memory.ts) runs on every search().
+-- The predicate is a full table scan without this — the rows carrying a
+-- defined alias pair are a tiny subset of a corpus that may be tens of
+-- thousands. A partial index keeps the lookup proportional to the number of
+-- aliases defined, not the size of the store.
+--
+-- No SCHEMA_VERSION bump: TABLE_SCHEMA runs on every db open (see db()), so
+-- existing installs pick this up on next open. Deliberately NOT a result
+-- cache — the alias registry must be re-read per query so a newly saved
+-- alias memory applies on the very next query. This index accelerates the
+-- lookup without caching results.
+CREATE INDEX IF NOT EXISTS idx_memories_alias
+  ON memories(scope_key) WHERE alias <> '' AND target <> '';
 `;
 // The `cjk` column holds pre-tokenized CJK unigrams+bigrams (see
 // src/retrieve/cjk.ts). FTS5's unicode61 treats a CJK run as one token, so
@@ -64,6 +78,7 @@ CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
   content,
   tags,
   aliases,
+  expansions,
   type,
   cjk,
   scope_key UNINDEXED,
@@ -73,24 +88,24 @@ CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
 );
 
 CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
-  INSERT INTO memories_fts(rowid, content, tags, aliases, type, cjk, scope_key)
-  VALUES (new.rowid, new.content, new.tags, new.aliases, new.type, new.cjk, new.scope_key);
+  INSERT INTO memories_fts(rowid, content, tags, aliases, expansions, type, cjk, scope_key)
+  VALUES (new.rowid, new.content, new.tags, new.aliases, new.expansions, new.type, new.cjk, new.scope_key);
 END;
 
 CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
-  INSERT INTO memories_fts(memories_fts, rowid, content, tags, aliases, type, cjk, scope_key)
-  VALUES ('delete', old.rowid, old.content, old.tags, old.aliases, old.type, old.cjk, old.scope_key);
+  INSERT INTO memories_fts(memories_fts, rowid, content, tags, aliases, expansions, type, cjk, scope_key)
+  VALUES ('delete', old.rowid, old.content, old.tags, old.aliases, old.expansions, old.type, old.cjk, old.scope_key);
 END;
 
 CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
-  INSERT INTO memories_fts(memories_fts, rowid, content, tags, aliases, type, cjk, scope_key)
-  VALUES ('delete', old.rowid, old.content, old.tags, old.aliases, old.type, old.cjk, old.scope_key);
-  INSERT INTO memories_fts(rowid, content, tags, aliases, type, cjk, scope_key)
-  VALUES (new.rowid, new.content, new.tags, new.aliases, new.type, new.cjk, new.scope_key);
+  INSERT INTO memories_fts(memories_fts, rowid, content, tags, aliases, expansions, type, cjk, scope_key)
+  VALUES ('delete', old.rowid, old.content, old.tags, old.aliases, old.expansions, old.type, old.cjk, old.scope_key);
+  INSERT INTO memories_fts(rowid, content, tags, aliases, expansions, type, cjk, scope_key)
+  VALUES (new.rowid, new.content, new.tags, new.aliases, new.expansions, new.type, new.cjk, new.scope_key);
 END;
 `;
 /** Current index schema version. Bump when TABLE_SCHEMA/FTS_SCHEMA change. */
-const SCHEMA_VERSION = 8;
+const SCHEMA_VERSION = 9;
 function userVersion(d) {
     const row = d.prepare("PRAGMA user_version").get();
     return row.user_version;

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, alias, target, 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, expansions, 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,7 @@ const UPSERT_SQL = `
     status       = excluded.status,
     tags         = excluded.tags,
     aliases      = excluded.aliases,
+    expansions   = excluded.expansions,
     alias        = excluded.alias,
     target       = excluded.target,
     content      = excluded.content,
@@ -57,16 +58,20 @@ export function upsertFromFile(mf) {
 function writeRow(mf, mtimeMs) {
     const { fm, body, filePath } = mf;
     const tags = (fm.tags ?? []).join(",");
-    // D80 index-time expansion: curated synonym/translation variants for the
-    // memory's keywords are indexed in the aliases column (and therefore the
-    // CJK bigram column below), so any related word matches in round one.
-    // Derived at sync time — the Markdown file stays the source of truth.
+    // D80 index-time expansion, D83: curated synonym/translation variants for
+    // the memory's keywords are indexed in their own `expansions` column —
+    // never mixed into `aliases`, which holds only user/authored alternate
+    // phrasings (so `(aka: …)` attribution stays honest). The CJK bigram
+    // column still covers expansions, so CJK variants stay substring-
+    // searchable. Derived at sync time — the Markdown file stays the source
+    // of truth.
     const supplied = fm.aliases ?? [];
     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(",");
+    const aliases = supplied.join(",");
+    const expansions = auto.join(",");
     // 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");
+    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, expansions, fm.alias ?? "", fm.target ?? "", body, cjkIndexText(body + "\n" + tags + "\n" + aliases + "\n" + expansions), 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

@@ -90,7 +90,10 @@ export const memorySearchArgs = {
         .enum(["project", "personal", "both"])
         .optional()
         .describe("Which scope(s) to search. Default: both."),
-    type: z.string().optional().describe("Restrict to memories of this type (e.g. decision, preference, gotcha)."),
+    type: z
+        .enum(MEMORY_TYPE_TAXONOMY)
+        .optional()
+        .describe("Restrict to memories of this type. Closed taxonomy — a misspelled type is rejected, never silently empty."),
     limit: z.number().int().min(1).max(50).optional().describe("Max results to return (default 8)."),
 };
 export const memoryListArgs = {
@@ -98,7 +101,10 @@ export const memoryListArgs = {
         .enum(["project", "personal", "both"])
         .optional()
         .describe("Which scope(s) to list. `project` = tied to this repo. `personal` = global across all your projects. `both` lists each scope's newest. Default: project."),
-    type: z.string().optional().describe("Only list memories of this type (e.g. decision, preference, gotcha)."),
+    type: z
+        .enum(MEMORY_TYPE_TAXONOMY)
+        .optional()
+        .describe("Only list memories of this type. Closed taxonomy — a misspelled type is rejected, never silently empty."),
     limit: z.number().int().min(1).max(100).optional().describe("Max entries to list, newest first (default 20)."),
     include: z
         .enum(["active", "all"])

package/docs/V2-DESIGN.md

@@ -1605,6 +1605,14 @@ requirement: personal data never touches third-party services). Benchmarks to tr
 - **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).
 
 
+- **D82 — closed `type` taxonomy on search/list (2026-10-07).** Follow-up deferred from the TDQS pass (#50), closes issue #51: `memory_search` / `memory_list` `type` is now `z.enum(MEMORY_TYPE_TAXONOMY)` instead of `z.string()` — a misspelled type (`"decisions"`) is rejected at the schema (MCP -32602) instead of returning zero results the agent can't distinguish from "no memories of that type". Hard rejection, not a soft "no matches" message: closed taxonomy + fail-fast. Existing rows with non-taxonomy types are possible (the frontmatter parser only coerces the v1 `instruction` → `knowledge` case) and are unaffected — they still surface in unfiltered search/list, they just can't be addressed by a type filter. The opencode plugin shares the same args objects, so both surfaces tighten together; `scripts/smoke-mcp.ts` guards the rejection. `memory_submit` keeps `destructiveHint: false` — settled in the #50 review (the outbox unlink happens after the repo copy is committed and hash-verified, so it's recoverable from git); recorded here so it isn't re-litigated.
+
+- **D83 — D80 expansions get their own index column (2026-10-07).** Design follow-up to issue #56 (deferred from the D80 review): the curated index-time variants (`expansionVariantsForDoc`) move out of the `aliases` column into a dedicated `expansions` column — on `memories`, on `memories_fts`, and in the ai/ad/au triggers. `writeRow` stores user/authored aliases in `aliases` and derived variants in `expansions` (still filtered against the supplied set, still never written to Markdown); the `cjk` bigram column keeps covering body + tags + aliases + expansions so CJK variants stay substring-searchable. Retrieval: the FTS MATCH set gains the column with its own bm25 weight (at or below `aliases` — the fixture is the gate, tune don't guess); `SearchHit.aliases` and the `(aka: …)` attribution surface only user-authored aliases; `search --explain` reports which column matched (alias vs expansion). Migration: `SCHEMA_VERSION` 8 → 9; the bump triggers `rebuildIndexSchema`, which repopulates from Markdown — safe because expansions are derived and Markdown is untouched.
+*Update (2026-10-07, implemented and measured):* the `how do we ship` rank did **not** improve (still 8) — the dilution for expansion-column matches is inherent to per-column BM25 length norm (32 variants in their own column dilute about as much as 36 did in the shared one), not to the mixing. What the split fixed is provenance (`(aka:)` / `SearchHit.aliases` are user-authored again) and the dilution of deliberate user aliases (a ≤4-term column now scores cleanly). Regression gate passed: `retrieval-eval` R@1 0.750 / R@5 0.977 / MRR 0.857, identical to pre-split; v8→v9 migration verified on a scratch DB (merged aliases re-split correctly, `user_version` 9). *Rationale: an agent reading `(aka: …)` must be able to trust it means "alternate phrasings someone attached to this memory", and a 32-variant derived list must not dilute the weight of 4 deliberate ones.*
+- **D84 — `limit` is a cap on the return, never a hint (2026-10-07).** Correction to D81's cut rule, raised by the review of #52. D81 widened the merged alias pool to `[1.5K, 2K]` and passed that widened value to `resolveVisible` as the slice — so when an alias round fired, `search()` returned up to **2× `limit`** rows to every caller (`memory_search`, the MCP tool, `cli search`), with nothing in `--explain` saying so. The pool stays wider than `limit` — each round already over-fetches by `fetchLimit`, and the starvation D79's slice-to-K caused is real and still prevented — but the *return* is cut to `limit`. (D81's `1.5K` line was also dead: `max(min(pool,2K), min(pool,1.5K))` is always `min(pool,2K)`, so the documented band never existed; it is gone.) No ranking change — the merge sorts before any cut, so top-k is byte-identical; `scripts/retrieval-eval.ts` unchanged at R@1 0.750 / R@5 0.977 / MRR 0.857. *Rationale: `limit` is a contract on what a caller receives. Headroom belongs inside the ranking, not in the result set — an agent paying 2× the tool-result tokens on alias-touching queries has no way to see that it happened.*
+- **D86 — the `expansions` BM25 weight, set by the fixture (2026-10-07).** Closes the two D83 clauses that were written into the decision log but never landed in code (`00c4d2d` shipped `bm25(memories_fts)` with no weight vector, and left `--explain` reporting only `fts:` / `candidates:` / `alias rounds:`). (1) **Weight vector** — `bm25(memories_fts, …)` now takes an explicit `[content, tags, aliases, expansions, type, cjk]`, with `expansions` at **0.75** (`src/retrieve/weights.ts`, kept out of `search.ts` so `smoke-pure.ts` keeps its no-sqlite guarantee). The measurement that sets it: on equal-length docs at weight 1.0, a direct body match and an expansion-only match score **identically** (`-3.983` vs `-3.983`) — the preference was being decided by tiebreak, not by the ranking function. Any weight < 1.0 breaks that tie toward the body. `0.75` is the *highest* weight the checked-in fixture cannot distinguish from 1.0 (sweep: 1.0 / 0.9 / 0.75 all yield R@1 0.750 / R@5 0.977 / MRR 0.857; 0.5 already costs MRR; below 0.35 R@5 breaks), so the ordering guarantee is free and the fixture remains the gate — retune by re-running the sweep, never by intuition. `SearchHit.matchedVia` (`body` | `alias` | `expansion` | `other`) is computed from the same per-column highlights the attribution already used. (2) **`--explain` attribution** — prints `matched via: body=N alias=N expansion=N other=N` alongside the active weights, so a surprising rank is traceable to the column that caused it. *Rationale: D83 promised the split would make the two columns distinguishable; on equal-weight columns they were not distinguishable at all, so the split bought provenance without buying ranking. This is the missing half.* **Explicit non-goal:** this does *not* repair D80's `how do we ship` rank-8 case — that is per-column length norm (one variant among many in a long `expansions` field), not a weighting problem. Fixing that means narrowing *what* lands in the column, not re-weighting it. Fixture unchanged: R@1 0.750 / R@5 0.977 / MRR 0.857.
+- **D85 — the alias registry is indexed, not cached (2026-10-07).** From the same review (#55). D81's `loadAliasEntries` runs on **every** `search()` call over `alias <> '' AND target <> ''` — a full table scan on a corpus that may be tens of thousands. Added `idx_memories_alias ON memories(scope_key) WHERE alias <> '' AND target <> ''` to `TABLE_SCHEMA`. Two deliberate choices: (1) **no `SCHEMA_VERSION` bump** — `TABLE_SCHEMA` executes on every db open, not only on rebuild, so `CREATE INDEX IF NOT EXISTS` is idempotent and existing installs pick it up on next open with no rebuild; this also keeps the bump free for D83's 8 → 9 schema change. (2) **No result cache** — the registry must be re-read per query so a newly saved alias memory applies on the very next query (D81's freshness property). An index accelerates the lookup without caching results; those two concerns are separable and this resolves only the first. Measured at 5k memories: 971ms → 39ms per 2000 scoped lookups (~25×), `EXPLAIN QUERY PLAN` confirms `SEARCH memories USING INDEX idx_memories_alias`. Note the *unscoped* variant of the query still prefers `idx_memories_status`; `search()` always passes `scopeKeys`, so the partial index is what ships. *Rationale: the alias table is tiny by construction — one row per defined nickname per scope — so its lookup cost must be proportional to aliases defined, not to store size.*
+
 ## Open Questions
 
 _Pruned 2026-10-04 (D75): entries decided in D56/D57/D61/D68 and the shipped layers of the retrieval-robustness question were removed — the decisions are the record. What remains below is genuinely open._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "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/smoke-mcp.ts

@@ -133,6 +133,18 @@ try {
   const listBoth = await req("tools/call", { name: "memory_list", arguments: { scope: "both" } });
   const listBothText = listBoth.result?.content?.[0]?.text ?? "";
   check("memory_list both scopes (D68)", listBothText.includes("About you"));
+  // D82: closed type taxonomy — a misspelled type is rejected at the schema,
+  // never silently empty.
+  const badType = await req("tools/call", {
+    name: "memory_search",
+    arguments: { query: "mcp e2e probe", type: "decisions" },
+  });
+  const badTypeText: string = badType.result?.content?.[0]?.text ?? "";
+  check(
+    "memory_search rejects misspelled type (D82)",
+    /-32602/.test(badTypeText) && /Invalid option/.test(badTypeText),
+    badTypeText.slice(0, 160),
+  );
   // D70: numbers run across the whole listing, so "delete #3" names one memory.
   // Needs a personal entry too, or there is only one section to number.
   const personalAdd = await req("tools/call", {

package/scripts/smoke-pure.ts

@@ -9,6 +9,7 @@ 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 { BM25_WEIGHTS, DEFAULT_EXPANSIONS_WEIGHT } from "../src/retrieve/weights.ts";
 import {
   planAliasExpansions,
   rewriteQueryOnce,
@@ -949,5 +950,20 @@ console.log("== D81 alias-memory query-time expansion ==");
   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("== D83 expansions BM25 weight + matchedVia ==");
+{
+  // The weight vector must stay in memories_fts declaration order:
+  // [content, tags, aliases, expansions, type, cjk]. A mis-ordered vector
+  // silently down-weights the wrong column, so pin the shape.
+  ok("BM25_WEIGHTS has one entry per fts column", BM25_WEIGHTS.length === 6, JSON.stringify(BM25_WEIGHTS));
+  ok("expansions is index 3", BM25_WEIGHTS[3] === DEFAULT_EXPANSIONS_WEIGHT, JSON.stringify(BM25_WEIGHTS));
+  // D83: expansions sits strictly below aliases, so a body match outranks an
+  // expansion-only match by construction instead of by tiebreak.
+  ok("expansions weighted below aliases", BM25_WEIGHTS[3] < BM25_WEIGHTS[2], `${BM25_WEIGHTS[3]} vs ${BM25_WEIGHTS[2]}`);
+  ok("expansions keeps non-zero weight (D80 rescue slice must survive)",
+    BM25_WEIGHTS[3] > 0, String(BM25_WEIGHTS[3]));
+  ok("body stays the strongest column", BM25_WEIGHTS[0] >= BM25_WEIGHTS[3], JSON.stringify(BM25_WEIGHTS));
+}
+
 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.8.0",
+  "version": "0.8.1",
   "repository": {
     "url": "https://github.com/stoneskin/open-memex",
     "source": "github"
@@ -13,7 +13,7 @@
     {
       "registryType": "npm",
       "identifier": "open-memex",
-      "version": "0.8.0",
+      "version": "0.8.1",
       "runtimeHint": "npx",
       "packageArguments": [
         {

package/src/cli.ts

@@ -10,6 +10,7 @@ import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatR
 import { getSyncStatus, formatSyncStatus, submitMemories } from "./submit.ts";
 import { getPrStatus, formatPrStatus, applyPrStatus } from "./github.ts";
 import { search, list, countList, hitStateLabel } from "./retrieve/search.ts";
+import { DEFAULT_EXPANSIONS_WEIGHT } from "./retrieve/weights.ts";
 import { formatInventoryLine, truncationNote } from "./retrieve/display.ts";
 import {
   writeMemoryFile,
@@ -1028,6 +1029,20 @@ async function main() {
       if (stats.aliasExpansions.length > 0) {
         console.log(`alias rounds: ${stats.aliasExpansions.map((q) => `"${q}"`).join(" → ")}`);
       }
+      // D83: which indexed column each hit matched on. `expansion` means the
+      // hit only surfaced through a D80 derived variant, so it ranks below an
+      // equal body match by construction (BM25_WEIGHTS) — this is how a
+      // surprising rank gets traced instead of guessed at.
+      if (hits.length > 0) {
+        const via = hits.reduce<Record<string, number>>((acc, h) => {
+          acc[h.matchedVia] = (acc[h.matchedVia] ?? 0) + 1;
+          return acc;
+        }, {});
+        console.log(
+          `matched via: ${Object.entries(via).map(([k, n]) => `${k}=${n}`).join(", ")}` +
+            `   (bm25 weights: content=1 tags=1 aliases=1 expansions=${DEFAULT_EXPANSIONS_WEIGHT} type=1 cjk=1)`,
+        );
+      }
     }
     if (hits.length === 0) {
       console.log("(no matches)");

package/src/retrieve/search.ts

@@ -1,19 +1,28 @@
 import { db } from "../store/db.ts";
 import { toFtsQuery } from "./query.ts";
+import { BM25_WEIGHTS } from "./weights.ts";
 import {
   loadAliasEntries,
   planAliasExpansions,
   mergeRounds,
 } from "./alias-memory.ts";
 
+/** D83: which indexed column a hit's match came from. */
+export type MatchedVia = "body" | "alias" | "expansion" | "other";
+
 export interface SearchHit {
   id: string;
   scope_key: string;
   project_name: string;
   type: string;
   tags: string[];
-  /** D61: capture-time aliases stored on this memory (search hits only). */
+  /** D61: capture-time aliases stored on this memory (search hits only).
+   *  D83: user/authored only — D80 derived variants live in `expansions`. */
   aliases: string[];
+  /** D83: which FTS column produced this hit's match — `body`, `alias`,
+   *  `expansion`, or `other` (tags/type/cjk). Surfaces in `search --explain`
+   *  so a surprising rank can be traced to the column that caused it. */
+  matchedVia: MatchedVia;
   snippet: string;
   score: number;
   updated_at: number;
@@ -31,6 +40,11 @@ interface RawRow {
   type: string;
   tags: string;
   aliases?: string;
+  /** D83: D80 index-time synonym/translation variants — derived, never user-authored. */
+  expansions?: string;
+  /** D83: per-column FTS highlight, so attribution knows which column matched. */
+  alias_hl?: string;
+  exp_hl?: string;
   updated_at: number;
   snippet: string;
   score: number;
@@ -44,10 +58,34 @@ interface RawRow {
 function toHit(r: RawRow): SearchHit {
   const aliases = r.aliases ? r.aliases.split(",").map((a) => a.trim()).filter(Boolean) : [];
   let snippet = r.snippet ?? "";
-  // D61: the snippet highlights matches in the body column only. When the
-  // match came through an alias (body shows no highlight), say so — the
-  // hit otherwise looks unrelated to the query.
-  if (aliases.length > 0 && !/\[[^\]]+\]/.test(snippet)) {
+  // D83: attribution is per-column now. The aliases column holds only
+  // user/authored phrasings (D61); the expansions column holds D80 derived
+  // variants. Say which one matched — the hit otherwise looks unrelated to
+  // the query when the body shows no highlight.
+  const hlTerms = (s: string | undefined): string[] => {
+    if (!s) return [];
+    const m = s.match(/\[([^\]]+)\]/g);
+    return m ? [...new Set(m.map((x) => x.slice(1, -1)))] : [];
+  };
+  const aliasTerms = hlTerms(r.alias_hl);
+  const expTerms = hlTerms(r.exp_hl);
+  // D83: attribute the hit to the column that matched, so `--explain` can
+  // trace an unexpected rank. Order matters: a body highlight is the most
+  // direct evidence, then an authored alias, then a derived expansion.
+  const matchedVia: MatchedVia = /\[[^\]]+\]/.test(snippet)
+    ? "body"
+    : aliasTerms.length > 0
+      ? "alias"
+      : expTerms.length > 0
+        ? "expansion"
+        : "other";
+  if (aliasTerms.length > 0 && aliases.length > 0) {
+    snippet += ` (aka: ${aliases.join(", ")})`;
+  } else if (expTerms.length > 0) {
+    snippet += ` (synonym: ${expTerms.join(", ")})`;
+  } else if (aliases.length > 0 && !/\[[^\]]+\]/.test(snippet)) {
+    // Match came through another column (tags/type/cjk) — the authored
+    // aliases are still honest context for the hit.
     snippet += ` (aka: ${aliases.join(", ")})`;
   }
   return {
@@ -57,6 +95,7 @@ function toHit(r: RawRow): SearchHit {
     type: r.type,
     tags: r.tags ? r.tags.split(",").filter(Boolean) : [],
     aliases,
+    matchedVia,
     snippet,
     score: r.score,
     updated_at: r.updated_at,
@@ -87,6 +126,9 @@ export function hitStateLabel(h: Pick<SearchHit, "scope_key" | "review_state">):
   return ` [${h.review_state || "draft"}]`;
 }
 
+// D83: BM25_WEIGHTS / DEFAULT_EXPANSIONS_WEIGHT live in ./weights.ts, not
+// here — smoke-pure.ts guards them and must stay free of any sqlite import.
+
 /** Optional diagnostics out-param for `search --explain` (D57). */
 export interface SearchStats {
   ftsQuery: string;
@@ -174,6 +216,12 @@ export function search(
     stopwords?: boolean;
     orJoin?: boolean;
     prefix?: boolean;
+    /**
+     * D83: override the BM25 weight of the `expansions` column. Omitted =
+     * `DEFAULT_EXPANSIONS_WEIGHT`. An ablation knob — it exists so the
+     * fixture can pick the value; not a per-call tuning surface.
+     */
+    expansionsWeight?: number;
   } = {},
 ): SearchHit[] {
   const qflags = { stopwords: opts.stopwords, orJoin: opts.orJoin, prefix: opts.prefix };
@@ -198,10 +246,12 @@ export function search(
   const typeFilter = opts.type ? ` AND m.type = ?` : "";
 
   const sql = `
-    SELECT m.id, m.scope_key, m.project_name, m.type, m.tags, m.aliases, m.updated_at,
+    SELECT m.id, m.scope_key, m.project_name, m.type, m.tags, m.aliases, m.expansions, m.updated_at,
            m.status, m.superseded_by, m.review_state, m.source, m.created_at,
            snippet(memories_fts, 0, '[', ']', ' ... ', 12) AS snippet,
-           bm25(memories_fts) AS score
+           highlight(memories_fts, 2, '[', ']') AS alias_hl,
+           highlight(memories_fts, 3, '[', ']') AS exp_hl,
+           bm25(memories_fts, ?, ?, ?, ?, ?, ?) AS score
     FROM memories_fts
     JOIN memories m ON m.rowid = memories_fts.rowid
     WHERE memories_fts MATCH ?${scopeFilter}${typeFilter}
@@ -214,6 +264,10 @@ export function search(
     project_name: string;
     type: string;
     tags: string;
+    aliases?: string;
+    expansions?: string;
+    alias_hl?: string;
+    exp_hl?: string;
     updated_at: number;
     status: string;
     superseded_by: string | null;
@@ -223,8 +277,15 @@ export function search(
     snippet: string;
     score: number;
   };
+  // D83: the weight vector is bound per statement, so it leads the parameter
+  // list (it appears in the SELECT list, before the WHERE's MATCH).
+  const weights =
+    opts.expansionsWeight === undefined
+      ? BM25_WEIGHTS
+      : BM25_WEIGHTS.map((w, i) => (i === 3 ? opts.expansionsWeight! : w));
   const fetchFts = (matchExpr: string): RawRow[] => {
-    const params: unknown[] = [matchExpr];
+    const params: unknown[] = [...weights];
+    params.push(matchExpr);
     if (opts.scopeKeys && opts.scopeKeys.length > 0) params.push(...opts.scopeKeys);
     if (opts.type) params.push(opts.type);
     params.push(fetchLimit);
@@ -244,7 +305,6 @@ export function search(
   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) {
@@ -255,20 +315,21 @@ export function search(
     // 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.
+    //
+    // The merged pool is deliberately wider than `limit` (each round already
+    // over-fetches by fetchLimit) so round-2 hits are never starved the way
+    // D79's slice-to-K starved them. #53: that headroom is for RANKING only —
+    // the return is still cut to the caller's `limit`, since `limit` is a cap
+    // on what every caller (tools, MCP, cli) receives, not a hint.
     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.
+  // expands variants into the indexed 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);
+  return resolveVisible(merged, limit, opts.stats);
 }
 
 export function list(

package/src/retrieve/weights.ts

@@ -0,0 +1,37 @@
+/**
+ * D83: BM25 column weights for the FTS index.
+ *
+ * Split out of `search.ts` deliberately: `smoke-pure.ts` must keep running
+ * with no SQLite dependency (its header says "pure-logic, no
+ * bun:sqlite"), and importing `search.ts` pulls in `store/db.ts` at module
+ * load. This module holds the tunable constant and nothing else, so the
+ * guard test can import it without opening a database.
+ *
+ * `expansions` (D80-derived synonym/translation variants) sits strictly below
+ * `aliases` so the preference is explicit rather than incidental: a body
+ * match outranks an expansion-only match, and a user-authored alias outranks
+ * a derived one. This is not cosmetic — measured on equal-length docs, at
+ * weight 1.0 a direct body match and an expansion-only match score
+ * *identically* (-3.983 vs -3.983), leaving the order to tiebreaks. Any
+ * weight < 1.0 breaks that tie in the right direction.
+ *
+ * The value is the highest one the checked-in fixture cannot distinguish from
+ * 1.0 (`scripts/retrieval-eval.ts`: R@1 0.750 / R@5 0.977 / MRR 0.857 hold
+ * from 1.0 down to 0.75; 0.5 already costs MRR, and below 0.35 R@5 breaks).
+ * So the ordering guarantee is free, and the fixture is the gate that keeps
+ * it honest — retune by re-running the sweep, not by feel.
+ *
+ * Known non-fix: this does NOT repair D80's `how do we ship` rank-8 case.
+ * That is per-column length norm (one variant among many in a long
+ * `expansions` field), not a weighting problem; see D83's update.
+ */
+
+/** Weight for the D80 `expansions` column. */
+export const DEFAULT_EXPANSIONS_WEIGHT = 0.75;
+
+/**
+ * Full weight vector for `memories_fts`, in declaration order.
+ * MUST stay in sync with FTS_SCHEMA column order in `store/db.ts`:
+ * `[content, tags, aliases, expansions, type, cjk]`.
+ */
+export const BM25_WEIGHTS: readonly number[] = [1, 1, 1, DEFAULT_EXPANSIONS_WEIGHT, 1, 1];

package/src/store/db.ts

@@ -48,6 +48,7 @@ CREATE TABLE IF NOT EXISTS memories (
   status       TEXT NOT NULL DEFAULT 'active',
   tags         TEXT NOT NULL DEFAULT '',
   aliases      TEXT NOT NULL DEFAULT '',
+  expansions   TEXT NOT NULL DEFAULT '',
   alias        TEXT NOT NULL DEFAULT '',
   target       TEXT NOT NULL DEFAULT '',
   content      TEXT NOT NULL,
@@ -66,6 +67,19 @@ CREATE INDEX IF NOT EXISTS idx_memories_scope_updated
   ON memories(scope_key, updated_at DESC);
 CREATE INDEX IF NOT EXISTS idx_memories_type ON memories(type);
 CREATE INDEX IF NOT EXISTS idx_memories_status ON memories(status);
+-- D81: the alias registry (retrieve/alias-memory.ts) runs on every search().
+-- The predicate is a full table scan without this — the rows carrying a
+-- defined alias pair are a tiny subset of a corpus that may be tens of
+-- thousands. A partial index keeps the lookup proportional to the number of
+-- aliases defined, not the size of the store.
+--
+-- No SCHEMA_VERSION bump: TABLE_SCHEMA runs on every db open (see db()), so
+-- existing installs pick this up on next open. Deliberately NOT a result
+-- cache — the alias registry must be re-read per query so a newly saved
+-- alias memory applies on the very next query. This index accelerates the
+-- lookup without caching results.
+CREATE INDEX IF NOT EXISTS idx_memories_alias
+  ON memories(scope_key) WHERE alias <> '' AND target <> '';
 `;
 
 // The `cjk` column holds pre-tokenized CJK unigrams+bigrams (see
@@ -78,6 +92,7 @@ CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
   content,
   tags,
   aliases,
+  expansions,
   type,
   cjk,
   scope_key UNINDEXED,
@@ -87,25 +102,25 @@ CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
 );
 
 CREATE TRIGGER IF NOT EXISTS memories_ai AFTER INSERT ON memories BEGIN
-  INSERT INTO memories_fts(rowid, content, tags, aliases, type, cjk, scope_key)
-  VALUES (new.rowid, new.content, new.tags, new.aliases, new.type, new.cjk, new.scope_key);
+  INSERT INTO memories_fts(rowid, content, tags, aliases, expansions, type, cjk, scope_key)
+  VALUES (new.rowid, new.content, new.tags, new.aliases, new.expansions, new.type, new.cjk, new.scope_key);
 END;
 
 CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
-  INSERT INTO memories_fts(memories_fts, rowid, content, tags, aliases, type, cjk, scope_key)
-  VALUES ('delete', old.rowid, old.content, old.tags, old.aliases, old.type, old.cjk, old.scope_key);
+  INSERT INTO memories_fts(memories_fts, rowid, content, tags, aliases, expansions, type, cjk, scope_key)
+  VALUES ('delete', old.rowid, old.content, old.tags, old.aliases, old.expansions, old.type, old.cjk, old.scope_key);
 END;
 
 CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
-  INSERT INTO memories_fts(memories_fts, rowid, content, tags, aliases, type, cjk, scope_key)
-  VALUES ('delete', old.rowid, old.content, old.tags, old.aliases, old.type, old.cjk, old.scope_key);
-  INSERT INTO memories_fts(rowid, content, tags, aliases, type, cjk, scope_key)
-  VALUES (new.rowid, new.content, new.tags, new.aliases, new.type, new.cjk, new.scope_key);
+  INSERT INTO memories_fts(memories_fts, rowid, content, tags, aliases, expansions, type, cjk, scope_key)
+  VALUES ('delete', old.rowid, old.content, old.tags, old.aliases, old.expansions, old.type, old.cjk, old.scope_key);
+  INSERT INTO memories_fts(rowid, content, tags, aliases, expansions, type, cjk, scope_key)
+  VALUES (new.rowid, new.content, new.tags, new.aliases, new.expansions, new.type, new.cjk, new.scope_key);
 END;
 `;
 
 /** Current index schema version. Bump when TABLE_SCHEMA/FTS_SCHEMA change. */
-const SCHEMA_VERSION = 8;
+const SCHEMA_VERSION = 9;
 
 function userVersion(d: AnyDatabase): number {
   const row = d.prepare("PRAGMA user_version").get() as { user_version: number };

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, alias, target, 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, expansions, 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,7 @@ const UPSERT_SQL = `
     status       = excluded.status,
     tags         = excluded.tags,
     aliases      = excluded.aliases,
+    expansions   = excluded.expansions,
     alias        = excluded.alias,
     target       = excluded.target,
     content      = excluded.content,
@@ -66,16 +67,20 @@ export function upsertFromFile(mf: MemoryFile): void {
 function writeRow(mf: MemoryFile, mtimeMs: number): void {
   const { fm, body, filePath } = mf;
   const tags = (fm.tags ?? []).join(",");
-  // D80 index-time expansion: curated synonym/translation variants for the
-  // memory's keywords are indexed in the aliases column (and therefore the
-  // CJK bigram column below), so any related word matches in round one.
-  // Derived at sync time — the Markdown file stays the source of truth.
+  // D80 index-time expansion, D83: curated synonym/translation variants for
+  // the memory's keywords are indexed in their own `expansions` column —
+  // never mixed into `aliases`, which holds only user/authored alternate
+  // phrasings (so `(aka: …)` attribution stays honest). The CJK bigram
+  // column still covers expansions, so CJK variants stay substring-
+  // searchable. Derived at sync time — the Markdown file stays the source
+  // of truth.
   const supplied = fm.aliases ?? [];
   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(",");
+  const aliases = supplied.join(",");
+  const expansions = auto.join(",");
   // D81: user-defined alias vocabulary (single nickname → referent pair).
   db().prepare(UPSERT_SQL).run(
     fm.id,
@@ -89,10 +94,11 @@ function writeRow(mf: MemoryFile, mtimeMs: number): void {
     fm.status,
     tags,
     aliases,
+    expansions,
     fm.alias ?? "",
     fm.target ?? "",
     body,
-    cjkIndexText(body + "\n" + tags + "\n" + aliases),
+    cjkIndexText(body + "\n" + tags + "\n" + aliases + "\n" + expansions),
     contentHash(body),
     fm.superseded_by ?? null,
     fm.source ?? "",

package/src/tools/ops.ts

@@ -143,7 +143,12 @@ export const memorySearchArgs = {
     .enum(["project", "personal", "both"])
     .optional()
     .describe("Which scope(s) to search. Default: both."),
-  type: z.string().optional().describe("Restrict to memories of this type (e.g. decision, preference, gotcha)."),
+  type: z
+    .enum(MEMORY_TYPE_TAXONOMY)
+    .optional()
+    .describe(
+      "Restrict to memories of this type. Closed taxonomy — a misspelled type is rejected, never silently empty.",
+    ),
   limit: z.number().int().min(1).max(50).optional().describe("Max results to return (default 8)."),
 };
 export type MemorySearchArgs = z.infer<z.ZodObject<typeof memorySearchArgs>>;
@@ -155,7 +160,12 @@ export const memoryListArgs = {
     .describe(
       "Which scope(s) to list. `project` = tied to this repo. `personal` = global across all your projects. `both` lists each scope's newest. Default: project.",
     ),
-  type: z.string().optional().describe("Only list memories of this type (e.g. decision, preference, gotcha)."),
+  type: z
+    .enum(MEMORY_TYPE_TAXONOMY)
+    .optional()
+    .describe(
+      "Only list memories of this type. Closed taxonomy — a misspelled type is rejected, never silently empty.",
+    ),
   limit: z.number().int().min(1).max(100).optional().describe("Max entries to list, newest first (default 20)."),
   include: z
     .enum(["active", "all"])