feat: add OpenCode persistent memory plugin

.github/workflows/test.yml

@@ -45,6 +45,7 @@ jobs:
       integrations-ag2: ${{ steps.filter.outputs.integrations-ag2 }}
       integrations-hermes: ${{ steps.filter.outputs.integrations-hermes }}
       integrations-llamaindex: ${{ steps.filter.outputs.integrations-llamaindex }}
+      integrations-opencode: ${{ steps.filter.outputs.integrations-opencode }}
       dev: ${{ steps.filter.outputs.dev }}
       ci: ${{ steps.filter.outputs.ci }}
       # Secrets are available for internal PRs, pull_request_review, and workflow_dispatch.
@@ -117,6 +118,8 @@ jobs:
             - 'hindsight-integrations/hermes/**'
           integrations-llamaindex:
             - 'hindsight-integrations/llamaindex/**'
+          integrations-opencode:
+            - 'hindsight-integrations/opencode/**'
           dev:
             - 'hindsight-dev/**'
           ci:
@@ -326,6 +329,37 @@ jobs:
       working-directory: ./hindsight-integrations/ai-sdk
       run: npm run test:deno
 
+  build-opencode-integration:
+    needs: [detect-changes]
+    if: >-
+      github.event_name != 'pull_request_review' &&
+      (github.event_name == 'workflow_dispatch' ||
+      needs.detect-changes.outputs.integrations-opencode == 'true' ||
+      needs.detect-changes.outputs.ci == 'true')
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v6
+      with:
+        ref: ${{ github.event.pull_request.head.sha || '' }}
+
+    - name: Set up Node.js
+      uses: actions/setup-node@v6
+      with:
+        node-version: '22'
+
+    - name: Install dependencies
+      working-directory: ./hindsight-integrations/opencode
+      run: npm ci
+
+    - name: Run tests
+      working-directory: ./hindsight-integrations/opencode
+      run: npm test
+
+    - name: Build
+      working-directory: ./hindsight-integrations/opencode
+      run: npm run build
+
   build-chat-integration:
     needs: [detect-changes]
     if: >-
@@ -2427,6 +2461,7 @@ jobs:
       - test-codex-integration
       - build-ai-sdk-integration
       - test-ai-sdk-integration-deno
+      - build-opencode-integration
       - build-chat-integration
       - build-control-plane
       - build-docs

hindsight-docs/docs-integrations/opencode.md

@@ -0,0 +1,141 @@
+---
+sidebar_position: 20
+title: "OpenCode Persistent Memory with Hindsight | Integration"
+description: "Add long-term memory to OpenCode with Hindsight. Automatically captures conversations and recalls relevant context across coding sessions."
+---
+
+# OpenCode
+
+Persistent long-term memory plugin for [OpenCode](https://opencode.ai) using [Hindsight](https://vectorize.io/hindsight). Automatically captures conversations, recalls relevant context on session start, and provides retain/recall/reflect tools the agent can call directly.
+
+## Quick Start
+
+```bash
+# 1. Install the plugin
+npm install @vectorize-io/opencode-hindsight
+```
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["@vectorize-io/opencode-hindsight"]
+}
+```
+
+```bash
+# 2. Configure your Hindsight server
+export HINDSIGHT_API_URL="http://localhost:8888"
+
+# Optional: API key for Hindsight Cloud
+export HINDSIGHT_API_TOKEN="your-api-key"
+
+# 3. Start OpenCode — the plugin activates automatically
+opencode
+```
+
+## Features
+
+### Custom Tools
+
+The plugin registers three tools the agent can call explicitly:
+
+| Tool | Description |
+|---|---|
+| `hindsight_retain` | Store information in long-term memory |
+| `hindsight_recall` | Search long-term memory for relevant information |
+| `hindsight_reflect` | Generate a synthesized answer from long-term memory |
+
+### 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
+
+```json
+{
+  "plugin": [
+    ["@vectorize-io/opencode-hindsight", {
+      "hindsightApiUrl": "http://localhost:8888",
+      "hindsightApiToken": "your-api-key",
+      "bankId": "my-project",
+      "autoRecall": true,
+      "autoRetain": true,
+      "recallBudget": "mid",
+      "retainEveryNTurns": 10,
+      "debug": false
+    }]
+  ]
+}
+```
+
+### Config File
+
+Create `~/.hindsight/opencode.json` for persistent configuration that applies across all projects:
+
+```json
+{
+  "hindsightApiUrl": "http://localhost:8888",
+  "hindsightApiToken": "your-api-key",
+  "recallBudget": "mid"
+}
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `HINDSIGHT_API_URL` | Hindsight API base URL | *(required)* |
+| `HINDSIGHT_API_TOKEN` | API key for authentication | |
+| `HINDSIGHT_BANK_ID` | Static memory bank ID | `opencode` |
+| `HINDSIGHT_AGENT_NAME` | Agent name for dynamic bank IDs | `opencode` |
+| `HINDSIGHT_AUTO_RECALL` | Auto-recall on session start | `true` |
+| `HINDSIGHT_AUTO_RETAIN` | Auto-retain on session idle | `true` |
+| `HINDSIGHT_RETAIN_MODE` | `full-session` or `last-turn` | `full-session` |
+| `HINDSIGHT_RECALL_BUDGET` | Recall budget: `low`, `mid`, `high` | `mid` |
+| `HINDSIGHT_RECALL_MAX_TOKENS` | Max tokens for recall results | `1024` |
+| `HINDSIGHT_DYNAMIC_BANK_ID` | Enable dynamic bank ID derivation | `false` |
+| `HINDSIGHT_BANK_MISSION` | Bank mission/context for reflect | |
+| `HINDSIGHT_DEBUG` | Enable debug logging to stderr | `false` |
+
+Configuration priority (later wins): defaults < `~/.hindsight/opencode.json` < plugin options < env vars.
+
+## Dynamic Bank IDs
+
+For multi-project isolation, enable dynamic bank ID derivation:
+
+```bash
+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):
+
+```bash
+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

