/hindsight-docs

OpenCode

⚠️ Superseded by the Coding Agents plugin

The opencode plugin is superseded by the Coding Agents plugin — one package covering Claude Code, Codex, opencode, Kilo, Cursor, Copilot, Grok, Antigravity, Devin and Cline and other CLI agents, with a per-repo memory bank they all share instead of one bank per agent.

This page and the published package still work; they are no longer developed. To switch:

cd /path/to/your/repo
npx @vectorize-io/hindsight-coding-agents install opencode

Memory does not move automatically — the banks are scoped differently and this agent's history cannot be imported (it is kept in an internal database). See Migrating from the per-agent plugins. Persistent long-term memory plugin for OpenCode using Hindsight. Automatically captures conversations, recalls relevant context on session start, and provides retain/recall/reflect tools the agent can call directly.

View Changelog →

Quick Start

Add to your opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@vectorize-io/opencode-hindsight"]
}

OpenCode auto-installs plugins in the "plugin" array on startup — no npm install required.

Point the plugin at your Hindsight server and start OpenCode:

export HINDSIGHT_API_URL="http://localhost:8888"
opencode

Using Hindsight Cloud

Get an API key at ui.hindsight.vectorize.io/connect:

export HINDSIGHT_API_URL="https://api.hindsight.vectorize.io"
export HINDSIGHT_API_TOKEN="your-api-key"
opencode

Or configure inline via plugin options in opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": [
    ["@vectorize-io/opencode-hindsight", {
      "hindsightApiUrl": "https://api.hindsight.vectorize.io",
      "hindsightApiToken": "your-api-key"
    }]
  ]
}

Features

Custom Tools

The plugin registers three tools the agent can call explicitly:

Auto-Retain

When the session goes idle (session.idle event), the plugin automatically retains the conversation transcript to Hindsight. Configurable via retainEveryNTurns to control frequency.

Session Recall

When a new session starts, the plugin recalls relevant project context and injects it into the system prompt, giving the agent access to memories from prior sessions.

Compaction Hook

When OpenCode compacts the context window, the plugin:

1. Retains the current conversation before compaction
2. Recalls relevant memories and injects them into the compaction context

This ensures memories survive context window trimming.

Configuration

Plugin Options

{
  "plugin": [
    ["@vectorize-io/opencode-hindsight", {
      "hindsightApiUrl": "http://localhost:8888",
      "hindsightApiToken": "your-api-key",
      "bankId": "my-project",
      "autoRecall": true,
      "autoRetain": true,
      "recallBudget": "mid",
      "recallTags": [],
      "recallTagsMatch": "any",
      "retainTags": [],
      "retainEveryNTurns": 3,
      "debug": false
    }]
  ]
}

Config File

Create ~/.hindsight/opencode.json for persistent configuration that applies across all projects:

{
  "hindsightApiUrl": "http://localhost:8888",
  "hindsightApiToken": "your-api-key",
  "recallBudget": "mid"
}

Environment Variables

Configuration priority (later wins): defaults < ~/.hindsight/opencode.json < plugin options < env vars.

Logging & debugging

The plugin logs through OpenCode's own log stream (service=hindsight), visible with opencode --print-logs or in the OpenCode log files. Errors (failed retain/recall, unreachable API, auth problems) and the resolved API URL + bank are logged by default — so if memories aren't saving, the reason is visible without any opt-in.

Verbose tracing is controlled by the debug option, which is config-only (set "debug": true in opencode.json plugin options or ~/.hindsight/opencode.json). There is intentionally no HINDSIGHT_DEBUG environment variable: env vars are unreliable to set for OpenCode's plugin runtime (notably on Windows, where a persistent OpenCode server may never see them).

{
  "plugin": [["@vectorize-io/opencode-hindsight", { "debug": true }]]
}

Dynamic Bank IDs

For multi-project isolation, enable dynamic bank ID derivation:

export HINDSIGHT_DYNAMIC_BANK_ID=true

The bank ID is composed from granularity fields (default: agent::project). Supported fields: agent, project, channel, user.

For multi-user scenarios (e.g., shared agent serving multiple users):

export HINDSIGHT_CHANNEL_ID="slack-general"
export HINDSIGHT_USER_ID="user123"

How It Works

1. Plugin loads when OpenCode starts — creates a HindsightClient, derives the bank ID, and registers tools + hooks
2. Session starts — session.created event triggers, plugin marks session for recall injection
3. System transform — on the first LLM call, recalled memories are injected into the system prompt
4. Agent works — can call hindsight_recall and hindsight_retain explicitly during the session
5. Session idles — session.idle event triggers auto-retain of the conversation
6. Compaction — if the context window fills up, memories are preserved through the compaction