Note: This project is not affiliated with the OpenCode team.

Quick Start

Add one line to your opencode.json:

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

Restart OpenCode. That's it.

The plugin automatically installs claude-mem, starts the worker, configures MCP search tools, and copies the mem-search skill. Context from previous sessions will appear in new sessions.

Key Features

• Shared Memory — Same worker, database, and memory as Claude Code. Work in either tool seamlessly.
• Automatic Setup — Zero manual configuration. The plugin installs and configures everything on first load.
• Context Injection — Relevant memories are appended to the system prompt every session.
• MCP Search — Query your project history with the 3-layer search workflow (search, timeline, get_observations).
• Graceful Degradation — If the worker is unavailable, the plugin loads without errors. Memory features activate when the worker starts.
• Fire-and-Forget — All memory operations (save, capture, summarize) are non-blocking. The plugin never slows down your session.

How It Works

opencode session
    |
    |-- plugin loads
    |   |-- detect claude-mem
    |   |-- auto-setup if needed (fire-and-forget)
    |   '-- connect to worker on port 37777
    |
    |-- session.created .............. initSession
    |-- chat.message ................. capturePrompt
    |-- tool.execute.after ........... saveObservation
    |-- system.transform ............. injectContext (memory -> system prompt) + memoryStatus
    |-- session.compacting ........... injectCompactionContext
    |-- session.idle ................. sendSummary
    '-- session.deleted .............. completeSession

The plugin maps OpenCode lifecycle events to claude-mem hooks. Observations and prompts are captured during your session, summaries are generated at idle, and relevant context is injected into every new session automatically.

Shared infrastructure:

| Component | Path | |-----------|------| | Worker | http://localhost:37777 | | Database | ~/.claude-mem/claude-mem.db | | Settings | ~/.claude-mem/settings.json | | Web Viewer | http://localhost:37777 |

Both Claude Code and OpenCode connect to the same worker and database. Memories are shared across tools.

Automatic Setup

When the plugin loads for the first time, it runs a 6-step setup sequence. No manual intervention required.

| Step | What happens | When skipped | |------|-------------|-------------| | Detect | Checks if claude-mem is in PATH or ~/.claude-mem exists | -- | | Install | Runs npm install -g claude-mem | Already installed | | Configure MCP | Adds claude-mem entry to ~/.config/opencode/opencode.json | Entry already exists | | Configure Commands | Adds 4 slash commands to ~/.config/opencode/opencode.json | Commands already exist | | Copy Skills | Copies mem-search skill to ~/.config/opencode/skills/ | Skill directory already exists | | Start Worker | Launches the claude-mem worker process | Worker already running | All steps are idempotent (safe to run multiple times) and independent (if one fails, the rest still run). Setup runs in the background and never blocks plugin initialization.

What Gets Configured

| File | Change | |------|--------| | ~/.config/opencode/opencode.json | MCP entry added under mcp.claude-mem | | ~/.config/opencode/opencode.json | 4 slash commands added under commands key | | ~/.config/opencode/skills/mem-search/ | Skill files copied from plugin package |

Installation

npm (recommended)

npm install @bloodf/opencode-claude-mem

Then in opencode.json:

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

Interactive Installer (Recommended for new users)

npx @bloodf/opencode-claude-mem install --no-tui

Or for LLM-guided setup, paste this URL into your AI agent:

https://raw.githubusercontent.com/bloodf/opencode-claude-mem/main/docs/guide/installation.md

Optional flags:

• --skip-worker — Skip worker startup if you manage the worker separately
• --port <number> — Specify a custom worker port (default: 37777)

Local path

Copy to plugins directory

cp -r node_modules/@bloodf/opencode-claude-mem .opencode/plugins/opencode-claude-mem

Prerequisites

• OpenCode installed
• npm available in PATH

claude-mem is installed automatically on first plugin load. If you already have claude-mem installed via Claude Code, the plugin connects to the existing worker and database — no reinstallation needed.

Search Tools

The plugin configures MCP search tools automatically. These tools follow a 3-layer workflow that saves ~10x tokens by filtering before fetching full details.

The 3-Layer Workflow

Step 1: search(query)           ~50-100 tokens/result
          |
Step 2: timeline(anchor=ID)     ~200-500 tokens/result
          |
