open-memex 0.7.0-alpha.1 → 0.7.0-alpha.3

package/AGENTS.md

@@ -102,7 +102,7 @@ The published `open-memex` bin points at `dist/cli.js` (compiled at publish time
 From a source checkout, `npm run cli` / `npm run mcp` still run `src/` directly
 with type-stripping — no build step needed for development.
 
-There is **no `npm test`** and no CI. Verification loop is: `npm run typecheck` + `smoke-pure.ts` + (if touching sqlite) `npm run cli -- reindex` against a scratch `MY_O_MEMORY_HOME`.
+There is **no `npm test`** and no CI. Verification loop is: `npm run typecheck` + `smoke-pure.ts` + (if touching sqlite) `npm run cli -- reindex` against a scratch `OPEN_MEMEX_HOME`.
 
 To load the plugin in opencode locally, `~/.config/opencode/opencode.jsonc` must have:
 ```
@@ -115,7 +115,7 @@ Restart opencode after any change — the plugin is not hot-reloaded.
 Storage root:
 - Windows: `%APPDATA%\open-memex\`
 - Linux/macOS: `$XDG_DATA_HOME/open-memex/` (fallback `~/.local/share/open-memex/`)
-- Override with `MY_O_MEMORY_HOME` (use this for tests to avoid clobbering real data).
+- Override with `OPEN_MEMEX_HOME` (use this for tests to avoid clobbering real data). The pre-rename `MY_O_MEMORY_HOME` is still honored as a fallback (D62).
 
 Layout: `memories/<scope_key>/<id>.md` (YAML frontmatter + body) + `index.db` (SQLite FTS5).
 
@@ -137,6 +137,15 @@ Every write path (tool, keyword hook, CLI `add`) must:
 3. Check `findDuplicates` (design §3.4): identical content is idempotent (return existing id); near-duplicates (similarity ≥ 0.8) warn but save — suggest `supersede` when the new content replaces the old.
 4. `writeMemoryFile` first, then `readMemoryFile` + `upsertFromFile` to keep FTS in sync.
 
+Capture-time aliases (D61): `memory_add`/`supersede` may carry up to 4
+`aliases` (alternate phrasings) into frontmatter; they index in their own FTS
+column. Only when `cfg.captureAliases` is on (init asks once, default on) —
+when off, passed aliases are dropped. Always pass them through
+`normalizeAliases`; the keyword-capture path (no agent in the loop) never
+invents aliases. Checkpoint-proposal guidance (propose, never auto-draft) is
+copy, not mechanism: keep the rubric wording in sync across the skill, the
+AGENTS.md hygiene footer, the MCP handshake, and the tool descriptions.
+
 ## Lifecycle invariants (design §3.3)
 
 - Statuses: `active → superseded | deprecated | retracted | archived`. Retrieval excludes `retracted`/`archived`, ranks `active` above `deprecated`.

package/CHANGELOG.md

@@ -9,6 +9,15 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+## Environment variable names (D62)
+
+- The override variables now answer to `OPEN_MEMEX_HOME` (storage root) and `OPEN_MEMEX_CONFIG` (config path). The pre-rename `MY_O_MEMORY_HOME` / `MY_O_MEMORY_CONFIG` names keep working as fallbacks — nothing to migrate, the data root itself does not move. `doctor` notes when the storage root came from the legacy variable.
+
+## Proactive capture: checkpoint proposals and aliases (D61)
+
+- At task checkpoints the agent now proposes instead of waiting to be asked: when a task wraps up, it offers 1–3 short candidate memories distilled from the session (decisions and their reasons, conventions, gotchas, approaches tried and abandoned) and saves only the ones you approve — approved inferences are marked `source: "inference"`. One memorability rubric and one search discipline (break the question into concepts, try several phrasings, check both scopes) are written into every guidance surface — the bundled skill, the AGENTS.md memory-hygiene footer, the MCP handshake, and the tool descriptions — so behavior is consistent across editors. Nothing is auto-drafted in the background; that posture waits on memory visibility.
+- Memories can carry up to 4 **aliases** — alternate phrasings, synonyms, other-language equivalents — stored in the memory file and indexed with it, so a differently-worded question still matches ("vacation days" finds the holiday policy; "节假日" too). `init` asks once (default on); `open-memex config set captureAliases false` turns it off. Existing memory files are untouched — the index rebuilds itself on first use.
+
 ## One plugin, both opencode generations (D60)
 
 - The native plugin now loads on **opencode 2** as well as opencode 1. `open-memex init --client opencode --global` writes both config spellings — the v1 `"plugin"` file entry and the v2 `"plugins"` directory entry — and each host reads its own. Previously an opencode 2 host silently skipped the plugin (a file entry is not a directory it can load), leaving no tools and no explanation.

package/README.md

@@ -373,7 +373,19 @@ Three ways memories get in:
   (or it saves on its own when you state a fact worth keeping) — it calls
   `memory_add`. The routing above is a heuristic; you can always say "save this
   to my personal memory" or use the CLI with `--scope` to be explicit.
-- **The CLI**: `open-memex add "…"` with optional `--scope` / `--tags` / `--type`.
+- **Checkpoint proposals**: when a task wraps up, the agent proposes 1–3 short
+  candidate memories distilled from the session — decisions and their reasons,
+  conventions, gotchas, approaches tried and abandoned — and saves only the
+  ones you approve. Nothing is written silently: no draft is created behind
+  your back.
+- **The CLI**: `open-memex add "…"` with optional `--scope` / `--tags` / `--type`
+  / `--aliases`.
+
+**Aliases.** Each saved memory can carry up to 4 alternate phrasings
+(synonyms, another language's equivalent) that are indexed with it, so a
+question worded differently still finds the memory — "vacation days" finds the
+holiday policy. `init` asks once whether to enable this (default on); turn it
+off any time with `open-memex config set captureAliases false`.
 
 **Redaction.** Wrap anything sensitive in `<private>…</private>` and it is
 stripped before saving. Recognized secrets (API keys, tokens, high-entropy
@@ -566,8 +578,9 @@ branches and PRs like any other file.
 
 Settings live in `~/.config/opencode/open-memex.jsonc` — the `opencode` in the
 path is historical; this one file is shared by every client. Override the config
-path with `MY_O_MEMORY_CONFIG` and the storage root with `MY_O_MEMORY_HOME`
-(legacy environment names from before the rename, still honored).
+path with `OPEN_MEMEX_CONFIG` and the storage root with `OPEN_MEMEX_HOME`
+(the pre-rename `MY_O_MEMORY_CONFIG` / `MY_O_MEMORY_HOME` names are still
+honored as fallbacks).
 
 Defaults:
 

package/README.zh-CN.md

@@ -254,7 +254,10 @@ open-memex uninstall --yes
 
 - **关键词触发**（仅 opencode 原生插件）：说 `remember …`、`note that …`、`don't forget …`、`TIL …`、`save this …`——中文 `记住…` / `记一下` / `记录一下` / `别忘了…`——这句话就被存下来，不需要任何工具调用。捕获默认进当前 **project**；`remember for me …`、`记住我…`、`替我记…`、`我觉得…`、`我喜欢…` 这类"这是关于我"的信号会改为进 **personal**；`我们决定…`、`帮我们记住…` 等团队语境仍留在项目里。
 - **助手主动保存**：在任何编辑器里，你让助手记住某件事（或者你陈述了一个值得记的事实、它自己判断该保存），它会调用 `memory_add`。上面的路由是启发式规则；你可以明说"存到我的个人记忆"，或用 CLI 加 `--scope` 明确指定。
-- **CLI**：`open-memex add "…"`，可选 `--scope` / `--tags` / `--type`。
+- **检查点提议**：一个任务收尾时，助手会提议 1–3 条从这轮工作里提炼的候选记忆——决定及其理由、约定、踩过的坑、走过又放弃的路——只有你点头的那几条才存。不会有任何东西在你不知情时被写下来。
+- **CLI**：`open-memex add "…"`，可选 `--scope` / `--tags` / `--type` / `--aliases`。
+
+**别名。** 每条记忆可以带最多 4 个换一种说法（同义词、另一种语言的对应词），和记忆一起进索引，这样问法不同也能找到——比如搜 "vacation days" 能找到假期政策那条。`init` 时会问一次是否开启（默认开）；随时可用 `open-memex config set captureAliases false` 关掉。
 
 **脱敏。** 把敏感内容包在 `<private>…</private>` 里，它在保存前会被整段剥离。识别出的密钥（API key、token、高熵凭证）会被就地掩码——保留前 4 个字符（让你能认出是哪个 key），其余替换——记忆仍会保存。随时安全地预览一句话会被捕获成什么样：
 
@@ -388,7 +391,7 @@ npm install -g open-memex@latest   # 或 @alpha
 
 ## 配置
 
-设置放在 `~/.config/opencode/open-memex.jsonc`——路径里的 `opencode` 是历史名；这一个文件由所有客户端共享。用 `MY_O_MEMORY_CONFIG` 覆盖配置路径，用 `MY_O_MEMORY_HOME` 覆盖存储根目录（改名之前留下的旧环境变量名，仍然有效）。
+设置放在 `~/.config/opencode/open-memex.jsonc`——路径里的 `opencode` 是历史名；这一个文件由所有客户端共享。用 `OPEN_MEMEX_CONFIG` 覆盖配置路径，用 `OPEN_MEMEX_HOME` 覆盖存储根目录（改名之前的旧变量名 `MY_O_MEMORY_CONFIG` / `MY_O_MEMORY_HOME` 仍然有效，作为回退）。
 
 默认值：
 

package/dist/cli.js

@@ -10,7 +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, hitStateLabel } from "./retrieve/search.js";
-import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
+import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, normalizeAliases, } from "./store/markdown.js";
 import { loadConfig } from "./config.js";
 import { paths, projectRoot } from "./paths.js";
 import { redact } from "./redact.js";
