OpenCode Memory Plugin

This package is a local/project-installable OpenCode plugin for Agent Memory Platform. It calls the shared memory-agent-gateway HTTP contracts directly, so lifecycle context injection does not depend on the MCP server being loaded.

The install experience has two parts:

1. Install the plugin so OpenCode can expose memory tools and optional bounded context hooks.
2. Install the bundled agent-memory skill so every OpenCode agent gets durable instructions for when and how to use memory.

The plugin never silently mutates global OpenCode config. Install the plugin and skill project-locally or globally by editing the intended OpenCode config yourself.

Safe Defaults

• injectionMode: manual by default; auto-readonly opt-in injects bounded context.
• saveMode: review-queue by default; automatic active-memory writes are not performed.
• captureToolMetadata: false by default; when enabled, only redacted metadata is captured.
• strategy: deterministic by default; set agentic only to explicitly opt into the chat-agent gateway.
• memory requires write_gate_confirmed=true and delegates to /v1/save-memory without LLM extraction by default.
• Expert MCP tools such as find, find2, graph tools, and raw session reads are fallback/diagnostic tools; normal agents should use the short aliases first.

Local Project Install

Use a project-local OpenCode config entry that points at this package path. Example shape:

{
  "plugin": ["./apps/opencode-memory-plugin"]
}

Install the bundled skill project-locally by copying or symlinking apps/opencode-memory-plugin/skill/agent-memory into the project's OpenCode skill directory, for example .opencode/skill/agent-memory. Keep the path under the project when you want repo-specific rollout and review.

Global Install

For global plugin installation, copy or package this directory and reference it from the user's global OpenCode config. For global skill installation, copy apps/opencode-memory-plugin/skill/agent-memory into the user's global OpenCode skill directory, for example ~/.config/opencode/skills/agent-memory.

Do not automate global config edits from this package. Make global changes only as an explicit user action so teams can review the plugin path, gateway URL, and skill instructions.

Configuration

{
  "gatewayUrl": "http://localhost:8080",
  "authHeaderEnv": "AMP_MEMORY_AUTH_HEADER",
  "projectScopeMode": "workspace",
  "maxContextChars": 4000,
  "injectionMode": "manual",
  "saveMode": "review-queue",
  "telemetryMode": "enabled",
  "redactionMode": "strict",
  "captureToolMetadata": false,
  "injectRuleReminders": true,
  "strategy": "deterministic"
}

Hooks And Tools

Hooks implemented: session.created, tui.prompt.append, message.updated, session.compacted, session.idle, tool.execute.before, tool.execute.after, and shell.env.

Primary normal-agent tools:

• context: read-only bounded context; call at session start unless plugin auto-context is fresh.
• recall: focused retrieval before unfamiliar, risky, cross-repo, infrastructure, integration, architecture, or debugging work.
• memory: explicit durable save after the Write Gate only.
• review: review proposed inferred facts before they become default-retrievable memory.
• whoAmI: inspect non-secret capabilities and safety policy.
• listProjects: inspect or derive project/container scopes.

The plugin intentionally avoids dotted tool names such as memory.context, because OpenAI-compatible tool calling requires names that match ^[a-zA-Z0-9_-]+$.

Bundled Skill

The bundled skill lives at skill/agent-memory/SKILL.md and has frontmatter name agent-memory. Its instructions are directive: use context and recall, save with memory only after the Write Gate, review inferred facts with review, never store secrets/raw transcripts/tool payloads, default to deterministic strategy, and reserve expert tools for fallback or diagnostics.