open-memex 0.6.2 → 0.7.0-alpha.2

package/dist/init.js

@@ -271,6 +271,15 @@ function opencodePluginUrl() {
     const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
     return pathToFileURL(path.join(pkgRoot, "src", "index.ts")).href;
 }
+/**
+ * D60: the same plugin directory, in the form OpenCode 2 wants. v2 rejects
+ * file entries in `plugins` ("configured plugin path must be a directory")
+ * and loads `<dir>/index.ts` instead.
+ */
+function opencodePluginDir() {
+    const pkgRoot = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+    return path.join(pkgRoot, "src");
+}
 /**
  * D46: opencode's user-level config. opencode reads `~/.config/opencode/`
  * (`$XDG_CONFIG_HOME` when set) on every platform; a `plugin` entry there
@@ -297,6 +306,63 @@ export function mergePluginEntry(doc, url, force) {
         list.push(url);
     return "added";
 }
+/** The package path an OpenCode 2 `plugins` entry refers to, if any. */
+function v2EntryPackage(entry) {
+    if (typeof entry === "string")
+        return entry;
+    if (entry !== null && typeof entry === "object" && "package" in entry) {
+        const p = entry.package;
+        return typeof p === "string" ? p : null;
+    }
+    return null;
+}
+/**
+ * D60: pure merge of the open-memex directory into the `plugins` array
+ * (the OpenCode 2 spelling). An existing open-memex entry (any form)
+ * counts as present; with force, stale open-memex entries are replaced
+ * by `dir`. Same "added"/"kept" contract as mergePluginEntry.
+ */
+export function mergeV2PluginEntry(doc, dir, force) {
+    let plugins = doc["plugins"];
+    if (!Array.isArray(plugins)) {
+        plugins = [];
+        doc["plugins"] = plugins;
+    }
+    const list = plugins;
+    const ours = (e) => (v2EntryPackage(e) ?? "").includes("open-memex");
+    if (!force && list.some(ours))
+        return "kept";
+    for (let i = list.length - 1; i >= 0; i--) {
+        const p = v2EntryPackage(list[i]);
+        if (p === dir) {
+            if (!force)
+                return "kept";
+            list.splice(i, 1);
+        }
+        else if (force && ours(list[i])) {
+            list.splice(i, 1);
+        }
+    }
+    list.push(dir);
+    return "added";
+}
+/**
+ * Pure removal of open-memex entries from the `plugins` array (OpenCode 2
+ * spelling — strings and `{package}` objects). Drops the key when empty.
+ */
+export function removeV2PluginEntry(doc, match) {
+    const plugins = doc["plugins"];
+    if (!Array.isArray(plugins))
+        return "absent";
+    const kept = plugins.filter((p) => !(v2EntryPackage(p) ?? "").includes(match));
+    if (kept.length === plugins.length)
+        return "absent";
+    if (kept.length === 0)
+        delete doc["plugins"];
+    else
+        doc["plugins"] = kept;
+    return "removed";
+}
 /**
  * D46: wire the native plugin at the opencode user level — the one-time
  * global setup. Merges into the existing config when it parses as JSON;
@@ -309,6 +375,7 @@ function writeOpencodeGlobalPlugin(force) {
         .map((f) => path.join(dir, f))
         .find((f) => fs.existsSync(f)) ?? path.join(dir, "opencode.json");
     const url = opencodePluginUrl();
+    const pluginDir = opencodePluginDir();
     let doc = {};
     if (fs.existsSync(file)) {
         try {
@@ -316,7 +383,8 @@ function writeOpencodeGlobalPlugin(force) {
         }
         catch {
             console.log(`  ! ${file} has comments or invalid JSON — left untouched, fix it manually.`);
-            console.log(`    To enable open-memex everywhere, add "plugin": ["${url}"] to it.`);
+            console.log(`    To enable open-memex everywhere, add "plugin": ["${url}"] (opencode 1)`);
+            console.log(`    and "plugins": ["${pluginDir}"] (opencode 2) to it.`);
             console.log(`    Also remove any "${LEGACY_PACKAGE_NAME}" entries from "plugin" (stale — package renamed).`);
             return null;
         }
@@ -325,8 +393,12 @@ function writeOpencodeGlobalPlugin(force) {
     // alongside the new one — it writes to the OLD data dir, silently splitting
     // memories in two. Drop it wherever init touches the plugin list.
     const staleRemoved = removePluginEntry(doc, LEGACY_PACKAGE_NAME) === "removed";
+    removeV2PluginEntry(doc, LEGACY_PACKAGE_NAME);
     const merged = mergePluginEntry(doc, url, force);
-    if (merged === "kept" && !staleRemoved) {
+    // D60: write both key generations — opencode 1 reads `plugin`, opencode 2
+    // reads `plugins`; each host ignores the other's key.
+    const mergedV2 = mergeV2PluginEntry(doc, pluginDir, force);
+    if (merged === "kept" && mergedV2 === "kept" && !staleRemoved) {
         console.log(`  = ${file} already loads the open-memex plugin — left as is (use --force to overwrite)`);
         return file;
     }
@@ -334,7 +406,7 @@ function writeOpencodeGlobalPlugin(force) {
     fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
     if (staleRemoved)
         console.log(`  - ${file} (stale my-o-memory plugin entry removed — package renamed to open-memex)`);
-    if (merged === "added")
+    if (merged === "added" || mergedV2 === "added")
         console.log(`  + ${file} (native plugin — works in every project, no per-project init needed)`);
     return file;
 }
@@ -733,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>\`)`);
@@ -882,13 +959,16 @@ function removeOpencodePluginFile(file) {
     const doc = parseJsonConfig(fs.readFileSync(file, "utf8"));
     if (doc === null) {
         console.error(`  ! ${file} is not valid JSON — left untouched, fix it manually`);
-        console.error(`    Delete the open-memex URL from the "plugin" array.`);
+        console.error(`    Delete the open-memex URL from the "plugin" array and the open-memex path from "plugins".`);
         return null;
     }
     const res = removePluginEntry(doc, "open-memex");
+    // D60: the v2 `plugins` entry goes too (strings and {package} objects).
+    const resV2 = removeV2PluginEntry(doc, "open-memex");
     // F30: also sweep the pre-rename leftover — see removeServerEntryFile.
     const stale = removePluginEntry(doc, LEGACY_PACKAGE_NAME);
-    if (res === "removed" || stale === "removed") {
+    removeV2PluginEntry(doc, LEGACY_PACKAGE_NAME);
+    if (res === "removed" || resV2 === "removed" || stale === "removed") {
         fs.writeFileSync(file, JSON.stringify(doc, null, 2) + "\n");
         console.log(`  - ${file} (memory-plugin entries removed)`);
         return "removed";

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/opencode-v2.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { PLUGIN_ID, bootstrapPlugin, captureFromText, injectOnce, } from "./plugin-core.js";
+import { makeTools } from "./tools/memory.js";
+/** Register the five memory tools on a v2 host. */
+async function registerTools(ctx, state) {
+    const tools = makeTools(() => state.scope, state.cfg);
+    await ctx.tool.transform((editor) => {
+        for (const [name, t] of Object.entries(tools)) {
+            editor.add({
+                name,
+                description: t.description,
+                input: z.toJSONSchema(z.object(t.args)),
+                options: { codemode: false },
+                execute: async (input) => {
+                    const r = await t.execute(input, undefined);
+                    const content = typeof r === "string" ? r : (r.output ?? JSON.stringify(r));
+                    return { content };
+                },
+            });
+        }
+    });
+}
+export const v2Plugin = {
+    id: PLUGIN_ID,
+    async setup(ctx) {
+        const root = ctx.location?.directory ?? ctx.location?.project?.directory ?? process.cwd();
+        const state = bootstrapPlugin(root);
+        const registrations = [];
+        await registerTools(ctx, state);
+        registrations.push(await ctx.session.hook("prompt", (ev) => {
+            captureFromText(ev.prompt?.text ?? "", state);
+        }));
+        registrations.push(await ctx.session.hook("context", (ev) => {
+            injectOnce(ev.sessionID ?? "", state, (block) => {
+                ev.system.push({ type: "text", text: block });
+            });
+        }));
+        return () => {
+            for (const r of registrations)
+                void r.dispose?.();
+        };
+    },
+};

