> 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.
OpenCode is strong at driving real coding work from the terminal. The painful gap is continuity: the next session often has to rediscover what the previous session already learned. Vestige gives OpenCode a local memory layer through MCP, so the agent can reuse the project context that should not be trapped in one chat transcript.
Useful memories include:
- project decisions: "we use Axum handlers thinly and keep database logic in storage modules"
- preferences: "prefer small focused PRs and explicit verification receipts"
- architecture context: "the dashboard talks to the MCP server through the Axum backend and WebSocket events"
- bug fixes: "OpenCode rejects `mcpServers`; use top-level `mcp.vestige` with a command array"
- workflow state: "PR #67 was merged, but the config shape needed correction before promotion"
Vestige is local-first. Memories are stored in SQLite on your machine, can be scoped globally or per project, and are retrieved with tools like `vestige_session_context`, `vestige_search`, `vestige_smart_ingest`, and `vestige_deep_reference`.
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:
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) |
