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

package/AGENTS.md

@@ -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,11 @@ the `@alpha` tag are development snapshots and are not listed individually.
 
 ## [Unreleased]
 
+## 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

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），其余替换——记忆仍会保存。随时安全地预览一句话会被捕获成什么样：
 

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+(.+)$",
@@ -79,6 +80,7 @@ export const SETTABLE_KEYS = {
     maxProfileItems: toNonNegInt,
     injectOnFirstTurn: toBool,
     keywordCaptureEnabled: toBool,
+    captureAliases: toBool,
     memoryDir: toRelativeDir,
     "sync.autoPull": toBool,
     logLevel: (v) => {

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/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/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);

package/docs/V2-DESIGN.md

@@ -1250,6 +1250,60 @@ requirement: personal data never touches third-party services). Benchmarks to tr
   name entries installed via `opencode plugin add` are recorded but not
   path-checked). Field-verified on real hosts 1.18.34 and 2.0.1.
 
+- **D61 — proactive capture cluster: propose posture, a shared
+  memorability rubric, and capture-time aliasing (retrieval layer 3).**
+  Builds on the "proactive capture" open question below and the
+  CHECKPOINT_PROACTIVITY / MEMORY_VISIBILITY notes. Three pieces,
+  shipped together because they are one user-visible behavior — the
+  agent capturing well without being asked each time:
+  (1) **Posture: propose, not auto-draft.** When the agent finishes a
+  task the user would describe in one sentence, it proposes 1–3 short
+  candidate memories in the conversation and saves only what the user
+  approves (approved inferences are saved with `source: "inference"`,
+  the §3.5 convention). The guidance is text, not mechanism — the same
+  rubric written into the bundled skill, the AGENTS.md memory-hygiene
+  footer, the MCP handshake instructions, the `memory_add` tool
+  description, and a one-line summary in the injected context block —
+  with throttling rules (task end / decision / gotcha moments only, no
+  mid-task interruptions, never re-propose a declined candidate). The
+  auto-draft posture (write first, surface later in bulk) is deferred
+  until memory visibility ships: without an inventory the user can
+  read, silent drafting reads as surveillance, so D61 deliberately
+  does not build it.
+  (2) **Rubric.** One memorability standard, shared by this live
+  capture path and the future retrospective-distillation group:
+  worth saving — decisions and their reasons, preferences,
+  conventions, gotchas, approaches tried and abandoned, and
+  `reference` memories pointing at authoritative docs; not worth
+  saving — one-off task details and anything re-derivable from the
+  code. Retrieval robustness layer 2 (agent-side query expansion:
+  decompose into concepts, 2–3 phrasings each, cross-language, check
+  the other scope) ships as guidance in the same texts, on top of the
+  D56 server-side layer 1.
+  (3) **Capture-time aliases (layer 3).** When a memory is saved, the
+  agent attaches up to 4 aliases — alternate phrasings, synonyms,
+  equivalents in the user's other language — stored in a new optional
+  frontmatter field `aliases` (additive; files without it parse
+  unchanged, `schema_version` stays 2) and indexed in their own FTS
+  column (index schema 6→7, rebuilt from markdown automatically).
+  Gated by a new `captureAliases` config flag (init asks once, default
+  on, `config set captureAliases off` opts out): when off, aliases
+  passed by agents are dropped and the alias guidance disappears from
+  the MCP handshake. Turning it off never rewrites existing memory
+  files — aliases already stored stay stored and searchable, and
+  supersede keeps carrying them forward; the flag gates new captures
+  only (no silent data destruction). Aliases pass through the same
+  secret redaction as memory content before they are stored, and a
+  malformed alias list (blanks, more than 4) is normalized silently —
+  never a tool-call error.
+  Keyword capture (no agent in the loop) leaves
+  aliases empty rather than inventing them; `supersede` carries
+  aliases forward unless the caller replaces them. Aliases are
+  normalized (trim, case-insensitive dedupe, cap 4) and bad ones cost
+  nothing — they rank as bm25 noise, never an error. Retrospective
+  distillation over host transcripts stays its own group; it will
+  reuse this rubric.
+
 ## Open Questions
 
 _All resolved — see D10 (rename), D11 (type/role split), D12 (explicit pull)._

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-memex",
-  "version": "0.7.0-alpha.1",
+  "version": "0.7.0-alpha.2",
   "description": "Local-first memory layer and protocol for AI coding agents. Markdown source of truth, SQLite FTS5 index, zero cloud.",
   "type": "module",
   "license": "Apache-2.0",

