opencode-claude-mem
Quick Start •
How It Works •
Automatic Setup •
Search Tools •
Configuration •
Troubleshooting
Share persistent memory between Claude Code and OpenCode. This plugin connects to the same claude-mem worker, database, and memory store — context from Claude Code sessions appears in OpenCode, and vice versa. Install the plugin, and everything else happens automatically.
> **Note:** This project is not affiliated with the OpenCode team.
---
## Quick Start
Add one line to your `opencode.json`:
```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)
```bash
npm install @bloodf/opencode-claude-mem
```
Then in `opencode.json`:
```json
{
"plugin": ["@bloodf/opencode-claude-mem"]
}
```
### Interactive Installer (Recommended for new users)
```bash
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 ` — Specify a custom worker port (default: 37777)
### Local path
### Copy to plugins directory
```bash
cp -r node_modules/@bloodf/opencode-claude-mem .opencode/plugins/opencode-claude-mem
```
### Prerequisites
- [OpenCode](https://opencode.ai) 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:
```json
{
"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:
```bash
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 ` | Search persistent memory for past observations and context |
| `/mem-save ` | 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](#manual-mcp-configuration) and [Manual Skill Setup](#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
```bash
# Install dependencies
bun install
# Run tests
bun test
# Type check
bunx tsc --noEmit
```
---
## License
MIT
---
Powered by claude-mem • Built for OpenCode • Made with TypeScript