Getting Started

For OpenCode v2, add the package to the native plugins list:

{
  "plugins": ["opencode-mem@latest"],
}

OpenCode also loads the package’s ./tui companion automatically so auto-capture / profile / error toasts render in the TUI (server plugins cannot call ui.toast directly). You do not need a second entry in plugins. If you run a CLI-only TUI against a remote OpenCode server, register opencode-mem/tui in that CLI’s plugin list (for example cli.json) so the companion can subscribe to toast RPC events.

For OpenCode v1, add the default entrypoint to your configuration at ~/.config/opencode/opencode.json:

{
  "plugin": ["opencode-mem@latest"],
}

With @latest (or a semver range) and autoUpdate: true in opencode-mem.jsonc (default), the plugin clears OpenCode’s cached install when a newer npm release is available and asks you to restart. Pinned versions like opencode-mem@2.26.0 are never auto-updated.

Automatic memory context on OpenCode v2

The v2 plugin supplies automatic memory context through the model’s system context. These blocks are not added to the authored user prompt or stored in the chat transcript. With chatMessage.injectOn: "first" (the default), the session’s initial context is retained across user turns and model steps. With "always", it is refreshed on each authored user turn.

After a host or plugin restart, a resumed session rebuilds its context from the current memory store on its next model request, even if no new user prompt arrives. The rebuilt context may differ from the original as memories and the profile evolve. Restoration does not capture a synthetic user prompt or store a second copy of the memory text in OpenCode plugin storage. Compaction invalidates the cached automatic context; the existing compaction-memory restoration also continues to run.