package/scripts/smoke-pure.ts

@@ -1,6 +1,6 @@
 // Quick smoke test — runs the pure-logic modules (no bun:sqlite dependency).
 // Usage:  node --experimental-strip-types scripts\smoke-pure.ts
-import { parse, serialize, ulid, normalizeFrontmatter, msToRfc3339, timeToMs, parseRawFrontmatter, type Frontmatter } from "../src/store/markdown.ts";
+import { parse, serialize, ulid, normalizeFrontmatter, msToRfc3339, timeToMs, parseRawFrontmatter, normalizeAliases, type Frontmatter } from "../src/store/markdown.ts";
 import { planConversion, isV2File, migrateV2 } from "../src/store/v2migrate.ts";
 import { redact, findSecret } from "../src/redact.ts";
 import { detectKeywords } from "../src/capture/keywords.ts";
@@ -10,6 +10,8 @@ import { cjkIndexText, cjkQueryExpr, hasCjk } from "../src/retrieve/cjk.ts";
 import { toFtsQuery } from "../src/retrieve/query.ts";
 import { contentHash, similarity, NEAR_DUP_THRESHOLD } from "../src/store/lifecycle.ts";
 import { userMcpConfigPath, mergeServerEntry, detectInstalledClients, mergePluginEntry, mergeV2PluginEntry, removeV2PluginEntry, opencodeGlobalConfigPath, printManualEntryHint, parseJsonConfig, removeServerEntry, removePluginEntry, removeInstructionsSection, LEGACY_PACKAGE_NAME, shouldInstallSkill } from "../src/init.ts";
