opencode-memtomem 0.1.0

package/LICENSE

@@ -0,0 +1,17 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2025-2026 memtomem contributors
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,52 @@
+# opencode-memtomem
+
+Safe, configuration-only memtomem integration for OpenCode 1.17.18 through the
+current v1 line. It adds an exact-pinned local MCP server, six slash commands,
+and three read-only skills. It does not add event hooks or automatic indexing.
+
+## Current status
+
+`opencode-memtomem` is present in this source repository but is not currently
+published to npm. Do not use an `opencode plugin add` command; OpenCode loads
+npm plugins from the singular `plugin` array in `opencode.json`.
+
+For a released memtomem installation, configure the local MCP server now:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "memtomem": {
+      "type": "local",
+      "command": ["uvx", "--isolated", "--from", "memtomem[all]==0.3.10", "memtomem-server"],
+      "enabled": true,
+      "timeout": 60000,
+      "environment": {"MEMTOMEM_TOOL_MODE": "core"}
+    }
+  }
+}
+```
+
+After the npm package is published, the plugin form will be:
+
+```json
+{"plugin": ["opencode-memtomem@0.1.0"]}
+```
+
+Restart OpenCode, then run `/memtomem-status` or `/memtomem-search topic`.
+`uvx` must be available on `PATH`. The manual configuration above starts the
+exact-pinned `memtomem[all]==0.3.10` runtime on demand.
+
+The plugin supports macOS, Linux, and Windows through WSL. Native Windows has
+not been verified.
+
+## Safety and precedence
+
+- Search, recall, status, stats, list, and read tools are allowed.
+- Add and index require confirmation.
+- The broad `mem_do` dispatcher is denied.
+- An existing `mcp.memtomem`, command of the same name, same-named user skill,
+  or memtomem-specific permission rule wins over the plugin default.
+
+OpenCode's `--auto` mode approves `ask` decisions, and agent-level permissions
+can override global settings. Review those settings before using write commands.

package/dist/generated.d.ts

@@ -0,0 +1,30 @@
+export declare const CORE_VERSION = "0.3.10";
+export declare const TOOL_MODE = "core";
+export declare const MCP_TIMEOUT_MS = 60000;
+export declare const OPENCODE_COMMANDS: {
+    readonly "memtomem-search": {
+        readonly description: "Search indexed memtomem memories by topic. Use for past decisions, notes, findings, or project context that may exist in the memory index.";
+        readonly template: "Use the memtomem search workflow.\n\nUser input: $ARGUMENTS\n\nCall `memtomem_mem_search` with the requested topic and use the compact output unless machine-readable details are necessary.\n\nPresent the strongest matches concisely with their source path, heading, and relevance score. Explain that memtomem uses BM25 by default and adds dense retrieval only when embeddings are configured. If nothing matches, suggest a broader query or the status workflow; do not write or index anything automatically.";
+    };
+    readonly "memtomem-recall": {
+        readonly description: "Recall memtomem memories created in a date range. Use for recent memories or requests scoped by day, week, month, source, or namespace.";
+        readonly template: "Use the memtomem recall workflow.\n\nUser input: $ARGUMENTS\n\nTranslate relative dates such as “last week” into `since` and `until` values when possible, then call `memtomem_mem_recall`. Preserve any source, namespace, scope, or result-limit constraint from the request.\n\nPresent memories newest first with their creation date and source. Ask for a date range only when the request provides no usable temporal constraint. Use topic search, not recall, when the user is asking what a memory says rather than when it was created.";
+    };
+    readonly "memtomem-status": {
+        readonly description: "Check memtomem configuration, storage, index counts, dense coverage, and warnings. Use when search is empty, degraded, or needs diagnosis.";
+        readonly template: "Use the memtomem status workflow.\n\nCall `memtomem_mem_status` once. Report the storage backend and database path, embedding state, source and chunk counts, dense-vector coverage, and warnings that the tool actually returns.\n\nTreat `provider=none` and BM25-only coverage as a supported default, not a failed setup. Do not claim namespace totals or other fields absent from the response.";
+    };
+    readonly "memtomem-remember": {
+        readonly description: "Save an explicit user-requested memory with memtomem. Use only when the user clearly asks to remember, record, or persist information for later.";
+        readonly template: "Use the memtomem remember workflow.\n\nUser input: $ARGUMENTS\n\nConfirm that the user explicitly requested persistence, then call `memtomem_mem_add` with the requested content. Add a natural title and a small set of useful tags only when they are clear from the content.\n\nUse `scope=\"user\"` by default and leave `force_unsafe=false`. Use `project_shared` only after explicit confirmation and set `confirm_project_shared=true`. Report the written file and indexed chunk count. If the tool reports a similar memory, surface the warning rather than silently creating another variant.";
+    };
+    readonly "memtomem-index": {
+        readonly description: "Index or re-index an explicitly selected file or directory with memtomem. Use for initial ingestion or intentional refresh after file changes.";
+        readonly template: "Use the memtomem index workflow.\n\nUser input: $ARGUMENTS\n\nRequire an explicit file or directory path before calling `memtomem_mem_index`; never rely on its `.` default. Resolve ambiguity with the user before indexing a broad directory.\n\nUse `force=false` and `auto_tag=false` unless the user explicitly requests otherwise. Report scanned, indexed, skipped, deleted, and blocked counts. Explain redaction or embedding-mismatch failures without bypassing them automatically.";
+    };
+    readonly "memtomem-setup": {
+        readonly description: "Set up and verify a first memtomem memory source. Use for onboarding, choosing an index path, or confirming that search works.";
+        readonly template: "Use the memtomem setup workflow.\n\nUser input: $ARGUMENTS\n\n1. Call `memtomem_mem_status` and treat the default `provider=none` BM25-only configuration as healthy.\n2. Obtain an explicit notes or memory directory from the request; ask for one when absent.\n3. Call `memtomem_mem_index` on that path with `force=false` and `auto_tag=false`.\n4. Choose a representative phrase from the indexed material and call `memtomem_mem_search` to verify retrieval.\n5. Report the first-success path and mention embeddings only as an optional relevance enhancement.\n\nDo not install Ollama, enable automation hooks, or edit host instruction files unless the user separately requests those actions.";
+    };
+};
+export declare const OPENCODE_READ_SKILLS: readonly ["memtomem-search", "memtomem-recall", "memtomem-status"];

