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

package/dist/submit.js

@@ -25,7 +25,7 @@ import { loadConfig } from "./config.js";
 import { inRepoMemoriesDir, memoriesDirPath, projectRoot } from "./paths.js";
 import { resolveProjectScope } from "./scope.js";
 import { contentHash } from "./store/lifecycle.js";
-import { msToRfc3339, parse as parseMemory, readMemoryFile, serialize, } from "./store/markdown.js";
+import { msToRfc3339, parse as parseMemory, readMemoryFile, serialize, atomicWriteTextSync, } from "./store/markdown.js";
 import { upsertFromFile, recordSync, readSyncState } from "./store/sync.js";
 import { db } from "./store/db.js";
 import { currentAuthor } from "./review.js";
@@ -127,7 +127,7 @@ export function outboxDraftCount(scopeKey) {
         .get(scopeKey, outboxDir + path.sep);
     return row?.n ?? 0;
 }
-export function formatSyncStatus(st) {
+export function formatSyncStatus(st, opts = {}) {
     const lines = [];
     lines.push(`project: ${st.projectName} (${st.scopeKey})`);
     // D31: when the index was last synced and what triggered it.
@@ -138,19 +138,27 @@ export function formatSyncStatus(st) {
     else {
         lines.push(`last sync: never`);
     }
+    // Agent-facing renders cap each section so a big store can't flood a
+    // tool result; the cap line points at the CLI, which shows everything.
+    const CAP = opts.cap ?? 20;
+    const more = (n) => `  … and ${n} more (full list: open-memex sync-status)`;
     lines.push(`outbox (appdata, pending sync): ${st.outbox.length}`);
-    for (const e of st.outbox) {
+    for (const e of st.outbox.slice(0, CAP)) {
         lines.push(`  ${e.id}  [${e.reviewState}] ${e.title}`);
     }
+    if (st.outbox.length > CAP)
+        lines.push(more(st.outbox.length - CAP));
     const byState = new Map();
     for (const e of st.inRepo)
         byState.set(e.reviewState, (byState.get(e.reviewState) ?? 0) + 1);
     const breakdown = [...byState.entries()].map(([s, n]) => `${n} ${s}`).join(", ") || "none";
     lines.push(`repo .ai/open-memex: ${st.inRepo.length} (${breakdown})`);
-    for (const e of st.inRepo) {
+    for (const e of st.inRepo.slice(0, CAP)) {
         const u = e.gitState === "uncommitted" ? " (uncommitted)" : "";
         lines.push(`  ${e.id}  [${e.reviewState}]${u} ${e.title}`);
     }
+    if (st.inRepo.length > CAP)
+        lines.push(more(st.inRepo.length - CAP));
     if (st.uncommitted.length > 0) {
         lines.push(`note: ${st.uncommitted.length} repo file(s) not yet committed — they ride with the working tree until you commit.`);
     }
@@ -279,7 +287,7 @@ export function submitMemories(ids, opts = {}) {
             ],
         };
         const text = serialize(fm, parsed.body);
-        fs.writeFileSync(destPath, text, "utf8");
+        atomicWriteTextSync(destPath, text);
         written.push({ id: v.id, srcPath: v.srcPath, destPath, hash: contentHash(parsed.body) });
         submitted.push({ id: v.id, filePath: destPath, reviewState: destState });
     }

package/dist/tools/memory.js

@@ -1,3 +1,5 @@
+import { PERSONAL_SCOPE } from "../scope.js";
+import { syncScope } from "../store/sync.js";
 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
@@ -9,10 +11,32 @@ function tool(input) {
     return input;
 }
 export function makeTools(getScope, cfg) {
+    // D64: the plugin host syncs only at bootstrap, so without this the
+    // index goes stale for the whole session — memories added through the
+    // CLI or another client stay invisible to the agent, and same-content
+    // duplicates accumulate. Mirror the MCP server: reconcile from disk
+    // before every tool call. syncScope is mtime-based, so the steady-state
+    // cost is one directory scan.
+    const syncFirst = () => {
+        try {
+            syncScope(getScope().key, "request");
+            syncScope(PERSONAL_SCOPE.key, "request");
+        }
+        catch (err) {
+            // Deliberate asymmetry with the MCP adapter (which lets sync errors
+            // propagate as tool errors): a failed sync must not take the plugin
+            // tools down — the index may be stale for this call but the tool
+            // still answers. Loud at debug, silent otherwise.
+            if (cfg.logLevel === "debug") {
+                console.error("[open-memex] pre-tool sync failed:", err);
+            }
+        }
+    };
     const memory_add = tool({
         description: TOOL_DESCRIPTIONS.memory_add,
         args: memoryAddArgs,
         async execute(args) {
+            syncFirst();
             return withOutboxNote(getScope().key, addMemory(getScope, cfg, args));
         },
     });
@@ -20,6 +44,7 @@ export function makeTools(getScope, cfg) {
         description: TOOL_DESCRIPTIONS.memory_search,
         args: memorySearchArgs,
         async execute(args) {
+            syncFirst();
             return searchMemories(getScope, args);
         },
     });
@@ -27,6 +52,7 @@ export function makeTools(getScope, cfg) {
         description: TOOL_DESCRIPTIONS.memory_list,
         args: memoryListArgs,
         async execute(args) {
+            syncFirst();
             return listMemories(getScope, args);
         },
     });
@@ -34,6 +60,7 @@ export function makeTools(getScope, cfg) {
         description: TOOL_DESCRIPTIONS.memory_supersede,
         args: memorySupersedeArgs,
         async execute(args) {
+            syncFirst();
             return withOutboxNote(getScope().key, supersedeMemory(cfg, args));
         },
     });
@@ -41,6 +68,7 @@ export function makeTools(getScope, cfg) {
         description: TOOL_DESCRIPTIONS.memory_forget,
         args: memoryForgetArgs,
         async execute(args) {
+            syncFirst();
             return withOutboxNote(getScope().key, forgetMemory(args));
         },
     });