hindsight-docs/src/data/integrations.json

@@ -180,6 +180,16 @@
       "link": "/sdks/integrations/autogen",
       "icon": "/img/icons/autogen.svg"
     },
+    {
+      "id": "opencode",
+      "name": "OpenCode",
+      "description": "Persistent long-term memory plugin for OpenCode. Auto-retains conversations, recalls context on session start, and provides retain/recall/reflect tools.",
+      "type": "official",
+      "by": "hindsight",
+      "category": "tool",
+      "link": "/sdks/integrations/opencode",
+      "icon": "/img/icons/opencode.svg"
+    },
     {
       "id": "hindclaw",
       "name": "HindClaw",

hindsight-integrations/opencode/README.md

@@ -0,0 +1,144 @@
+# @vectorize-io/opencode-hindsight
+
+Hindsight memory plugin for [OpenCode](https://opencode.ai) — give your AI coding agent persistent long-term memory across sessions.
+
+## Features
+
+- **Custom tools**: `hindsight_retain`, `hindsight_recall`, `hindsight_reflect` — the agent calls these explicitly
+- **Auto-retain**: Captures conversation on `session.idle` and stores to Hindsight
+- **Memory injection**: Recalls relevant memories when a new session starts
+- **Compaction hook**: Injects memories during context compaction so they survive window trimming
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @vectorize-io/opencode-hindsight
+```
+
+### 2. Configure
+
+Add to your `opencode.json`:
+
+```json
+{
+  "plugin": ["@vectorize-io/opencode-hindsight"]
+}
+```
+
+### 3. Set Environment Variables
+
+```bash
+# Required: Hindsight API URL
+export HINDSIGHT_API_URL="http://localhost:8888"
+
+# Optional: API key for Hindsight Cloud
+export HINDSIGHT_API_TOKEN="your-api-key"
+
+# Optional: Override the memory bank ID
+export HINDSIGHT_BANK_ID="my-project"
+```
+
+## Configuration
+
+### Plugin Options
+
+Pass options directly in `opencode.json`:
+
+```json
+{
+  "plugin": [
+    ["@vectorize-io/opencode-hindsight", {
+      "hindsightApiUrl": "http://localhost:8888",
+      "bankId": "my-project",
+      "autoRecall": true,
+      "autoRetain": true,
+      "recallBudget": "mid"
+    }]
+  ]
+}
+```
+
+### Config File
+
+Create `~/.hindsight/opencode.json` for persistent configuration:
+
+```json
+{
+  "hindsightApiUrl": "http://localhost:8888",
+  "hindsightApiToken": "your-api-key",
+  "recallBudget": "mid",
+  "retainEveryNTurns": 10,
+  "debug": false
+}
+```
+
+### Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `HINDSIGHT_API_URL` | Hindsight API base URL | (required) |
+| `HINDSIGHT_API_TOKEN` | API key for authentication | (none) |
+| `HINDSIGHT_BANK_ID` | Static memory bank ID | `opencode` |
+| `HINDSIGHT_AGENT_NAME` | Agent name for dynamic bank IDs | `opencode` |
+| `HINDSIGHT_AUTO_RECALL` | Auto-recall on session start | `true` |
+| `HINDSIGHT_AUTO_RETAIN` | Auto-retain on session idle | `true` |
+| `HINDSIGHT_RETAIN_MODE` | `full-session` or `last-turn` | `full-session` |
+| `HINDSIGHT_RECALL_BUDGET` | Recall budget: `low`, `mid`, `high` | `mid` |
+| `HINDSIGHT_RECALL_MAX_TOKENS` | Max tokens for recall results | `1024` |
+| `HINDSIGHT_DYNAMIC_BANK_ID` | Enable dynamic bank ID derivation | `false` |
+| `HINDSIGHT_BANK_MISSION` | Bank mission/context | (none) |
+| `HINDSIGHT_DEBUG` | Enable debug logging | `false` |
+
+### Configuration Priority
+
+Settings are loaded in this order (later wins):
+
+1. Built-in defaults
+2. `~/.hindsight/opencode.json`
+3. Plugin options from `opencode.json`
+4. Environment variables
+
+## Tools
+
+### `hindsight_retain`
+
+Store information in long-term memory. The agent uses this to save important facts, user preferences, project context, and decisions.
+
+### `hindsight_recall`
+
+Search long-term memory. The agent uses this proactively before answering questions where prior context would help.
+
+### `hindsight_reflect`
+
+Generate a synthesized answer from long-term memory. Unlike recall (raw memories), reflect produces a coherent summary.
+
+## Dynamic Bank IDs
+
+For multi-project setups, enable dynamic bank ID derivation:
+
+```bash
+export HINDSIGHT_DYNAMIC_BANK_ID=true
+```
+
+The bank ID is composed from granularity fields (default: `agent::project`). Supported fields: `agent`, `project`, `channel`, `user`.
+
+**Note:** The bank ID is derived once when the plugin loads, from environment variables set before OpenCode starts. These dimensions are process-scoped — they don't change per session within a running OpenCode process. For per-user isolation, set the env vars before launching each user's OpenCode instance:
+
+```bash
+export HINDSIGHT_CHANNEL_ID="slack-general"
+export HINDSIGHT_USER_ID="user123"
+```
+
+## Development
+
+```bash
+npm install
+npm test        # Run tests
+npm run build   # Build to dist/
+```
+
+## License
+
+MIT