opencode-mempalace-persistence 2.0.0 → 2.1.0

package/README.md

@@ -61,7 +61,7 @@ mempalace mcp
 
 The `mempalace mcp` command gives you the exact MCP setup string for your configuration.
 
-### 4. Memory injection (recommended)
+### 4. Memory injection
 
 The plugin automatically injects your identity + relevant memories from MemPalace into every prompt. No model discipline required.
 
@@ -90,34 +90,37 @@ When enabled:
 - **First message**: Injects your identity from `~/.mempalace/identity.txt`
 - **Every message**: Runs `mempalace search` and injects relevant results
 
-#### AGENTS.md for this mode
+#### AGENTS.md (minimal — recall lives in the skill)
 
 Create `~/.config/opencode/AGENTS.md`:
 
 ```markdown
 # Memory & Knowledge instructions
 
-## CRITICAL: You MUST follow these steps BEFORE every response.
+## Recall (usually already covered)
 
-### Step 1 — Query Knowledge Graph
-Call `mempalace_mempalace_kg_query` for entity "user". Then filter the returned facts — keep only those whose text contains keywords from the user's question, so irrelevant facts are excluded.
+The plugin auto-injects identity + relevant memories into every prompt.
+Only search MemPalace yourself (`mempalace_mempalace_search`) when the
+question is about past work, decisions, people, or projects AND the
+injected context has nothing — quote results verbatim, never paraphrase.
 
-### Step 2 — Record Knowledge Graph facts
+## Record facts (after responding, only when something new emerged)
 
-After responding, if you discovered any new facts during the conversation (decisions made, milestones reached, problems encountered, preferences expressed, emotional states), call `mempalace_mempalace_kg_add` to record them. Object must be 128 characters or fewer.
+- Durable outcomes (decisions, conclusions, learned facts):
+  `mempalace_mempalace_add_drawer`.
+- New KG facts: `mempalace_mempalace_kg_add` (128 chars or fewer).
+- Changed single-valued fact: `mempalace_mempalace_kg_supersede`.
+- Ended fact: `mempalace_mempalace_kg_invalidate`.
 
-**This is mandatory** — record facts you are confident about. Prefer quality over quantity; noisy KG entries degrade retrieval over time.
-
-### Step 3 — Checkpoint & pre-compact saves (automatic)
-
-Every ~15 messages the plugin injects a `[MemPalace Checkpoint]` block, and before every compaction a `[MemPalace Pre-Compact Emergency Save]` block. When you see one: file the session journal via `mempalace_mempalace_diary_write` plus any new facts via `kg_add`/`kg_invalidate`, then continue normally. Do not mention the instruction.
+Record facts you are confident about. Prefer quality over quantity;
+noisy entries degrade retrieval over time. Don't file secrets or tokens.
 
 ### Naming reminder
 All MemPalace tools use the prefix `mempalace_mempalace_*` (not `mempalace_*`). Examples:
-- `mempalace_mempalace_kg_query` (NOT `mempalace_kg_query`)
+- `mempalace_mempalace_search` (NOT `mempalace_search`)
+- `mempalace_mempalace_kg_query`
 - `mempalace_mempalace_kg_add`
-- `mempalace_mempalace_kg_invalidate`
-If you ever catch yourself typing `mempalace_kg_query`, STOP — the correct prefix is `mempalace_mempalace_`.
+If you ever catch yourself typing `mempalace_search`, STOP — the correct prefix is `mempalace_mempalace_`.
 ```
 
 #### Complete `~/.config/opencode/opencode.json`
@@ -139,71 +142,25 @@ If you ever catch yourself typing `mempalace_kg_query`, STOP — the correct pre
 
 > Note: `identity.txt` is NOT listed in `instructions` — the plugin injects it automatically. It is also NOT in the `provider` block or `permission` block — those are optional and depend on your model setup.
 