package/dist/tools/ops.js

@@ -9,14 +9,16 @@
 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 { search, list, countList, hitStateLabel } from "../retrieve/search.js";
+import { formatInventoryLine, truncationNote } from "../retrieve/display.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 { findDuplicates, supersede, setStatus } from "../store/lifecycle.js";
 import { db } from "../store/db.js";
 import { redact } from "../redact.js";
 import { getSyncStatus, formatSyncStatus, submitMemories, outboxDraftCount } from "../submit.js";
 import { getPrStatus, formatPrStatus, applyPrStatus } from "../github.js";
+import { isInRepoMemoryFile } from "../paths.js";
 import { proposeMemories, promoteMemory, listConflicts, resolveConflict, formatReviewHistory, } from "../review.js";
 /**
  * D53: push, don't poll. Append the project-outbox pending count to mutating
@@ -35,11 +37,11 @@ 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_list: "List memories in a scope, newest first. Useful for browsing what is remembered, or verifying that a save landed.",
+    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, as a numbered inventory. Each line keeps the raw fields — [type] id=… created=… source=… — say them back to the user in plain words (source=user → 'you told me this'; inference → 'I inferred this, check me'; keyword → 'caught from your own wording'), never read the raw id aloud unless they ask. When the user asks 'what do you remember about me?', use scope=both and present the inventory conversationally. The user may point at an entry by its number ('delete #3'): numbers are only valid for the listing you just produced — re-run memory_list, read the candidate back in full, and get a confirmation before calling memory_forget (deletion is permanent). include=all is the audit view (superseded versions, retracted, archived also shown).",
     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_forget: "Delete a memory by id. Use when the user asks to forget something. Deletion is permanent: before deleting, restate the memory's content to the user and get a confirmation. With soft=true the memory is hidden instead (retracted: out of lists and search, file kept, one-way).",
     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.)",
@@ -52,6 +54,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 +66,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()
@@ -78,9 +85,16 @@ export const memorySearchArgs = {
     limit: z.number().int().min(1).max(50).optional(),
 };
 export const memoryListArgs = {
-    scope: scopeArg,
+    scope: z
+        .enum(["project", "personal", "user", "both"])
+        .optional()
+        .describe("Which scope(s) to list. `project` = tied to this repo. `personal` = global across all your projects. `both` lists each scope's newest. Default: project."),
     type: z.string().optional(),
     limit: z.number().int().min(1).max(100).optional(),
+    include: z
+        .enum(["active", "all"])
+        .optional()
+        .describe("D68: `active` (default) shows what is currently remembered — newest version of each fact, retracted/archived hidden. `all` is the audit view: every stored row including superseded versions and hidden ones. The default CHANGED in D68: superseded versions no longer appear unless include=all."),
 };
 export const memorySupersedeArgs = {
     id: z.string().min(1).describe("ID of the memory being replaced."),
@@ -90,9 +104,14 @@ 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),
+    soft: z
+        .boolean()
+        .optional()
+        .describe("D68: hide instead of delete. The memory is retracted — excluded from lists and search — but its file stays. Retraction is one-way (D64): it does not come back; to restore the fact, save it again as a new memory. Offer `soft` when the user is unsure about deleting."),
 };
 export const memoryStatusArgs = {};
 export const memorySubmitArgs = {
@@ -149,6 +168,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 +200,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);
@@ -214,13 +241,52 @@ export async function searchMemories(getScope, args) {
     return { title: `memory: ${hits.length} result(s)`, output: lines.join("\n") };
 }
 export async function listMemories(getScope, args) {
-    const s = resolveScope(getScope, args.scope);
-    const hits = list(s.key, { type: args.type, limit: args.limit });
-    if (hits.length === 0) {
+    // D68: the list is the user's inventory of what is remembered. Lines
+    // are structured (number + id + created= + source= + state tags) and
+    // every section reports its true total — a truncated list says so
+    // instead of quietly looking complete (the D66 sync-status lesson).
+    const include = args.include ?? "active";
+    // D70: numbering runs across every section of THIS listing, so "delete
+    // #3" names exactly one memory. A per-section counter emitted two "#1"s.
+    let seq = 0;
+    const render = (scopeKey) => {
+        const hits = list(scopeKey, { type: args.type, limit: args.limit, include });
+        const total = countList(scopeKey, { type: args.type, include });
+        const lines = hits.map((h) => formatInventoryLine(seq++, h, PERSONAL_SCOPE.key));
+        const note = truncationNote(hits.length, total);
+        if (note)
+            lines.push(note);
+        return lines;
+    };
+    if (args.scope === "both") {
+        // D64: "what do you remember about me" spans both stores; search
+        // already defaults to both, list now matches. Each scope lists its
+        // own newest (the limit applies per scope).
+        const project = getScope();
+        const sections = [];
+        for (const s of [PERSONAL_SCOPE, project]) {
+            const lines = render(s.key);
+            const heading = s.key === PERSONAL_SCOPE.key
+                ? "## About you (personal — stays on this machine, applies everywhere)"
+                : `## This project (${s.projectName || s.key})`;
+            sections.push(lines.length === 0 ? `${heading}\n(none yet)` : `${heading}\n${lines.join("\n")}`);
+        }
+        return { title: "memory: list (both scopes)", output: sections.join("\n\n") };
+    }
+    const s = resolveScope(getScope, args.scope === "project" || args.scope === "personal" || args.scope === "user"
+        ? args.scope
+        : undefined);
+    const lines = render(s.key);
+    if (lines.length === 0) {
         return { title: "memory: empty", output: `No memories in scope ${s.key}.` };
     }
-    const lines = hits.map((h) => `- [${h.type}]${hitStateLabel(h)} id=${h.id} — ${h.snippet.replace(/\s+/g, " ").trim()}`);
-    return { title: `memory: ${hits.length} in ${s.key}`, output: lines.join("\n") };
+    const heading = s.key === PERSONAL_SCOPE.key
+        ? "## About you (personal — stays on this machine, applies everywhere)"
+        : `## This project (${s.projectName || s.key})`;
+    return {
+        title: `memory: ${countList(s.key, { type: args.type, include })} in ${s.key}`,
+        output: `${heading}\n${lines.join("\n")}`,
+    };
 }
 export async function supersedeMemory(cfg, args) {
     const { content: redacted, hadSecret, matchedPattern } = redact(args.content, cfg.redactPatterns);
@@ -230,6 +296,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);
@@ -253,17 +324,57 @@ export async function forgetMemory(args) {
     if (!row) {
         return { title: "memory: not found", output: `No memory with id ${args.id}.` };
     }
+    if (args.soft) {
+        // D68: hide instead of delete. The status flip is the whole action —
+        // retrieval and the inventory exclude retracted, the file stays put.
+        // One-way (D64): no un-hide; restoring the fact means saving it again.
+        try {
+            const mf = setStatus(args.id, "retracted");
+            upsertFromFile(mf);
+            return {
+                title: "memory: hidden",
+                output: `Hidden ${args.id} (retracted). It no longer appears in lists or search, but the file is kept. This is one-way — to bring the fact back, save it again as a new memory.` +
+                    // D70: a retraction of an in-repo memory is a local working-tree
+                    // edit like the delete — without a commit (and a push) the memory
+                    // stands on every teammate's clone, so "hidden" would be a lie.
+                    (isInRepoMemoryFile(row.file_path)
+                        ? ` Note: this memory lives in the repo (.ai/open-memex/), so the retraction is only local until you commit and push it — until then the team still sees it.`
+                        : ""),
+            };
+        }
+        catch (e) {
+            return { title: "memory: hide failed", output: e.message };
+        }
+    }
     // Delete by indexed file_path — location-agnostic (appdata or in-repo, 2B/D24).
+    // Only ENOENT counts as "deleted": on any other unlink failure the file
+    // is still the source of truth and would be re-indexed on next sync, so
+    // report failure instead of lying (P0 review, 2026-10-03).
     if (row.file_path) {
         try {
             fs.unlinkSync(row.file_path);
         }
-        catch {
-            /* already gone */
+        catch (e) {
+            const code = e.code;
+            if (code !== "ENOENT") {
+                return {
+                    title: "memory: forget failed",
+                    output: `Could not delete ${row.file_path} (${code ?? "error"}) — the memory was NOT forgotten and is still in the index. Close anything holding the file and retry.`,
+                };
+            }
         }
     }
     deleteFromIndex(args.id);
