opencode-mempalace-persistence 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 geco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# opencode-mempalace-persistence
+
+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.
+
+> **It just works** — install, use OpenCode, the plugin handles the rest.
+
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+---
+
+## How it works in 3 seconds
+
+| Without plugin | With plugin |
+|---|---|
+| Every session starts from scratch | The model knows who you are and what you've done |
+| You repeat context each time | Memory is automatic |
+| No Knowledge Graph | Decisions, milestones, problems tracked |
+
+The model searches MemPalace on every question (via AGENTS.md + MCP), and the plugin saves every response. A perfect feedback loop.
+
+---
+
+## Installation
+
+### 1. Plugin (saves conversations)
+
+```json
+{
+  "plugin": ["opencode-mempalace-persistence"]
+}
+```
+
+Add this line to your `~/.config/opencode/opencode.json` and restart OpenCode.
+
+### 2. Instructions for the model (uses memory)
+
+Create `~/.config/opencode/AGENTS.md`:
+
+```markdown
+# Memory & Knowledge instructions
+
+Before answering the user, always search your MemPalace memory for relevant context using the MCP tools.
+
+1. **Search MemPalace**: Call `mempalace_search` with the user's question or key topics as query. Get the top 5-10 most relevant memory drawers.
+2. **Query Knowledge Graph**: Call `mempalace_kg_query` for entity "user". Then filter the returned facts — keep only those whose text contains keywords from the user's question.
+3. **Use the context**: Incorporate relevant memory and facts into your response, referencing the source naturally when useful.
+```
+
+### 3. Identity (who you are)
+
+Create `~/.mempalace/identity.txt`:
+
+```
+I am [name], a [role]. I work with [technologies]. My main projects are [projects].
+```
+
+This is loaded automatically at session start via `instructions` in opencode.json.
+
+### 4. Complete configuration
+
+`~/.config/opencode/opencode.json`:
+
+```json
+{
+  "model": "opencode/deepseek-v4-flash-free",
+  "instructions": ["AGENTS.md", "~/.mempalace/identity.txt"],
+  "plugin": ["opencode-mempalace-persistence"],
+  "mcp": {
+    "mempalace": {
+      "type": "local",
+      "command": ["mempalace-mcp"],
+      "enabled": true
+    }
+  }
+}
+```
+
+### 5. MemPalace (if not already installed)
+
+```bash
+# Install
+pipx install mempalace
+
+# Create palace
+mempalace init ~/opencode-memory
+
+# Configure MCP
+mempalace mcp
+```
+
+The `mempalace mcp` command gives you the exact MCP setup string for your configuration.
+
+---
+
+## What happens after installation
+
+```
+You ask a question
+  → AGENTS.md tells the model: "search MemPalace first"
+  → The model calls mempalace_search("question") via MCP
+  → Finds relevant memories → gives a better answer
+
+The model responds
+  → The opencode-mempalace-persistence plugin detects the response is complete
+  → Saves the conversation to MemPalace
+  → Extracts Knowledge Graph facts
+
+Next time you ask
+  → The model finds the previous memory → coherent responses
+  → The cycle continues, memory grows
+```
+
+---
+
+## What gets saved
+
+Every turn (question + answer):
+
+- **Text** categorized by wing (developer, creative, emotions, family, consciousness)
+- **Knowledge Graph**: automatically extracted facts
+  - `decision` → "decided to use TypeScript"
+  - `milestone` → "backend deploy completed"
+  - `problem` → "chromadb ModuleNotFoundError"
+  - `preference` → "prefer Svelte over React"
+  - `emotional` → "frustrated with Docker compose"
+
+---
+
+## Architecture
+
+```
+                 ┌──────────────────────────┐
+                 │       OpenCode            │
+                 │                           │
+  User msg ─────►│  chat.message hook        │
+                 │    ↓                      │
+                 │  Query OpenCode DB        │
+                 │  (messages since lastSync)│
+                 │    ↓                      │
+                 │  Categorize by wing       │
+                 │    ↓                      │
+                 │  Export delta → tmp       │
+                 │    ↓                      │
+                 │  Save state immediately   │
+                 │    ↓                      │
+                 │  mempalace mine (async)   │ ← non-blocking
+                 │    ↓                      │
+                 │  Extract KG facts         │
+                 │    ↓                      │
+  Session idle ─►│  session.idle hook        │
+                 │  (saves last turn)        │
+                 └──────────────────────────┘
+                            │
+                            ▼
+                 ┌──────────────────────────┐
+                 │      MemPalace            │
+                 │  ~/opencode-memory/       │
+                 │  Vector DB + KG SQLite    │
+                 └──────────────────────────┘
+                            ▲
+                            │
+                 ┌──────────────────────────┐
+                 │  AGENTS.md + MCP          │
+                 │  The model searches       │
+                 │  MemPalace on every       │
+                 │  question                 │
+                 └──────────────────────────┘
+```
+
+---
+
+## Relevant files
+
+| File | Purpose |
+|---|---|
+| `~/.config/opencode/opencode.json` | OpenCode config with plugin + MCP + instructions |
+| `~/.config/opencode/AGENTS.md` | Tells the model to search MemPalace |
+| `~/.mempalace/identity.txt` | Your identity (loaded every session) |
+| `~/.mempalace/config.json` | MemPalace config (palace path, wings, keywords) |
+| `~/.mempalace/knowledge_graph.sqlite3` | Knowledge Graph (structured facts) |
+| `~/opencode-memory/` | MemPalace vector DB (all drawers) |
+| `~/.mempalace/sync_state.json` | Last sync state (plugin + Python script) |
+
+---
+
+## Install from npm
+
+```json
+{
+  "plugin": ["opencode-mempalace-persistence"]
+}
+```
+
+## Local development
+
+```json
+{
+  "plugin": ["/path/to/opencode-mempalace-persistence/dist/index.js"]
+}
+```
+
+## Debug logging
+
+```bash
+export OPENCODE_MEMPALACE_DEBUG=1
+```
+
+When set, the plugin writes a debug log to `/tmp/opencode-mempalace.log`.
+
+---
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+declare const _default: () => Promise<{
+    "chat.message": (_input: {
+        sessionID: string;
+        agent?: string;
+        model?: {
+            providerID: string;
+            modelID: string;
+        };
+        messageID?: string;
+        variant?: string;
+    }, output: {
+        message: import("@opencode-ai/sdk").UserMessage;
+        parts: import("@opencode-ai/sdk").Part[];
+    }) => Promise<void>;
+    event: ({ event }: any) => Promise<void>;
+}>;
+export default _default;