package/dist/generated.js

@@ -0,0 +1,35 @@
+// Generated by tools/render_plugin_assets.py. Do not edit.
+export const CORE_VERSION = "0.3.10";
+export const TOOL_MODE = "core";
+export const MCP_TIMEOUT_MS = 60000;
+export const OPENCODE_COMMANDS = {
+    "memtomem-search": {
+        "description": "Search indexed memtomem memories by topic. Use for past decisions, notes, findings, or project context that may exist in the memory index.",
+        "template": "Use the memtomem search workflow.\n\nUser input: $ARGUMENTS\n\nCall `memtomem_mem_search` with the requested topic and use the compact output unless machine-readable details are necessary.\n\nPresent the strongest matches concisely with their source path, heading, and relevance score. Explain that memtomem uses BM25 by default and adds dense retrieval only when embeddings are configured. If nothing matches, suggest a broader query or the status workflow; do not write or index anything automatically."
+    },
+    "memtomem-recall": {
+        "description": "Recall memtomem memories created in a date range. Use for recent memories or requests scoped by day, week, month, source, or namespace.",
+        "template": "Use the memtomem recall workflow.\n\nUser input: $ARGUMENTS\n\nTranslate relative dates such as “last week” into `since` and `until` values when possible, then call `memtomem_mem_recall`. Preserve any source, namespace, scope, or result-limit constraint from the request.\n\nPresent memories newest first with their creation date and source. Ask for a date range only when the request provides no usable temporal constraint. Use topic search, not recall, when the user is asking what a memory says rather than when it was created."
+    },
+    "memtomem-status": {
+        "description": "Check memtomem configuration, storage, index counts, dense coverage, and warnings. Use when search is empty, degraded, or needs diagnosis.",
+        "template": "Use the memtomem status workflow.\n\nCall `memtomem_mem_status` once. Report the storage backend and database path, embedding state, source and chunk counts, dense-vector coverage, and warnings that the tool actually returns.\n\nTreat `provider=none` and BM25-only coverage as a supported default, not a failed setup. Do not claim namespace totals or other fields absent from the response."
+    },
+    "memtomem-remember": {
+        "description": "Save an explicit user-requested memory with memtomem. Use only when the user clearly asks to remember, record, or persist information for later.",
+        "template": "Use the memtomem remember workflow.\n\nUser input: $ARGUMENTS\n\nConfirm that the user explicitly requested persistence, then call `memtomem_mem_add` with the requested content. Add a natural title and a small set of useful tags only when they are clear from the content.\n\nUse `scope=\"user\"` by default and leave `force_unsafe=false`. Use `project_shared` only after explicit confirmation and set `confirm_project_shared=true`. Report the written file and indexed chunk count. If the tool reports a similar memory, surface the warning rather than silently creating another variant."
+    },
+    "memtomem-index": {
+        "description": "Index or re-index an explicitly selected file or directory with memtomem. Use for initial ingestion or intentional refresh after file changes.",
+        "template": "Use the memtomem index workflow.\n\nUser input: $ARGUMENTS\n\nRequire an explicit file or directory path before calling `memtomem_mem_index`; never rely on its `.` default. Resolve ambiguity with the user before indexing a broad directory.\n\nUse `force=false` and `auto_tag=false` unless the user explicitly requests otherwise. Report scanned, indexed, skipped, deleted, and blocked counts. Explain redaction or embedding-mismatch failures without bypassing them automatically."
+    },
+    "memtomem-setup": {
+        "description": "Set up and verify a first memtomem memory source. Use for onboarding, choosing an index path, or confirming that search works.",
+        "template": "Use the memtomem setup workflow.\n\nUser input: $ARGUMENTS\n\n1. Call `memtomem_mem_status` and treat the default `provider=none` BM25-only configuration as healthy.\n2. Obtain an explicit notes or memory directory from the request; ask for one when absent.\n3. Call `memtomem_mem_index` on that path with `force=false` and `auto_tag=false`.\n4. Choose a representative phrase from the indexed material and call `memtomem_mem_search` to verify retrieval.\n5. Report the first-success path and mention embeddings only as an optional relevance enhancement.\n\nDo not install Ollama, enable automation hooks, or edit host instruction files unless the user separately requests those actions."
+    }
+};
+export const OPENCODE_READ_SKILLS = [
+    "memtomem-search",
+    "memtomem-recall",
+    "memtomem-status",
+];

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+import type { Config, PluginInput } from "@opencode-ai/plugin";
+type PermissionValue = "allow" | "ask" | "deny";
+export declare const SAFE_PERMISSIONS: Record<string, PermissionValue>;
+declare const plugin: {
+    id: string;
+    server(input: PluginInput): Promise<{
+        config(config: Config): Promise<void>;
+    }>;
+};
+export default plugin;