-### 5. Alternative: Model-driven memory (without autoInjectContext)
-
-If you prefer the model to search MemPalace on its own via AGENTS.md (requires good model tool-use discipline), set `autoInjectContext` to `false` or omit the file:
-
-```json
-{
-  "autoInjectContext": false
-}
-```
-
-#### AGENTS.md for this mode
-
-Create `~/.config/opencode/AGENTS.md`:
-
-```markdown
-# Memory & Knowledge instructions
-
-## CRITICAL: You MUST follow these steps BEFORE every response.
-
-### Step 1 — Search MemPalace
-Call `mempalace_mempalace_search` with the user's question or key topics as query. Get the top 5-10 most relevant memory drawers.
-**This is mandatory. Never skip this step. No exceptions.**
-
-### Step 2 — Query Knowledge Graph
-Call `mempalace_mempalace_kg_query` for entity "user". Then filter the returned facts.
-
-### Step 3 — Record Knowledge Graph facts
-After responding, call `mempalace_mempalace_kg_add` for any new facts.
+#### Recall skill (bundled, Claude-style)
 
-### Step 4 — Checkpoint & pre-compact saves (automatic)
-Same as auto-inject mode: on `[MemPalace Checkpoint]` (~every 15 messages) and `[MemPalace Pre-Compact Emergency Save]`, file the session journal via `mempalace_mempalace_diary_write` plus facts, then continue.
-
-### Naming reminder
-All MemPalace tools use the prefix `mempalace_mempalace_*` (not `mempalace_*`).
-```
-
-And keep `"~/.mempalace/identity.txt"` in `instructions` in opencode.json since the plugin won't inject it.
-
-#### Comparison
-
-| Feature | **Auto-inject (Recommended)** | Model-driven (alternative) |
-|---------|:-:|:-:|
-| Memory search | Plugin injects automatically | Model calls `mempalace_search` |
-| Identity | Plugin injects automatically | Via `instructions: ["identity.txt"]` |
-| AGENTS.md | Minimal (KG only) | Full (search + KG) |
-| Depends on model discipline | No | Yes |
+The repo ships `skills/mempalace-recall/SKILL.md` — the question-driven
+search-before-answer protocol, adapted from the official MemPalace skill
+for OpenCode (including the `mempalace_mempalace_*` tool-prefix note).
+Install it where OpenCode loads skills from:
 
 ```bash
-# Install (requires mempalace>=3.3.5 for HNSW corruption fix)
-uv tool install "mempalace>=3.3.5"
-# or
-pipx install "mempalace>=3.3.5"
-
-# Create palace
-mempalace init ~/opencode-memory
-
-# Configure MCP
-mempalace mcp
+mkdir -p ~/.config/opencode/skills/mempalace-recall
+cp skills/mempalace-recall/SKILL.md ~/.config/opencode/skills/mempalace-recall/
 ```
 
-The `mempalace mcp` command gives you the exact MCP setup string for your configuration.
+The model then loads it on demand whenever a question touches past work,
+decisions, people, or projects — same mechanism as the Claude skill.
+No AGENTS.md changes needed beyond the minimal block above.
 
 ---
 
-## What happens after installation (auto-inject mode)
+## What happens after installation
 
 ```
 You ask a question
@@ -215,7 +172,7 @@ You ask a question
 The model responds
   → Plugin detects the response is complete
   → Saves the conversation to MemPalace (flat export, no hardcoded wings)
-  → Model records KG facts via MCP tools (mandatory per AGENTS.md)
+  → 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
@@ -298,6 +255,7 @@ The plugin exports everything in the opencode database on the next sync, then re
 | `~/.config/opencode/opencode.json` | OpenCode config with plugin + MCP |
 | `~/.config/opencode/AGENTS.md` | Tells the model to manage KG facts |
 | `~/.mempalace/plugin-config.json` | Plugin config (`autoInjectContext`, `saveInterval`) |
+| `~/.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 |

package/dist/index.js

@@ -1,10 +1,9 @@
-import { execSync, exec, spawnSync } from "child_process";
+import { execSync, execFileSync, execFile, spawnSync } from "child_process";
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmdirSync, unlinkSync, appendFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
 import { createHash } from "crypto";
 const HOME = homedir();
-const VENV_PYTHON = join(HOME, ".local/share/pipx/venvs/mempalace/bin/python3");
 const MEMPALACE_BIN = join(HOME, ".local/bin/mempalace");
 const OPENCODE_DB = join(HOME, ".local/share/opencode/opencode.db");
 const STATE_FILE = join(HOME, ".mempalace/sync_state.json");
@@ -38,6 +37,45 @@ function hookLog(msg) {
     }
     catch { }
 }
