open-memex 0.6.0 → 0.6.1-alpha.3

package/dist/cli.js

@@ -41,12 +41,14 @@ Examples:
   open-memex list --scope personal --limit 20`,
     search: `Search memories by keyword (BM25 full-text), best matches first.
 
-Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+Usage: open-memex search "query" [--scope project|personal|both] [--type T] [--limit N] [--explain]
 
 Flags:
-  --scope   project (default), personal, or both
-  --type    filter by memory type
-  --limit   max results
+  --scope    project (default), personal, or both
+  --type     filter by memory type
+  --limit    max results
+  --explain  show the FTS expression, per-hit score, and how many matches
+             lifecycle hid (superseded / retracted / archived)
 
 Example:
   open-memex search "deploy checklist" --scope both`,
@@ -304,6 +306,18 @@ Usage: open-memex doctor
 
 Example:
   open-memex doctor`,
+    audit: `Memory health audit (read-only, reports never mutates): near-duplicate
+pairs among active memories, stale actives untouched for 90+ days, broken
+supersede chains, personal files found inside the repo memory dir, and
+index/file drift.
+
+Usage: open-memex audit [--scope project|personal|both]
+
+Flags:
+  --scope   project (default), personal, or both
+
+Example:
+  open-memex audit --scope both`,
 };
 function usage(exitCode = 1) {
     console.log(`open-memex CLI
@@ -311,7 +325,7 @@ function usage(exitCode = 1) {
 Usage:
   open-memex where
   open-memex list [--scope project|personal] [--type T] [--limit N]
-  open-memex search "query" [--scope project|personal|both] [--type T] [--limit N]
+  open-memex search "query" [--scope project|personal|both] [--type T] [--limit N] [--explain]
   open-memex add "content" [--scope project|personal] [--type T] [--tag t1,t2]
   open-memex supersede <id> "new content" [--type T] [--tag t1,t2]
   open-memex status <id> active|deprecated|retracted|archived
@@ -328,6 +342,7 @@ Usage:
   open-memex submit <id...> [--branch <name>] [--base <branch>]
   open-memex pr-status [--apply]
   open-memex reindex
+  open-memex audit [--scope project|personal|both]
   open-memex scopes
   open-memex migrate [--from <key>] [--to <key>]
                                           [--dry-run] [--on-conflict newer|overwrite|skip]
@@ -621,6 +636,36 @@ async function main() {
             process.exitCode = 1;
         return;
     }
+    if (cmd === "audit") {
+        const flags = parseFlags(rest);
+        syncScope(project.key, "cli");
+        syncScope(PERSONAL_SCOPE.key, "cli");
+        const keys = flags.scope === "personal"
+            ? [PERSONAL_SCOPE.key]
+            : flags.scope === "both"
+                ? [project.key, PERSONAL_SCOPE.key]
+                : [project.key];
+        const { runAudit, STALE_DAYS } = await import("./store/audit.js");
+        const r = runAudit(keys);
+        console.log(`audit: ${r.totalMemories} memories (${keys.length === 2 ? "project+personal" : keys[0] === PERSONAL_SCOPE.key ? "personal" : "project"})`);
+        console.log(`  near-duplicate active pairs: ${r.duplicatePairs.length}`);
+        for (const p of r.duplicatePairs.slice(0, 10)) {
+            console.log(`    ${p.a} ~ ${p.b} (similarity ${p.score.toFixed(2)}) — consider supersede`);
+        }
+        console.log(`  stale actives (>= ${STALE_DAYS} days untouched): ${r.stale.length}`);
+        for (const s of r.stale.slice(0, 10)) {
+            console.log(`    ${s.id} — ${s.ageDays} days`);
+        }
+        console.log(`  broken supersede chains: ${r.brokenChains.length}`);
+        for (const b of r.brokenChains) {
+            console.log(`    ${b.id} -> missing ${b.missingTarget}`);
+        }
+        console.log(`  personal files inside repo memory dir: ${r.personalInRepo.length}`);
+        for (const f of r.personalInRepo)
+            console.log(`    ${f}`);
+        console.log(`  index drift: ${r.drift.filesNotIndexed} files not indexed, ${r.drift.rowsMissingFiles} rows missing files`);
+        return;
+    }
     // `config` prints the effective configuration (defaults + file). No DB needed.
     // `config set <key> <value>` persists a setting to the config file.
     if (cmd === "config") {
@@ -743,11 +788,20 @@ async function main() {
             : flags.scope === "project"
                 ? [project.key]
                 : [project.key, PERSONAL_SCOPE.key];
+        const explain = flags.explain === "true";
+        const stats = explain
+            ? { ftsQuery: "", candidates: 0, hiddenSuperseded: 0, hiddenExcluded: 0 }
+            : undefined;
         const hits = search(query, {
             scopeKeys: keys,
             limit: flags.limit ? Number(flags.limit) : undefined,
             type: flags.type,
+            stats,
         });
+        if (explain && stats) {
+            console.log(`fts: ${stats.ftsQuery || "(empty query)"}`);
+            console.log(`candidates: ${stats.candidates}, hidden by lifecycle: ${stats.hiddenSuperseded} superseded, ${stats.hiddenExcluded} retracted/archived`);
+        }
         if (hits.length === 0) {
             console.log("(no matches)");
             return;
@@ -756,7 +810,8 @@ async function main() {
             const tag = h.scope_key === PERSONAL_SCOPE.key ? "personal" : "project";
             const dep = h.status === "deprecated" ? " [deprecated]" : "";
             const rev = hitStateLabel(h);
-            console.log(`[${tag}/${h.type}]${dep}${rev} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
+            const sc = explain ? ` score=${h.score.toFixed(3)}` : "";
+            console.log(`[${tag}/${h.type}]${dep}${rev}${sc} ${h.id}  ${h.snippet.replace(/\s+/g, " ").trim()}`);
         }
         return;
     }