+import { z } from "zod";
+import { memoryAddArgs } from "../src/tools/ops.ts";
 
 let fails = 0;
 function ok(name: string, cond: boolean, info?: unknown) {
@@ -57,6 +59,28 @@ ok("id survives", parsed?.fm.id === a);
 ok("tags survive", JSON.stringify(parsed?.fm.tags) === '["hello","world"]');
 ok("body survives", parsed?.body.trim() === body);
 
+console.log("== capture aliases (D61) ==");
+ok("normalize trims/dedupes/caps at 4",
+  JSON.stringify(normalizeAliases(["  Time Off ", "time off", "", "节假日", "vacation", "PTO", "leave"])) === '["Time Off","节假日","vacation","PTO"]');
+ok("normalize of undefined is empty", JSON.stringify(normalizeAliases(undefined)) === "[]");
+const fmA: Frontmatter = { ...fm, id: ulid(), aliases: ["time off", "节假日", "vacation days"] };
+const parsedA = parse(serialize(fmA, "body text"));
+ok("aliases survive round-trip",
+  JSON.stringify(parsedA?.fm.aliases) === '["time off","节假日","vacation days"]');
+ok("no aliases -> field omitted from file",
+  !/^aliases:/m.test(serialize(fm, "x")));
+ok("empty aliases array -> field omitted",
+  !/^aliases:/m.test(serialize({ ...fm, aliases: [] }, "x")));
+ok("parse caps hand-edited aliases at 4",
+  (normalizeFrontmatter({ id: "x", aliases: ["1", "2", "3", "4", "5"] } as never).aliases ?? []).length === 4);
+{
+  // D61 review: the tool schema must never reject a sloppy alias list —
+  // normalization decides, not validation (bad aliases are noise).
+  const shape = z.object(memoryAddArgs);
+  const sloppy = shape.safeParse({ content: "x", aliases: ["a", "", "b", "c", "d", "e"] });
+  ok("tool schema accepts >4 / blank aliases (normalize drops them)", sloppy.success);
+}
+
 console.log("== redact ==");
 const r1 = redact("api key is <private>sk-supersecretkey</private> ok", DEFAULT_CONFIG.redactPatterns);
 ok("private stripped", !r1.content.includes("sk-supersecretkey"));

package/scripts/test-full.ts

@@ -133,6 +133,34 @@ ok("list --type filter", r.out.includes(idDecision) && !r.out.includes(idFact));
 r = cli(["search", "ff merges"], PROJ);
 ok("search finds decision", r.out.includes(idDecision), r.out.slice(0, 150));
 
+// D61: capture-time aliases — a differently-worded query still hits.
+const idAlias = addMem(["fulltest holiday policy lives in the handbook", "--aliases", "time off;vacation days"], PROJ);
+r = cli(["search", "vacation"], PROJ);
+ok("search hits via alias-only term", r.out.includes(idAlias), r.out.slice(0, 150));
+ok("alias-only hit explains itself (aka)", /aka:/i.test(r.out), r.out.slice(0, 150));
+
+// D61 review: aliases go through the same redaction as content. (The
+// secret is assembled at runtime so no credential-shaped literal sits
+// in this file.)
+const fakePat = "ghp_" + "Ab3".repeat(12);
+const idSecretAlias = addMem(["fulltest alias redaction target", "--aliases", `${fakePat}; benign alias`], PROJ);
+r = cli(["search", "benign"], PROJ);
+ok("benign alias still searchable", r.out.includes(idSecretAlias), r.out.slice(0, 150));
+{
+  const dir = path.join(TESTENV.MY_O_MEMORY_HOME, "memories");
+  const stack = [dir];
+  let hit = "";
+  while (stack.length && !hit) {
+    const d = stack.pop()!;
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) stack.push(p);
+      else if (p.endsWith(`${idSecretAlias}.md`)) hit = fs.readFileSync(p, "utf8");
+    }
+  }
+  ok("secret-looking alias is masked in the stored file", !!hit && !hit.includes(fakePat), hit.slice(0, 200));
+}
+
 // ---------- 3. supersede / status / forget ----------
 console.log("== supersede / status / forget ==");
 r = cli(["supersede", idFact, "fulltest fact about deploys v2"], PROJ);

package/skills/open-memex/SKILL.md

@@ -25,6 +25,32 @@ open-memex add "I prefer concise diffs" --scope personal   # applies everywhere
 Keep each memory one self-contained statement. Scope routing: facts about the
 user ("I"/"me") → `personal`; everything else → the current project.
 
+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.
+
+Attach alternate phrasings when saving — synonyms, another way the question
+might be worded, equivalents in the user's other language — so reworded
+questions still find the memory:
+
+```sh
+open-memex add "Public holidays are listed in the HR portal" --aliases "holidays;time off;节假日"
+```
+
+(Aliases are stored only when the install has capture aliases enabled — the
+init default.)
+
+## At task checkpoints — propose, don't just save
+
+For conclusions you infer yourself (the user never stated them): when you
+finish a task the user would describe in one sentence, 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 the user did not approve; on approval, save it —
+with the `memory_add` tool pass `source: "inference"` so the capture is marked
+as agent-proposed. Don't interrupt mid-task, and don't re-propose something
+the user already declined.
+
 ## Recall
 
 ```sh
@@ -33,7 +59,10 @@ open-memex list                       # recent memories in the current project
 ```
 
 Search before asking the user about past decisions or preferences they may
-have told you before.
+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.
 
 ## Project outbox → repo (the sync flow)
 

