opencode-mnemoteca 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gandazgul
+
+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,99 @@
+# opencode-mnemoteca
+
+OpenCode plugin for **local persistent memory** using
+[Mnemoteca](https://github.com/gandazgul/mnemoteca). It gives your AI coding
+agent memory that persists across sessions. It is offline and does not use cloud
+APIs.
+
+## Prerequisites
+
+Install the `mnemoteca` binary first:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/gandazgul/mnemoteca/main/install.sh | sh
+mnemoteca setup
+```
+
+See the [Mnemoteca README](https://github.com/gandazgul/mnemoteca#installation)
+for detailed setup instructions. On first use, Mnemoteca downloads its ML models,
+approximately 500 MB one time.
+
+Make sure the `mnemoteca` binary is in your `PATH`.
+
+## Installation
+
+Add the plugin to your OpenCode configuration:
+
+```json
+{
+  "plugin": ["opencode-mnemoteca"]
+}
+```
+
+For local development, install from this repository checkout:
+
+```bash
+npm install
+npm run build
+```
+
+## Upgrade from opencode-mnemosyne
+
+If you already used the old OpenCode plugin, stop OpenCode before you change the
+configuration.
+
+1. Migrate CLI data first if needed. Use the
+   [Mnemoteca migration guide](https://github.com/gandazgul/mnemoteca/blob/main/docs/migrate-from-mnemosyne.md).
+2. Add `opencode-mnemoteca` to the same OpenCode configuration scope that used
+   `opencode-mnemosyne`.
+3. Restart OpenCode and verify that the memory tools work. Store and recall a
+   harmless test memory if needed.
+4. Remove `opencode-mnemosyne` from that same configuration scope.
+5. Restart OpenCode again.
+
+Do not load the old and new plugins together for normal use. The agent-facing
+`memory_*` tool names stay stable; only the plugin package and CLI command names
+change.
+
+Windows users must finish this replacement before restarting OpenCode. There is
+no Windows `mnemosyne` compatibility shim, alias, copied executable, or renamed
+executable.
+
+## Memory tools
+
+The agent-facing tool names stay stable. They describe memory capabilities, not
+product branding.
+
+| Tool | Purpose |
+| --- | --- |
+| `memory_recall` | Search project memory. |
+| `memory_recall_global` | Search global memory. |
+| `memory_store` | Store a project memory. Set `core=true` to tag it as core. |
+| `memory_store_global` | Store a global memory. Set `core=true` to tag it as core. |
+| `memory_delete` | Delete a memory by the numeric document ID shown in recall or list output. |
+
+Project memory uses a collection name derived from the project directory name.
+If that name is empty or `global`, the plugin uses `default`.
+
+The project collection is initialized when the plugin loads. The global
+collection is created on first use of `mnemoteca add -g` or the equivalent
+global store tool.
+
+## Commands taught to the agent
+
+- Use `mnemoteca search -f plain [query]` and `mnemoteca search -g -f plain [query]` to search relevant memories.
+- After significant decisions, use `mnemoteca add "memory content"` to save a concise fact. Use `mnemoteca add -g "memory content"` for cross-project preferences.
+- Delete contradicted memories with `mnemoteca delete [memory id]` after storing the updated memory.
+- Mark critical, always-relevant context as core with `-t core`. You can use repeated tags, such as `mnemoteca add "database is sqlite" -t core -t tech-stack`.
+
+## How it works
+
+Mnemoteca is a local document store with hybrid search:
+
+- SQLite storage on your machine.
+- BM25 plus vector search.
+- Local ONNX Runtime inference.
+- No cloud API calls.
+
+The plugin calls the `mnemoteca` executable with argument arrays. It does not
+own data storage, select databases, or run migrations.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { type Plugin } from "@opencode-ai/plugin";
+export declare const MnemotecaPlugin: Plugin;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,MAAM,EAAQ,MAAM,qBAAqB,CAAC;AAExD,eAAO,MAAM,eAAe,EAAE,MAwN7B,CAAC"}

package/dist/index.js

@@ -0,0 +1,175 @@
+import path from "node:path";
+import { tool } from "@opencode-ai/plugin";
+export const MnemotecaPlugin = async (ctx) => {
+    const { directory, worktree, client } = ctx;
+    const targetDir = directory || worktree || process.cwd();
+    const log = {
+        debug: (msg) => client.app
+            .log({ body: { service: "mnemoteca", level: "debug", message: msg } })
+            .catch(() => { }),
+        info: (msg) => client.app
+            .log({ body: { service: "mnemoteca", level: "info", message: msg } })
+            .catch(() => { }),
+        warn: (msg) => client.app
+            .log({ body: { service: "mnemoteca", level: "warn", message: msg } })
+            .catch(() => { }),
+        error: (msg) => client.app
+            .log({ body: { service: "mnemoteca", level: "error", message: msg } })
+            .catch(() => { }),
+    };
+    // Strip trailing slashes but keep the root slash if it is just "/".
+    let projectDir = targetDir.replace(/(.+?)\/+$/, "$1");
+    const projectRaw = path.basename(projectDir);
+    const project = projectRaw === "global" ? "default" : (projectRaw || "default");
+    await log.debug(`Plugin loaded for project: ${project} (dir: ${targetDir})`);
+    /**
+     * Run the Mnemoteca CLI binary gracefully using Bun.spawn.
+     * Avoid shell interpolation entirely by passing args as an array.
+     */
+    async function mnemoteca(...args) {
+        await log.debug(`Executing: mnemoteca ${args.join(" ")}`);
+        try {
+            // @ts-ignore - Bun is globally available in the OpenCode environment.
+            const proc = Bun.spawn(["mnemoteca", ...args], {
+                cwd: targetDir,
+                stdout: "pipe",
+                stderr: "pipe",
+            });
+            const [stdout, stderr, exitCode] = await Promise.all([
+                new Response(proc.stdout).text(),
+                new Response(proc.stderr).text(),
+                proc.exited,
+            ]);
+            if (exitCode !== 0) {
+                await log.error(`Execution failed (code ${exitCode}): ${stderr}`);
+                throw new Error(stderr.trim() || `mnemoteca ${args[0]} failed`);
+            }
+            // Mnemoteca can write output to stderr in older compatible paths. Use whichever has content.
+            const output = stdout || stderr;
+            await log.debug(`Execution successful. Output size: ${output.length}`);
+            return output;
+        }
+        catch (e) {
+            await log.error(`Execution error: ${e instanceof Error ? e.stack : String(e)}`);
+            const msg = e instanceof Error ? e.message : String(e);
+            if (msg.includes("not found") ||
+                msg.includes("ENOENT") ||
+                msg.includes("No such file")) {
+                return "Error: mnemoteca binary not found. Install it: https://github.com/gandazgul/mnemoteca#install";
+            }
+            throw e;
+        }
+    }
+    // Auto-init the project collection (idempotent).
+    try {
+        // @ts-ignore - Bun is globally available in the OpenCode environment.
+        await Bun.spawn(["mnemoteca", "init", "--name", project], {
+            cwd: targetDir,
+            stdout: "ignore", // Silence "collection already exists" logs.
+            stderr: "pipe", // Keep stderr for critical errors.
+        }).exited;
+        await log.info(`Ensured collection exists: ${project}`);
+    }
+    catch (e) {
+        await log.warn(`Failed to auto-init collection: ${e}`);
+    }
+    return {
+        tool: {
+            memory_recall: tool({
+                description: "Search project memory for relevant context, past decisions, and preferences. Use this at the start of conversations and whenever past context would help.",
+                args: {
+                    query: tool.schema.string().describe("Semantic search query"),
+                },
+                async execute(args) {
+                    await log.info(`Searching project memory for: ${args.query}`);
+                    // Quote the query to prevent SQLite FTS errors with hyphens and special characters.
+                    const safeQuery = `"${args.query.replaceAll('"', '""')}"`;
+                    const result = await mnemoteca("search", "--name", project, "--format", "plain", safeQuery);
+                    return result.trim() || "No memories found.";
+                },
+            }),
+            memory_recall_global: tool({
+                description: "Search global memory for cross-project preferences, decisions and patterns.",
+                args: {
+                    query: tool.schema.string().describe("Semantic search query"),
+                },
+                async execute(args) {
+                    await log.info(`Searching global memory for: ${args.query}`);
+                    const safeQuery = `"${args.query.replaceAll('"', '""')}"`;
+                    const result = await mnemoteca("search", "--global", "--format", "plain", safeQuery);
+                    return result.trim() || "No global memories found.";
+                },
+            }),
+            memory_store: tool({
+                description: "Store a project memory: a decision, preference, or important context. One concise concept per memory. Set core=true for critical context that should always be available in every session (use sparingly).",
+                args: {
+                    content: tool.schema.string().describe("Concise memory to store"),
+                    core: tool.schema.boolean().optional().describe("If true, this memory is always injected into context (like AGENTS.md). Use sparingly."),
+                },
+                async execute(args) {
+                    await log.info(`Storing project memory: ${args.content}`);
+                    const cmdArgs = ["add", "--name", project];
+                    if (args.core) {
+                        cmdArgs.push("--tag", "core");
+                    }
+                    cmdArgs.push(args.content);
+                    return (await mnemoteca(...cmdArgs)).trim();
+                },
+            }),
+            memory_store_global: tool({
+                description: "Store a cross-project memory: personal preferences, coding style, tool choices. Set core=true for critical cross-project context that should always be available.",
+                args: {
+                    content: tool.schema.string().describe("Global memory to store"),
+                    core: tool.schema.boolean().optional().describe("If true, this memory is always injected into context. Use sparingly."),
+                },
+                async execute(args) {
+                    await log.info(`Storing global memory: ${args.content}`);
+                    // Ensure the global collection exists.
+                    try {
+                        // @ts-ignore - Bun is globally available in the OpenCode environment.
+                        await Bun.spawn(["mnemoteca", "init", "--global"], {
+                            cwd: targetDir,
+                            stdout: "ignore", // Silence "collection already exists" logs.
+                            stderr: "pipe", // Keep stderr for critical errors.
+                        }).exited;
+                        await log.info("Ensured global collection exists.");
+                    }
+                    catch (e) {
+                        await log.warn(`Failed to auto-init global collection: ${e}`);
+                    }
+                    const cmdArgs = ["add", "--global"];
+                    if (args.core) {
+                        cmdArgs.push("--tag", "core");
+                    }
+                    cmdArgs.push(args.content);
+                    return (await mnemoteca(...cmdArgs)).trim();
+                },
+            }),
+            memory_delete: tool({
+                description: "Delete an outdated or incorrect memory by its document ID (shown in [brackets] in recall/list results).",
+                args: {
+                    id: tool.schema.number().describe("Document ID to delete"),
+                },
+                async execute(args) {
+                    await log.info(`Deleting memory document ID: ${args.id}`);
+                    return (await mnemoteca("delete", String(args.id))).trim();
+                },
+            }),
+        },
+        // Inject memory instructions into compaction so they survive context window resets.
+        "experimental.session.compacting": async (_input, output) => {
+            output.context.push(`## Persistent Memory (Mnemoteca)
+
+You have persistent memory tools: memory_recall, memory_store, memory_delete,
+memory_recall_global, memory_store_global.
+
+When to use memory:
+- Search memory when past context would help answer the user's request.
+- Store concise summaries of important decisions, preferences, and patterns.
+- Delete outdated memories when new decisions contradict them.
+- Use **core** for facts that should always be in context (project architecture, key conventions, user preferences).
+- Use **global** variants for cross-project preferences (coding style, tool choices).
+- At the end of a session, store any relevant memories for future sessions.`);
+        },
+    };
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "opencode-mnemoteca",
+  "version": "0.3.0",
+  "description": "OpenCode plugin for local persistent memory using Mnemoteca — offline semantic search, no cloud required",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "typecheck": "tsc --noEmit",
+    "ci": "tsc --noEmit && tsc",
+    "test": "tsc --noEmit -p tsconfig.test.json && tsx src/index.test.ts"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "mnemoteca",
+    "memory",
+    "local",
+    "offline",
+    "semantic-search",
+    "ai",
+    "coding-agent"
+  ],
+  "author": "gandazgul",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gandazgul/opencode-mnemoteca.git"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.2.24"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "typescript": "^5.9.3",
+    "tsx": "^4.20.6"
+  },
+  "opencode": {
+    "type": "plugin"
+  },
+  "files": [
+    "dist"
+  ]
+}