@@ -54,18 +54,25 @@ Example:
   open-memex search "deploy checklist" --scope both`,
     add: `Save a fact, preference, decision, or note to local memory.
 
-Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2] [--aliases "a;b"]
 
 Flags:
-  --scope   project (default) or personal (personal never leaves this machine)
-  --type    memory type (default: fact)
-  --tag     comma-separated tags
+  --scope    project (default) or personal (personal never leaves this machine)
+  --type     memory type (default: fact)
+  --tag      comma-separated tags
+  --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)
 
 Example:
   open-memex add "We deploy on Fridays" --scope project --tag process`,
     supersede: `Replace a memory with a newer version. The old one is kept as history.
 
-Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
+Usage: open-memex supersede <id> "new content" [--type T] [--tag t1,t2] [--aliases "a;b"]
+
+Without --aliases, the old memory's aliases carry over.
 
 Example:
   open-memex supersede 01ABC "We deploy on Thursdays now"`,
@@ -849,6 +856,18 @@ async function main() {
                     .map((t) => t.trim())
                     .filter(Boolean)
                 : [],
+            // D61: --aliases "phrase one; phrase two" (comma also accepted; use
+            // ; when an alias itself contains a comma). A bare --aliases with no
+            // value makes parseFlags yield "true" — treat that as absent. Stored
+            // only when the install enables capture aliases, redacted like content.
+            ...(typeof flags.aliases === "string" && flags.aliases !== "true" && cfg.captureAliases
+                ? {
+                    aliases: normalizeAliases(flags.aliases
+                        .split(/[;,]/)
+                        .map((a) => redact(a.trim(), cfg.redactPatterns).content)
+                        .filter(Boolean)),
+                }
+                : {}),
             source: "cli",
             created_at: rfc,
             updated_at: rfc,
@@ -888,6 +907,12 @@ async function main() {
                 tags: flags.tag
                     ? flags.tag.split(",").map((t) => t.trim()).filter(Boolean)
                     : undefined,
+                aliases: typeof flags.aliases === "string" && flags.aliases !== "true" && cfg.captureAliases
+                    ? normalizeAliases(flags.aliases
+                        .split(/[;,]/)
+                        .map((a) => redact(a.trim(), cfg.redactPatterns).content)
+                        .filter(Boolean))
+                    : undefined,
                 source: "cli",
             });
             upsertFromFile(oldMf);

package/dist/config.js

@@ -6,6 +6,7 @@ export const DEFAULT_CONFIG = {
     maxProfileItems: 5,
     injectOnFirstTurn: true,
     keywordCaptureEnabled: true,
+    captureAliases: true,
     keywordPatterns: [
         "^\\s*remember(?!\\s+for\\s+me)(?:\\s+that)?[:,]?\\s+(.+)$",
         "^\\s*(?:please\\s+)?(?:note|don'?t\\s+forget)(?:\\s+that)?[:,]?\\s+(.+)$",
@@ -45,9 +46,13 @@ function stripJsonComments(raw) {
     out = out.replace(/,(\s*[}\]])/g, "$1");
     return out;
 }
-/** Where `config set` / interactive `init` persist. Respects MY_O_MEMORY_CONFIG. */
+/**
+ * Where `config set` / interactive `init` persist. Respects OPEN_MEMEX_CONFIG
+ * (D62); MY_O_MEMORY_CONFIG is the pre-rename fallback, still honored.
+ */
 export function configFilePath() {
-    return (process.env.MY_O_MEMORY_CONFIG ??
+    return (process.env.OPEN_MEMEX_CONFIG ??
+        process.env.MY_O_MEMORY_CONFIG ??
         path.join(os.homedir(), ".config", "opencode", "open-memex.jsonc"));
 }
 function toBool(v) {
@@ -79,6 +84,7 @@ export const SETTABLE_KEYS = {
     maxProfileItems: toNonNegInt,
     injectOnFirstTurn: toBool,
     keywordCaptureEnabled: toBool,
+    captureAliases: toBool,
     memoryDir: toRelativeDir,
     "sync.autoPull": toBool,
     logLevel: (v) => {
@@ -109,6 +115,7 @@ export function saveConfig(patch) {
 /** Path of the config file in effect, or null when using built-in defaults. */
 export function configSource() {
     const candidates = [
+        process.env.OPEN_MEMEX_CONFIG,
         process.env.MY_O_MEMORY_CONFIG,
         path.join(os.homedir(), ".config", "opencode", "open-memex.jsonc"),
         path.join(os.homedir(), ".config", "opencode", "open-memex.json"),

package/dist/distill-agents.js

@@ -57,7 +57,7 @@ export function distillAgentsMarkdown(opts) {
     // (D53: the checkpoint mechanism is gone).
     lines.push(`### Memory hygiene (open-memex)`);
     lines.push(``);
