Plan: OpenCode Memory Plugin (1:1 port)

Port the Claude Code demarkus-memory plugin (plugins/claude-code/) 1:1 to OpenCode (opencode.ai, sst/opencode), as plugins/opencode-memory/. Same behavior, same shared state, third harness adapter after Claude Code and pi.

Architecture stance

Identical to pi-memory: a thin TypeScript adapter over the shared demarkus-plugin Go binary, which owns all gate, nudge, guidance, provisioning, and registry logic. The adapter hands the binary normalized JSON (gate, nudge, guidance, provision, registry mcp add) and applies the result. No new binary subcommands and no --format opencode needed; the generic JSON contract pi uses is sufficient. Fails open when the binary is absent (pre-provisioning), matching the bash and pi adapters. Shares ~/.demarkus state, so all three plugins coexist on one machine: one soul, one token, one registry.

OpenCode extension surface (verified 2026-08-09)

Plugins: JS/TS in .opencode/plugins/ or ~/.config/opencode/plugins/, or npm packages listed under "plugin" in opencode.json (auto-installed via Bun). A plugin exports async ({ project, client, $, directory, worktree }) => Hooks.
Hooks (from @opencode-ai/plugin): config (receives the merged Config, mutable), event (bus: session.created, session.idle, ...), chat.message (mutable output.parts), tool.execute.before (throw to block), tool.execute.after (mutable output.output), permission.ask, custom tool map.
MCP: opencode.json "mcp" key, {type: "local", command: [...], environment, enabled}.
Commands: markdown in ~/.config/opencode/commands/ or the config "command" key; frontmatter description, template, $ARGUMENTS.
Skills: native; SKILL.md discovered from .opencode/skills/, ~/.config/opencode/skills/, and Claude-compatible ~/.claude/skills/ paths, surfaced via a skill tool.

Behavior mapping (Claude Code → OpenCode)

Claude Code hook	OpenCode
`SessionStart` provisioning	plugin init function on load: `bootstrap.sh` then `demarkus-plugin provision` (async, warn on failure)
`SessionStart` guidance injection	`chat.message`: append guidance part on first message of a session (per-session flag; retry next turn if binary unavailable, as pi does)
`UserPromptSubmit` recall-nudge	`chat.message`: `demarkus-plugin nudge --event recall` on the prompt text, append part
`PreToolUse` publish/dest gate (deny)	`tool.execute.before` on `mark_publish`/`mark_append`: `demarkus-plugin gate`; `block` → `throw new Error(reason)`
gate `ask` strictness	no native ask in `tool.execute.before`; block with reason instructing agent to confirm with the user first (same compromise as pi)
`PostToolUse` gate warn	`tool.execute.after`: append gate warning to `output.output`
`PostToolUse` promote-nudge	`tool.execute.after` on `mark_publish`: `nudge --event promote`, append
`Stop` journal-nudge	`event` hook on `session.idle`: `nudge --event session-end` with changed-files / soul-write signals tracked in-process (port pi's `SessionActivity`); surface via toast (`client`) since no extra turn can be forced
`.mcp.json` bundled MCP server	`config` hook: set `config.mcp["demarkus-memory"] = {type: "local", command: [BIN, "mcp-serve"], enabled: true}`; remote souls keep registering via `demarkus-plugin registry mcp add`
`commands/*.md` slash commands	`config` hook: populate `config.command` from the bundled `commands/*.md` bodies (frontmatter description + body as template), so nothing is copied into the user's config dir
`skills/soul-memory/SKILL.md`	ships in package; provision symlinks/copies it into `~/.config/opencode/skills/soul-memory/` (Claude-path discovery already covers machines with the Claude plugin installed, but don't rely on it)

MCP tool names on OpenCode are servername_toolname style rather than mcp__server__tool; the gate matcher must accept both (regex on mark_(publish|append)$ suffix, as pi's normalizer does).

Layout

plugins/opencode-memory/
  package.json          # npm: opencode-demarkus-memory (opencode-* convention)
  tsconfig.json
  src/index.ts          # adapter: hooks per mapping table
  src/plugin.ts         # runBin/callGate/callNudge/callGuidance — copy from pi-memory
  src/nudges.ts         # SessionActivity — copy from pi-memory
  scripts/bootstrap.sh  # reused verbatim from claude-code plugin
  commands/*.md         # reused; frontmatter converted (allowed-tools dropped, template = body)
  skills/soul-memory/   # reused verbatim
  context/session-guidance.md  # reused verbatim
  README.md, CHANGELOG.md

Steps

Branch (git switch -c opencode-memory-plugin).
Scaffold plugins/opencode-memory/ per layout; copy src/plugin.ts + src/nudges.ts from pi-memory, scripts/bootstrap.sh + commands/ + skills/ + context/ from claude-code.
Write src/index.ts against @opencode-ai/plugin types implementing the mapping table.
Command frontmatter conversion: keep description, drop allowed-tools, body becomes template; resolve ${DEMARKUS_SCRIPTS} to the bundled scripts dir at load (pi's commandBody pattern).
Skill install step in provision path (idempotent copy into ~/.config/opencode/skills/).
Tests where pi-memory has them; bash pre-commit.sh.
README with behavior-mapping table and install instructions; version starts at the current plugin line (0.13.x) to keep the pin-bump convention (SERVER/CLIENT/TOOLS_VERSION move with every change).
Distribution: extend the pi mirror flow (setup-pi-repos.sh + pi-plugin-mirror.yml) or npm-publish; see open questions.
Roadmap + index updates; journal.

Open questions (for Fritz)

Distribution: npm publish (opencode-demarkus-memory, cleanest for OpenCode's "plugin" key + ecosystem registry) vs standalone-repo mirror like pi. npm implies a publish pipeline the repo doesn't have yet.
Commands via config hook vs file install: config-hook injection is clean (no user-dir pollution) but depends on the command config shape accepting full template bodies; verify against a live OpenCode before committing. Fallback: idempotent copy into ~/.config/opencode/commands/.
Scope: memory plugin only; claude-code-knowledge port is a follow-up plan once this lands (same adapter, --surface knowledge).

Risks

config hook mutation semantics (MCP + command registration) are the least-documented part of the surface; prototype first, fall back to registry-file writes via demarkus-plugin registry mcp add if config mutation doesn't persist.
session.idle fires more often than Claude's Stop; the session-end nudge needs a once-per-session guard (sentinel, as the bash Stop hook has).
OpenCode runs plugins under Bun; keep to node: APIs that Bun supports (execFile is fine, pi code carries over unchanged).