opencode-supermemory, a plugin that gives an OpenCode agent a memory across sessions

One package for two OpenCode generations

The plugin exists so that your agent remembers what you tell it, across sessions and across projects, and the packaging detail that makes it usable is that one package supports both OpenCode generations. OpenCode V1 loads the root entry from the plugin array, while OpenCode 2 loads the server entry from the plugins array, plus a small TUI companion for notices. The module exports make that explicit, with a root entry, a server entry, a tui entry, an rpc entry and a v2 entry, and the package is built with a script that produces a Node target for most of them and a Bun target for the TUI bundle with the OpenTUI and solid-js packages marked external. The version in the package metadata is 2.0.17, the primary language is TypeScript, and the last push to the repository was on 2026-10-14.

Installing it, and the agent-driven path

Installation is a set of three commands run through bunx: an install command that registers the plugin, a login command that authenticates, and a status command that checks the connection, and the login step can be replaced by setting the SUPERMEMORY_API_KEY environment variable instead. The project also offers a path for agents to install it, by pasting a line into OpenCode that tells it to follow the installation instructions from the project README. The same four operations, install, login, logout and status, are also available as in-chat commands once the plugin is registered, with the names supermemory-init, supermemory-login, supermemory-logout and supermemory-status. That last point is the one that makes the plugin feel native, because a user who has forgotten the CLI can ask the agent itself to check the connection.

bunx opencode-supermemory@latest install
bunx opencode-supermemory@latest login     # or set SUPERMEMORY_API_KEY
bunx opencode-supermemory@latest status    # check the connection any time

The installer writes to your OpenCode config

The installer registers the plugin in the OpenCode configuration file at the user level, and the documentation goes into detail about what it writes. It adds the plugin to the plugin array for OpenCode V1 and to the plugins array for OpenCode 2, adds a permissions entry allowing the read-only supermemory_recall tool, and creates the supermemory-index command with supermemory-init as an alias. The configuration file is JSONC, so the installer preserves comments and other settings, and it is safe to re-run. The documented example shows the shape of the result, with the two generation-specific arrays and a permissions block. The installer also takes a --no-tui flag for headless environments, and a --disable-context-recovery flag to add if the user also has another plugin installed, to avoid its auto-compact hook fighting with this plugin's compaction on OpenCode V1.

{
  // OpenCode V1
  "plugin": [
    "opencode-supermemory@latest",
  ],
  // OpenCode 2
  "plugins": [
    "opencode-supermemory",
  ],
  "permissions": [
    { "action": "supermemory_recall", "resource": "*", "effect": "allow" },
  ],
}

What the agent actually receives

On the first message of a session, the agent silently receives your profile, all project knowledge, and, if the autoRecallEveryPrompt option is on, a semantic search over personal memories. The example block in the documentation shows what that looks like in practice, with a user profile section listing preferences and expertise, a project knowledge section with entries like the project using Bun rather than Node and the build command, and a relevant memories section with confidence percentages and a specific fact, in this case that the build fails if a local environment file is missing. The percentages are relevance scores, and the format is designed to be read by the model rather than by a human, which is why it is a compact block instead of a chat message. The agent uses this context automatically with no manual prompting needed.

[SUPERMEMORY]

User Profile:
- Prefers concise responses
- Expert in TypeScript

Project Knowledge:
- [100%] Uses Bun, not Node.js
- [100%] Build: bun run build

Relevant Memories:
- [82%] Build fails if .env.local missing

Recall has three modes, and one of them times out

Recall is where the design choices get interesting. On every substantive prompt, Supermemory directly searches the current project and injects up to five strong, fresh matches, and short prompts and commands are skipped, repeat results are suppressed per session, and recall fails open after three seconds so it never blocks the agent indefinitely. That last point is a sensible failure policy for a memory layer. There is also a reasoned recall mode, where every turn the agent is shown a directive asking it to decide whether recalling memory would help before answering, and it searches via the supermemory tool only when it decides to, with the search itself auto-approved. The recallMode option selects between advisory and off, and the recallDirective option customises advisory mode, and the older autoRecallEveryPrompt flag maps to direct mode when true and to advisory mode when false if recallMode is unset.

Capture, keyword triggers and the private tag

The capture side runs in the opposite direction. Completed conversations are captured automatically, with every captureEveryNTurns completed turns saved as a batch, any remaining turns flushed when the session is deleted or the OpenCode instance shuts down, synthetic plugin context excluded, and private content redacted. Stable capture IDs retain batch identity across repeated lifecycle events, though the documentation is careful that they do not guarantee exactly-once processing or billing after an ambiguous response. There is also a keyword path, where saying remember, save this or don't forget nudges the agent to save to memory, with custom triggers through the keywordPatterns option. The privacy mechanism is the one to understand before enabling anything: content wrapped in the private tags is never stored, and everything else in a captured conversation goes to the service.

You: "Remember that this project uses bun"
Agent: [saves to project memory]

Codebase indexing, compaction and the update check

Three features are about the agent's own behaviour rather than about storage. The codebase indexing feature has the supermemory-init command, with supermemory-index as an alias, ask the agent to explore and memorize the codebase's structure, patterns and conventions, which is a one-off index rather than something that runs on every prompt. Compaction memory is the feature that interacts with OpenCode's own context management: on OpenCode V1 it triggers summarization at 80 percent context capacity, and on OpenCode 2 it enriches the native compaction request, and in both cases it injects project memories into the summary and saves the summary itself as a memory. The last feature is the least glamorous and the most practical: the plugin checks npm for a newer release on session start and surfaces a one-line notice. The licence is MIT and the documentation site is at supermemory.ai/docs/integrations/opencode.

Editorial conclusion

Adopt opencode-supermemory if you work with an OpenCode agent across many sessions and keep re-explaining the same project facts, and skip it if you are working on a single short task or your code cannot leave the machine, because the capture path sends conversation content to a hosted service. Verify three things before you switch it on: that your private content is actually wrapped in the private tags, since content in those tags is never stored while everything else is; which recall mode you want, since direct mode injects matches on every substantive prompt while advisory mode asks the model to decide; and how the plugin behaves alongside another compaction plugin, since the documentation warns that an auto-compact hook can fight with this plugin's own compaction on the first generation of OpenCode.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. supermemoryai/opencode-supermemory on GitHub