package/src/cli.ts

@@ -15,6 +15,7 @@ import {
   readMemoryFile,
   ulid,
   msToRfc3339,
+  normalizeAliases,
   type Frontmatter,
 } from "./store/markdown.ts";
 import { loadConfig } from "./config.ts";
@@ -64,19 +65,26 @@ Example:
 
   add: `Save a fact, preference, decision, or note to local memory.
 
-Usage: open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
+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"`,
@@ -943,6 +951,20 @@ 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,
@@ -985,6 +1007,15 @@ 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/src/config.ts

@@ -7,6 +7,14 @@ export interface MyOMemoryConfig {
   maxProfileItems: number;
   injectOnFirstTurn: boolean;
   keywordCaptureEnabled: boolean;
+  /**
+   * D61: capture-time aliasing (retrieval layer 3). When on, agents are
+   * asked to attach 2–4 aliases (alternate phrasings, other-language
+   * equivalents) to each memory they save; ops stores them and the index
+   * searches them, so differently-worded questions still hit. Asked once
+   * at init, default on; off = aliases passed by agents are dropped.
+   */
+  captureAliases: boolean;
   /** Patterns whose capture group 1 becomes the memory body; saved to the current scope. */
   keywordPatterns: string[];
   /** Same shape, but hits are forced into the personal scope (e.g. "remember for me"). */
@@ -34,6 +42,7 @@ export const DEFAULT_CONFIG: MyOMemoryConfig = {
   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+(.+)$",
@@ -110,6 +119,7 @@ export const SETTABLE_KEYS: Record<string, (v: unknown) => unknown> = {
   maxProfileItems: toNonNegInt,
   injectOnFirstTurn: toBool,
   keywordCaptureEnabled: toBool,
+  captureAliases: toBool,
   memoryDir: toRelativeDir,
   "sync.autoPull": toBool,
   logLevel: (v) => {

package/src/distill-agents.ts

@@ -78,8 +78,14 @@ export function distillAgentsMarkdown(opts: DistillAgentsOptions): string {
     `  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/src/init.ts

@@ -894,6 +894,14 @@ export async function initProject(opts: {
     );
     if (injectOnFirstTurn !== DEFAULT_CONFIG.injectOnFirstTurn)
       patch.injectOnFirstTurn = injectOnFirstTurn;
+    // D61: capture-time aliases — agents attach alternate phrasings to each
+    // memory so differently-worded questions still find it.
+    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(

package/src/mcp.ts

@@ -112,9 +112,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
@@ -178,10 +179,16 @@ 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);
+  // 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
+    (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 },

package/src/retrieve/inject.ts

@@ -28,7 +28,7 @@ export function buildContextBlock(scope: Scope, cfg: MyOMemoryConfig): string |
 
   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.",
+    "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/src/retrieve/search.ts

@@ -7,6 +7,8 @@ export interface SearchHit {
   project_name: string;
   type: string;
   tags: string[];
+  /** D61: capture-time aliases stored on this memory (search hits only). */
+  aliases: string[];
   snippet: string;
   score: number;
   updated_at: number;
@@ -20,6 +22,7 @@ interface RawRow {
   project_name: string;
   type: string;
   tags: string;
+  aliases?: string;
   updated_at: number;
   snippet: string;
   score: number;
@@ -29,13 +32,22 @@ 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)) {
+    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,
@@ -161,7 +173,7 @@ 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.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/src/store/db.ts

@@ -35,6 +35,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 '',
@@ -62,6 +63,7 @@ const FTS_SCHEMA = `
 CREATE VIRTUAL TABLE IF NOT EXISTS memories_fts USING fts5(
   content,
   tags,
+  aliases,
   type,
   cjk,
   scope_key UNINDEXED,
@@ -71,25 +73,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, 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: AnyDatabase): number {
   const row = d.prepare("PRAGMA user_version").get() as { user_version: number };

package/src/store/lifecycle.ts

@@ -206,6 +206,7 @@ export interface SupersedeInput {
   body: string;
   type?: string;
   tags?: string[];
+  aliases?: string[];
   source?: string;
 }
 
@@ -232,6 +233,8 @@ export function supersede(
     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/src/store/markdown.ts

@@ -53,6 +53,13 @@ export interface Frontmatter {
   importance: Importance;
   status: MemoryStatus;
   tags: string[];
+  /**
+   * D61: capture-time aliases — alternate phrasings / other-language
+   * equivalents of this memory, indexed alongside the body so a
+   * differently-worded question still matches (retrieval layer 3).
+   * Optional and additive: files without it parse unchanged.
+   */
+  aliases?: string[];
   source: string;
   created_at: string; // RFC 3339, never bare epoch (§3)
   updated_at: string; // RFC 3339
@@ -232,6 +239,14 @@ export function normalizeFrontmatter(
     tags: Array.isArray(raw.tags)
       ? raw.tags.filter((t): t is string => typeof t === "string")
       : [],
+    ...(Array.isArray(raw.aliases)
+      ? (() => {
+          const aliases = normalizeAliases(
+            raw.aliases.filter((a): a is string => 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)),
@@ -254,12 +269,41 @@ export function normalizeFrontmatter(
   };
 }
 
+/**
+ * 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?: string[]): string[] {
+  if (!input) return [];
+  const seen = new Set<string>();
+  const out: string[] = [];
+  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: string): boolean {
   return TAXONOMY.has(t);
 }
 
 export function serialize(fm: Frontmatter, body: string): string {
-  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: Frontmatter = 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`;
 }
 

package/src/store/sync.ts

@@ -14,8 +14,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, 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,
@@ -26,6 +26,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,
@@ -62,6 +63,7 @@ export function upsertFromFile(mf: MemoryFile): void {
 function writeRow(mf: MemoryFile, mtimeMs: number): void {
   const { fm, body, filePath } = mf;
   const tags = (fm.tags ?? []).join(",");
+  const aliases = (fm.aliases ?? []).join(",");
   db().prepare(UPSERT_SQL).run(
     fm.id,
     fm.scope_key,
@@ -73,8 +75,9 @@ function writeRow(mf: MemoryFile, mtimeMs: number): void {
     fm.importance,
     fm.status,
     tags,
+    aliases,
     body,
-    cjkIndexText(body + "\n" + tags),
+    cjkIndexText(body + "\n" + tags + "\n" + aliases),
     contentHash(body),
     fm.superseded_by ?? null,
     fm.source ?? "",

package/src/tools/ops.ts

@@ -18,6 +18,7 @@ import {
   ulid,
   msToRfc3339,
   MEMORY_TYPE_TAXONOMY,
+  normalizeAliases,
   type Frontmatter,
 } from "../store/markdown.ts";
 import { upsertFromFile, deleteFromIndex } from "../store/sync.ts";
@@ -62,9 +63,9 @@ export async function withOutboxNote(
 /** 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.",
+    "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 — try a few keyword variants, including the user's own language, when the first search comes up empty.",
+    "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:
@@ -92,6 +93,13 @@ export const scopeArg = z
     "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
@@ -100,6 +108,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()
@@ -138,6 +147,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 type MemorySupersedeArgs = z.infer<z.ZodObject<typeof memorySupersedeArgs>>;
 
@@ -210,6 +220,7 @@ function buildFrontmatter(
   body: {
     type: Frontmatter["type"];
     tags: string[];
+    aliases?: string[];
     source: Frontmatter["source"];
   },
 ): Frontmatter {
@@ -226,6 +237,7 @@ function buildFrontmatter(
     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,
@@ -265,6 +277,15 @@ export async function addMemory(
   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);
@@ -335,6 +356,14 @@ export async function supersedeMemory(
       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);