> ## Documentation Index
> Fetch the complete documentation index at: https://agent-memory.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode

> MCP wiring plus a 22-hook capture plugin with direct system prompt injection

OpenCode gets two layers: MCP wiring through `connect`, and a bundled capture plugin that observes the full session lifecycle and injects memory context directly into the system prompt.

## Setup

<Steps>
  <Step title="Start agentmemory">
    ```bash theme={"dark"}
    npx @agentmemory/agentmemory
    ```
  </Step>

  <Step title="Wire MCP">
    ```bash theme={"dark"}
    npx @agentmemory/agentmemory connect opencode
    ```

    The adapter detects `~/.config/opencode/`, backs up the config, writes the entry below, and verifies it after writing.
  </Step>

  <Step title="Install the capture plugin">
    Copy the bundled plugin and register it:

    ```bash theme={"dark"}
    mkdir -p ~/.config/opencode/plugins
    cp plugin/opencode/agentmemory-capture.ts ~/.config/opencode/plugins/
    ```

    ```json ~/.config/opencode/opencode.json theme={"dark"}
    {
      "plugin": ["./plugins/agentmemory-capture.ts"]
    }
    ```

    Optionally add the slash commands:

    ```bash theme={"dark"}
    mkdir -p ~/.config/opencode/commands
    cp plugin/opencode/commands/recall.md ~/.config/opencode/commands/
    cp plugin/opencode/commands/remember.md ~/.config/opencode/commands/
    ```
  </Step>

  <Step title="Restart OpenCode">
    Restart OpenCode or open a new session. The plugin auto-captures from the first turn.
  </Step>

  <Step title="Verify">
    Confirm the MCP server handshake first:

    ```bash theme={"dark"}
    opencode mcp list
    ```

    It should show `✓ agentmemory connected`. Then run one prompt, open `http://localhost:3113` and check the Sessions tab, or:

    ```bash theme={"dark"}
    curl -X POST http://localhost:3111/agentmemory/smart-search \
      -H 'Content-Type: application/json' \
      -d '{"query": "your prompt topic"}'
    ```
  </Step>
</Steps>

## What connect writes

OpenCode does not use the standard `mcpServers` envelope. Its config is a top-level `mcp` key whose entries carry `type`, `command` as an array, and `enabled`:

```json ~/.config/opencode/opencode.json theme={"dark"}
{
  "mcp": {
    "agentmemory": {
      "type": "local",
      "command": ["npx", "-y", "@agentmemory/mcp"],
      "enabled": true
    }
  }
}
```

<Note>
  The entry deliberately carries no `environment` block. OpenCode does not expand shell-style `${VAR:-default}` values, so writing them would override your real shell `AGENTMEMORY_URL` with an unexpanded literal. The stdio child inherits the shell environment, and the shim defaults unset vars (URL to `localhost:3111`, no secret, all tools).
</Note>

`connect` also writes a memory-usage guideline block into `~/.config/opencode/AGENTS.md` so the agent proactively calls the memory tools. Skip that with `--no-guidelines`.

## What the capture plugin does

The plugin registers 22 hooks over the OpenCode SDK, covering session lifecycle (`session.created`, `session.idle`, `session.compacted`, `session.deleted`, `session.error`), messages (`chat.message`, `message.updated`, `message.removed`), tool parts (`message.part.updated` for subtasks, tool completions, tool errors, reasoning, patches, retries), permissions, todos, executed commands, and model parameters. Everything posts to the REST API as observations.

Project attribution is per-session: one OpenCode process spanning several repositories files each session under its own project.

Instead of a memory file, OpenCode gets direct injection. `experimental.chat.system.transform` fires before every LLM call and pushes two layers into `output.system[]`:

1. Memory context from `POST /context`, fetched once per session on the first turn, together with agentmemory usage instructions.
2. File enrichment from `POST /enrich` on every file-touching turn, batching the files stashed by `tool.execute.before`, `file.edited`, and file parts.

There is no MEMORY.md intermediary, so context is never stale. The plugin calls the consolidation pipeline on `session.deleted`, mirroring Claude Code's `CONSOLIDATION_ENABLED=true` behavior.

Slash commands: `/recall <query>` searches past observations and lessons, `/remember <text>` saves an insight.

## Troubleshooting

<AccordionGroup>
  <Accordion title="Sessions appear but no context is injected">
    Injection runs through `experimental.chat.system.transform`. Confirm the plugin file is listed under the `plugin` key and the path is relative to the config directory. Restart OpenCode after any plugin edit; plugins load at startup.
  </Accordion>

  <Accordion title="Connection refused on port 3111">
    The agentmemory server is not running. Start it with `npx @agentmemory/agentmemory` and re-run the prompt; the plugin fails open, so the session continues without capture until the server is reachable.
  </Accordion>
</AccordionGroup>

Adapter source: `src/cli/connect/opencode.ts`. Plugin: `plugin/opencode/agentmemory-capture.ts`, full hook table in `plugin/opencode/README.md`.