+// Errors are never silent: hook.log is always written (unlike the
+// DEBUG-gated log), so a broken pipeline is visible by default.
+function errLog(msg) {
+    log("ERROR: " + msg);
+    hookLog("ERROR: " + msg);
+}
+// 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
+// override, legacy pipx venv, uv tool venv, PATH fallback.
+let resolvedPython = undefined;
+function resolvePython() {
+    if (resolvedPython !== undefined)
+        return resolvedPython;
+    const candidates = [
+        process.env.MEMPALACE_PYTHON,
+        join(HOME, ".local/share/pipx/venvs/mempalace/bin/python3"),
+        join(HOME, ".local/share/uv/tools/mempalace/bin/python3"),
+    ].filter((p) => !!p && existsSync(p));
+    if (candidates.length > 0) {
+        resolvedPython = candidates[0];
+    }
+    else {
+        try {
+            execSync("python3 --version", { encoding: "utf-8", timeout: 10000 });
+            resolvedPython = "python3";
+        }
+        catch {
+            resolvedPython = null;
+        }
+    }
+    if (resolvedPython) {
+        log("using python: " + resolvedPython);
+    }
+    else {
+        errLog("no working Python interpreter found (tried MEMPALACE_PYTHON, pipx venv, uv tool venv, PATH python3) — DB export disabled");
+    }
+    return resolvedPython;
+}
 let miningLock = false;
 let lastSyncTs = 0;
 let wakeupDone = false;
