opencode-claude-mem

Persistent memory for OpenCode, powered by Claude-Mem.

Share the same Claude-Mem worker, database, and search tools between Claude Code and OpenCode. Once connected, previous observations and summaries are injected into new OpenCode sessions automatically.

Note: This plugin is a thin OpenCode adapter for an existing Claude-Mem installation. It does not install Claude-Mem, manage slash commands, or start the worker for you.

Quick Start

1. Install and configure Claude-Mem in Claude Code.
2. Add this plugin to your opencode.json:

{
  "plugin": ["@ephemushroom/opencode-claude-mem"]
}

3. Restart OpenCode.
4. Start a session — memory context will be injected automatically when the Claude-Mem worker is available.

Key Features

• Shared Memory — Uses the same Claude-Mem worker and memory store as Claude Code.
• Auto-Start — When the plugin loads and the Claude-Mem worker is not already running, it spawns bunx claude-mem start once per OpenCode process (skipped silently if bun is not on PATH or the worker is already up).
• Automatic Context Injection — Injects relevant project memory into the system prompt for new OpenCode turns.
• Compaction Support — Re-injects memory context during OpenCode session compaction so long conversations keep their historical context.
• Observation Capture — Sends tool observations to Claude-Mem for future retrieval and summarization.
• Observation Hardening — Skips low-value meta tools, strips <claude-mem-context> and <private> tags before storage, and truncates oversized observation payloads by UTF-8 byte size.
• Graceful Degradation — If the worker is offline and cannot be started, the plugin fails open and OpenCode continues to work normally.

How It Works

OpenCode session
    |
    |-- plugin loads
    |   '-- connect to Claude-Mem worker on port 37777
    |
    |-- session.created ................ track session + reset cache
    |-- chat.message ................... init session with real user prompt
    |-- tool.execute.after ............. send tool observation
    |-- system.transform ............... inject memory into system prompt
    |-- session.compacting ............. preserve memory during compaction
    |-- message.updated ................ capture assistant text (debounced)
    |-- file.edited .................... record file edit observation
    |-- session.compacted .............. summarize after compaction
    |-- session.idle ................... flush + summarize + complete session
    '-- session.deleted ................ flush + complete (no zombie sessions)

The plugin is intentionally small. It only adapts OpenCode hook events to the Claude-Mem worker HTTP API. All indexing, summarization, memory search, and storage stay in upstream Claude-Mem.

Architecture

OpenCode <-> Plugin (this repo) <-> Claude-Mem Worker (port 37777) <-> SQLite + ChromaDB

Hook Mapping

Claude Code	OpenCode plugin	Purpose
SessionStart	experimental.chat.system.transform	Inject memory context
SessionStart	experimental.session.compacting	Preserve memory during compaction
UserPromptSubmit	chat.message	Initialize session with real user prompt
PostToolUse	tool.execute.after	Capture tool observations
(streaming)	event (message.updated)	Capture assistant text (debounced)
(streaming)	event (file.edited)	Record file edit observations
(compaction)	event (session.compacted)	Summarize after OpenCode compacts
Stop	event (session.idle)	Flush + summarize + complete
SessionEnd	event (session.deleted)	Flush + complete (no zombie active rows)

Worker API Endpoints Used

Method	Endpoint	Purpose
GET	/api/health	Health check
GET	/api/context/inject?project={name}	Fetch formatted memory context
POST	/api/sessions/init	Initialize session
POST	/api/sessions/observations	Store tool observation
POST	/api/sessions/summarize	Trigger summarization
POST	/api/sessions/complete	Complete session

Installation

Prerequisites

• Claude Code with Claude-Mem installed
• OpenCode with plugin support
• A running Claude-Mem worker on port 37777 (default)

Step 1: Install Claude-Mem

In Claude Code:

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Restart Claude Code so the worker can start and initialize its data directory.

Step 2: Add the OpenCode Plugin

Add this plugin to your project or global opencode.json:

{
  "plugin": ["@ephemushroom/opencode-claude-mem"]
}

Then restart OpenCode.

Step 3: Verify

curl -s http://127.0.0.1:37777/api/health

If the worker is healthy, OpenCode should show a toast like Memory active · <project> when a session starts.

Usage

Once installed, the plugin works automatically:

• Context injection — Memory is injected into the system prompt on each LLM call, with session-level caching to avoid repeated worker requests.
• Compaction preservation — The same cached memory context is pushed into OpenCode’s compaction path so memory survives conversation compression.
• Tool observation capture — Tool executions are stored as observations, except for low-value/meta tools and Claude-Mem search tools.
• Assistant message capture — Assistant text from message.updated is buffered with 250ms debounce per session and sent as a single assistant_message observation per turn (avoids streaming-chunk floods).
• File edit capture — file.edited events are forwarded as file_edit observations (path only; OpenCode does not include diff in the event).
• Session summarization — On session.compacted and session.idle, the plugin flushes any pending assistant buffer, fetches the latest user and assistant messages, and asks Claude-Mem to summarize them.
• Session lifecycle hygiene — On session.deleted the plugin tells the worker to completeSession, preventing zombie 'active' rows from accumulating stale pending_messages (the "queueDepth never decreases" failure mode).

Memory Search

Memory search is provided by Claude-Mem’s MCP server, not by this plugin.

If your OpenCode environment already has Claude-Mem MCP tools configured, the assistant can query project memory directly with Claude-Mem’s search workflow:

1. search(query="...")
2. timeline(anchor=ID)
3. get_observations(ids=[...])

This plugin focuses on sending memory data to the worker and injecting returned context back into OpenCode sessions.

Key Implementation Details

• Thin client architecture — src/index.ts handles OpenCode hooks and session state; src/worker-client.ts is a static HTTP client.
• No console logging — The plugin never writes to console.* because that can corrupt the OpenCode TUI.
• Deferred toast — Health toasts only happen after hook execution begins, avoiding startup crashes caused by early TUI access.
• Real prompt initialization — chat.message sends the actual user prompt to Claude-Mem instead of a synthetic placeholder.
• Real summarize payloads — On session.idle, the plugin reads the latest session messages and sends the last user and assistant messages for summary.
• Context caching — Memory context is fetched once per session and reused across prompt injection and compaction.
• Circular memory protection — Injected context is wrapped in <claude-mem-context> tags, Claude-Mem MCP search tools are skipped, and memory-related tags are stripped before storing observations.
• UTF-8 truncation — Large observation outputs are capped by byte size to reduce token waste and avoid oversize worker payloads.
• Field name correctness — Worker payloads use contentSessionId, not claudeSessionId.

Differences from bloodf/opencode-mem

This project intentionally stays smaller in scope.

• This plugin does: bridge OpenCode hooks to an already-installed Claude-Mem worker.
• This plugin does not: auto-install Claude-Mem, auto-edit OpenCode config, auto-copy skills, auto-register slash commands, or auto-start the worker.

That keeps the runtime behavior predictable and leaves worker ownership with the upstream Claude-Mem installation.

Troubleshooting

No memory appears in OpenCode

• Confirm the worker is running:

curl -s http://127.0.0.1:37777/api/health

• Make sure Claude-Mem has already been installed and used from Claude Code.
• Start a fresh OpenCode session after the worker is healthy.

OpenCode shows Worker offline

The plugin will try to launch the worker via bunx claude-mem start once on plugin load. If that toast still appears:

• Confirm bun is on your PATH — bun --version should print a version.
• Confirm claude-mem is installed for bunx/npx — run bunx claude-mem --version once to populate the cache.
• On Windows after a forced kill, port 37777 may stay in TIME_WAIT for 30-120 seconds; wait it out or restart Claude Code.
• Restart Claude Code to bring Claude-Mem back up via its own supervisor.
• Verify the worker port is still 37777.

OpenCode crashes on startup

• Update to a version with deferred TUI access.
• Ensure there are no console.log, console.warn, or console.error calls in local plugin modifications.

Observations are missing or incomplete

• Ensure the worker API payload uses contentSessionId.
• Be aware that low-value meta tools and Claude-Mem search tools are skipped by design.
• Very large tool outputs are truncated before storage.

Memory search is unavailable

• This plugin does not configure MCP tools for you.
• Configure Claude-Mem’s MCP server separately in your OpenCode environment if you want in-editor memory search.

Development

bun install
bun run build
bun run lint
bun run fmt:check

If you edit source code locally, rebuild and restart OpenCode to pick up the new plugin bundle.

License

MIT