-    lines.push(`- When you finish a task the user would describe in one sentence, distill`, `  the session: propose 1–3 short memories capturing the useful`, `  conclusion — what was learned or decided, how an issue was resolved, what`, `  to avoid, where the authoritative doc lives — not the raw transcript.`, `  Save nothing without user approval.`, `- If the knowledge already lives in project docs, save a \`reference\` memory`, `  pointing at the doc instead of copying it.`);
+    lines.push(`- When you finish a task the user would describe in one sentence, distill`, `  the session: propose 1–3 short memories capturing the useful`, `  conclusion — what was learned or decided, how an issue was resolved, what`, `  to avoid, where the authoritative doc lives — not the raw transcript.`, `  Save nothing without user approval.`, `  Worth keeping: decisions and their reasons, preferences, conventions,`, `  gotchas, approaches tried and abandoned. Not worth keeping: one-off task`, `  details or anything re-derivable from the code.`, `- If the knowledge already lives in project docs, save a \`reference\` memory`, `  pointing at the doc instead of copying it.`, `- When saving via \`memory_add\`, attach 2–4 aliases (alternate phrasings,`, `  synonyms, equivalents in the user's other language) when the install has`, `  capture aliases enabled — they make reworded questions find the memory.`);
     lines.push(``);
     return lines.join("\n");
 }