Step 3: get_observations([IDs]) full content

Available MCP Tools

| Tool | Purpose | Key Params | |------|---------|-----------| | search | Search memory index | query, limit, project, type, dateStart, dateEnd | | timeline | Get context around a result | anchor (ID) or query, depth_before, depth_after | | get_observations | Fetch full details by IDs | ids (array, required) | | save_memory | Save a manual observation | text (required), title, project |

Example

1. search(query="authentication bug", limit=10)
2. timeline(anchor=42, depth_before=3, depth_after=3)
3. get_observations(ids=[42, 43])

Manual MCP Configuration

MCP is configured automatically. If you need to set it up manually:

{
  "mcp": {
    "claude-mem": {
      "type": "local",
      "command": ["/path/to/mcp-server.cjs"],
      "enabled": true
    }
  }
}

The path to mcp-server.cjs is auto-configured during setup. Run the plugin once to configure automatically.

Manual Skill Setup

The mem-search skill is copied automatically. To install manually:

cp -r node_modules/@bloodf/opencode-claude-mem/skills/mem-search ~/.config/opencode/skills/

Memory Commands

The plugin configures 4 slash commands in OpenCode automatically. Commands are auto-configured in opencode.json during setup.

| Command | Description | |---------|-------------| | /mem-search <query> | Search persistent memory for past observations and context | | /mem-save <text> | Save a manual memory entry to the persistent store | | /mem-status | Show memory connection status and worker health | | /mem-timeline | Show recent memory timeline entries |

Usage Examples

/mem-search authentication bug from last week
/mem-save Decided to use JWT with 24h expiry for auth tokens
/mem-status
/mem-timeline

Configuration

The plugin auto-detects settings from ~/.claude-mem/settings.json. No configuration required.

| Setting | Source | Default | |---------|--------|---------| | Worker port | ~/.claude-mem/settings.json | 37777 | | Data directory | ~/.claude-mem/ | auto | | Database | ~/.claude-mem/claude-mem.db | auto |

Environment Variables

| Variable | Description | |----------|-------------| | CLAUDE_MEM_DATA_DIR | Override the data directory path (useful for testing) |

Troubleshooting

Plugin loads but no memory appears

• Verify the worker is running: curl http://localhost:37777/health
• Check that claude-mem has been used with Claude Code to build up memory
• If this is a fresh install, memories will start appearing after your first session

Worker not starting

• Check if the worker is already running on a different port
• Start manually: claude-mem start
• If auto-setup failed: npm install -g claude-mem, then restart OpenCode

Auto-setup failed to install claude-mem

• Confirm npm is available: npm --version
• Check for permission issues with global installs — use a version manager like nvm or configure npm's prefix
• Install manually: npm install -g claude-mem

Auto-setup failed to configure MCP or skills

• Check that ~/.config/opencode/ exists and is writable
• Configure manually using the instructions in Manual MCP Configuration and Manual Skill Setup
• The plugin still works for memory injection even if MCP search setup fails

Port conflict

• Check ~/.claude-mem/settings.json for the configured port
• The plugin reads this file automatically

Sharing memory between Claude Code and OpenCode

• Both tools must point to the same worker (default: port 37777)
• If Claude Code is already running claude-mem, OpenCode connects to the same worker automatically
• Memories are shared via the SQLite database at ~/.claude-mem/claude-mem.db

Architecture

                    opencode-claude-mem
                           |
                    OpenCode Plugin API
                           |
              +------------+------------+
              |                         |
         Auto-Setup               Event Hooks
         (first load)            (every session)
              |                         |
    +---------+---------+     +---------+---------+
    | detect binary     |     | initSession       |
    | install npm       |     | capturePrompt     |
    | configure MCP     |     | saveObservation   |
    | copy skills       |     | injectContext     |
    | start worker      |     | sendSummary       |
    +-------------------+     | completeSession   |
                              +-------------------+
                                        |
                                claude-mem worker
                                  (port 37777)
                                        |
                              +-------------------+
                              | SQLite database   |
                              | ~/.claude-mem/    |
                              | claude-mem.db     |
                              +-------------------+

Development

# Install dependencies
bun install

# Run tests
bun test

# Type check
bunx tsc --noEmit

License

MIT