-    return { title: "memory: forgotten", output: `Deleted ${args.id}.` };
+    // D64: forgetting an in-repo memory deletes a file inside the user's
+    // git working tree. Say so — the deletion should ride a commit, or the
+    // file silently diverges from what teammates have.
+    const inRepo = isInRepoMemoryFile(row.file_path);
+    return {
+        title: "memory: forgotten",
+        output: inRepo
+            ? `Deleted ${args.id}. Note: the file lived in the repo (.ai/open-memex/) — commit the deletion so the team sees it too.`
+            : `Deleted ${args.id}.`,
+    };
 }
 // ---------------------------------------------------------------------------
 // 2B/D26: review workflow ops (also exposed over MCP so agents can drive the

package/docs/CURATOR.md

@@ -7,9 +7,13 @@ decide who is *allowed* to.
 
 ## What the curator does
 
-1. **Triage proposals.** `open-memex propose` puts memories up for review.
-   The curator reads them, then `open-memex promote <id>` to approve or
-   `open-memex promote <id> --reject` to send back, with `--note` saying why.
+1. **Triage proposals.** Contributors put a memory up for review in two
+   steps: `open-memex propose` (personal memory → outbox draft), then
+   `open-memex submit` (draft lands in the repo as `proposed`, riding a
+   branch/PR). The curator reviews the proposed ones: `open-memex promote
+   <id>` approves (promote again to publish), or `open-memex promote <id>
+   --reject` to send back, with `--note` saying why. (`promote` refuses
+   drafts by design — an outbox draft must be submitted first.)
 2. **Resolve conflicts.** `open-memex resolve` lists file-level and semantic
    conflicts. The curator merges or picks a winner — Core never silently
    resolves a semantic conflict; both sides stay `active` until a human