package/dist/plugin-core.js

@@ -0,0 +1,138 @@
+import { loadConfig } from "./config.js";
+import { resolveProjectScope, resolveCwdScope, PERSONAL_SCOPE } from "./scope.js";
+import { db } from "./store/db.js";
+import { syncScope, upsertFromFile } from "./store/sync.js";
+import { scopeHasFiles } from "./store/migrate.js";
+import { writeMemoryFile, readMemoryFile, ulid, msToRfc3339, } from "./store/markdown.js";
+import { buildContextBlock } from "./retrieve/inject.js";
+import { detectKeywords } from "./capture/keywords.js";
+import { findDuplicates } from "./store/lifecycle.js";
+import { redact } from "./redact.js";
+/**
+ * Host-agnostic plugin core (D60). Both opencode host generations adapt to
+ * this module: the v1 plugin (src/index.ts `server`) and the v2 plugin
+ * (src/opencode-v2.ts `setup`). Host-specific glue — tool registration and
+ * hook shapes — stays in the adapters; everything memory-shaped lives here.
+ */
+export const PLUGIN_ID = "open-memex";
+/**
+ * Resolve the project scope for a host working directory and bring the
+ * index up to date. Never throws: a broken store must not keep the host
+ * from starting — failures land in the host's log instead.
+ */
+export function bootstrapPlugin(root) {
+    const cfg = loadConfig();
+    const scope = resolveProjectScope(root);
+    try {
+        db();
+        syncScope(scope.key);
+        syncScope(PERSONAL_SCOPE.key);
+        if (cfg.logLevel === "debug") {
+            console.log(`[open-memex] loaded. scope=${scope.key}`);
+        }
+        // If a git remote was added *after* memories were first captured, the
+        // scope key changes (cwd-hash -> origin-hash). Detect the legacy dir on
+        // disk and tell the user how to migrate. We do NOT auto-migrate: two
+        // different repos at the same cwd would collide.
+        const cwdScope = resolveCwdScope(root);
+        if (cwdScope.key !== scope.key && scopeHasFiles(cwdScope.key)) {
+            console.warn(`[open-memex] found memories under legacy scope key "${cwdScope.key}". ` +
+                `Current project scope is "${scope.key}". ` +
+                `To move them: npm run cli -- migrate --from ${cwdScope.key}`);
+        }
+    }
+    catch (err) {
+        console.error("[open-memex] init failed:", err);
+    }
+    return { cfg, scope, injectedSessions: new Set() };
+}
+/**
+ * Keyword capture (§ capture): scan one user message for "remember …"
+ * triggers and save each hit. Shared by the v1 `chat.message` hook and
+ * the v2 session `prompt` hook — both hand us the message text.
+ */
+export function captureFromText(text, state) {
+    const { cfg, scope } = state;
+    if (!cfg.keywordCaptureEnabled || !text)
+        return;
+    const hits = detectKeywords(text, cfg);
+    for (const h of hits) {
+        const { content, hadSecret, matchedPattern } = redact(h.content, cfg.redactPatterns);
+        // Secrets are masked (first 4 chars kept) and the capture proceeds;
+        // skip only when nothing usable remains.
+        if (content.length === 0)
+            continue;
+        if (hadSecret && cfg.logLevel === "debug") {
+            console.log(`[open-memex] keyword capture masked secret (${matchedPattern})`);
+        }
+        // Personal patterns ("remember for me" / "记住（个人）") force the personal scope.
+        const target = h.personal ? PERSONAL_SCOPE : scope;
+        // Dedup (§3.4): skip exact duplicates captured before.
+        if (findDuplicates(target.key, content).exact)
+            continue;
+        const now = Date.now();
+        const rfc = msToRfc3339(now);
+        const fm = {
+            id: ulid(),
+            schema_version: 2,
+            scope_key: target.key,
+            scope: target.kind === "project" ? "project" : "personal",
+            visibility: target.kind === "project" ? "internal" : "private",
+            project_name: target.projectName,
+            type: "fact",
+            role: "knowledge",
+            importance: "normal",
+            status: "active",
+            tags: ["keyword"],
+            source: "keyword",
+            created_at: rfc,
+            updated_at: rfc,
+            supersedes: null,
+            superseded_by: null,
+            review_state: "draft",
+            proposed_by: null,
+            approved_by: null,
+            derived_from: null,
+            review_note: null,
+            review_history: [],
+        };
+        try {
+            const { filePath } = writeMemoryFile(fm, content);
+            const mf = readMemoryFile(filePath);
+            if (mf)
+                upsertFromFile(mf);
+            // Capture feedback: always visible (not debug-only) — the user said
+            // "记住…", they should see that it landed. The opencode plugin API
+            // offers no toast channel, so the plugin log is the feedback surface.
+            const preview = content.length > 60 ? content.slice(0, 60) + "…" : content;
+            console.log(`[open-memex] remembered → ${target.kind} scope: "${preview}"`);
+        }
+        catch (err) {
+            console.error("[open-memex] keyword capture failed:", err);
+        }
+    }
+}
+/**
+ * First-turn context injection: exactly once per session. The host adapter
+ * supplies `push` (v1: output.system.push; v2: the session context hook's
+ * system array). Returns true when a block was pushed.
+ */
+export function injectOnce(sessionID, state, push) {
+    const { cfg, scope } = state;
+    if (!cfg.injectOnFirstTurn)
+        return false;
+    if (state.injectedSessions.has(sessionID))
+        return false;
+    state.injectedSessions.add(sessionID);
+    try {
+        const block = buildContextBlock(scope, cfg);
+        if (block) {
+            push(block);
+            return true;
+        }
+    }
+    catch (err) {
+        console.error("[open-memex] context injection failed:", err);
+    }
+    return false;
+}

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