package/dist/doctor.js

@@ -8,7 +8,7 @@ import path from "node:path";
 import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.js";
-import { paths } from "./paths.js";
+import { paths, homeOverride } from "./paths.js";
 import { resolveCwdScope } from "./scope.js";
 import { db, backendName } from "./store/db.js";
 import { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.js";
@@ -54,7 +54,13 @@ function storageCheck() {
     try {
         const p = paths();
         fs.accessSync(p.memories, fs.constants.W_OK);
-        return { name: "storage", ok: true, detail: `${p.root} (writable)` };
+        // D62: when the root came from the legacy env var, say so (still ok —
+        // the fallback is supported, doctor just names the current one).
+        const via = homeOverride()?.via;
+        const note = via === "MY_O_MEMORY_HOME"
+            ? " (via legacy MY_O_MEMORY_HOME — OPEN_MEMEX_HOME is the current name)"
+            : "";
+        return { name: "storage", ok: true, detail: `${p.root} (writable)${note}` };
     }
     catch (err) {
         return { name: "storage", ok: false, detail: String(err) };
@@ -559,9 +565,11 @@ export async function runDoctor() {
 function legacyCheck() {
     const name = "legacy my-o-memory";
     const found = [];
-    const envHome = process.env.MY_O_MEMORY_HOME;
+    // D62: the override may arrive via either env var name; check the value
+    // in effect, not just the legacy one.
+    const envHome = homeOverride()?.dir;
     if (envHome && envHome.includes(LEGACY_PACKAGE_NAME))
-        found.push(`MY_O_MEMORY_HOME points at a pre-rename dir (${envHome}) — unset it, then merge old data with \`open-memex migrate --to-v2\``);
+        found.push(`memory home points at a pre-rename dir (${envHome}) — unset it, then merge old data with \`open-memex migrate --to-v2\``);
     const root = paths().root;
     const legacyDir = path.join(path.dirname(root), LEGACY_PACKAGE_NAME);
     if (fs.existsSync(legacyDir) && fs.statSync(legacyDir).isDirectory())

package/dist/init.js

@@ -805,6 +805,11 @@ export async function initProject(opts) {
         const injectOnFirstTurn = await askBool("Inject relevant memories when a session starts?", DEFAULT_CONFIG.injectOnFirstTurn);
         if (injectOnFirstTurn !== DEFAULT_CONFIG.injectOnFirstTurn)
             patch.injectOnFirstTurn = injectOnFirstTurn;
+        // D61: capture-time aliases — agents attach alternate phrasings to each
+        // memory so differently-worded questions still find it.
+        const captureAliases = await askBool("Attach alternate phrasings (aliases) to memories so reworded questions still find them?", DEFAULT_CONFIG.captureAliases);
+        if (captureAliases !== DEFAULT_CONFIG.captureAliases)
+            patch.captureAliases = captureAliases;
         if (Object.keys(patch).length > 0) {
             const file = saveConfig(patch);
             console.log(`  + settings saved to ${file} (change later with \`open-memex config set <key> <value>\`)`);

package/dist/mcp.js

@@ -85,9 +85,10 @@ memory_resolve, memory_pr_status — always call them by these full names.
   docs, save it as type "reference" pointing at the doc instead of copying it.
   Long-form notes are fine ONLY when the user explicitly asks to save one.
 - Before asking the user about past decisions, conventions, or preferences they
-  may have told you before, call memory_search first — try a few keyword
-  variants (including the user's own language) when the first search comes up
-  empty.
+  may have told you before, call memory_search first — search well: break the
+  question into its concepts and try 2–3 phrasings per concept (synonyms, the
+  user's other language, shorter keyword forms), and check the other scope too,
+  before concluding nothing is stored.
 - Memories default to this project's scope; use the personal scope for facts
   about the user that hold across all projects. When a saved fact becomes
   outdated, call memory_supersede (find the old memory's id with memory_search
@@ -141,9 +142,15 @@ export async function runMcpServer() {
     // D53: session-start outbox state, pushed. The stdio server starts fresh per
     // session, so construction-time state ≈ session-start state.
     const n = outboxDraftCount(scope.key);
-    const instructions = n > 0
+    // D61: the alias guidance rides the handshake only when the install
+    // enables capture aliases — otherwise agents would attach aliases the
+    // server then drops.
+    const aliasGuidance = cfg.captureAliases
+        ? "\n- When you save a memory, attach 2–4 aliases via memory_add's aliases parameter: alternate phrasings, synonyms, equivalents in the user's other language. They are indexed with the memory so a differently-worded question still finds it."
+        : "";
+    const instructions = (n > 0
         ? `${SERVER_INSTRUCTIONS}\n\nSession start: the project outbox has ${n} draft${n === 1 ? "" : "s"} waiting for review — call memory_status to see them.`
-        : SERVER_INSTRUCTIONS;
+        : SERVER_INSTRUCTIONS) + aliasGuidance;
     const server = new McpServer({ name: "open-memex", version: SERVER_VERSION }, { instructions });
     server.registerTool("memory_add", {
         description: TOOL_DESCRIPTIONS.memory_add,

package/dist/paths.js

@@ -2,9 +2,23 @@ import path from "node:path";
 import fs from "node:fs";
 import os from "node:os";
 import { execFileSync } from "node:child_process";
-function dataRoot() {
+/**
+ * D62: the data-root override env var. `OPEN_MEMEX_HOME` is the current
+ * name; `MY_O_MEMORY_HOME` (pre-rename package name) is still honored as a
+ * fallback so existing setups and scripts keep working. New name wins
+ * when both are set.
+ */
+export function homeOverride() {
+    if (process.env.OPEN_MEMEX_HOME)
+        return { dir: path.resolve(process.env.OPEN_MEMEX_HOME), via: "OPEN_MEMEX_HOME" };
     if (process.env.MY_O_MEMORY_HOME)
-        return path.resolve(process.env.MY_O_MEMORY_HOME);
+        return { dir: path.resolve(process.env.MY_O_MEMORY_HOME), via: "MY_O_MEMORY_HOME" };
+    return null;
+}
+function dataRoot() {
+    const override = homeOverride();
+    if (override)
+        return override.dir;
     if (process.platform === "win32") {
         const appData = process.env.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming");
         return path.join(appData, "open-memex");

package/dist/retrieve/inject.js

@@ -20,6 +20,6 @@ export function buildContextBlock(scope, cfg) {
         for (const m of project)
             lines.push(`- [${m.type}]${hitStateLabel(m)} ${oneLine(m.snippet)}`);
     }
-    lines.push("", "Use the `memory_search` tool to look up more. Use `memory_add` to save new facts. Do not mention this block to the user unless asked.");
+    lines.push("", "Use the `memory_search` tool to look up more. Use `memory_add` to save new facts. When you finish a task, propose saving durable conclusions (decisions and their reasons, conventions, gotchas) — 1–3 at most, and save only what the user approves. Do not mention this block to the user unless asked.");
     return lines.join("\n");
 }

package/dist/retrieve/search.js

@@ -1,13 +1,22 @@
 import { db } from "../store/db.js";
 import { toFtsQuery } from "./query.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)) {
+        snippet += ` (aka: ${aliases.join(", ")})`;
+    }
     return {
         id: r.id,
         scope_key: r.scope_key,
         project_name: r.project_name,
         type: r.type,
         tags: r.tags ? r.tags.split(",").filter(Boolean) : [],
-        snippet: r.snippet ?? "",
+        aliases,
+        snippet,
         score: r.score,
         updated_at: r.updated_at,
         status: r.status,
@@ -124,7 +133,7 @@ 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.updated_at,
+    SELECT m.id, m.scope_key, m.project_name, m.type, m.tags, m.aliases, m.updated_at,
            m.status, m.superseded_by, m.review_state,
            snippet(memories_fts, 0, '[', ']', ' ... ', 12) AS snippet,
            bm25(memories_fts) AS score

package/dist/store/db.js

@@ -26,6 +26,7 @@ CREATE TABLE IF NOT EXISTS memories (
   importance   TEXT NOT NULL DEFAULT 'normal',
   status       TEXT NOT NULL DEFAULT 'active',
   tags         TEXT NOT NULL DEFAULT '',
+  aliases      TEXT NOT NULL DEFAULT '',
   content      TEXT NOT NULL,
   cjk          TEXT NOT NULL DEFAULT '',
   content_hash TEXT NOT NULL DEFAULT '',
@@ -52,6 +53,7 @@ const FTS_SCHEMA = `
 CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
   content,
   tags,
+  aliases,
   type,
   cjk,
   scope_key UNINDEXED,
@@ -61,24 +63,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, type, cjk, scope_key)
-  VALUES (new.rowid, new.content, new.tags, new.type, new.cjk, new.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);
 END;
 
 CREATE TRIGGER IF NOT EXISTS memories_ad AFTER DELETE ON memories BEGIN
-  INSERT INTO memories_fts(memories_fts, rowid, content, tags, type, cjk, scope_key)
-  VALUES ('delete', old.rowid, old.content, old.tags, old.type, old.cjk, old.scope_key);
+  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);
 END;
 
 CREATE TRIGGER IF NOT EXISTS memories_au AFTER UPDATE ON memories BEGIN
-  INSERT INTO memories_fts(memories_fts, rowid, content, tags, type, cjk, scope_key)
-  VALUES ('delete', old.rowid, old.content, old.tags, old.type, old.cjk, old.scope_key);
-  INSERT INTO memories_fts(rowid, content, tags, type, cjk, scope_key)
-  VALUES (new.rowid, new.content, new.tags, new.type, new.cjk, new.scope_key);
+  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);
 END;
 `;
 /** Current index schema version. Bump when TABLE_SCHEMA/FTS_SCHEMA change. */
-const SCHEMA_VERSION = 6;
+const SCHEMA_VERSION = 7;
 function userVersion(d) {
     const row = d.prepare("PRAGMA user_version").get();
     return row.user_version;

package/dist/store/lifecycle.js

@@ -171,6 +171,8 @@ export function supersede(oldId, input) {
         id: ulid(),
         type: input.type ?? oldMf.fm.type,
         tags: input.tags ?? oldMf.fm.tags,
+        // D61: aliases carry forward unless the caller replaces them.
+        aliases: input.aliases ?? oldMf.fm.aliases,
         source: input.source ?? oldMf.fm.source,
         status: "active",
         created_at: now,

package/dist/store/markdown.js

@@ -155,6 +155,12 @@ export function normalizeFrontmatter(raw) {
         tags: Array.isArray(raw.tags)
             ? raw.tags.filter((t) => typeof t === "string")
             : [],
+        ...(Array.isArray(raw.aliases)
+            ? (() => {
+                const aliases = normalizeAliases(raw.aliases.filter((a) => typeof a === "string"));
+                return aliases.length > 0 ? { aliases } : {};
+            })()
+            : {}),
         source: typeof raw.source === "string" ? raw.source : "",
         created_at: msToRfc3339(timeToMs(raw.created_at)),
         updated_at: msToRfc3339(timeToMs(raw.updated_at)),
@@ -170,11 +176,43 @@ export function normalizeFrontmatter(raw) {
         review_history: asReviewHistory(raw.review_history),
     };
 }
+/**
+ * D61: normalize capture-time aliases — trim, drop empties, dedupe
+ * (case-insensitive), cap at 4. Bad aliases are noise, never an error.
+ * Shared by the tool ops, the CLI, and frontmatter parsing.
+ */
+export function normalizeAliases(input) {
+    if (!input)
+        return [];
+    const seen = new Set();
+    const out = [];
+    for (const a of input) {
+        const t = a.trim();
+        if (!t)
+            continue;
+        const k = t.toLowerCase();
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(t);
+        if (out.length >= 4)
+            break;
+    }
+    return out;
+}
 export function isTaxonomyType(t) {
     return TAXONOMY.has(t);
 }
 export function serialize(fm, body) {
-    const yml = yaml.dump(fm, { lineWidth: -1, quotingType: '"' });
+    // D61: an empty aliases list is noise in the file — drop the key entirely
+    // rather than relying on the YAML dumper to skip an undefined value
+    // (parse only sets the field when non-empty; keep both ends consistent).
+    let out = fm;
+    if (fm.aliases && fm.aliases.length === 0) {
+        out = { ...fm };
+        delete out.aliases;
+    }
+    const yml = yaml.dump(out, { lineWidth: -1, quotingType: '"' });
     return `---\n${yml}---\n\n${body.trimEnd()}\n`;
 }
 /** Raw frontmatter parse (no normalization) — for migration tooling. */

package/dist/store/sync.js

@@ -7,8 +7,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, 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, 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,
@@ -19,6 +19,7 @@ const UPSERT_SQL = `
     importance   = excluded.importance,
     status       = excluded.status,
     tags         = excluded.tags,
+    aliases      = excluded.aliases,
     content      = excluded.content,
     cjk          = excluded.cjk,
     content_hash = excluded.content_hash,
@@ -53,7 +54,8 @@ export function upsertFromFile(mf) {
 function writeRow(mf, mtimeMs) {
     const { fm, body, filePath } = mf;
     const tags = (fm.tags ?? []).join(",");
-    db().prepare(UPSERT_SQL).run(fm.id, fm.scope_key, fm.scope, fm.visibility, fm.project_name, fm.type, fm.role, fm.importance, fm.status, tags, body, cjkIndexText(body + "\n" + tags), contentHash(body), fm.superseded_by ?? null, fm.source ?? "", filePath, mtimeMs, timeToMs(fm.created_at), timeToMs(fm.updated_at), fm.review_state ?? "draft");
+    const aliases = (fm.aliases ?? []).join(",");
+    db().prepare(UPSERT_SQL).run(fm.id, fm.scope_key, fm.scope, fm.visibility, fm.project_name, fm.type, fm.role, fm.importance, fm.status, tags, aliases, body, cjkIndexText(body + "\n" + tags + "\n" + aliases), contentHash(body), fm.superseded_by ?? null, fm.source ?? "", filePath, mtimeMs, timeToMs(fm.created_at), timeToMs(fm.updated_at), fm.review_state ?? "draft");
 }
 export function deleteFromIndex(id) {
     db().prepare(`DELETE FROM memories WHERE id = ?`).run(id);

package/dist/tools/ops.js

@@ -10,7 +10,7 @@ import fs from "node:fs";
 import { z } from "zod";
 import { PERSONAL_SCOPE } from "../scope.js";
 import { search, list, hitStateLabel } from "../retrieve/search.js";
-import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, MEMORY_TYPE_TAXONOMY, } from "../store/markdown.js";
+import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, MEMORY_TYPE_TAXONOMY, normalizeAliases, } from "../store/markdown.js";
 import { upsertFromFile, deleteFromIndex } from "../store/sync.js";
 import { findDuplicates, supersede } from "../store/lifecycle.js";
 import { db } from "../store/db.js";
@@ -35,8 +35,8 @@ export async function withOutboxNote(scopeKey, p, reviewHint) {
 }
 /** LLM-facing tool descriptions, shared by the opencode plugin and the MCP server. */
 export const TOOL_DESCRIPTIONS = {
-    memory_add: "Save a fact, preference, decision, or note to persistent local memory. Call this PROACTIVELY whenever the user shares something worth remembering across sessions — project conventions, tool choices, personal preferences, decisions made, error fixes and their causes. Do not wait to be asked. Keep each memory to one self-contained statement. Default scope is the current project; use the personal scope for facts about the user that apply across all projects.",
-    memory_search: "Search persistent memory by keyword (BM25 full-text). Returns matching memories from the current project and/or personal scope. Call before asking the user about past decisions, conventions, or preferences they may have told you before — try a few keyword variants, including the user's own language, when the first search comes up empty.",
+    memory_add: "Save a fact, preference, decision, or note to persistent local memory. Call this PROACTIVELY whenever the user shares something worth remembering across sessions — project conventions, tool choices, personal preferences, decisions made, error fixes and their causes. Worth saving: decisions and their reasons, preferences, conventions, gotchas, approaches tried and abandoned. Not worth saving: one-off task details or anything re-derivable from the code. Do not wait to be asked. For facts you infer yourself rather than the user stating, propose them first and save only on approval. Keep each memory to one self-contained statement; attach aliases when the parameter is available. Default scope is the current project; use the personal scope for facts about the user that apply across all projects.",
+    memory_search: "Search persistent memory by keyword (BM25 full-text). Returns matching memories from the current project and/or personal scope. Call before asking the user about past decisions, conventions, or preferences they may have told you before. Search well: break the question into its concepts and try 2–3 phrasings per concept — synonyms, the user's other language, shorter keyword forms — and check the other scope too, before concluding nothing is stored.",
     memory_list: "List memories in a scope, newest first. Useful for browsing what is remembered, or verifying that a save landed.",
     memory_supersede: "Replace an existing memory with a newer version. The old memory is kept as history (status: superseded) and retrieval returns the new one. Use when a saved fact becomes outdated and should be replaced rather than duplicated.",
     memory_forget: "Delete a memory by id. Use when the user asks to forget something.",
@@ -52,6 +52,10 @@ export const scopeArg = z
     .enum(["project", "personal", "user"])
     .optional()
     .describe("Memory scope. `project` = tied to this repo. `personal` = global across all your projects. `user` is a deprecated alias of `personal`. Default: project.");
+export const aliasesArg = z
+    .array(z.string())
+    .optional()
+    .describe("Optional: alternate phrasings of this fact — synonyms, another way a question might be worded, equivalents in the user's other language (e.g. 节假日 for 'public holidays'). They are indexed with the memory so differently-worded questions still match. Only used when the install has capture aliases enabled (init default). Send at most 4; extras and blanks are dropped silently, never an error.");
 export const memoryAddArgs = {
     content: z.string().min(1).describe("The fact to remember. One idea per memory."),
     type: z
@@ -60,6 +64,7 @@ export const memoryAddArgs = {
         .describe("Category of memory. Default: fact."),
     scope: scopeArg,
     tags: z.array(z.string()).optional().describe("Optional tags for filtering."),
+    aliases: aliasesArg,
     source: z
         .string()
         .optional()
@@ -90,6 +95,7 @@ export const memorySupersedeArgs = {
         .optional()
         .describe("Category of the new memory. Defaults to the old memory's type."),
     tags: z.array(z.string()).optional().describe("Optional tags for the new memory."),
+    aliases: aliasesArg,
 };
 export const memoryForgetArgs = {
     id: z.string().min(1),
@@ -149,6 +155,7 @@ function buildFrontmatter(s, body) {
         importance: "normal",
         status: "active",
         tags: body.tags,
+        ...(body.aliases && body.aliases.length > 0 ? { aliases: body.aliases } : {}),
         source: body.source,
         created_at: rfc,
         updated_at: rfc,
@@ -180,6 +187,13 @@ export async function addMemory(getScope, cfg, args) {
     const fm = buildFrontmatter(s, {
         type: args.type ?? "fact",
         tags: args.tags ?? [],
+        // D61: aliases are stored only when the install enables them (init
+        // asks once, default on); normalize caps at 4 and drops junk silently.
+        // Aliases pass through the same redaction as content (write-path
+        // invariant) — an alias carrying a token gets masked, not stored raw.
+        aliases: cfg.captureAliases
+            ? normalizeAliases((args.aliases ?? []).map((a) => redact(a, cfg.redactPatterns).content))
+            : [],
         source: args.source ?? "tool",
     });
     const { filePath } = writeMemoryFile(fm, redacted);
@@ -230,6 +244,11 @@ export async function supersedeMemory(cfg, args) {
             body: redacted,
             type: args.type,
             tags: args.tags,
+            // D61: explicit aliases replace the carried-over ones, only when
+            // the install enables capture aliases. Same redaction as content.
+            aliases: cfg.captureAliases && args.aliases !== undefined
+                ? normalizeAliases(args.aliases.map((a) => redact(a, cfg.redactPatterns).content))
+                : undefined,
             source: "tool",
         });
         upsertFromFile(oldMf);