OpenCode Memory
Automatic long-term memory for OpenCode: one plugin line in your config auto-installs opencode-memorysync, which injects recalled context into the system prompt per session, captures the durable facts in your messages as you send them, registers the MemorySync MCP servers and three slash commands — and is incapable of breaking a session by contract.
What the plugin provides
| Layer | What it does |
|---|---|
| Recall (system transform) | OpenCode’s experimental.chat.system.transform hook injects your profile and this project’s context into the system prompt — recalled once per session, replayed identically on every LLM call from a bounded per-session cache. |
| Capture (message hooks) | chat.message sends your message for fact extraction — fire-and-forget with content-hash seeds, so retries and repeated events are recognised server-side and extracted once. experimental.text.complete sends nothing: replies are not stored. |
| Config registration | The config hook registers the MemorySync MCP server (API key or OAuth) plus the zero-auth docs server, and three slash commands — never overwriting anything you configured yourself. |
| Compaction | When OpenCode compacts a session, memory context is re-supplied so continuity survives the squeeze. |
| Mem0 | Supermemory | Zep | MemorySync | |
|---|---|---|---|---|
| OpenCode plugin exists | ✓ | ✓ | ✗ nothing (404) | ✓ |
| Recall guaranteed per session | ✓ injected | △ model decides — can silently skip | ✗ | ✓ injected, cached per session |
| Auth for individuals | ✓ API key | △ OAuth-first | ✗ | ✓ API key or OAuth |
| Respects your existing config | ❌ undocumented | ❌ undocumented | — | ✓ non-destructive, frozen-config safe, tested |
| Hook failure can break a session | ❌ undocumented | ❌ undocumented | — | ✓ impossible: every hook swallows every failure, tested |
Install
# Get an API key at https://app.memorysync.io, then:# macOS/Linux: export MEMORYSYNC_API_KEY=ms_...# Windows: setx MEMORYSYNC_API_KEY ms_...
Option A: Full plugin (recommended)
{ "plugin": ["opencode-memorysync"] }
One line — in the global config or a project’s .opencode.json — and OpenCode installs the plugin on next start: hooks, slash commands, and the MCP server together.
Option B: MCP only, one command
npx memorysync-mcp-install --client opencode
Option C: MCP only, by hand
{ "mcp": { "memorysync": { "type": "remote","url": "https://mcp.memorysync.io/mcp", "enabled": true } } }
With MEMORYSYNC_API_KEY set, the plugin authenticates the MCP server with your key and disables the OAuth prompt; without it, OpenCode’s own OAuth flow signs you in on first tool use (opencode mcp auth). Set MEMORYSYNC_DISABLE=1 to switch the plugin off without uninstalling.
What runs when
| Moment | What happens |
|---|---|
| First LLM call of a session | Recall runs once — profile plus project context — and lands in the system prompt. Every later call in that session replays the identical block from cache (no per-call latency, no drift mid-session). |
| You send a message | The text is sent to MemorySync, which extracts the durable facts in it and stores only those, tagged with the opencode::<project> session scope; the message text itself is not stored. A content-hash seed lets the server recognise a replayed message, and a failed send can be retried by a later event. Slash-command template expansions are recognised and skipped. |
| The reply completes | Nothing is sent: assistant replies are not stored as memories. |
| Session compaction | Memory context is added to what survives the compact. |
| Any failure — no key, network down, quota exhausted | Silent skip; the session continues untouched. Every hook is wrapped: a thrown hook would break OpenCode, so none can throw. |
Identity and scope resolve like every MemorySync agent surface: MEMORYSYNC_USER_ID (default: OS username), project from the git remote — worktree-aware — with MEMORYSYNC_PROJECT override.
Slash commands
| Command | What it does |
|---|---|
/memorysync-recall <query> | Searches long-term memory and answers from what comes back. |
/memorysync-remember <fact> | Saves a durable fact through the MCP add_memory tool. |
/memorysync-status | Checks connectivity and reports what MemorySync knows in this project. |
The commands ride the same MCP tools the model can call on its own — they are shortcuts, not a separate pathway. Your own command or MCP entries with the same names are never overwritten.
Supported versions
| Surface | Requires | Verified on |
|---|---|---|
opencode-memorysync 1.1.0 | OpenCode with plugin support (@opencode-ai/plugin 1.0+), Node.js 18+ | Plugin contract suite 18/18 — loaded exactly as OpenCode loads plugins, driven against documented hook shapes |
CI loads the plugin the way OpenCode does and drives every hook on every push: non-destructive registration (including frozen config objects), injection caching, user-message-only capture (replies never sent), both monthly-quota server modes, and the never-throw discipline.