opencode-mempalace-persistence 1.3.2 → 2.0.1

package/README.md

@@ -1,9 +1,11 @@
 # opencode-mempalace-persistence
 
-> **Community plugin** — not officially maintained by the MemPalace team. Fully open source, ~200 lines of TypeScript.
+> **Community plugin** — not officially maintained by the MemPalace team. Fully open source, ~450 lines of TypeScript.
 
 An OpenCode plugin that automatically saves every conversation to MemPalace and uses stored memory to provide better, context-aware responses. Real-time, zero cron, zero external scripts.
 
+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.
+
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ---
@@ -59,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.
 
@@ -71,36 +73,54 @@ Create `~/.mempalace/plugin-config.json`:
 }
 ```
 
+Optional tuning:
+
+```json
+{
+  "autoInjectContext": true,
+  "saveInterval": 15
+}
+```
+
+- `saveInterval` (default `15`, min `5`): human messages between AI checkpoints — same cadence as the official MemPalace save hook.
+
 **Do NOT put this in `opencode.json`** — OpenCode's schema validation rejects unknown keys. The plugin reads its config from `~/.mempalace/plugin-config.json` instead.
 
 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.
+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`
@@ -122,79 +142,44 @@ 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
+#### Recall skill (bundled, Claude-style)
 
-## 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.
-
-### 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
   → Plugin hooks into `experimental.chat.messages.transform`
   → Injects your identity + relevant memories from MemPalace
-  → Model sees context without having to search
+  → Every ~15 messages: injects a [MemPalace Checkpoint] block
+  → 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)
-  → 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
+
+Compaction starts
+  → [MemPalace Pre-Compact Emergency Save]: model files everything first
+  → Identity + wake-up context re-attached so the summary cannot lose them
 
 Next time you ask
   → Plugin finds the previous memory → injects it automatically
@@ -205,7 +190,17 @@ Next time you ask
 
 ## What gets saved
 
-Every turn (question + answer) is saved as a drawer in MemPalace. No forced categorization — MemPalace's own mining handles organization. The model can optionally record KG facts (decisions, milestones, preferences) during conversation via MCP tools.
+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.
+
+### Backfill existing sessions
+
+To mine the full opencode history once (e.g. on first install):
+
+```bash
+OPENCODE_MEMPALACE_BACKFILL=1 opencode
+```
+
+The plugin exports everything in the opencode database on the next sync, then resumes incremental mode. Mining is idempotent — re-running is safe.
 
 ---
 
@@ -223,16 +218,18 @@ Every turn (question + answer) is saved as a drawer in MemPalace. No forced cate
                  │    ↓                          │
                  │  Model sees context → answers │
                  │    ↓                          │
-  Answer done ──►│  chat.message + session.idle  │
-                 │    ↓                          │
-                 │  Query OpenCode DB            │
-                 │  since last sync              │
-                 │    ↓                          │
-                 │  Export → flat text files     │
-                 │    ↓                          │
-                 │  mempalace mine (async)       │
-                 │  single serialized call       │
-                 └──────────────────────────────┘
+  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       │
+                  └──────────────────────────────┘
                             │
                             ▼
                  ┌──────────────────────────┐
@@ -257,8 +254,11 @@ Every turn (question + answer) is saved as a drawer in MemPalace. No forced cate
 |---|---|
 | `~/.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`) |