package/dist/index.js

@@ -0,0 +1,273 @@
+import { execSync, exec } from "child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, rmSync, 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");
+const KG_DB = join(HOME, ".mempalace/knowledge_graph.sqlite3");
+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";
+function log(msg) {
+    if (!DEBUG)
+        return;
+    const ts = new Date().toISOString();
+    try {
+        appendFileSync(LOG_FILE, `[${ts}] ${msg}\n`);
+    }
+    catch { }
+}
+let pendingSync = false;
+let lastSyncTs = 0;
+function runPython(code) {
+    writeFileSync(TMP_SCRIPT, code);
+    try {
+        return execSync(`${VENV_PYTHON} ${TMP_SCRIPT}`, { encoding: "utf-8", timeout: 30000 }).trim();
+    }
+    finally {
+        unlinkSync(TMP_SCRIPT);
+    }
+}
+const WING_KEYWORDS = {
+    creative: ["eurovision", "music", "art", "film", "game", "festival", "song", "concert"],
+    family: ["family", "kid", "son", "daughter", "wife", "husband", "parent", "mother", "father"],
+    emotions: ["feel", "happy", "sad", "love", "hate", "angry", "fear", "anxiety", "grateful"],
+    consciousness: ["think", "mind", "conscious", "self", "identity", "exist", "meaning"],
+};
+const KG_PATTERNS = {
+    decision: ["ho deciso", "ho scelto", "implementato", "added ", "ho aggiunto", "decided", "chosen", "created", "creato", "modified"],
+    milestone: ["completato", "finito", "rilasciato", "deployato", "ho completato", "successo", "funziona", "completed", "done", "deployed"],
+    problem: ["problema", "bug", "errore", "issue", "fix", "fixato", "risolto", "solved", "fixed", "error"],
+    preference: ["preferisco", "mi piace", "non mi piace", "prefer", "like to", "better"],
+    emotional: ["sentimento", "emozione", "frustrato", "contento", "happy", "sad", "feel", "emotion"],
+};
+function categorize(text) {
+    if (!text)
+        return "developer";
+    const lower = text.toLowerCase();
+    for (const [wing, keywords] of Object.entries(WING_KEYWORDS)) {
+        if (keywords.some((kw) => lower.includes(kw)))
+            return wing;
+    }
+    return "developer";
+}
+function hasText(parts) {
+    return parts
+        .filter((p) => p?.type === "text" && p?.text?.trim())
+        .map((p) => p.text.trim())
+        .join("\n");
+}
+function getLastSync() {
+    if (!existsSync(STATE_FILE))
+        return 0;
+    try {
+        return JSON.parse(readFileSync(STATE_FILE, "utf-8")).last_sync_ms || 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function dbSync() {
+    if (pendingSync)
+        return;
+    pendingSync = true;
+    try {
+        doDbSync();
+    }
+    catch (e) {
+        log("sync err: " + String(e));
+    }
+}
+function doDbSync() {
+    if (lastSyncTs && Date.now() - lastSyncTs < 5000)
+        return;
+    const lastSync = getLastSync();
+    const sessions = runPython(`
+import sqlite3, json
+db = sqlite3.connect(${JSON.stringify(OPENCODE_DB)})
+rows = db.execute("""
+  SELECT DISTINCT s.id, s.title, p.worktree, s.directory, s.slug, s.time_created
+  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}
+  ORDER BY s.time_created
+""").fetchall()
+db.close()
+print(json.dumps(rows))
+`);
+    let sessionsArr;
+    try {
+        sessionsArr = JSON.parse(sessions);
+    }
+    catch {
+        pendingSync = false;
+        return;
+    }
+    if (!sessionsArr || sessionsArr.length === 0) {
+        pendingSync = false;
+        return;
+    }
+    const now = Date.now();
+    const exported = [];
+    for (const sess of sessionsArr) {
+        const [sessId, title, worktree, directory] = sess;
+        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(`
+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}
+  ORDER BY m.time_created
+""").fetchall()
+texts = []
+for (mid, mts, mdata_raw) in rows:
+    try: mdata = json.loads(mdata_raw)
+    except: mdata = {}
+    role = mdata.get("role", "unknown")
+    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)
+            if pdata.get("type") == "text" and pdata.get("text","").strip():
+                texts.append({"role": role, "text": pdata.get("text").strip(), "ts": mts})
+        except: pass
+db.close()
+print(json.dumps(texts))
+`);
+        let msgList;
+        try {
+            msgList = JSON.parse(msgs);
+        }
+        catch {
+            continue;
+        }
+        if (msgList.length < 2)
+            continue;
+        const lines = [
+            `# ${title || label}`,
+            `Date: ${new Date().toISOString().slice(0, 10)}`,
+            `Session: ${sessId}`,
+            "",
+        ];
+        for (const m of msgList) {
+            const ts = m.ts ? new Date(m.ts).toISOString().slice(11, 19) : "";
+            lines.push(`## ${m.role.toUpperCase()} — ${ts}`);
+            lines.push("");
+            lines.push(m.text);
+            lines.push("");
+        }
+        const content = lines.join("\n").trim();
+        if (!content)
+            continue;
+        const wing = categorize(content);
+        const contentHash = createHash("sha256").update(content).digest("hex").slice(0, 12);
+        const fname = `sync_${prefix}_${contentHash}.txt`;
+        const wingDir = join(OUT_DIR, wing);
+        mkdirSync(wingDir, { recursive: true });
+        writeFileSync(join(wingDir, fname), content + "\n");
+        exported.push({ wing, fname, dir: wingDir });
+    }
+    if (exported.length === 0) {
+        pendingSync = false;
+        return;
+    }
+    // Save state immediately so next sync doesn't re-process
+    writeFileSync(STATE_FILE, JSON.stringify({ last_sync_ms: now }));
+    lastSyncTs = Date.now();
+    pendingSync = false;
+    log(`queued ${exported.length} files for mining`);
+    // Mining async (fire-and-forget, non-blocking)
+    for (const { wing, fname, dir: wingDir } of exported) {
+        const filePath = join(wingDir, fname);
+        exec(`${MEMPALACE_BIN} mine ${wingDir} --mode convos --extract general --wing ${wing}`, {
+            encoding: "utf-8",
+            timeout: 120000,
+        }, (err) => {
+            if (err) {
+                log(`mine err ${wing}: ${err.message}`);
+                return;
+            }
+            rmSync(filePath);
+            try {
+                rmdirSync(wingDir);
+            }
+            catch { }
+            log(`mined ${wing}`);
+            // KG extraction after mining
+            try {
+                const raw = runPython(`
+from mempalace.config import MempalaceConfig
+import chromadb, json, re
+c = MempalaceConfig()
+col = chromadb.PersistentClient(path=c.palace_path).get_collection(c.collection_name)
+d = col.get(limit=5000, include=["metadatas","documents"])
+p = ${JSON.stringify(KG_PATTERNS)}
+r = []
+for i,m,doc in zip(d.get("ids",[]), d.get("metadatas",[]), d.get("documents",[])):
+  if not m or not doc: continue
+  rm = m.get("room","")
+  if rm not in ("decision","milestone","problem","preference","emotional"): continue
+  da = doc.split("Date: ")[1][:10] if "Date: " in doc else ""
+  if not da: continue
+  if not any(pat in doc.lower() for pat in p.get(rm,[])): continue
+  for ln in doc.strip().split("\\n")[:5]:
+    l = ln.strip()
+    if l and not l.startswith("#") and len(l) > 20 and len(re.findall(r"[^a-zA-Z0-9\\s]", l))/len(l) <= 0.3:
+      r.append([da, rm, l[:120]]); break
+print(json.dumps(r))
+`);
+                const nf = JSON.parse(raw) || [];
+                if (nf.length > 0) {
+                    const ex = runPython(`import sqlite3,json;d=sqlite3.connect(${JSON.stringify(KG_DB)});r=d.execute("SELECT predicate,object FROM triples WHERE subject='user'").fetchall();d.close();print(json.dumps(r))`);
+                    const seen = new Set();
+                    try {
+                        for (const [p, o] of JSON.parse(ex))
+                            seen.add(p + "::" + o);
+                    }
+                    catch { }
+                    const ins = [];
+                    for (const [d, t, x] of nf) {
+                        const k = t + "::" + x;
+                        if (seen.has(k))
+                            continue;
+                        seen.add(k);
+                        ins.push(`INSERT OR IGNORE INTO triples(id,subject,predicate,object,valid_from,confidence,extracted_at) VALUES('t_user_${t}_${createHash("sha256").update(x).digest("hex").slice(0, 12)}','user','${t}','${x.replace(/'/g, "''")}','${d}',1.0,datetime('now'))`);
+                    }
+                    if (ins.length > 0) {
+                        runPython(`import sqlite3;db=sqlite3.connect(${JSON.stringify(KG_DB)});[db.execute(s) for s in ${JSON.stringify(ins)}];db.commit();db.close()`);
+                    }
+                }
+            }
+            catch { }
+        });
+    }
+}
+export default (async () => {
+    mkdirSync(OUT_DIR, { recursive: true });
+    log("loaded");
+    return {
+        "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);
+        },
+        event: async ({ event }) => {
+            if (event?.type !== "session.idle")
+                return;
+            log("idle - queue sync");
+            setTimeout(() => dbSync(), 3000);
+        },
+    };
+});

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "opencode-mempalace-persistence",
+  "version": "1.0.0",
+  "description": "OpenCode plugin — auto-sync conversations to MemPalace memory in real-time with auto-categorization and Knowledge Graph",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["opencode", "mempalace", "memory", "opencode-plugin", "typescript"],
+  "author": "geco",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/geco/opencode-mempalace.git"
+  },
+  "bugs": {
+    "url": "https://github.com/geco/opencode-mempalace/issues"
+  },
+  "homepage": "https://github.com/geco/opencode-mempalace#readme",
+  "devDependencies": {
+    "@opencode-ai/plugin": "^1.15.0",
+    "@types/node": "^25.8.0",
+    "typescript": "^6.0.3"
+  }
+}