opencode-mempalace-persistence 2.1.0 → 2.3.0

package/README.md

@@ -6,8 +6,12 @@ An OpenCode plugin that automatically saves every conversation to MemPalace and
 
 Follows the official MemPalace automation pattern (same as the Claude Code hooks): the plugin decides **when** to save, the model decides **what** to file via the MemPalace MCP tools.
 
+[![npm version](https://img.shields.io/npm/v/opencode-mempalace-persistence.svg)](https://www.npmjs.com/package/opencode-mempalace-persistence)
+[![npm downloads](https://img.shields.io/npm/dm/opencode-mempalace-persistence.svg)](https://www.npmjs.com/package/opencode-mempalace-persistence)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
+![Demo: a decision filed on Monday is recalled verbatim by a different session on Thursday — memory outlives sessions, not just compaction](demo.gif)
+
 ---
 
 ## How it works in 3 seconds
@@ -170,12 +174,12 @@ You ask a question
   → Model files topics/decisions/quotes via MCP tools, then answers
 
 The model responds
-  → Plugin detects the response is complete
-  → Saves the conversation to MemPalace (flat export, no hardcoded wings)
+  → Once the turn completes, the next idle/exit/startup mines it to MemPalace (flat export, no hardcoded wings)
   → Model records new KG facts via MCP tools (only when something new emerged)
 
 Session goes idle / process exits
   → Background mine of everything new since last sync
+  → TUI toast confirms what was mined (disable with `"toasts": false`)
 
 Compaction starts
   → [MemPalace Pre-Compact Emergency Save]: model files everything first
@@ -190,7 +194,7 @@ Next time you ask
 
 ## What gets saved
 
-Every turn (question + answer) is saved as a drawer in MemPalace. No forced categorization — mining runs with `--mode convos --extract general`, so MemPalace itself classifies content into decisions, preferences, milestones, problems, and emotional context. Exports are grouped one wing per project (official multi-project pattern: `bot-oc` sessions land in wing `bot-oc`, never leaking across projects). The model additionally records KG facts (decisions, milestones, preferences) during conversation and at each checkpoint via MCP tools.
+Every turn (question + answer) is saved as a drawer in MemPalace. Mining runs with `--mode convos` (default `exchange` extraction: one drawer per exchange pair, verbatim, no paraphrasing). Exports are grouped one wing per project (official multi-project pattern: `bot-oc` sessions land in wing `bot-oc`, never leaking across projects). Only completed turns are exported (in-flight replies are revisited by the next sync). The model additionally records KG facts (decisions, milestones, preferences) during conversation and at each checkpoint via MCP tools.
 
 ### Backfill existing sessions
 
@@ -218,18 +222,16 @@ The plugin exports everything in the opencode database on the next sync, then re
                  │    ↓                          │
                  │  Model sees context → answers │
                  │    ↓                          │
-  Answer done ──►│  chat.message (count) + session.idle    │
-                  │  Every N msgs / idle / exit:              │
-                  │    ↓                          │
-                  │  Query OpenCode DB            │
-                  │  since last sync              │
-                  │    ↓                          │
-                  │  Export → flat text files     │
-                  │    ↓                          │
-                  │  mempalace mine --mode convos │
-                  │  --extract general (async)    │
-                  │  single serialized call       │
-                  └──────────────────────────────┘
+  Answer done ──►│  chat.message (count) + session.idle   │
+                 │  mine on idle / exit / startup           │
+                 │    ↓                                     │
+                 │  Query OpenCode DB (completed turns)     │
+                 │    ↓                                     │
+                 │  Export → flat text files (0700)         │
+                 │    ↓                                     │
+                 │  mempalace mine --mode convos            │
+                 │  single serialized call                  │
+                 └──────────────────────────────────────────┘
                             │
                             ▼
                  ┌──────────────────────────┐
@@ -258,7 +260,8 @@ The plugin exports everything in the opencode database on the next sync, then re
 | `~/.config/opencode/skills/mempalace-recall/SKILL.md` | Bundled recall skill (copy from `skills/` in this repo) |
 | `~/.mempalace/identity.txt` | Your identity (injected by plugin) |
 | `~/.mempalace/hook_state/opencode_counters.json` | Per-session message counters (checkpoint cadence) |
-| `~/.mempalace/hook_state/hook.log` | Checkpoint / pre-compact event log |
+| `~/.mempalace/hook_state/hook.log` | Checkpoint / pre-compact event log (errors always land here) |
+| `~/.mempalace/oc-sessions/` | Private (0700) export workspace for pending transcripts |
 | `~/.mempalace/config.json` | MemPalace config (palace path) |
 | `~/.mempalace/knowledge_graph.sqlite3` | Knowledge Graph (structured facts) |
 | `~/opencode-memory/` | MemPalace vector DB (all drawers) |

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-declare const _default: () => Promise<{
+declare const _default: ({ client }: any) => Promise<{
     "chat.message": (input: {
         sessionID: string;
         agent?: string;

package/dist/index.js

@@ -12,8 +12,11 @@ const IDENTITY_FILE = join(HOME, ".mempalace/identity.txt");
 const HOOK_STATE_DIR = join(HOME, ".mempalace/hook_state");
 const COUNTERS_FILE = join(HOOK_STATE_DIR, "opencode_counters.json");
 const HOOK_LOG = join(HOOK_STATE_DIR, "hook.log");
-const OUT_DIR = "/tmp/oc-sessions";
-const TMP_SCRIPT = "/tmp/oc-plugin-query.py";
+// Private sync workspace (0700): transcripts contain conversation text,
+// so they must never sit world-readable in /tmp (see PR #1524 review).
+const SYNC_DIR = join(HOME, ".mempalace/oc-sessions");
+const OUT_DIR = SYNC_DIR;
+const TMP_SCRIPT = join(SYNC_DIR, "oc-plugin-query.py");
 const DEBUG = !!process.env.OPENCODE_MEMPALACE_DEBUG;
 const LOG_FILE = "/tmp/opencode-mempalace.log";
 const MAX_INJECT_CHARS = 900;
@@ -43,6 +46,29 @@ function errLog(msg) {
     log("ERROR: " + msg);
     hookLog("ERROR: " + msg);
 }
+function toastsEnabled() {
+    try {
+        const raw = readFileSync(PLUGIN_CONFIG, "utf-8");
+        const v = JSON.parse(raw)?.toasts;
+        if (v === false)
+            return false;
+    }
+    catch { }
+    return true;
+}
+// TUI toast client (set by the factory). Fire-and-forget: headless runs
+// (`opencode run`, no TUI attached) must never break on this.
+let tuiClient = null;
+function toast(variant, title, message) {
+    if (!toastsEnabled() || !tuiClient?.tui?.showToast)
+        return;
+    try {
+        const p = tuiClient.tui.showToast({ body: { title, message, variant, duration: 5000 } });
+        if (p && typeof p.catch === "function")
+            p.catch(() => { });
+    }
+    catch { }
+}
 // Probe for a working Python interpreter at startup instead of hardcoding
 // one installer layout (pipx vs uv tool vs system). runPython only needs
 // stdlib (sqlite3/json), so any python3 works. Priority: explicit env
@@ -87,7 +113,8 @@ function runPython(code) {
     const python = resolvePython();
     if (!python)
         throw new Error("no working Python interpreter (see hook.log)");
-    writeFileSync(TMP_SCRIPT, code);
+    mkdirSync(SYNC_DIR, { recursive: true, mode: 0o700 });
+    writeFileSync(TMP_SCRIPT, code, { mode: 0o600 });
     try {
         // argv array, no shell (see PR #2): paths here are fixed, never user input.
         return execFileSync(python, [TMP_SCRIPT], { encoding: "utf-8", timeout: 30000 }).trim();
@@ -99,6 +126,39 @@ function runPython(code) {
         catch { }
     }
 }
+// Resolve the mempalace CLI without hardcoding one installer layout:
+// explicit env override, PATH lookup (cross-platform, incl. Windows),
+// legacy ~/.local/bin fallback.
+let resolvedBin = undefined;
+function resolveBin() {
+    if (resolvedBin !== undefined)
+        return resolvedBin;
+    const envBin = process.env.MEMPALACE_BIN;
+    if (envBin && existsSync(envBin)) {
+        resolvedBin = envBin;
+    }
+    else {
+        try {
+            const found = execSync(process.platform === "win32" ? "where mempalace" : "command -v mempalace", {
+                encoding: "utf-8", timeout: 10000,
+            }).trim().split(/\r?\n/)[0]?.trim();
+            if (found)
+                resolvedBin = found;
+        }
+        catch { }
+        if (!resolvedBin && existsSync(MEMPALACE_BIN))
+            resolvedBin = MEMPALACE_BIN;
+        if (!resolvedBin)
+            resolvedBin = null;
+    }
+    if (resolvedBin) {
+        log("using mempalace: " + resolvedBin);
+    }
+    else {
+        errLog("mempalace CLI not found (tried MEMPALACE_BIN env, PATH, ~/.local/bin) — search/wake-up/mine disabled");
+    }
+    return resolvedBin;
+}
 function hasText(parts) {
     return parts
         .filter((p) => p?.type === "text" && p?.text?.trim())
@@ -143,9 +203,12 @@ function persistCounters(counters) {
     }
 }
 function mempalaceWakeup() {
+    const bin = resolveBin();
+    if (!bin)
+        return "";
     try {
         // argv array, no shell.
-        const out = execFileSync(MEMPALACE_BIN, ["wake-up"], { encoding: "utf-8", timeout: 15000 }).trim();
+        const out = execFileSync(bin, ["wake-up"], { encoding: "utf-8", timeout: 15000 }).trim();
         if (!out)
             return "";
         return out.slice(0, MAX_WAKEUP_CHARS);
@@ -178,10 +241,13 @@ function readIdentity() {
     }
 }
 function mempalaceSearch(query) {
+    const bin = resolveBin();
+    if (!bin)
+        return "";
     try {
         // argv array, no shell (see PR #2): the query is raw user message
         // text, so it must never pass through /bin/sh. No manual escaping needed.
-        const out = execFileSync(MEMPALACE_BIN, ["search", query, "--results", String(MAX_SEARCH_RESULTS)], {
+        const out = execFileSync(bin, ["search", query, "--results", String(MAX_SEARCH_RESULTS)], {
             encoding: "utf-8",
             timeout: 15000,
         }).trim();
@@ -245,8 +311,11 @@ print(json.dumps(rows))
     if (!sessionsArr || sessionsArr.length === 0)
         return { wings: new Map(), now: Date.now() };
     const now = Date.now();
+    // Never advance the cursor past an in-flight reply: anything skipped
+    // as incomplete is revisited by the next sync (idle/exit/startup).
+    let cursor = now;
     const wings = new Map();
-    mkdirSync(OUT_DIR, { recursive: true });
+    mkdirSync(OUT_DIR, { recursive: true, mode: 0o700 });
     for (const sess of sessionsArr) {
         const [sessId, title, , directory] = sess;
         const wing = ((directory || "").split("/").filter(Boolean).pop() || "global")
@@ -262,10 +331,20 @@ rows = db.execute("""
   ORDER BY m.time_created
 """).fetchall()
 texts = []
+incomplete = []
 for (mid, mts, mdata_raw) in rows:
     try: mdata = json.loads(mdata_raw)
     except: mdata = {}
     role = mdata.get("role", "unknown")
+    # Completion tracking (see PR #1524 review): the assistant message row
+    # is created when a reply STARTS, parts stream in afterwards, and
+    # finish is set only on completion. Exporting mid-reply would
+    # snapshot partial parts while the cursor advances past the message
+    # timestamp — losing the rest of the reply forever. So assistant
+    # messages without finish are skipped and revisited next sync.
+    if role == "assistant" and not mdata.get("finish"):
+        incomplete.append(mts)
+        continue
     for (pdata_raw,) in db.execute("SELECT data FROM part WHERE message_id = ? ORDER BY time_created", (mid,)).fetchall():
         try:
             pdata = json.loads(pdata_raw)
@@ -273,16 +352,22 @@ for (mid, mts, mdata_raw) in rows:
                 texts.append({"role": role, "text": pdata.get("text").strip(), "ts": mts})
         except: pass
 db.close()
-print(json.dumps(texts))
+print(json.dumps({"texts": texts, "incomplete": incomplete}))
 `);
         let msgList;
+        let incompleteTs = [];
         try {
-            msgList = JSON.parse(msgs);
+            const parsed = JSON.parse(msgs);
+            msgList = parsed.texts;
+            incompleteTs = parsed.incomplete || [];
         }
         catch {
             continue;
         }
-        if (msgList.length < 2)
+        if (incompleteTs.length > 0) {
+            cursor = Math.min(cursor, Math.min(...incompleteTs) - 1);
+        }
+        if (msgList.length < 2 && incompleteTs.length === 0)
             continue;
         const lines = [
             `# ${title || label}`,
@@ -302,26 +387,28 @@ print(json.dumps(texts))
             continue;
         const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 12);
         const wingDir = join(OUT_DIR, wing);
-        mkdirSync(wingDir, { recursive: true });
+        mkdirSync(wingDir, { recursive: true, mode: 0o700 });
         const fname = `sync_${prefix}_${contentHash}.txt`;
-        writeFileSync(join(wingDir, fname), content + "\n");
+        writeFileSync(join(wingDir, fname), content + "\n", { mode: 0o600 });
         if (!wings.has(wing))
             wings.set(wing, []);
         wings.get(wing).push(join(wingDir, fname));
     }
-    return { wings, now };
+    return { wings, now: cursor };
 }
 function markSynced(now) {
     writeFileSync(STATE_FILE, JSON.stringify({ last_sync_ms: now }));
     lastSyncTs = Date.now();
 }
-// Official classification: decisions, preferences, milestones, problems,
-// emotional context. Agent tag keeps opencode-mined drawers attributable.
+// Default `exchange` extraction: one drawer per exchange pair, verbatim,
+// no paraphrasing (see PR #1524 review). Intelligent filing (decisions,
+// KG facts, diary) happens through AI checkpoints, not the miner.
+// Agent tag keeps opencode-mined drawers attributable.
 // One wing per project (official multi-project pattern).
 // Argv array, no shell (see PR #2): wing names are sanitized, but the
 // spawn path stays shell-free regardless.
 function mineArgs(wingDir, wing) {
-    return ["mine", wingDir, "--mode", "convos", "--extract", "general", "--agent", "opencode", "--wing", wing];
+    return ["mine", wingDir, "--mode", "convos", "--agent", "opencode", "--wing", wing];
 }
 function cleanupExport(wings) {
     for (const files of wings.values()) {
@@ -370,6 +457,8 @@ function doDbSync() {
             markSynced(now);
             cleanupExport(wings);
             log("mine done");
+            const names = [...wings.keys()].join(", ");
+            toast("success", "MemPalace", `mined ${wingCount(wings)} session(s) → ${names}`);
             return;
         }
         const [wing, files] = entries[i];
@@ -377,12 +466,19 @@ function doDbSync() {
         // wrapper shell and orphan the python mine process, which keeps
         // holding the palace lock while the next mine piles up. miningLock
         // already serializes concurrent mines; long mines run to completion.
-        execFile(MEMPALACE_BIN, mineArgs(join(OUT_DIR, wing), wing), {
+        const bin = resolveBin();
+        if (!bin) {
+            miningLock = false;
+            errLog("mine skipped: mempalace CLI not found");
+            return;
+        }
+        execFile(bin, mineArgs(join(OUT_DIR, wing), wing), {
             encoding: "utf-8",
         }, (err) => {
             if (err) {
                 miningLock = false;
                 errLog(`mine err (${wing}): ${err.message}`);
+                toast("error", "MemPalace", `mine failed (${wing}): ${err.message.slice(0, 120)}`);
                 return;
             }
             log(`mined wing ${wing} (${files.length} sessions)`);
@@ -392,17 +488,31 @@ function doDbSync() {
     mineNext(0);
 }
 // Best-effort synchronous save for process exit (SIGINT/SIGTERM/exit):
-// only synchronous calls are allowed here.
+// only synchronous calls are allowed here. Bounded by EXIT_BUDGET_MS so
+// shutdown stays fast; miningLock is deliberately ignored here because
+// any in-flight async mine dies with the process — at exit this sync
+// mine takes ownership (see PR #1524 review).
+const EXIT_BUDGET_MS = 45000;
+const EXIT_WING_TIMEOUT_MS = 30000;
 function exitSync() {
     try {
+        const bin = resolveBin();
+        if (!bin)
+            return;
         const { wings, now } = exportNewSessions(getLastSync());
         if (wings.size === 0)
             return;
+        const deadline = Date.now() + EXIT_BUDGET_MS;
         for (const [wing] of wings) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                log("exit save: budget exhausted, rest covered next startup");
+                break;
+            }
             log(`exit save: mining wing ${wing}`);
-            const res = spawnSync(MEMPALACE_BIN, mineArgs(join(OUT_DIR, wing), wing), {
+            const res = spawnSync(bin, mineArgs(join(OUT_DIR, wing), wing), {
                 encoding: "utf-8",
-                timeout: 60000,
+                timeout: Math.min(EXIT_WING_TIMEOUT_MS, remaining),
             });
             if (res.error || res.status !== 0) {
                 errLog(`exit mine err (${wing}): ${String(res.error || res.status)}`);
@@ -417,13 +527,17 @@ function exitSync() {
         errLog("exit save err: " + String(e));
     }
 }
-export default (async () => {
-    mkdirSync(OUT_DIR, { recursive: true });
+export default (async ({ client }) => {
+    tuiClient = client || null;
+    mkdirSync(OUT_DIR, { recursive: true, mode: 0o700 });
     mkdirSync(HOOK_STATE_DIR, { recursive: true });
     const autoInject = isAutoInjectEnabled();
     const identity = readIdentity();
     const interval = saveInterval();
     log(`loaded (autoInjectContext: ${autoInject}, saveInterval: ${interval})`);
+    // Catch anything missed by a previous run (e.g. content skipped when
+    // the exit budget ran out). Fires once per server lifetime.
+    setTimeout(() => dbSync(), 10000);
     // Crash safety: best-effort synchronous save on hard exit.
     // Mirrors the official emergency-save intent (nothing async allowed here).
     let exitHandled = false;
@@ -448,6 +562,10 @@ export default (async () => {
             // Official Save-hook cadence: count human messages per session,
             // persist like ~/.mempalace/hook_state/, arm ONE AI checkpoint
             // per boundary. The model decides WHAT to file.
+            // NOTE: no mine here by design (see PR #1524 review) — mining a
+            // mid-reply snapshot would export partial assistant parts. Mines
+            // run on idle/exit/startup, when turns are complete; the export
+            // additionally skips unfinished replies (finish tracking).
             const counters = loadCounters();
             const c = counters[sessionID] || { humanMsgs: 0, lastCheckpoint: 0 };
             c.humanMsgs += 1;
@@ -456,8 +574,7 @@ export default (async () => {
                 c.lastCheckpoint = boundary;
                 pendingCheckpoint = { sessionID, count: c.humanMsgs };
                 hookLog(`session ${sessionID}: ${c.humanMsgs} human msgs — checkpoint armed`);
-                log("threshold crossed - queue sync");
-                setTimeout(() => dbSync(), 500);
+                toast("info", "MemPalace", `checkpoint armed (~${c.humanMsgs} msgs): the model will file memories now`);
             }
             counters[sessionID] = c;
             persistCounters(counters);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-mempalace-persistence",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "OpenCode plugin — auto-sync conversations to MemPalace memory in real-time. No forced wings, KG extraction via MCP tools.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",