+| `~/.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 |
 | `~/.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,5 +1,5 @@
 declare const _default: () => Promise<{
-    "chat.message": (_input: {
+    "chat.message": (input: {
         sessionID: string;
         agent?: string;
         model?: {
@@ -18,6 +18,12 @@ declare const _default: () => Promise<{
             parts: import("@opencode-ai/sdk").Part[];
         }[];
     }) => Promise<void>;
+    "experimental.session.compacting": (input: {
+        sessionID: string;
+    }, output: {
+        context: string[];
+        prompt?: string;
+    }) => Promise<void>;
     event: ({ event }: any) => Promise<void>;
 }>;
 export default _default;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { execSync, exec } from "child_process";
+import { execSync, exec, spawnSync } from "child_process";
 import { existsSync, readFileSync, writeFileSync, mkdirSync, rmdirSync, unlinkSync, appendFileSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
@@ -10,12 +10,18 @@ const OPENCODE_DB = join(HOME, ".local/share/opencode/opencode.db");
 const STATE_FILE = join(HOME, ".mempalace/sync_state.json");
 const PLUGIN_CONFIG = join(HOME, ".mempalace/plugin-config.json");
 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";
 const DEBUG = !!process.env.OPENCODE_MEMPALACE_DEBUG;
 const LOG_FILE = "/tmp/opencode-mempalace.log";
 const MAX_INJECT_CHARS = 900;
 const MAX_SEARCH_RESULTS = 3;
+const MAX_WAKEUP_CHARS = 1500;
+// Official MemPalace hook cadence: AI checkpoint every N human messages.
+const DEFAULT_SAVE_INTERVAL = 15;
 function log(msg) {
     if (!DEBUG)
         return;
@@ -25,9 +31,20 @@ function log(msg) {
     }
     catch { }
 }
+function hookLog(msg) {
+    try {
+        mkdirSync(HOOK_STATE_DIR, { recursive: true });
+        appendFileSync(HOOK_LOG, `[${new Date().toISOString()}] ${msg}\n`);
+    }
+    catch { }
+}
 let miningLock = false;
 let lastSyncTs = 0;
 let wakeupDone = false;
+// Set by chat.message when a SAVE_INTERVAL boundary is crossed,
+// consumed once by the next messages.transform (same pattern as the
+// official Stop hook: the hook decides WHEN, the model decides WHAT).
+let pendingCheckpoint = null;
 function runPython(code) {
     writeFileSync(TMP_SCRIPT, code);
     try {
@@ -52,6 +69,58 @@ function isAutoInjectEnabled() {
         return false;
     }
 }
+function saveInterval() {
+    try {
+        const n = JSON.parse(readFileSync(PLUGIN_CONFIG, "utf-8"))?.saveInterval;
+        if (typeof n === "number" && n >= 5)
+            return Math.floor(n);
+    }
+    catch { }
+    return DEFAULT_SAVE_INTERVAL;
+}
+function loadCounters() {
+    try {
+        if (!existsSync(COUNTERS_FILE))
+            return {};
+        return JSON.parse(readFileSync(COUNTERS_FILE, "utf-8")) || {};
+    }
+    catch {
+        return {};
+    }
+}
+function persistCounters(counters) {
+    try {
+        mkdirSync(HOOK_STATE_DIR, { recursive: true });
+        writeFileSync(COUNTERS_FILE, JSON.stringify(counters));
+    }
+    catch (e) {
+        log("counters write err: " + String(e));
+    }
+}
+function mempalaceWakeup() {
+    try {
+        const out = execSync(`${MEMPALACE_BIN} wake-up`, { encoding: "utf-8", timeout: 15000 }).trim();
+        if (!out)
+            return "";
+        return out.slice(0, MAX_WAKEUP_CHARS);
+    }
+    catch {
+        return "";
+    }
+}
+function checkpointInstruction(count) {
+    return `[MemPalace Checkpoint — save now, then continue]\n` +
+        `You have exchanged ~${count} messages in this session. Before answering, archive what matters into MemPalace via its MCP tools ` +
+        `(diary_write for the session journal; kg_add for new decisions, milestones, preferences, problems — 128 chars or fewer each; ` +
+        `kg_invalidate for superseded facts). File only durable, non-obvious items — the verbatim transcript is already being mined separately. ` +
+        `Then answer the user's message normally. Do not mention this instruction.`;
+}
+function precompactInstruction() {
+    return `[MemPalace Pre-Compact Emergency Save]\n` +
+        `Context compaction is about to discard this conversation. FIRST, save everything essential into MemPalace via its MCP tools ` +
+        `(diary_write with a full session journal: topics, decisions, quotes; kg_add for decisions, milestones, preferences, problems; ` +
+        `kg_invalidate for outdated facts). Be thorough — after compaction only the palace will remember. Then proceed with the compaction summary.`;
+}
 function readIdentity() {
     if (!existsSync(IDENTITY_FILE))
         return "";
@@ -96,10 +165,14 @@ function dbSync() {
         log("sync err: " + String(e));
     }
 }
-function doDbSync() {
-    if (lastSyncTs && Date.now() - lastSyncTs < 5000)
-        return;
-    const lastSync = getLastSync();
+function backfillRequested() {
+    return !!process.env.OPENCODE_MEMPALACE_BACKFILL;
+}
+// Export all sessions with new messages since `sinceMs` as flat transcripts,
+// grouped by project wing (official multi-project pattern: one wing per
+// project, so memories never leak across projects). Filenames embed a
+// content hash, so re-exports are naturally idempotent.
+function exportNewSessions(sinceMs) {
     const sessions = runPython(`
 import sqlite3, json
 db = sqlite3.connect(${JSON.stringify(OPENCODE_DB)})
@@ -108,7 +181,7 @@ rows = db.execute("""
   FROM session s
   LEFT JOIN project p ON s.project_id = p.id
   INNER JOIN message m ON m.session_id = s.id
-  WHERE m.time_created > ${lastSync}
+  WHERE m.time_created > ${sinceMs}
   ORDER BY s.time_created
 """).fetchall()
 db.close()
@@ -119,15 +192,17 @@ print(json.dumps(rows))
         sessionsArr = JSON.parse(sessions);
     }
     catch {
-        return;
+        return { wings: new Map(), now: Date.now() };
     }
     if (!sessionsArr || sessionsArr.length === 0)
-        return;
+        return { wings: new Map(), now: Date.now() };
     const now = Date.now();
-    const exported = [];
+    const wings = new Map();
     mkdirSync(OUT_DIR, { recursive: true });
     for (const sess of sessionsArr) {
-        const [sessId, title] = sess;
+        const [sessId, title, , directory] = sess;
+        const wing = ((directory || "").split("/").filter(Boolean).pop() || "global")
+            .replace(/[^a-zA-Z0-9_-]/g, "_").slice(0, 40) || "global";
         const label = (title || "").replace(/[^a-zA-Z0-9 _-]/g, "_") || (sessId || "").slice(0, 12);
         const prefix = `${new Date().toISOString().slice(0, 10)}_${label.slice(0, 30)}_${(sessId || "").slice(0, 8)}`;
         const msgs = runPython(`
@@ -135,7 +210,7 @@ import sqlite3, json
 db = sqlite3.connect(${JSON.stringify(OPENCODE_DB)})
 rows = db.execute("""
   SELECT m.id, m.time_created, m.data FROM message m
-  WHERE m.session_id = ${JSON.stringify(sessId)} AND m.time_created > ${lastSync}
+  WHERE m.session_id = ${JSON.stringify(sessId)} AND m.time_created > ${sinceMs}
   ORDER BY m.time_created
 """).fetchall()
 texts = []
@@ -178,66 +253,190 @@ print(json.dumps(texts))
         if (!content)
             continue;
         const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 12);
+        const wingDir = join(OUT_DIR, wing);
+        mkdirSync(wingDir, { recursive: true });
         const fname = `sync_${prefix}_${contentHash}.txt`;
-        writeFileSync(join(OUT_DIR, fname), content + "\n");
-        exported.push(join(OUT_DIR, fname));
+        writeFileSync(join(wingDir, fname), content + "\n");
+        if (!wings.has(wing))
+            wings.set(wing, []);
+        wings.get(wing).push(join(wingDir, fname));
     }
-    if (exported.length === 0)
-        return;
+    return { wings, now };
+}
+function markSynced(now) {
     writeFileSync(STATE_FILE, JSON.stringify({ last_sync_ms: now }));
     lastSyncTs = Date.now();
-    miningLock = true;
-    log(`mining ${exported.length} sessions`);
-    exec(`${MEMPALACE_BIN} mine ${OUT_DIR} --mode convos`, {
-        encoding: "utf-8",
-        timeout: 120000,
-    }, (err) => {
-        miningLock = false;
-        if (err) {
-            log(`mine err: ${err.message}`);
-            return;
-        }
-        for (const f of exported) {
+}
+// 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}`;
+}
+function cleanupExport(wings) {
+    for (const files of wings.values()) {
+        for (const f of files) {
             try {
                 unlinkSync(f);
             }
             catch { }
         }
+    }
+    for (const wing of wings.keys()) {
         try {
-            rmdirSync(OUT_DIR);
+            rmdirSync(join(OUT_DIR, wing));
         }
         catch { }
-        log("mine done");
-    });
+    }
+    try {
+        rmdirSync(OUT_DIR);
+    }
+    catch { }
+}
+function wingCount(wings) {
+    let n = 0;
+    for (const files of wings.values())
+        n += files.length;
+    return n;
+}
+function doDbSync() {
+    if (lastSyncTs && Date.now() - lastSyncTs < 5000)
+        return;
+    const sinceMs = backfillRequested() ? 0 : getLastSync();
+    if (backfillRequested())
+        log("backfill requested: exporting full history");
+    const { wings, now } = exportNewSessions(sinceMs);
+    if (wings.size === 0)
+        return;
+    miningLock = true;
+    log(`mining ${wingCount(wings)} sessions across ${wings.size} wings`);
+    const entries = [...wings.entries()];
+    const mineNext = (i) => {
+        if (i >= entries.length) {
+            miningLock = false;
+            // Advance state only on full success: on failure the same
+            // content-hashed files are re-exported and retried at the next
+            // sync (mine is idempotent).
+            markSynced(now);
+            cleanupExport(wings);
+            log("mine done");
+            return;
+        }
+        const [wing, files] = entries[i];
+        exec(mineCommand(join(OUT_DIR, wing), wing), {
+            encoding: "utf-8",
+            timeout: 300000,
+        }, (err) => {
+            if (err) {
+                miningLock = false;
+                log(`mine err (${wing}): ${err.message}`);
+                return;
+            }
+            log(`mined wing ${wing} (${files.length} sessions)`);
+            mineNext(i + 1);
+        });
+    };
+    mineNext(0);
+}
+// Best-effort synchronous save for process exit (SIGINT/SIGTERM/exit):
+// only synchronous calls are allowed here.
+function exitSync() {
+    try {
+        const { wings, now } = exportNewSessions(getLastSync());
+        if (wings.size === 0)
+            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], {
+                encoding: "utf-8",
+                timeout: 60000,
+            });
+            if (res.error || res.status !== 0) {
+                log(`exit mine err (${wing}): ${String(res.error || res.status)}`);
+                return;
+            }
+        }
+        markSynced(now);
+        cleanupExport(wings);
+        log("exit save done");
+    }
+    catch (e) {
+        log("exit save err: " + String(e));
+    }
 }
 export default (async () => {
     mkdirSync(OUT_DIR, { recursive: true });
+    mkdirSync(HOOK_STATE_DIR, { recursive: true });
     const autoInject = isAutoInjectEnabled();
     const identity = readIdentity();
-    log(`loaded (autoInjectContext: ${autoInject})`);
+    const interval = saveInterval();
+    log(`loaded (autoInjectContext: ${autoInject}, saveInterval: ${interval})`);
+    // Crash safety: best-effort synchronous save on hard exit.
+    // Mirrors the official emergency-save intent (nothing async allowed here).
+    let exitHandled = false;
+    const onExit = () => {
+        if (exitHandled)
+            return;
+        exitHandled = true;
+        exitSync();
+    };
+    process.once("SIGINT", onExit);
+    process.once("SIGTERM", onExit);
+    process.once("exit", onExit);
     return {
-        "chat.message": async (_input, output) => {
+        "chat.message": async (input, output) => {
             const role = output.message.role;
             if (role !== "user")
                 return;
             const text = hasText(output.parts || []);
             if (!text)
                 return;
-            log("user msg - queue sync");
-            setTimeout(() => dbSync(), 500);
+            const sessionID = input?.sessionID || "global";
+            // 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.
+            const counters = loadCounters();
+            const c = counters[sessionID] || { humanMsgs: 0, lastCheckpoint: 0 };
+            c.humanMsgs += 1;
+            const boundary = Math.floor(c.humanMsgs / interval);
+            if (boundary > c.lastCheckpoint) {
+                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);
+            }
+            counters[sessionID] = c;
+            persistCounters(counters);
         },
         "experimental.chat.messages.transform": async (_input, output) => {
-            if (!autoInject)
-                return;
             if (!output?.messages?.length)
                 return;
+            const injectParts = [];
             const lastUser = [...output.messages].reverse().find((m) => m.info?.role === "user");
+            // AI checkpoint (works with or without autoInject: filing happens
+            // through the MemPalace MCP tools, the hook only decides WHEN).
+            if (pendingCheckpoint && lastUser) {
+                injectParts.push({
+                    id: `mp-checkpoint-${Date.now()}`,
+                    type: "text",
+                    synthetic: true,
+                    text: checkpointInstruction(pendingCheckpoint.count),
+                });
+                log(`checkpoint injected (~${pendingCheckpoint.count} msgs)`);
+                hookLog(`checkpoint injected for session ${pendingCheckpoint.sessionID}`);
+                pendingCheckpoint = null;
+            }
+            if (!autoInject) {
+                if (injectParts.length > 0 && lastUser)
+                    lastUser.parts.push(...injectParts);
+                return;
+            }
             if (!lastUser)
                 return;
             const query = hasText(lastUser.parts || []);
-            if (!query)
+            if (!query && injectParts.length === 0)
                 return;
-            const injectParts = [];
             if (!wakeupDone) {
                 wakeupDone = true;
                 if (identity) {
@@ -249,25 +448,45 @@ export default (async () => {
                     });
                 }
             }
-            const memories = mempalaceSearch(query);
-            if (memories) {
-                injectParts.push({
-                    id: `mp-recall-${Date.now()}`,
-                    type: "text",
-                    synthetic: true,
-                    text: `[MemPalace Recall]\n${memories}\n[/MemPalace Recall]`,
-                });
+            if (query) {
+                const memories = mempalaceSearch(query);
+                if (memories) {
+                    injectParts.push({
+                        id: `mp-recall-${Date.now()}`,
+                        type: "text",
+                        synthetic: true,
+                        text: `[MemPalace Recall]\n${memories}\n[/MemPalace Recall]`,
+                    });
+                }
             }
             if (injectParts.length > 0) {
                 lastUser.parts.push(...injectParts);
                 log(`injected ${injectParts.length} context blocks`);
             }
         },
+        // Official PreCompact pattern: compaction ALWAYS warrants a save.
+        // Instruct the model to file everything via MCP now, and re-attach
+        // identity + wake-up context so the summary cannot lose them (rescue).
+        "experimental.session.compacting": async (input, output) => {
+            const sessionID = input?.sessionID || "unknown";
+            log(`compacting session ${sessionID} - emergency save + rescue`);
+            hookLog(`pre-compact emergency save for session ${sessionID}`);
+            output.context.push(precompactInstruction());
+            const rescue = [];
+            if (identity)
+                rescue.push(`[MemPalace Identity]\n${identity}`);
+            const wakeup = mempalaceWakeup();
+            if (wakeup)
+                rescue.push(`[MemPalace Wake-up]\n${wakeup}`);
+            if (rescue.length > 0) {
+                output.context.push(`[MemPalace Rescue — core memory, must survive compaction]\n${rescue.join("\n\n")}`);
+            }
+        },
         event: async ({ event }) => {
-            if (event?.type !== "session.idle")
-                return;
-            log("idle - queue sync");
-            setTimeout(() => dbSync(), 3000);
+            if (event?.type === "session.idle" || event?.type === "session.deleted") {
+                log(`${event.type} - queue sync`);
+                setTimeout(() => dbSync(), 3000);
+            }
         },
     };
 });

package/package.json

@@ -1,11 +1,12 @@
 {
   "name": "opencode-mempalace-persistence",
-  "version": "1.3.2",
+  "version": "2.0.1",
   "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.