OpenCode Memory Across Sessions

OpenCode connects to MemoryRouter as a remote MCP server. You add one entry to opencode.json, run opencode mcp auth, and the agent gets tools to search and store memories in your MemoryRouter vault. The vault lives outside OpenCode, so what you stored is still there after /compact and in a brand new session.

The same vault is reachable from Claude Code, Codex, ChatGPT, and Claude. A decision stored from OpenCode can be recalled in any of them.

This is a remote MCP connection, not a native OpenCode plugin. There is no hook package for OpenCode today, so recall and capture are model-directed: the agent decides when to call the tools.

How this fits with OpenCode's own context

OpenCode keeps project instructions in files. AGENTS.md in the repository holds project rules, /init scans the repo and writes or improves it, and ~/.config/opencode/AGENTS.md applies to every session. When a long session fills up, /compact replaces the history with a summary.

Those files describe how to work in a repository, and they are worth keeping. MemoryRouter holds the record of the work itself, such as decisions, reasoning, and approaches you already rejected, in a vault a new session can search instead of starting from the summary or from nothing.

Prerequisites

• OpenCode installed, with a model provider configured.
• A MemoryRouter account and a vault you are allowed to use.
• A local browser for the OAuth step.

You do not need a model-provider API key in MemoryRouter for this setup. OpenCode keeps using its own provider.

Add the server

Merge this into opencode.json in your project root, or into ~/.config/opencode/opencode.json to use memory in every project:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "memoryrouter": {
      "type": "remote",
      "url": "https://mcp.memoryrouter.ai/mcp",
      "enabled": true,
      "oauth": {
        "scope": "memories:read memories:write"
      }
    }
  }
}

The oauth.scope value asks for recall and storage only. MemoryRouter scopes are independent, so this connection cannot delete memories or run consolidation. Add memories:delete or memories:reflect later only if you want those tools.

Do not add a Memory Key under headers, and do not set "oauth": false. The MCP server accepts OAuth access tokens, not mk_ keys.

Authenticate

Run this once from your shell:

opencode mcp auth memoryrouter

Your browser opens the MemoryRouter consent screen. Sign in, review the listed permissions, and choose the vault this connection should use. OpenCode registers itself automatically and stores the tokens in ~/.local/share/opencode/mcp-auth.json.

Check the result with opencode mcp auth list. Run the auth step even if opencode mcp list already shows the server as connected. MemoryRouter lets clients list its tools without signing in, so "connected" only means the server answered. Searching or storing memories requires the token. opencode mcp debug memoryrouter shows the current auth status in detail.

One OAuth connection is bound to one vault. To switch vaults, run opencode mcp logout memoryrouter, then opencode mcp auth memoryrouter again and choose a different vault.

Make recall a habit

Tool calls are model-directed. A short section in AGENTS.md makes recall and capture more consistent without guaranteeing a call on every turn:

## Memory
- At the start of a task, search MemoryRouter for earlier decisions about this module.
- When I say "remember this", store it in MemoryRouter as one concise memory.

Keep the memory instructions short. They tell the agent when to look; the vault holds what it finds.

Cross-session proof

Use a synthetic fact, not source code or secrets.

1. In an OpenCode session, ask: "Store this in MemoryRouter: the demo project's release phrase is ORCHID-7419." Check that the store_memory call succeeded.
2. Start a new session, or run /compact, so the fact is no longer in the active context.
3. Ask: "Search MemoryRouter for the demo project's release phrase." Do not include the answer.
4. Confirm the search_memories result contains ORCHID-7419. Check the tool result, not only the model's reply.
5. Optional: ask the same question from Claude Code, Codex, or ChatGPT connected to the same vault.

This is a test you run in your own account. Recall is relevance-ranked over the vault, not a dump of every memory on every request.

What the agent can do

With memories:read and memories:write, OpenCode can use search_memories, date_search_memories, inspect_memory, memory_status, the search alias, and store_memory. The MCP server reference lists every tool, its inputs, and the scope it requires.

About the custom provider route

OpenCode can also use an OpenAI-compatible custom provider with its own baseURL, and MemoryRouter has an OpenAI-compatible endpoint. That route is not documented here. The proxy stores and recalls message text and does not guarantee tool-calling parity, which an agent like OpenCode depends on. Use the MCP route above, which keeps OpenCode on its normal provider.

Limitations

• Capture is model-directed. Nothing is stored unless the agent calls store_memory, and nothing is recalled unless it calls a search tool.
• Connecting does not import earlier OpenCode sessions or your AGENTS.md files.
• OAuth needs a local browser on the machine running opencode mcp auth.
• A shared vault is shared. Use a separate vault and a separate connection when projects or people must stay isolated.

Troubleshooting

Disabling the server or logging out stops future tool calls. It does not delete memories already in the vault. See security and data isolation for deletion.

Next steps

• MCP server reference: tools, scopes, and vaults
• OpenCode memory overview
• Coding tools guide
• OpenCode MCP server documentation
• Create a MemoryRouter account