@ephemushroom/opencode-claude-mem 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bryan
+
+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,260 @@
+# opencode-claude-mem
+
+OpenCode plugin for [Claude-Mem](https://github.com/thedotmack/claude-mem) persistent memory system.
+
+Enables OpenCode to share the same memory database as Claude Code — observations, summaries, and context injection all work across both editors.
+
+## How It Works
+
+This plugin communicates with the Claude-Mem worker service (HTTP API on port 37777) to:
+
+- **Capture tool observations** — every tool execution is recorded as a structured observation
+- **Inject memory context** — previous session context is injected into the system prompt via `/api/context/inject`
+- **Summarize sessions** — when a session goes idle, the last user/assistant messages are sent for summarization
+- **Search memory** — `mem-search` tool lets the LLM query project history
+
+## Prerequisites
+
+- [Claude Code](https://claude.com/claude-code) with [claude-mem plugin](https://github.com/thedotmack/claude-mem) installed and running
+- [OpenCode](https://opencode.ai) with plugin support
+
+## Installation
+
+### Step 1: Install Claude-Mem (if not already)
+
+In Claude Code terminal:
+
+```
+/plugin marketplace add thedotmack/claude-mem
+/plugin install claude-mem
+```
+
+Restart Claude Code. The worker service will start automatically on port 37777.
+
+### Step 2: Add the Plugin
+
+Add to your `opencode.json` (project or global `~/.config/opencode/opencode.json`):
+
+```json
+{
+  "plugin": ["@ephemushroom/opencode-claude-mem"]
+}
+```
+
+Restart OpenCode. The plugin will be installed automatically.
+
+### Step 3: Verify
+
+```bash
+# Check worker is running
+curl -s http://127.0.0.1:37777/api/health
+
+# Restart OpenCode — you should see toast: "Memory active · {project}"
+```
+
+### Alternative: Manual Installation (from source)
+
+If you prefer to install from source instead of npm:
+
+```bash
+git clone https://github.com/Ephemushroom/opencode-claude-mem.git
+cd opencode-claude-mem
+bun install
+bun run build
+```
+
+Then symlink into OpenCode:
+
+**macOS / Linux:**
+
+```bash
+mkdir -p ~/.config/opencode/plugin
+ln -sf "$(pwd)/dist/index.js" ~/.config/opencode/plugin/claude-mem.js
+```
+
+**Windows (requires elevated terminal):**
+
+```powershell
+# Option A: If you have gsudo / sudo installed
+sudo powershell -Command "New-Item -ItemType SymbolicLink -Path '$env:USERPROFILE\.config\opencode\plugin\claude-mem.js' -Target 'D:\path\to\opencode-claude-mem\dist\index.js'"
+
+# Option B: Run PowerShell as Administrator
+New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.config\opencode\plugin\claude-mem.js" -Target "D:\path\to\opencode-claude-mem\dist\index.js"
+```
+
+---
+
+## Windows-Specific Setup
+
+### Python Version for ChromaDB
+
+Claude-Mem uses ChromaDB for vector semantic search. ChromaDB's `chroma-mcp` tool requires **Python ≤ 3.13** (Pydantic V1 is incompatible with Python 3.14+).
+
+If `uv` defaults to Python 3.14, you'll see:
+
+```
+Chroma connection failed: Chroma server not reachable.
+```
+
+**Fix — set global Python version:**
+
+```bash
+uv python pin --global 3.13
+```
+
+This creates a global `.python-version` file in `%APPDATA%\uv\` so all `uvx` calls default to 3.13.
+
+### ChromaDB on Windows x64
+
+The npm `chromadb` package only supports Windows ARM64, not x64. The worker will fail to start Chroma natively.
+
+**Fix — use Python ChromaDB instead:**
+
+```bash
+# Install Python ChromaDB CLI
+uv tool install chromadb --python 3.13
+```
+
+Update `~/.claude-mem/settings.json`:
+
+```json
+{
+  "CLAUDE_MEM_CHROMA_MODE": "remote"
+}
+```
+
+Start Chroma server manually:
+
+```bash
+chroma run --path %USERPROFILE%\.claude-mem\vector-db --host 127.0.0.1 --port 8000
+```
+
+> **Note**: Chroma server must be running before Claude Code starts. Consider creating a startup script or scheduled task.
+
+### ChromaDB Embedding Model Crash (Bun Runtime)
+
+After connecting to Chroma, the worker may crash with:
+
+```
+Collection setup failed: undefined is not an object
+  (evaluating 'e.cacheDir = ...')
+```
+
+This happens because `@huggingface/transformers` returns `undefined` when imported through Bun's CJS shim.
+
+**Fix — patch `worker-service.cjs`:**
+
+Locate the bundled worker file:
+
+```
+~/.claude/plugins/cache/thedotmack/claude-mem/<version>/scripts/worker-service.cjs
+```
+
+Find this pattern (minified):
+
+```javascript
+let{env:e}=await Promise.resolve().then(()=>(F9(),N9));
+```
+
+Replace with:
+
+```javascript
+let{env:e}=await import("@huggingface/transformers");
+```
+
+Then install the dependency:
+
+```bash
+cd ~/.claude/plugins/cache/thedotmack/claude-mem/<version>
+bun install
+```
+
+> ⚠️ **This patch is lost on plugin updates.** You'll need to re-apply after each claude-mem version upgrade.
+
+### Verifying ChromaDB Works
+
+```bash
+# Check Chroma server
+curl -s http://127.0.0.1:8000/api/v1/heartbeat
+
+# Check worker health
+curl -s http://127.0.0.1:37777/api/health
+
+# Check for sync errors in worker logs
+# Open http://localhost:37777 in browser for the web viewer
+```
+
+When working correctly, worker logs should show:
+
+```
+CHROMA_SYNC connected (remote mode, 127.0.0.1:8000)
+```
+
+> **ChromaDB is optional.** Without it, claude-mem falls back to SQLite FTS5 full-text search. You lose semantic/vector search but keyword search still works.
+
+---
+
+## Development
+
+After editing source:
+
+```bash
+bun run build
+# Restart OpenCode to pick up changes
+```
+
+If using symlink install, changes are picked up after rebuild. If using npm install, bump version and republish.
+
+## Architecture
+
+```
+OpenCode ←→ Plugin (this repo) ←→ Claude-Mem Worker (port 37777) ←→ SQLite + ChromaDB
+```
+
+The plugin is a thin HTTP client. All heavy lifting (LLM processing, storage, search) happens in the worker.
+
+### Hook Mapping (Claude Code → OpenCode)
+
+| Claude Code Hook | OpenCode Hook | Purpose |
+|-----------------|---------------|---------|
+| `SessionStart` → context | `experimental.chat.system.transform` | Inject memory into system prompt |
+| `UserPromptSubmit` → session-init | `chat.message` | Init session with real user prompt |
+| `PostToolUse` → observation | `tool.execute.after` | Capture tool executions |
+| `Stop` → summarize | `event` (session.idle) | Summarize with real message content |
+| `Stop` → session-complete | `event` (session.idle) | Mark session complete |
+
+### Worker API Endpoints Used
+
+| Method | Endpoint | Purpose |
+|--------|----------|---------|
+| `GET` | `/api/health` | Health check |
+| `GET` | `/api/context/inject?project={name}` | Get formatted context for system prompt |
+| `POST` | `/api/sessions/init` | Initialize session |
+| `POST` | `/api/sessions/observations` | Send tool observation |
+| `POST` | `/api/sessions/summarize` | Trigger summarization |
+| `POST` | `/api/sessions/complete` | Complete session |
+| `GET` | `/api/search?q={query}&project={name}` | Search memory |
+
+## Key Implementation Details
+
+- **Field name**: All worker API calls use `contentSessionId` (not `claudeSessionId`) — using the wrong field name causes silent failures
+- **No console output**: All `console.log/warn/error` removed to avoid corrupting OpenCode TUI
+- **Deferred toast**: `client.tui.showToast()` is deferred to first hook invocation (TUI not ready during plugin init, calling it crashes OpenCode)
+- **Real prompt**: `chat.message` hook extracts actual user input instead of hardcoded "SESSION_START"
+- **Real summarize**: `session.idle` fetches last user/assistant messages via `client.session.messages()` for meaningful summaries
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| No toast on startup | Worker not running | Start Claude Code first, or check `curl http://127.0.0.1:37777/api/health` |
+| "Worker offline" toast | Worker crashed or not started | Restart Claude Code |
+| OpenCode crashes on startup | Plugin calling TUI too early | Update to latest version (deferred toast fix) |
+| TUI display corrupted | console.log in plugin code | Ensure no console output in source |
+| "SESSION_START" in prompts | Old version bug | Update — `session.created` no longer calls sessionInit |
+| Chroma sync failed | Python version or Chroma not running | See [Windows-Specific Setup](#windows-specific-setup) |
+| Observations not saved | Wrong field name | Ensure `contentSessionId` (not `claudeSessionId`) |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import { type Plugin } from '@opencode-ai/plugin';
+/**
+ * OpenCode Plugin for Claude-Mem
+ *
+ * Hooks used:
+ * - `event` — session lifecycle (session.created, session.idle)
+ * - `tool.execute.after` — capture tool observations
+ * - `experimental.chat.system.transform` — inject memory context into system prompt
+ * - `chat.message` — fallback session init when event hook doesn't fire
+ * - `tool` — mem-search custom tool
+ *
+ * Uses TUI toast notifications for status feedback.
+ */
+export declare const ClaudeMemPlugin: Plugin;

package/dist/index.js

@@ -0,0 +1,258 @@
+// @bun
+// src/index.ts
+import { tool } from "@opencode-ai/plugin";
+
+// src/worker-client.ts
+class WorkerClient {
+  static PORT = 37777;
+  static BASE_URL = `http://127.0.0.1:${WorkerClient.PORT}`;
+  static async isHealthy() {
+    try {
+      const controller = new AbortController;
+      const timeoutId = setTimeout(() => controller.abort(), 1000);
+      const response = await fetch(`${this.BASE_URL}/api/health`, {
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      return response.ok;
+    } catch {
+      return false;
+    }
+  }
+  static async ensureRunning(_projectRoot) {
+    return await this.isHealthy();
+  }
+  static async sessionInit(contentSessionId, project, prompt) {
+    try {
+      const response = await fetch(`${this.BASE_URL}/api/sessions/init`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ contentSessionId, project, prompt })
+      });
+      if (!response.ok) {
+        return null;
+      }
+      return await response.json();
+    } catch {
+      return null;
+    }
+  }
+  static async sendObservation(contentSessionId, toolName, toolInput, toolResponse, cwd) {
+    try {
+      await fetch(`${this.BASE_URL}/api/sessions/observations`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          contentSessionId,
+          tool_name: toolName,
+          tool_input: toolInput,
+          tool_response: toolResponse,
+          cwd
+        })
+      });
+    } catch {}
+  }
+  static async summarize(contentSessionId, lastUserMessage, lastAssistantMessage) {
+    try {
+      await fetch(`${this.BASE_URL}/api/sessions/summarize`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          contentSessionId,
+          last_user_message: lastUserMessage,
+          last_assistant_message: lastAssistantMessage
+        })
+      });
+    } catch {}
+  }
+  static async completeSession(contentSessionId) {
+    try {
+      await fetch(`${this.BASE_URL}/api/sessions/complete`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ contentSessionId })
+      });
+    } catch {}
+  }
+  static async getContext(project) {
+    try {
+      const response = await fetch(`${this.BASE_URL}/api/context/inject?project=${encodeURIComponent(project)}`);
+      if (!response.ok) {
+        return null;
+      }
+      const data = await response.json();
+      if (typeof data === "string") {
+        return data;
+      }
+      if (data && typeof data.content === "string") {
+        return data.content;
+      }
+      const text = JSON.stringify(data, null, 2);
+      return text === "{}" || text === "null" ? null : text;
+    } catch {
+      return null;
+    }
+  }
+  static async search(query, project) {
+    try {
+      const response = await fetch(`${this.BASE_URL}/api/search?q=${encodeURIComponent(query)}&project=${encodeURIComponent(project)}`);
+      if (!response.ok) {
+        return "Search failed";
+      }
+      const data = await response.json();
+      return JSON.stringify(data, null, 2);
+    } catch (error) {
+      return `Error performing search: ${error}`;
+    }
+  }
+}
+
+// src/index.ts
+var ClaudeMemPlugin = async (ctx) => {
+  const { project, directory, client } = ctx;
+  const projectRoot = directory || process.cwd();
+  const projectName = project?.worktree ? project.worktree.split(/[\\/]/).findLast(Boolean) || "unknown-project" : "unknown-project";
+  async function toast(message, variant = "info", duration = 3000) {
+    try {
+      await client.tui.showToast({
+        body: { title: "Claude-Mem", message, variant, duration }
+      });
+    } catch {}
+  }
+  let workerHealthy = null;
+  let initToastShown = false;
+  async function checkWorkerAndToast() {
+    if (workerHealthy === null) {
+      workerHealthy = await WorkerClient.isHealthy();
+    }
+    if (!initToastShown) {
+      initToastShown = true;
+      if (workerHealthy) {
+        await toast(`Memory active \xB7 ${projectName}`, "success");
+      } else {
+        await toast("Worker offline \u2014 start Claude Code first", "warning", 5000);
+      }
+    }
+    return workerHealthy;
+  }
+  let currentSessionId = null;
+  const initializedSessions = new Set;
+  async function ensureSessionInit(sessionId, prompt) {
+    if (initializedSessions.has(sessionId)) {
+      return true;
+    }
+    const isHealthy = await checkWorkerAndToast();
+    if (!isHealthy) {
+      return false;
+    }
+    try {
+      await WorkerClient.sessionInit(sessionId, projectName, prompt || "SESSION_START");
+      initializedSessions.add(sessionId);
+      currentSessionId = sessionId;
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  function extractTextFromParts(parts) {
+    if (!parts || !Array.isArray(parts)) {
+      return "";
+    }
+    return parts.filter((p) => p.type === "text" && typeof p.text === "string").map((p) => p.text).join(`
+`).trim();
+  }
+  return {
+    event: async ({ event }) => {
+      if (event.type === "session.created") {
+        const sessionId = event.properties?.info?.id;
+        if (!sessionId) {
+          return;
+        }
+        currentSessionId = sessionId;
+        const isHealthy = await checkWorkerAndToast();
+        if (isHealthy) {
+          await toast("Session linked to memory", "info", 2000);
+        }
+      }
+      if (event.type === "session.idle") {
+        const sessionId = event.properties?.sessionID || currentSessionId;
+        if (!sessionId) {
+          return;
+        }
+        try {
+          let lastUserMessage = "";
+          let lastAssistantMessage = "";
+          try {
+            const result = await client.session.messages({
+              path: { id: sessionId }
+            });
+            if (result.data && Array.isArray(result.data)) {
+              const messages = result.data;
+              for (let i = messages.length - 1;i >= 0; i--) {
+                if (messages[i].info.role === "user") {
+                  lastUserMessage = extractTextFromParts(messages[i].parts);
+                  break;
+                }
+              }
+              for (let i = messages.length - 1;i >= 0; i--) {
+                if (messages[i].info.role === "assistant") {
+                  lastAssistantMessage = extractTextFromParts(messages[i].parts);
+                  break;
+                }
+              }
+            }
+          } catch {}
+          await WorkerClient.summarize(sessionId, lastUserMessage, lastAssistantMessage);
+          await WorkerClient.completeSession(sessionId);
+          await toast("Session summarized", "success", 2000);
+        } catch {}
+      }
+    },
+    "chat.message": async (input, output) => {
+      const sessionId = input.sessionID;
+      if (sessionId) {
+        const userPrompt = extractTextFromParts(output.parts);
+        await ensureSessionInit(sessionId, userPrompt || undefined);
+      }
+    },
+    "experimental.chat.system.transform": async (input, output) => {
+      const sessionId = input.sessionID;
+      if (sessionId) {
+        await ensureSessionInit(sessionId);
+      }
+      const isHealthy = await checkWorkerAndToast();
+      if (!isHealthy) {
+        return;
+      }
+      try {
+        const context = await WorkerClient.getContext(projectName);
+        if (context) {
+          output.system.push(`[Claude-Mem] Memory Active. Previous Context:
+${context}`);
+        }
+      } catch {}
+    },
+    "tool.execute.after": async (input, output) => {
+      const sessionId = input.sessionID || currentSessionId;
+      if (!sessionId) {
+        return;
+      }
+      await ensureSessionInit(sessionId);
+      try {
+        await WorkerClient.sendObservation(sessionId, input.tool, input.args || {}, output.output, projectRoot);
+      } catch {}
+    },
+    tool: {
+      "mem-search": tool({
+        description: "Search project history and memory. Use this to find information about past decisions, code changes, or bug fixes.",
+        args: {
+          query: tool.schema.string()
+        },
+        execute: async (args) => await WorkerClient.search(args.query, projectName)
+      })
+    }
+  };
+};
+export {
+  ClaudeMemPlugin
+};

package/dist/worker-client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Worker Client for Claude-Mem
+ * Handles communication with the local worker service running on port 37777.
+ */
+export declare class WorkerClient {
+    private static readonly PORT;
+    private static readonly BASE_URL;
+    /**
+     * Check if the worker is healthy
+     */
+    static isHealthy(): Promise<boolean>;
+    /**
+     * Ensure the worker is running.
+     */
+    static ensureRunning(_projectRoot: string): Promise<boolean>;
+    /**
+     * Initialize a session
+     */
+    static sessionInit(contentSessionId: string, project: string, prompt: string): Promise<{
+        sessionDbId: number;
+        promptNumber: number;
+    } | null>;
+    /**
+     * Send observation
+     */
+    static sendObservation(contentSessionId: string, toolName: string, toolInput: any, toolResponse: any, cwd: string): Promise<void>;
+    /**
+     * Trigger summarization
+     */
+    static summarize(contentSessionId: string, lastUserMessage: string, lastAssistantMessage: string): Promise<void>;
+    /**
+     * Complete session
+     */
+    static completeSession(contentSessionId: string): Promise<void>;
+    /**
+     * Get pre-formatted context for system prompt injection.
+     * Uses /api/context/inject which returns rich markdown with observations + session summaries.
+     */
+    static getContext(project: string): Promise<string | null>;
+    /**
+     * Perform Search (used by mem-search tool)
+     */
+    static search(query: string, project: string): Promise<string>;
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@ephemushroom/opencode-claude-mem",
+  "version": "0.1.0",
+  "description": "OpenCode plugin for Claude-Mem persistent memory system",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun build src/index.ts --outfile dist/index.js --target bun --format esm --external @opencode-ai/plugin && tsc --emitDeclarationOnly",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "lint": "oxlint",
+    "fmt": "oxfmt --write src/",
+    "fmt:check": "oxfmt --check src/",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run clean && bun run build"
+  },
+  "keywords": [
+    "opencode",
+    "claude-mem",
+    "memory",
+    "plugin",
+    "persistent-memory"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ephemushroom/opencode-claude-mem.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ephemushroom/opencode-claude-mem/issues"
+  },
+  "homepage": "https://github.com/Ephemushroom/opencode-claude-mem#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "oxfmt": "^0.33.0",
+    "oxlint": "^1.48.0",
+    "typescript": "^5.0.0"
+  }
+}