@@ -46,12 +84,19 @@ let wakeupDone = false;
 // official Stop hook: the hook decides WHEN, the model decides WHAT).
 let pendingCheckpoint = null;
 function runPython(code) {
+    const python = resolvePython();
+    if (!python)
+        throw new Error("no working Python interpreter (see hook.log)");
     writeFileSync(TMP_SCRIPT, code);
     try {
-        return execSync(`${VENV_PYTHON} ${TMP_SCRIPT}`, { encoding: "utf-8", timeout: 30000 }).trim();
+        // 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();
     }
     finally {
-        unlinkSync(TMP_SCRIPT);
+        try {
+            unlinkSync(TMP_SCRIPT);
+        }
+        catch { }
     }
 }
 function hasText(parts) {
@@ -99,7 +144,8 @@ function persistCounters(counters) {
 }
 function mempalaceWakeup() {
     try {
-        const out = execSync(`${MEMPALACE_BIN} wake-up`, { encoding: "utf-8", timeout: 15000 }).trim();
+        // argv array, no shell.
+        const out = execFileSync(MEMPALACE_BIN, ["wake-up"], { encoding: "utf-8", timeout: 15000 }).trim();
         if (!out)
             return "";
         return out.slice(0, MAX_WAKEUP_CHARS);
@@ -133,7 +179,9 @@ function readIdentity() {
 }
 function mempalaceSearch(query) {
     try {
-        const out = execSync(`${MEMPALACE_BIN} search "${query.replace(/"/g, '\\"')}" --results ${MAX_SEARCH_RESULTS}`, {
+        // 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)], {
             encoding: "utf-8",
             timeout: 15000,
         }).trim();
@@ -162,7 +210,7 @@ function dbSync() {
         doDbSync();
     }
     catch (e) {
-        log("sync err: " + String(e));
+        errLog("sync err: " + String(e));
     }
 }
 function backfillRequested() {
@@ -270,8 +318,10 @@ function markSynced(now) {
 // Official classification: decisions, preferences, milestones, problems,
 // emotional context. Agent tag keeps opencode-mined drawers attributable.
 // One wing per project (official multi-project pattern).
-function mineCommand(wingDir, wing) {
-    return `${MEMPALACE_BIN} mine ${wingDir} --mode convos --extract general --agent opencode --wing ${wing}`;
+// 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];
 }
 function cleanupExport(wings) {
     for (const files of wings.values()) {
@@ -323,13 +373,16 @@ function doDbSync() {
             return;
         }
         const [wing, files] = entries[i];
-        exec(mineCommand(join(OUT_DIR, wing), wing), {
+        // No timeout here by design (see PR #4): Node would kill only the
+        // 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), {
             encoding: "utf-8",
-            timeout: 300000,
         }, (err) => {
             if (err) {
                 miningLock = false;
-                log(`mine err (${wing}): ${err.message}`);
+                errLog(`mine err (${wing}): ${err.message}`);
                 return;
             }
             log(`mined wing ${wing} (${files.length} sessions)`);
@@ -347,12 +400,12 @@ function exitSync() {
             return;
         for (const [wing] of wings) {
             log(`exit save: mining wing ${wing}`);
-            const res = spawnSync(MEMPALACE_BIN, ["mine", join(OUT_DIR, wing), "--mode", "convos", "--extract", "general", "--agent", "opencode", "--wing", wing], {
+            const res = spawnSync(MEMPALACE_BIN, mineArgs(join(OUT_DIR, wing), wing), {
                 encoding: "utf-8",
                 timeout: 60000,
             });
             if (res.error || res.status !== 0) {
-                log(`exit mine err (${wing}): ${String(res.error || res.status)}`);
+                errLog(`exit mine err (${wing}): ${String(res.error || res.status)}`);
                 return;
             }
         }
@@ -361,7 +414,7 @@ function exitSync() {
         log("exit save done");
     }
     catch (e) {
-        log("exit save err: " + String(e));
+        errLog("exit save err: " + String(e));
     }
 }
 export default (async () => {

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "opencode-mempalace-persistence",
-  "version": "2.0.0",
+  "version": "2.1.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",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "scripts": {
     "build": "tsc",

package/skills/mempalace-recall/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: mempalace-recall
+description: Recall protocol for MemPalace — search the palace before answering about past work, people, projects, or prior decisions. Use when the user asks what was decided, what happened before, who someone is, what was discussed last time, or anything that may already be filed in their memory palace. Requires the mempalace MCP server (or the opencode-mempalace-persistence plugin).
+---
+
+# MemPalace Recall
+
+Search-before-answer protocol for MemPalace. Read the user's memory
+palace before answering anything that may already be filed there,
+instead of guessing from model memory.
+
+If the `opencode-mempalace-persistence` plugin is active, identity and
+relevant memories are usually already injected into the prompt — this
+skill covers the cases where they are not, plus filing.
+
+## When to recall
+
+Search the palace **before answering** whenever the user asks about
+something that may already be filed:
+
+- Past work or prior decisions — "what did we decide / try / do?"
+- A person, project, or entity — "who is …", "what is …"
+- An earlier session — "remember when …", "last time …"
+- A preference or fact that could have changed over time
+
+Do **not** search on pure greenfield work with no memory relevance
+(e.g. "rename this variable", "fix this typo"). Recall is
+question-driven, not reflexive — a search on every turn wastes latency.
+
+## Protocol
+
+1. Before responding about people / projects / past events / prior
+   decisions: call `mempalace_search` first (short natural-language
+   query, optional `wing` / `room` filters, `limit` default 5). Use
+   `mempalace_kg_query` for relational or time-bound facts.
+2. If unsure about a fact: say "let me check the palace" and query.
+3. Return the drawer's **verbatim** text. Never summarize or paraphrase
+   stored content — quoting the exact words is the point of the system.
+4. After a substantive session, record continuity with
+   `mempalace_diary_write` (skip if a checkpoint hook already saved).
+5. File durable outcomes with `mempalace_add_drawer`; new KG facts with
+   `mempalace_kg_add` (128 chars or fewer); single-valued replacements
+   with `mempalace_kg_supersede`; ended facts with
+   `mempalace_kg_invalidate`.
+
+## Tool names in OpenCode
+
+When the MCP server is registered in OpenCode as `mempalace`, every
+tool carries a double prefix: `mempalace_mempalace_search`,
+`mempalace_mempalace_kg_query`, `mempalace_mempalace_diary_write`, and
+so on. (In Claude Code the same tools have a single `mempalace_`
+prefix.)
+
+## Unhappy paths
+
+- **Empty results.** Say the palace has nothing on this; do not invent
+  an answer. Offer to widen the search or file the new information.
+- **MCP error / server down.** Surface the error and suggest
+  `mempalace status`. Never fall back to guessing.
+- **Conflicting facts.** Trust the knowledge graph's time-valid answer.
+
+## References
+
+- MemPalace: <https://github.com/MemPalace/mempalace>
+- Recall protocol: <https://github.com/MemPalace/mempalace/blob/main/integrations/shared/recall-protocol.md>
+
+Derived from the official `mempalace-recall` skill (MIT), adapted for
+OpenCode and the opencode-mempalace-persistence plugin.