mem9 · OpenCode 2 Plugin

Persistent, cloud-backed AI agent memory for OpenCode 2. A V2 port of the mem9 OpenCode plugin, published as @fimars/mem9-oc2.

Origin

The original mem9 plugin for OpenCode V1 lives in the upstream mem9 repository under opencode-plugin/. It used the V1 plugin API (@opencode-ai/[email protected]) with server hooks (chat.message, experimental.chat.*, experimental.session.compacting) and a V1 TUI entrypoint (/mem9-setup).

OpenCode V2 broke the plugin API on purpose, so the plugin was migrated here:

• one module (Plugin.define({ id, setup })) that adapts to the runtime context — the background server (recall, auto-ingest, tools) and the TUI (/mem9-setup);
• recall via session.hook("context"), ingest via the session.idle / session.compaction.started events;
• tools exposed directly to the model (codemode: false) with JSON Schema output;
• a promise-based TUI setup flow.

Install

Give this to your OpenCode assistant (or run it yourself):

Install the mem9 OpenCode 2 memory plugin: add @fimars/mem9-oc2 to the plugins array in ~/.config/opencode/opencode.json, restart opencode2, then run /mem9-setup in the TUI to connect a mem9 API key.

Or manually:

opencode2 plugin add @fimars/mem9-oc2   # or add to ~/.config/opencode/opencode.json
opencode2                               # restart, then run /mem9-setup

/mem9-setup walks you through creating or pasting a mem9 API key and saving it to ~/.mem9/.credentials.json.

Project overrides (optional)

Add <project>/.opencode/mem9.json to override the profile, debug flag, or timeouts per repository:

{
  "schemaVersion": 1,
  "profileId": "default",
  "debug": false,
  "defaultTimeoutMs": 8000,
  "searchTimeoutMs": 15000
}

What it does

Server: recalls relevant memories before each turn and injects a <relevant-memories> block into the system prompt; registers memory_store, memory_search, memory_get, memory_update, memory_delete; ingests transcripts in the background on session.idle and session.compaction.started.

TUI: registers the /mem9-setup slash command.

Data & config locations

• Credentials: $MEM9_HOME/.credentials.json (default ~/.mem9)
• Global config: ~/.config/opencode/mem9.json
• Project override: <project>/.opencode/mem9.json
• Debug logs: ~/.local/share/opencode/plugins/mem9/log/YYYY-MM-DD.jsonl

Env overrides at runtime: MEM9_API_KEY, MEM9_API_URL, MEM9_DEBUG, MEM9_HOME, MEM9_TENANT_ID (legacy alias for the API key).

Differences from the V1 plugin

• V2 plugin API (@opencode-ai/plugin@next).
• Single module serves server and TUI; setup branches on context capabilities.
• Tools are direct provider tools (codemode: false) with JSON Schema output.
• No V2 equivalent for experimental.session.compacting; ingest now triggers from the session.compaction.started event and the compaction hint is not injected.
• Ingest transcripts come from the context hook instead of a client.session.messages() fetch.

Development

pnpm install
pnpm run typecheck   # tsc --noEmit
pnpm run test        # tsc -p tsconfig.test.json && node --test dist-test/tests

The repo-root opencode.json registers ./src/index.ts as a local plugin, so you can develop and test in this directory with opencode2 directly.