OpenCode integration¶

The OpenCode integration is a plugin that loads MemCastle's wake-up context when a session starts, reminds the model to search before it answers, and checkpoints the conversation, and can audit the palace. One plugin serves OpenCode 1 and OpenCode 2. It is installed with memcastle integration; this page is what is specific to OpenCode.

Requirements¶

• OpenCode 1.18.29 or later (2.x included), with the opencode command on your PATH. The installer runs opencode --version and refuses an older release, naming the version it found.
• MemCastle 0.4 or later with plugin installation support.
• A running daemon when you use OpenCode, not when you install: the plugin connects lazily and OpenCode starts normally without one.

Install, update, remove¶

memcastle plugin install /path/to/opencode-0.1.0.tar.gz --consent opencode=SHA256_FROM_PREVIEW
memcastle integration install opencode
memcastle integration update opencode
memcastle integration remove opencode

Build the archive from memcastle-opencode until an independent release is available. If the preview reports previously mined legacy OpenCode history, also pass --adopt-source opencode after reviewing the source identity; --consent must match the digest shown for this release's permissions.

Restart OpenCode after each, because it loads plugins when it starts. Integrations describes what each command does and checks. The source and integration have separate lifecycles under one plugin archive; the installed integration ID and agent configuration remain opencode.

What it changes¶

OpenCode loads every file in its plugins/ directory, so the shim is the whole registration: MemCastle does not open opencode.json, and every setting and other plugin you have is untouched. OPENCODE_CONFIG_DIR and XDG_CONFIG_HOME move the directory, as they do for OpenCode. The shim carries a comment saying MemCastle wrote it. remove deletes the file only if that comment is there, and install refuses to overwrite a memcastle.ts without it (conflict), so a plugin of your own with that name is safe.

The five MemCastle skills come with the integration, so no separate skill installation follows. The plugin adds the skills/ directory beside it to OpenCode's skill paths, so they show in OpenCode's skill tool, and it adds none in an off session. A skill of your own with the same name wins.

Do not also add mcp.memcastle to opencode.json. The plugin opens its own MCP connection for each session, so that a session's memory mode is its own, and a second entry would show the model every tool twice.

Auditing the palace¶

/memcastle-audit [wing] runs MemCastle's read-only audit, shows what it found and plans the repair as a dry run. It changes nothing. OpenCode has no dialog a plugin can ask a question with, so the confirmation is a second command: /memcastle-repair applies the plan this session was just shown, once, and then writes a before and after summary to the diary. Without a plan from the same session it refuses, and a read-only session is shown the plan and never able to apply it. The same two steps exist as the memcastle_palace_audit and memcastle_palace_repair tools.

Configuration¶

The installed plugin is configured through the environment of the opencode process. A default setup needs none. The ones you are most likely to set:

MEMCASTLE_MODE takes this integration's labels (full, read-only, off), which are not the daemon's (full, read_only, disabled). The complete list is in the plugin's integration guide.

The plugin also accepts options, which win over the environment, but only when it is listed in opencode.json's plugin (OpenCode 1) or plugins (OpenCode 2) list, and MemCastle does not edit that file. To use options, point that entry at ~/.local/share/memcastle/agents/opencode/index.js, and remove the shim with rm ~/.config/opencode/plugins/memcastle.ts so the plugin is not loaded twice; memcastle integration update opencode writes the shim again, so prefer the environment when you can.

Troubleshooting¶

• Nothing happens in OpenCode. Run memcastle integration list: the STATE must be installed. Then check that the daemon is running (memcastle status) and that OpenCode was restarted.
• conflict. A plugins/memcastle.ts that MemCastle did not write is in the way. Move it aside, or rename it, and install again.
• The checkpoint tool is missing. The plugin imports OpenCode's tool helper from @opencode-ai/plugin at load time and logs when it cannot; every other feature keeps working.
• Other failures. See the troubleshooting table.