package/dist/server.js

@@ -0,0 +1,127 @@
+import { access } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CORE_VERSION, MCP_TIMEOUT_MS, OPENCODE_COMMANDS, OPENCODE_READ_SKILLS, TOOL_MODE, } from "./generated.js";
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+export const SAFE_PERMISSIONS = {
+    "memtomem_*": "ask",
+    memtomem_mem_search: "allow",
+    memtomem_mem_recall: "allow",
+    memtomem_mem_status: "allow",
+    memtomem_mem_stats: "allow",
+    memtomem_mem_list: "allow",
+    memtomem_mem_read: "allow",
+    memtomem_mem_do: "deny",
+};
+function mergePermissions(existing) {
+    if (typeof existing === "string") {
+        if (existing === "deny")
+            return { "*": "deny" };
+        if (existing === "ask")
+            return { "*": "ask", memtomem_mem_do: "deny" };
+        return { "*": existing, ...SAFE_PERMISSIONS };
+    }
+    const generic = {};
+    const memtomem = {};
+    for (const [pattern, value] of Object.entries(existing ?? {})) {
+        (pattern.startsWith("memtomem_") ? memtomem : generic)[pattern] = value;
+    }
+    if (generic["*"] === "deny")
+        return { ...generic, ...memtomem };
+    if (generic["*"] === "ask") {
+        return { ...generic, memtomem_mem_do: "deny", ...memtomem };
+    }
+    return { ...generic, ...SAFE_PERMISSIONS, ...memtomem };
+}
+function ancestors(start) {
+    const result = [];
+    let current = resolve(start);
+    for (;;) {
+        result.push(current);
+        const parent = dirname(current);
+        if (parent === current)
+            return result;
+        current = parent;
+    }
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function hasUserSkill(name, input, configuredPaths) {
+    const roots = new Set();
+    for (const start of [input.directory, input.worktree].filter((item) => !!item)) {
+        for (const parent of ancestors(start)) {
+            for (const relative of [
+                ".opencode/skills",
+                ".opencode/skill",
+                ".claude/skills",
+                ".agents/skills",
+            ])
+                roots.add(join(parent, relative));
+        }
+    }
+    for (const relative of [
+        ".config/opencode/skills",
+        ".config/opencode/skill",
+        ".claude/skills",
+        ".agents/skills",
+    ])
+        roots.add(join(homedir(), relative));
+    for (const configured of configuredPaths) {
+        const absolute = resolve(configured);
+        if (absolute === packageRoot || absolute.startsWith(`${packageRoot}${sep}`))
+            continue;
+        if (basename(absolute) === name && await exists(join(absolute, "SKILL.md")))
+            return true;
+        roots.add(absolute);
+    }
+    for (const root of roots) {
+        if (await exists(join(root, name, "SKILL.md")))
+            return true;
+    }
+    return false;
+}
+async function configure(config, input) {
+    config.mcp ??= {};
+    if (!("memtomem" in config.mcp)) {
+        config.mcp.memtomem = {
+            type: "local",
+            command: ["uvx", "--from", `memtomem==${CORE_VERSION}`, "memtomem-server"],
+            enabled: true,
+            timeout: MCP_TIMEOUT_MS,
+            environment: { MEMTOMEM_TOOL_MODE: TOOL_MODE },
+        };
+    }
+    config.command ??= {};
+    for (const [name, command] of Object.entries(OPENCODE_COMMANDS)) {
+        if (!(name in config.command))
+            config.command[name] = command;
+    }
+    config.skills ??= {};
+    config.skills.paths ??= [];
+    for (const name of OPENCODE_READ_SKILLS) {
+        const path = join(packageRoot, "skills", name);
+        if (!config.skills.paths.includes(path) && !(await hasUserSkill(name, input, config.skills.paths))) {
+            config.skills.paths.push(path);
+        }
+    }
+    config.permission = mergePermissions(config.permission);
+}
+const plugin = {
+    id: "opencode-memtomem",
+    async server(input) {
+        return {
+            async config(config) {
+                await configure(config, input);
+            },
+        };
+    },
+};
+export default plugin;

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "opencode-memtomem",
+  "version": "0.1.0",
+  "description": "Safe memtomem MCP, commands, and read skills for OpenCode",
+  "type": "module",
+  "sideEffects": false,
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/memtomem/memtomem.git",
+    "directory": "packages/opencode-memtomem"
+  },
+  "homepage": "https://github.com/memtomem/memtomem/tree/main/packages/opencode-memtomem",
+  "bugs": "https://github.com/memtomem/memtomem/issues",
+  "engines": {
+    "node": ">=20",
+    "opencode": ">=1.17.18 <2"
+  },
+  "exports": {
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.17.18",
+    "@types/node": "26.1.1",
+    "typescript": "5.9.3"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/skills/memtomem-recall/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: memtomem-recall
+description: Recall memtomem memories created in a date range. Use for recent memories or requests scoped by day, week, month, source, or namespace.
+license: Apache-2.0
+compatibility: OpenCode >=1.17.18 <2
+metadata:
+  provider: memtomem
+---
+
+# Recall memories
+
+Derive the date range or recent-memory request from the current user request.
+If the request does not clearly specify the date range or recent-memory request, ask before calling a tool.
+Translate relative dates such as “last week” into `since` and `until` values when possible, then call `memtomem_mem_recall`. Preserve any source, namespace, scope, or result-limit constraint from the request.
+
+Present memories newest first with their creation date and source. Ask for a date range only when the request provides no usable temporal constraint. Use topic search, not recall, when the user is asking what a memory says rather than when it was created.

package/skills/memtomem-search/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: memtomem-search
+description: Search indexed memtomem memories by topic. Use for past decisions, notes, findings, or project context that may exist in the memory index.
+license: Apache-2.0
+compatibility: OpenCode >=1.17.18 <2
+metadata:
+  provider: memtomem
+---
+
+# Search memories
+
+Derive the search query from the current user request.
+If the request does not clearly specify the search query, ask before calling a tool.
+Call `memtomem_mem_search` with the requested topic and use the compact output unless machine-readable details are necessary.
+
+Present the strongest matches concisely with their source path, heading, and relevance score. Explain that memtomem uses BM25 by default and adds dense retrieval only when embeddings are configured. If nothing matches, suggest a broader query or the status workflow; do not write or index anything automatically.

package/skills/memtomem-status/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: memtomem-status
+description: Check memtomem configuration, storage, index counts, dense coverage, and warnings. Use when search is empty, degraded, or needs diagnosis.
+license: Apache-2.0
+compatibility: OpenCode >=1.17.18 <2
+metadata:
+  provider: memtomem
+---
+
+# Check memory status
+Call `memtomem_mem_status` once. Report the storage backend and database path, embedding state, source and chunk counts, dense-vector coverage, and warnings that the tool actually returns.
+
+Treat `provider=none` and BM25-only coverage as a supported default, not a failed setup. Do not claim namespace totals or other fields absent from the response.