OpenCode

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.

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:

exportHINDSIGHT_API_URL="http://localhost:8888"
opencode

Using Hindsight Cloud​

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

exportHINDSIGHT_API_URL="https://api.hindsight.vectorize.io"
exportHINDSIGHT_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:

exportHINDSIGHT_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):

exportHINDSIGHT_CHANNEL_ID="slack-general"
exportHINDSIGHT_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