OpenCode

OpenCode gets two layers: MCP wiring through connect, and a bundled capture plugin that observes the full session lifecycle and injects memory context directly into the system prompt.

Setup

Start agentmemory

npx @agentmemory/agentmemory

Wire MCP

npx @agentmemory/agentmemory connect opencode

The adapter detects ~/.config/opencode/, backs up the config, writes the entry below, and verifies it after writing.

Install the capture plugin

Copy the bundled plugin and register it:

mkdir -p ~/.config/opencode/plugins
cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/

~/.config/opencode/opencode.json

{
  "plugin": ["./plugins/agentmemory-capture.ts"]
}

Optionally add the slash commands:

mkdir -p ~/.config/opencode/commands
cp plugin/opencode/commands/recall.md ~/.config/opencode/commands/
cp plugin/opencode/commands/remember.md ~/.config/opencode/commands/

Restart OpenCode

Restart OpenCode or open a new session. The plugin auto-captures from the first turn.

Verify

Confirm the MCP server handshake first:

opencode mcp list

It should show ✓ agentmemory connected. Then run one prompt, open http://localhost:3113 and check the Sessions tab, or:

curl -X POST http://localhost:3111/agentmemory/smart-search \
  -H 'Content-Type: application/json' \
  -d '{"query": "your prompt topic"}'

What connect writes

OpenCode does not use the standard mcpServers envelope. Its config is a top-level mcp key whose entries carry type, command as an array, and enabled:

~/.config/opencode/opencode.json

{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  }
}

The entry deliberately carries no environment block. OpenCode does not expand shell-style ${VAR:-default} values, so writing them would override your real shell AGENTMEMORY_URL with an unexpanded literal. The stdio child inherits the shell environment, and the shim defaults unset vars (URL to localhost:3111, no secret, all tools).

connect also writes a memory-usage guideline block into ~/.config/opencode/AGENTS.md so the agent proactively calls the memory tools. Skip that with --no-guidelines.

What the capture plugin does

The plugin registers 22 hooks over the OpenCode SDK, covering session lifecycle (session.created, session.idle, session.compacted, session.deleted, session.error), messages (chat.message, message.updated, message.removed), tool parts (message.part.updated for subtasks, tool completions, tool errors, reasoning, patches, retries), permissions, todos, executed commands, and model parameters. Everything posts to the REST API as observations. Project attribution is per-session: one OpenCode process spanning several repositories files each session under its own project. Instead of a memory file, OpenCode gets direct injection. experimental.chat.system.transform fires before every LLM call and pushes two layers into output.system[]:

Memory context from POST /context, fetched once per session on the first turn, together with agentmemory usage instructions.
File enrichment from POST /enrich on every file-touching turn, batching the files stashed by tool.execute.before, file.edited, and file parts.

There is no MEMORY.md intermediary, so context is never stale. The plugin calls the consolidation pipeline on session.deleted, mirroring Claude Code’s CONSOLIDATION_ENABLED=true behavior. Slash commands: /recall <query> searches past observations and lessons, /remember <text> saves an insight.

Troubleshooting

Sessions appear but no context is injected

Injection runs through experimental.chat.system.transform. Confirm the plugin file is listed under the plugin key and the path is relative to the config directory. Restart OpenCode after any plugin edit; plugins load at startup.

Connection refused on port 3111

The agentmemory server is not running. Start it with npx @agentmemory/agentmemory and re-run the prompt; the plugin fails open, so the session continues without capture until the server is reachable.

Adapter source: src/cli/connect/opencode.ts. Plugin: plugin/opencode/agentmemory-capture.ts, full hook table in plugin/opencode/README.md.

Get started

Concepts

Connect

Integrations

Workflows

Setup

What connect writes

What the capture plugin does

Troubleshooting

​Setup

​What connect writes

​What the capture plugin does

​Troubleshooting

Setup

What connect writes

What the capture plugin does

Troubleshooting