@@ -1261,7 +1316,16 @@ async function main() {
 }
 main()
     .catch((err) => {
-    console.error(err);
+    // D57: lock contention past the busy timeout should read as a transient
+    // condition, not a stack trace. The memory file is written before the
+    // index update, so a locked-out write still lands on the next sync.
+    const code = err?.code;
+    if (code === "SQLITE_BUSY" || code === "SQLITE_LOCKED") {
+        console.error("open-memex: the memory store is busy (another open-memex process is writing). Wait a moment and retry — nothing was lost.");
+    }
+    else {
+        console.error(err);
+    }
     process.exit(1);
 })
     .finally(() => {

package/dist/doctor.js

@@ -10,6 +10,7 @@ import { fileURLToPath } from "node:url";
 import { loadConfig, configSource, DEFAULT_CONFIG } from "./config.js";
 import { paths } from "./paths.js";
 import { resolveCwdScope } from "./scope.js";
+import { db, backendName } from "./store/db.js";
 import { LEGACY_PACKAGE_NAME, opencodeGlobalConfigPath, userMcpConfigPath } from "./init.js";
 const EXPECTED_TOOLS = [
     "memory_add",
@@ -59,6 +60,27 @@ function storageCheck() {
         return { name: "storage", ok: false, detail: String(err) };
     }
 }
+/**
+ * D57: several processes share one index (CLI, MCP per editor, opencode
+ * plugin). WAL + a 5s busy timeout is what keeps an overlapping write a
+ * brief wait instead of an instant failure — report the live settings.
+ */
+function lockingCheck() {
+    try {
+        const d = db();
+        const jm = d.prepare("PRAGMA journal_mode").get().journal_mode;
+        const bt = d.prepare("PRAGMA busy_timeout").get().timeout;
+        const ok = jm === "wal" && bt >= 1000;
+        return {
+            name: "locking",
+            ok,
+            detail: `journal=${jm}, busy_timeout=${bt}ms (${backendName()})`,
+        };
+    }
+    catch (err) {
+        return { name: "locking", ok: false, detail: String(err) };
+    }
+}
 /** Spawn the real MCP server, handshake, and verify the five tools list. */
 function mcpCheck() {
     const name = "mcp";
@@ -277,7 +299,7 @@ function vscodeMcpCheck() {
 }
 export async function runDoctor() {
     console.log("open-memex doctor");
-    const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), vscodeMcpCheck()];
+    const checks = [nodeCheck(), configCheck(), scopeCheck(), storageCheck(), lockingCheck(), vscodeMcpCheck()];
     checks.push(await mcpCheck());
     checks.push(legacyCheck());
     let allOk = true;

package/dist/init.js

@@ -792,6 +792,9 @@ export async function initProject(opts) {
     // D51: close the init→first-use gap — one concrete next step so a new user
     // sees what "it works" looks like instead of stopping at "it's wired".
     console.log(`  Next step: \`open-memex add "standup is at 9:30"\` — then ask your agent what it remembers.`);
+    // Privacy in one line, at the moment of maximum doubt (right after a tool
+    // just wrote into the user's editors): local-only, nothing uploaded.
+    console.log(`  Privacy: memories live only on this machine — personal ones never leave it, and nothing is uploaded anywhere.`);
     // D50: init completed — the bare-`open-memex` first-run offer won't ask again.
     markFirstRunDone("initialized");
 }

package/dist/retrieve/cjk.js

@@ -40,8 +40,11 @@ function esc(t) {
  * column. Multi-char runs become an OR of bigrams (recall-oriented; bm25
  * ranks docs matching more bigrams higher). Single chars stay unigrams.
  * Returns "" when the query has no CJK.
+ *
+ * Options: `dropBigrams` filters question bigrams (什么/怎么/…) when other
+ * terms remain; `maxTerms` caps the term count (applied after dedupe).
  */
-export function cjkQueryExpr(query) {
+export function cjkQueryExpr(query, opts = {}) {
     const parts = [];
     for (const m of query.matchAll(CJK_RUN_RE)) {
         const chars = [...m[0]];
@@ -54,5 +57,14 @@ export function cjkQueryExpr(query) {
             }
         }
     }
-    return parts.join(" OR ");
+    let terms = [...new Set(parts)];
+    if (opts.dropBigrams && terms.length > 1) {
+        const kept = terms.filter((t) => !opts.dropBigrams.has(t.slice(1, -1).replace(/""/g, '"')));
+        if (kept.length > 0)
+            terms = kept;
+    }
+    if (opts.maxTerms && terms.length > opts.maxTerms) {
+        terms = terms.slice(0, opts.maxTerms);
+    }
+    return terms.join(" OR ");
 }

package/dist/retrieve/query.js

@@ -0,0 +1,54 @@
+// Search query construction (pure logic, no sqlite).
+//
+// Free-text questions — "how do we configure the SSO login", "中文记忆怎么
+// 检索" — are the natural way users and agents ask, but fed raw into FTS5
+// they dilute ranking: question words ("how", "什么", "怎么") match
+// everything and drag the score. So the query builder keeps the existing
+// shape (Latin prefix terms OR-ed, CJK bigrams OR-ed against the `cjk`
+// column, bm25 ranks) and additionally drops a small set of function words
+// on both sides, dedupes, and caps term counts so a rambling sentence
+// cannot crowd out its own content words. If filtering would empty a
+// side, the unfiltered terms are used — a query must never be made worse
+// than the raw one.
+import { cjkQueryExpr, hasCjk } from "./cjk.js";
+/** English function words that carry no retrieval signal in questions. */
+const LATIN_STOPWORDS = new Set([
+    "the", "a", "an", "and", "or", "of", "to", "in", "on", "for", "with",
+    "without", "is", "are", "was", "were", "be", "been", "do", "does", "did",
+    "how", "what", "why", "when", "where", "which", "who", "whom", "we", "i",
+    "you", "he", "she", "it", "they", "them", "us", "me", "my", "our", "your",
+    "his", "her", "its", "their", "this", "that", "these", "those", "there",
+    "here", "can", "could", "should", "would", "will", "shall", "may", "might",
+    "please", "if", "then", "than", "so", "as", "at", "by", "from", "into",
+    "about", "over", "under", "again", "once", "just",
+]);
+/** Chinese question bigrams — the CJK counterpart of the list above. */
+const CJK_QUESTION_BIGRAMS = new Set([
+    "什么", "怎么", "如何", "为何", "为什", "哪些", "哪个", "请问",
+]);
+const MAX_TERMS = 24;
+function latinTerms(q) {
+    const raw = q.toLowerCase().match(/[a-z0-9_.\-]+/g) ?? [];
+    const kept = raw.filter((t) => t.length > 1 && !LATIN_STOPWORDS.has(t));
+    const chosen = kept.length > 0 ? kept : raw;
+    return [...new Set(chosen)].slice(0, MAX_TERMS);
+}
+/**
+ * Convert free-text query into a safe FTS5 MATCH expression.
+ * Latin tokens keep the old behavior (prefix match on content/tags/type).
+ * CJK runs become an OR of bigrams against the `cjk` column (see cjk.ts).
+ * Mixed queries OR the two parts together.
+ */
+export function toFtsQuery(q) {
+    const latin = latinTerms(q)
+        .map((t) => `"${t.replace(/"/g, '""')}"*`)
+        .join(" OR ");
+    const cjk = hasCjk(q)
+        ? cjkQueryExpr(q, { dropBigrams: CJK_QUESTION_BIGRAMS, maxTerms: MAX_TERMS })
+        : "";
+    if (latin && cjk)
+        return `(${latin}) OR {cjk}:(${cjk})`;
+    if (cjk)
+        return `{cjk}:(${cjk})`;
+    return latin;
+}

package/dist/retrieve/search.js

@@ -1,5 +1,5 @@
 import { db } from "../store/db.js";
-import { cjkQueryExpr, hasCjk } from "./cjk.js";
+import { toFtsQuery } from "./query.js";
 function toHit(r) {
     return {
         id: r.id,
@@ -44,7 +44,7 @@ export function hitStateLabel(h) {
  *   drafts/rejected rank after unreviewed content;
  * - deprecated stays visible as a warning but ranks after active.
  */
-function resolveVisible(rows, limit) {
+function resolveVisible(rows, limit, stats) {
     const byId = new Map(rows.map((r) => [r.id, r]));
     const fullRow = (id) => {
         const cached = byId.get(id);
@@ -65,10 +65,15 @@ function resolveVisible(rows, limit) {
     const tiers = [[], [], [], []];
     const deprecated = [];
     for (const r of rows) {
-        if (r.status === "retracted" || r.status === "archived")
+        if (r.status === "retracted" || r.status === "archived") {
+            if (stats)
+                stats.hiddenExcluded++;
             continue;
+        }
         let target = r;
         if (r.status === "superseded") {
+            if (stats)
+                stats.hiddenSuperseded++;
             let cur = r;
             const chain = new Set([r.id]);
             while (cur.status === "superseded" && cur.superseded_by) {
@@ -96,24 +101,18 @@ function resolveVisible(rows, limit) {
     return [...tiers[0], ...tiers[1], ...tiers[2], ...deprecated].slice(0, limit);
 }
 /**
- * Convert free-text query into a safe FTS5 MATCH expression.
- * Latin tokens keep the old behavior (prefix match on content/tags/type).
- * CJK runs become an OR of bigrams against the `cjk` column (see cjk.ts).
- * Mixed queries OR the two parts together.
+ * FTS5 query construction lives in query.ts (pure, unit-tested): free-text
+ * questions are split into content terms (OR-ed; bm25 ranks), with
+ * function/question words filtered so they can't dilute the ranking.
  */
-function toFtsQuery(q) {
-    const latin = (q.toLowerCase().match(/[a-z0-9_.\-]+/g) ?? [])
-        .map((t) => `"${t.replace(/"/g, '""')}"*`)
-        .join(" OR ");
-    const cjk = hasCjk(q) ? cjkQueryExpr(q) : "";
-    if (latin && cjk)
-        return `(${latin}) OR {cjk}:(${cjk})`;
-    if (cjk)
-        return `{cjk}:(${cjk})`;
-    return latin;
-}
 export function search(query, opts = {}) {
     const q = toFtsQuery(query);
+    if (opts.stats) {
+        opts.stats.ftsQuery = q;
+        opts.stats.candidates = 0;
+        opts.stats.hiddenSuperseded = 0;
+        opts.stats.hiddenExcluded = 0;
+    }
     if (!q)
         return [];
     const limit = Math.max(1, Math.min(opts.limit ?? 8, 50));
@@ -146,7 +145,9 @@ export function search(query, opts = {}) {
         .all(...params);
     // FTS5 bm25: lower = better; invert for intuition.
     const raw = rows.map((r) => ({ ...r, score: -r.score }));
-    return resolveVisible(raw, limit);
+    if (opts.stats)
+        opts.stats.candidates = raw.length;
+    return resolveVisible(raw, limit, opts.stats);
 }
 export function list(scopeKey, opts = {}) {
     const limit = Math.max(1, Math.min(opts.limit ?? 20, 100));

package/dist/store/audit.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import { db } from "./db.js";
+import { readMemoryFile, iterInRepoMemoryFiles, iterMemoryFiles, } from "./markdown.js";
+import { similarity, NEAR_DUP_THRESHOLD } from "./lifecycle.js";
+import { projectRoot } from "../paths.js";
+import { loadConfig } from "../config.js";
+// Memory health audit (D57). Read-only: reports, never mutates.
+// Checks, per open question "retrieval explainability & memory health":
+//   - near-duplicate pairs among active memories (same dedup yardstick
+//     as write-time: Jaccard >= 0.8) that were never superseded;
+//   - stale actives: untouched for STALE_DAYS, still in the retrieval /
+//     injection pool;
+//   - broken supersede chains: superseded_by pointing at a missing id;
+//   - personal files inside the in-repo memory dir (iron-rule breach:
+//     personal memory must never land in a shared repo);
+//   - index/file drift after sync (should be zero; reported if not).
+export const STALE_DAYS = 90;
+export function runAudit(scopeKeys) {
+    const d = db();
+    const rows = d
+        .prepare(`SELECT id, scope_key, status, updated_at, superseded_by, content, file_path
+       FROM memories`)
+        .all();
+    const inScope = rows.filter((r) => scopeKeys.includes(r.scope_key));
+    const ids = new Set(rows.map((r) => r.id));
+    // Near-duplicate pairs: active only, same scope. O(n^2) per scope with a
+    // length pre-filter; local stores are small enough for this to be fine.
+    const pairs = [];
+    const byScope = new Map();
+    for (const r of inScope) {
+        if (r.status !== "active")
+            continue;
+        const arr = byScope.get(r.scope_key) ?? [];
+        arr.push(r);
+        byScope.set(r.scope_key, arr);
+    }
+    for (const [scopeKey, arr] of byScope) {
+        for (let i = 0; i < arr.length; i++) {
+            for (let j = i + 1; j < arr.length; j++) {
+                const a = arr[i];
+                const b = arr[j];
+                const la = a.content.length;
+                const lb = b.content.length;
+                if (Math.min(la, lb) / Math.max(la, lb) < 0.5)
+                    continue;
+                const score = similarity(a.content, b.content);
+                if (score >= NEAR_DUP_THRESHOLD) {
+                    pairs.push({ a: a.id, b: b.id, scopeKey, score });
+                }
+            }
+        }
+    }
+    pairs.sort((x, y) => y.score - x.score);
+    const now = Date.now();
+    const stale = inScope
+        .filter((r) => r.status === "active")
+        .map((r) => ({ id: r.id, scopeKey: r.scope_key, ageDays: Math.floor((now - r.updated_at) / 86_400_000) }))
+        .filter((s) => s.ageDays >= STALE_DAYS)
+        .sort((x, y) => y.ageDays - x.ageDays);
+    const brokenChains = inScope
+        .filter((r) => r.superseded_by && !ids.has(r.superseded_by))
+        .map((r) => ({ id: r.id, scopeKey: r.scope_key, missingTarget: r.superseded_by }));
+    // Personal files must never sit in the in-repo dir. Read-only: this only
+    // parses frontmatter of files already in the repo tree.
+    const personalInRepo = [];
+    try {
+        const root = projectRoot();
+        const memoryDir = loadConfig().memoryDir;
+        for (const fp of iterInRepoMemoryFiles(root, memoryDir)) {
+            const mf = readMemoryFile(fp);
+            if (mf && mf.fm.scope === "personal")
+                personalInRepo.push(fp);
+        }
+    }
+    catch {
+        // No project root (e.g. personal-only usage): nothing to scan.
+    }
+    // Drift: index rows whose file vanished, and files on disk the index
+    // never picked up. syncScope normally heals both before audit runs.
+    const indexedPaths = new Set(rows.map((r) => r.file_path));
+    let rowsMissingFiles = 0;
+    for (const r of inScope) {
+        if (!r.file_path || !fs.existsSync(r.file_path))
+            rowsMissingFiles++;
+    }
+    let filesNotIndexed = 0;
+    for (const key of scopeKeys) {
+        for (const fp of iterMemoryFiles(key)) {
+            if (!indexedPaths.has(fp))
+                filesNotIndexed++;
+        }
+    }
+    return {
+        totalMemories: inScope.length,
+        duplicatePairs: pairs,
+        stale,
+        brokenChains,
+        personalInRepo,
+        drift: { filesNotIndexed, rowsMissingFiles },
+    };
+}

package/dist/store/db.js

@@ -111,6 +111,11 @@ export function db() {
     const Database = loadDatabase();
     const d = new Database(indexDb);
     d.exec("PRAGMA journal_mode = WAL;");
+    // Multiple processes share this index (CLI, one MCP server per editor,
+    // the opencode plugin). Without a busy timeout, bun:sqlite defaults to
+    // 0 — any overlapping write fails instantly. 5s matches the tolerance
+    // better-sqlite3 was already giving the CLI/MCP side (D57).
+    d.exec("PRAGMA busy_timeout = 5000;");
     d.exec("PRAGMA synchronous = NORMAL;");
     d.exec("PRAGMA foreign_keys = ON;");
     d.exec(TABLE_SCHEMA);

package/dist/store/markdown.js

@@ -205,7 +205,12 @@ export function writeMemoryFile(fm, body) {
     // Personal stays in appdata and never leaves the machine.
     const dir = memoriesDirFor(fm.scope_key);
     const filePath = path.join(dir, `${fm.id}.md`);
-    fs.writeFileSync(filePath, serialize(fm, body), "utf8");
+    // Atomic publish (D57): write a sibling tmp file and rename over the
+    // target, so a concurrent reader (another process mid-sync) never sees a
+    // torn half-written memory. Same-directory rename is atomic on one fs.
+    const tmpPath = `${filePath}.tmp-${process.pid}`;
+    fs.writeFileSync(tmpPath, serialize(fm, body), "utf8");
+    fs.renameSync(tmpPath, filePath);
     const st = fs.statSync(filePath);
     return { filePath, mtimeMs: st.mtimeMs };
 }

package/dist/tools/memory.js

@@ -1,5 +1,13 @@
-import { tool } from "@opencode-ai/plugin/tool";
 import { addMemory, searchMemories, listMemories, supersedeMemory, forgetMemory, memoryAddArgs, memorySearchArgs, memoryListArgs, memorySupersedeArgs, memoryForgetArgs, TOOL_DESCRIPTIONS, withOutboxNote, } from "./ops.js";
+// Local stand-in for the SDK's tool() helper — same signature, and the SDK
+// function is a runtime identity (`return input`). Do NOT import it from
+// @opencode-ai/plugin at runtime: that package is a devDependency, and when
+// opencode loads this plugin by file:// URL from a global npm install
+// nothing resolves the module — the import fails and opencode silently
+// skips the whole plugin: no error, no tools (D58).
+function tool(input) {
+    return input;
+}
 export function makeTools(getScope, cfg) {
     const memory_add = tool({
         description: TOOL_DESCRIPTIONS.memory_add,

package/dist/tools/ops.js

@@ -40,12 +40,12 @@ export const TOOL_DESCRIPTIONS = {
     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.",
-    memory_status: "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start, when the server reports drafts waiting for review, or when the user says 'sync memory' (or '同步记忆'); then ask the user which drafts to sync.",
-    memory_submit: "Move outbox drafts into the repo memory dir for review: copies the drafts in as proposed (or keeps a local approval), commits locally on the current branch, and moves the outbox originals out. Never creates a branch on its own — pass branch= only with the user's explicit approval for the full chain. Prints the push and PR commands — those need the user's explicit approval and are never run automatically.",
-    memory_propose: "Copy personal memories into the project outbox as review drafts. The personal originals stay put.",
-    memory_promote: "Advance a project memory one step up the review ladder (proposed → approved → published), or reject it with a note. Rejected memories are never deleted — they can be revised and resubmitted.",
-    memory_resolve: "List git-conflicted memory files, or attempt a field-level 3-way merge of one. Semantic conflicts are reported, never auto-resolved.",
-    memory_pr_status: "Read the current branch's GitHub PR and map its review state onto each in-repo memory: merged PR → published, PR approval → approved (approved_by = reviewer), changes-requested → suggestion only. Report by default; apply=true performs the mapped transitions locally (no push).",
+    memory_status: "Show the project memory sync pipeline: drafts waiting in the outbox (appdata), memories in the repo awaiting review or published, and any repo files not yet committed. Call this at session start, when the server reports drafts waiting for review, or when the user says 'sync memory' (or '同步记忆'); then ask the user which drafts to sync. (MCP server and the `open-memex sync-status` CLI; the opencode native plugin does not expose this tool.)",
+    memory_submit: "Move outbox drafts into the repo memory dir for review: copies the drafts in as proposed (or keeps a local approval), commits locally on the current branch, and moves the outbox originals out. Never creates a branch on its own — pass branch= only with the user's explicit approval for the full chain. Prints the push and PR commands — those need the user's explicit approval and are never run automatically. (MCP server and the `open-memex submit` CLI; the opencode native plugin does not expose this tool.)",
+    memory_propose: "Copy personal memories into the project outbox as review drafts. The personal originals stay put. (MCP server and the `open-memex propose` CLI; the opencode native plugin does not expose this tool.)",
+    memory_promote: "Advance a project memory one step up the review ladder (proposed → approved → published), or reject it with a note. Rejected memories are never deleted — they can be revised and resubmitted. (MCP server and the `open-memex promote` CLI; the opencode native plugin does not expose this tool.)",
+    memory_resolve: "List git-conflicted memory files, or attempt a field-level 3-way merge of one. Semantic conflicts are reported, never auto-resolved. (MCP server and the `open-memex resolve` CLI; the opencode native plugin does not expose this tool.)",
+    memory_pr_status: "Read the current branch's GitHub PR and map its review state onto each in-repo memory: merged PR → published, PR approval → approved (approved_by = reviewer), changes-requested → suggestion only. Report by default; apply=true performs the mapped transitions locally (no push). (MCP server and the `open-memex pr-status` CLI; the opencode native plugin does not expose this tool.)",
 };
 /** Shared zod input shapes (raw shape, not z.object — hosts wrap as needed). */
 export const scopeArg = z