Add OpenCode integration and adoption plan

2026-06-22 21:28:08 +02:00 · 2026-06-08 13:12:06 -05:00 · 2026-06-08 13:12:06 -05:00 · 575d02a6f5
commit 575d02a6f5
parent 6324bb7a24
20 changed files with 508 additions and 25 deletions
--- a/docs/AGENT-MEMORY-PROTOCOL.md
+++ b/docs/AGENT-MEMORY-PROTOCOL.md
@ -76,6 +76,6 @@ call `memory` with `action="purge"` and `confirm=true`.
 ## Portability Notes

 The same protocol applies to Claude Code, Codex, Cursor, VS Code, Xcode,
-JetBrains, Windsurf, and any other client that can run a stdio MCP server. Claude
+OpenCode, JetBrains, Windsurf, and any other client that can run a stdio MCP server. Claude
 Code's Cognitive Sandwich hooks are optional companion files; they are not
 required for normal Vestige memory.
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@ -141,6 +141,40 @@ Add to `%APPDATA%\Claude\claude_desktop_config.json`:
 }
 ```

+### OpenCode
+
+OpenCode supports global and project-local config. For a project-local setup, add to `opencode.json`:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["vestige-mcp"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}
+```
+
+For isolated per-project memory, pass the data directory in the command array:
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["vestige-mcp", "--data-dir", "./.vestige"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}
+```
+
+See the [OpenCode integration guide](integrations/opencode.md) for global config, verification, and troubleshooting.
+
 ---

 ## Custom Data Directory
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@ -45,7 +45,7 @@ Target: make the first 30 minutes with Vestige hard to mess up.
 | Atomic memory guide | Clear examples for one fact, one preference, one decision, one bug fix, one source note, and one code pattern per memory. |
 | Default tag vocabulary | Recommended tags for source quality, confidence, project, type, urgency, and lifecycle without overloading words like `verified`. |
 | Smart vs force-create guide | Agents know when to use `forceCreate`, `batchMergePolicy="force_create"`, or normal PE gating. |
-| Updated agent templates | Claude, Codex, Cursor, VS Code, Xcode, JetBrains, and Windsurf templates start with `session_context` and use the same memory vocabulary. |
+| Updated agent templates | Claude, Codex, Cursor, VS Code, Xcode, OpenCode, JetBrains, and Windsurf templates start with `session_context` and use the same memory vocabulary. |

 Planned docs:

--- a/docs/VESTIGE_STATE_AND_PLAN.md
+++ b/docs/VESTIGE_STATE_AND_PLAN.md
@ -73,8 +73,8 @@ Vestige is organized as:

 HTTP MCP is disabled unless the user passes `--http`, passes `--http-port`, or
 sets `VESTIGE_HTTP_ENABLED=1`. The stdio MCP server remains the portable default
-for Claude Code, Codex, Cursor, VS Code, Xcode, JetBrains, Windsurf, and other
-clients.
+for Claude Code, Codex, Cursor, VS Code, Xcode, OpenCode, JetBrains, Windsurf,
+and other clients.

 Purge is implemented transactionally in storage and surfaced through the MCP
 `memory` tool. `memory(action="purge", confirm=true)` is the explicit hard
--- a/docs/integrations/codex.md
+++ b/docs/integrations/codex.md
@ -145,6 +145,7 @@ codex mcp add vestige -- /usr/local/bin/vestige-mcp
 | Xcode 26.3 | [Setup](./xcode.md) |
 | Cursor | [Setup](./cursor.md) |
 | VS Code (Copilot) | [Setup](./vscode.md) |
+| OpenCode | [Setup](./opencode.md) |
 | JetBrains | [Setup](./jetbrains.md) |
 | Windsurf | [Setup](./windsurf.md) |
 | Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
--- a/docs/integrations/cursor.md
+++ b/docs/integrations/cursor.md
@ -135,6 +135,7 @@ Cursor does not surface MCP server errors in the UI. Test by running the command
 | Xcode 26.3 | [Setup](./xcode.md) |
 | Codex | [Setup](./codex.md) |
 | VS Code (Copilot) | [Setup](./vscode.md) |
+| OpenCode | [Setup](./opencode.md) |
 | JetBrains | [Setup](./jetbrains.md) |
 | Windsurf | [Setup](./windsurf.md) |
 | Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
--- a/docs/integrations/jetbrains.md
+++ b/docs/integrations/jetbrains.md
@ -123,6 +123,7 @@ In **Settings > Tools > MCP Server**, click the expansion arrow next to your cli
 | Cursor | [Setup](./cursor.md) |
 | VS Code (Copilot) | [Setup](./vscode.md) |
 | Codex | [Setup](./codex.md) |
+| OpenCode | [Setup](./opencode.md) |
 | Windsurf | [Setup](./windsurf.md) |
 | Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
 | Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
--- a/docs/integrations/opencode.md
+++ b/docs/integrations/opencode.md
@ -0,0 +1,217 @@
+# OpenCode
+
+> Give OpenCode persistent local memory across TUI, CLI, and desktop sessions.
+
+OpenCode supports local MCP servers through its `mcp` config. Add Vestige once and your OpenCode agents can remember project decisions, architecture context, preferences, and previous fixes between sessions.
+
+Verified with OpenCode `1.16.2` on June 8, 2026.
+
+---
+
+## Setup
+
+### 1. Install Vestige
+
+```bash
+npm install -g vestige-mcp-server@latest
+```
+
+Verify the binary:
+
+```bash
+vestige-mcp --version
+```
+
+If you prefer not to install globally, use `npx` directly in the OpenCode command array:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["npx", "-y", "-p", "vestige-mcp-server@latest", "vestige-mcp"],
+      "enabled": true,
+      "timeout": 60000
+    }
+  }
+}
+```
+
+The higher timeout is for the first cold `npx` run, which may need to download the npm package before OpenCode can connect. If you install `vestige-mcp-server` globally, `10000` is enough for normal startup.
+
+If `npx` times out against an older published Vestige build, install globally once and use `command: ["vestige-mcp"]`. The current integration keeps the MCP handshake fast by moving embedding startup work into the background.
+
+### 2. Add Vestige To OpenCode
+
+For global use across projects, create or edit:
+
+```bash
+mkdir -p ~/.config/opencode
+${EDITOR:-vi} ~/.config/opencode/opencode.json
+```
+
+Add:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["vestige-mcp"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}
+```
+
+OpenCode also supports project-local config. Put the same block in `opencode.json` at the repo root when you want the setting checked in with a project.
+
+For a custom config file, set `OPENCODE_CONFIG=/path/to/opencode.json` before launching OpenCode.
+
+### 3. Verify
+
+Restart OpenCode, then validate the resolved config and MCP server list:
+
+```bash
+opencode debug config
+opencode mcp list
+```
+
+You should see `vestige` listed. In a session, ask:
+
+> "What MCP tools can you use?"
+
+Vestige tools should be available with the `vestige_` prefix, such as `vestige_search`, `vestige_smart_ingest`, `vestige_session_context`, and `vestige_deep_reference`.
+
+---
+
+## First Use
+
+In OpenCode:
+
+> "Remember that this project uses Rust with Axum and SQLite."
+
+Start a new OpenCode session, then ask:
+
+> "What stack does this project use?"
+
+It remembers.
+
+---
+
+## Project-Specific Memory
+
+To isolate memory per repo, add `--data-dir` to OpenCode's command array:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["vestige-mcp", "--data-dir", "./.vestige"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}
+```
+
+For an absolute path:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["/usr/local/bin/vestige-mcp", "--data-dir", "/Users/you/projects/my-app/.vestige"],
+      "enabled": true,
+      "timeout": 10000
+    }
+  }
+}
+```
+
+---
+
+## Automatic Setup
+
+If `opencode` is installed or `~/.config/opencode` exists, Vestige's installer can add the global config automatically:
+
+```bash
+npx @vestige/init
+```
+
+The installer writes a backup before modifying an existing config file. It also migrates Vestige entries copied from older `mcpServers` examples into OpenCode's current `mcp.vestige` shape.
+
+---
+
+## Troubleshooting
+
+<details>
+<summary>Vestige tools do not appear</summary>
+
+1. Verify OpenCode can see configured MCP servers:
+   ```bash
+   opencode debug config
+   opencode mcp list
+   ```
+2. Verify the binary is on your path:
+   ```bash
+   which vestige-mcp
+   ```
+3. Use an absolute binary path if OpenCode cannot resolve `vestige-mcp`.
+4. Restart OpenCode after changing `opencode.json`.
+5. Keep `timeout` at `10000` or higher for installed binaries. If you use the direct `npx` command, use `60000` so the first cold npm download does not fail OpenCode startup.
+</details>
+
+<details>
+<summary>Config does not validate</summary>
+
+OpenCode uses the top-level `mcp` key. Do not use the `mcpServers` shape from Claude Desktop, Cursor, or Windsurf.
+
+If you copied an older Vestige example that used `mcpServers`, rerun:
+
+```bash
+npx @vestige/init
+```
+
+Correct:
+
+```json
+{
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["vestige-mcp"],
+      "timeout": 10000
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Too many MCP tools in context</summary>
+
+OpenCode loads MCP tools alongside built-in tools. If you have many MCP servers enabled, disable unused servers or restrict MCP tools per agent in your OpenCode config.
+</details>
+
+---
+
+## Also Works With
+
+| IDE | Guide |
+|-----|-------|
+| Codex | [Setup](./codex.md) |
+| Cursor | [Setup](./cursor.md) |
+| VS Code (Copilot) | [Setup](./vscode.md) |
+| JetBrains | [Setup](./jetbrains.md) |
+| Windsurf | [Setup](./windsurf.md) |
+| Xcode 26.3 | [Setup](./xcode.md) |
+| Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
+| Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
--- a/docs/integrations/vscode.md
+++ b/docs/integrations/vscode.md
@ -153,6 +153,7 @@ Every team member with Vestige installed will automatically get memory-enabled C
 | Xcode 26.3 | [Setup](./xcode.md) |
 | Cursor | [Setup](./cursor.md) |
 | Codex | [Setup](./codex.md) |
+| OpenCode | [Setup](./opencode.md) |
 | JetBrains | [Setup](./jetbrains.md) |
 | Windsurf | [Setup](./windsurf.md) |
 | Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
--- a/docs/integrations/windsurf.md
+++ b/docs/integrations/windsurf.md
@ -149,6 +149,7 @@ If you have many MCP servers and exceed 100 total tools, Cascade will ignore exc
 | Cursor | [Setup](./cursor.md) |
 | VS Code (Copilot) | [Setup](./vscode.md) |
 | Codex | [Setup](./codex.md) |
+| OpenCode | [Setup](./opencode.md) |
 | JetBrains | [Setup](./jetbrains.md) |
 | Claude Code | [Setup](../CONFIGURATION.md#claude-code-one-liner) |
 | Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
--- a/docs/integrations/xcode.md
+++ b/docs/integrations/xcode.md
@ -252,6 +252,7 @@ Vestige uses the MCP standard — the same memory works across all your tools:
 | Claude Desktop | [Setup](../CONFIGURATION.md#claude-desktop-macos) |
 | Cursor | [Setup](./cursor.md) |
 | VS Code (Copilot) | [Setup](./vscode.md) |
+| OpenCode | [Setup](./opencode.md) |
 | JetBrains | [Setup](./jetbrains.md) |
 | Windsurf | [Setup](./windsurf.md) |

--- a/docs/launch/opencode-adoption.md
+++ b/docs/launch/opencode-adoption.md
@ -0,0 +1,114 @@
+# OpenCode Adoption Plan
+
+Status: Vestige was tested with OpenCode `1.16.2` on June 8, 2026. The working config uses OpenCode's top-level `mcp.vestige` schema, not `mcpServers`.
+
+## Release Gate
+
+- PR #67 is merged upstream and should be treated as the contributor-driven starting point.
+- Ship the corrected OpenCode config docs and `@vestige/init` migration from stale `mcpServers.vestige` to `mcp.vestige`.
+- Ship the background embedding initialization fix before making direct `npx` the main OpenCode install path. A cold published `2.1.23` package can still time out while OpenCode waits for tools.
+- After release, verify all three OpenCode paths again:
+  - installed binary: `command: ["vestige-mcp"]`
+  - project memory: `command: ["vestige-mcp", "--data-dir", "./.vestige"]`
+  - direct npm: `command: ["npx", "-y", "-p", "vestige-mcp-server@latest", "vestige-mcp"]` with `timeout: 60000`
+
+## Official OpenCode PR
+
+Target repo: `https://github.com/anomalyco/opencode`
+
+Files:
+
+- `packages/web/src/content/docs/mcp-servers.mdx`
+- `packages/web/src/content/docs/ecosystem.mdx`
+
+MCP docs snippet:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "vestige": {
+      "type": "local",
+      "command": ["npx", "-y", "-p", "vestige-mcp-server@latest", "vestige-mcp"],
+      "enabled": true,
+      "timeout": 60000
+    }
+  }
+}
+```
+
+Ecosystem row:
+
+```md
+| [Vestige](https://github.com/samvallad33/vestige) | Local MCP memory server for OpenCode that remembers project decisions, preferences, and previous fixes across sessions |
+```
+
+Positioning: local, inspectable MCP memory for OpenCode. Avoid claiming Vestige fixes OpenCode's process memory or session resume behavior.
+
+## Awesome OpenCode
+
+Target repo: `https://github.com/awesome-opencode/awesome-opencode`
+
+Suggested entry, with category to confirm against maintainer preference (`data/projects/vestige.yaml` or `data/resources/vestige.yaml`):
+
+```yaml
+name: Vestige
+repo: https://github.com/samvallad33/vestige
+tagline: Local persistent memory for OpenCode
+description: Local MCP server that lets OpenCode remember project decisions, preferences, architecture context, and previous fixes across sessions.
+scope:
+  - global
+  - project
+tags:
+  - mcp
+  - memory
+  - local-first
+  - sqlite
+  - opencode
+min_version: 1.16.2
+homepage: https://github.com/samvallad33/vestige/blob/main/docs/integrations/opencode.md
+installation: |
+  npm install -g vestige-mcp-server@latest
+  npx @vestige/init
+```
+
+## MCP Directories
+
+Current state:
+
+- Official MCP Registry already lists `io.github.samvallad33/vestige` at `https://registry.modelcontextprotocol.io/v0/servers?search=vestige`.
+- Smithery already lists Vestige and indexes 25 tools: `https://smithery.ai/server/@samvallad33/vestige`.
+- Glama already lists Vestige, but the listing needs a refresh/fix if it shows no tools: `https://glama.ai/mcp/servers/samvallad33/vestige`.
+- `mcp.so` does not show Vestige under the expected slugs yet; submit manually at `https://mcp.so/submit`.
+
+Priority order:
+
+1. Official MCP Registry: `https://github.com/modelcontextprotocol/registry`
+2. Awesome MCP Servers: `https://github.com/punkpeye/awesome-mcp-servers`
+3. Glama MCP directory: `https://glama.ai/mcp/servers`
+4. Smithery: `https://smithery.ai`
+5. PulseMCP: `https://www.pulsemcp.com`
+
+Registry metadata is mostly ready: `server.json` exists and `packages/vestige-mcp-npm/package.json` has `mcpName: "io.github.samvallad33/vestige"`. Publish only when the package version and `server.json` version match the released npm package.
+
+## Community Launch
+
+Use tested technical copy, not hype:
+
+> Vestige now works with OpenCode as a local MCP memory server. It gives OpenCode persistent memory for project decisions, preferences, architecture context, and previous fixes across sessions. Install with `npm install -g vestige-mcp-server@latest`, run `npx @vestige/init`, then verify with `opencode mcp list`.
+
+High-signal channels after release:
+
+- OpenCode Discord: `https://opencode.ai/discord`
+- opencode.cafe MCP Server listing: `https://opencode.cafe`
+- OpenCode memory-related GitHub issues, only where directly relevant
+- Hacker News and Lobsters with a technical post about the tested OpenCode integration and failure modes
+- npm keyword/discovery after the next package release includes `opencode`
+
+## Proof Checklist
+
+- `opencode debug config` accepts `mcp.vestige`.
+- `opencode mcp list` shows `vestige connected`.
+- Stale `mcpServers.vestige` examples fail in OpenCode and are migrated by `@vestige/init`.
+- OpenCode tools are prefixed as `vestige_search`, `vestige_smart_ingest`, `vestige_session_context`, and `vestige_deep_reference`.
+- The OpenCode guide says `timeout: 60000` for direct `npx` and `timeout: 10000` for installed binaries.