OpenCode Memory with the Supermemory Plugin

OpenCode supports persistent project instructions through rules and AGENTS.md. Supermemory adds external memory capture and retrieval for context you want to reuse across sessions.

Use the plugin when a controlled test exposes a continuity gap in your existing workflow. Check what was saved, which repository scope it used, and what was retrieved before relying on the final answer.

The two-command install

bunx opencode-supermemory@latest install
bunx opencode-supermemory@latest login

That's it. The installer registers the plugin in ~/.config/opencode/opencode.jsonc and adds a /supermemory-index command (/supermemory-init remains an alias). Check the connection any time with bunx opencode-supermemory@latest status. (GitHub)

Or skip the terminal entirely: paste the README link into OpenCode and let the agent install it for you.

What you get out of the box

The current plugin README documents these behaviors. They depend on configuration and successful service calls:

Context injection - on your first message of a session, the agent silently receives your personal profile, the project's memories, and relevant past memories with confidence scores. Inspect the injected records; a displayed similarity score is not a calibrated probability that a fact is correct.
Reasoned recall - every turn, the agent decides whether recalling memory would actually help this message, and only searches when it's worth it. Trivial messages don't burn a network call.
Automatic capture - completed conversation turns are saved in batches, and flushed when the session ends. A successful capture must still be verified; shutdown failures and unavailable services can interrupt the path.
Keyword detection - say "remember that..." or "don't forget..." and it's saved. Add your own trigger phrases in config.
Preemptive compaction - when context hits 80%, the plugin feeds your project memories into OpenCode's summarization and saves the session summary as a memory. This can preserve useful context but is not lossless capture.
/supermemory-init - point the agent at your codebase and it explores, then memorizes the architecture, patterns, and conventions.

For example, a cross-session exchange might look like this:

You: "add rate limiting to the ingest endpoint"
OpenCode: [recalls the sliding-window Redis limiter you built
for payments-api last month, and that you prefer
middleware over decorators - writes it that way]

Memory scoped to the repository

Here's the thing I actually love about this plugin.

Every supermemory coding-agent plugin - OpenCode, Claude Code, Codex - writes to the same shared container for a repository, derived from the repo's git origin remote. Personal memories and project memories stay separate inside it (sm_scope metadata), but the container is one.

With compatible credentials and access to the same records, you can save a project decision in Claude Code and retrieve it in OpenCode. The repository remote identifies the project; your account's permissions determine who can read its memory.

Repositories with the same folder name but different remotes stay isolated. No origin remote? It falls back to the real filesystem path. And if you used an older version of any of the plugins, the legacy containers are still read - upgrading needs no migration.

The `supermemory` tool

The agent gets one tool with five modes, auto-approved where it matters:

Mode	What it does
`add`	Store a memory (typed: `project-config`, `architecture`, `error-solution`, `preference`, `learned-pattern`, `conversation`)
`search`	Semantic search across memories
`profile`	View your user profile
`list`	List memories by scope
`forget`	Invoke the plugin’s removal operation for the selected record; verify source and derived-memory effects

Scopes are user (your personal memories for this project) and project (shared project knowledge, the default).

Knobs worth turning

Everything lives in ~/.config/opencode/supermemory.jsonc, all optional:

{
  // point at a self-hosted instance
  "baseUrl": "https://api.supermemory.ai",

  // retrieval tuning
  "similarityThreshold": 0.55,
  "maxMemories": 5,
  "maxProjectMemories": 10,

  // capture cadence: save every N turns (0 = session end only)
  "captureEveryNTurns": 3,

  // when compaction kicks in (0-1)
  "compactionThreshold": 0.8,

  // your own "save this" triggers (regex)
  "keywordPatterns": ["log\\s+this", "write\\s+down"],
}

SUPERMEMORY_API_KEY takes precedence over the config file, which keeps keys out of dotfiles if you prefer. Running Oh My OpenCode? Disable its built-in auto-compact hook so supermemory owns compaction - one line in its config, covered in the README.

Privacy and self-hosting

The plugin documents redaction of <private> content from its capture path. That does not remove the same content from the model provider, tool logs, existing history or unrelated integrations. Test the exact capture path with synthetic data and keep credentials in supported secret configuration.

A self-hosted memory endpoint can be configured with baseUrl. For an offline workflow, the answering model, memory-service model providers and tools must also stay local. Pointing one URL at localhost does not establish that nothing leaves the machine. Review the self-hosting options.

The coding plugin is free to use; hosted operations consume usage under current pricing.

Why not just use the supermemory MCP?

The MCP works in OpenCode, but it has one structural limit: we can't control when the agent decides to call the tools. With MCP alone, capture depends on the client or agent invoking the save tool.

The plugin supplies host-specific hooks beyond simply exposing MCP tools:

Context injection - your profile arrives on session start, automatically
Automatic capture - conversation turns are stored whether or not the agent thinks to do it
Compaction integration - saved project context can help the agent resume after the active conversation is summarized

Use both if you want. Check account and scope if both paths are enabled, and avoid duplicate capture.

Start with one explicit save, retrieve it in a new session, then verify correction and removal in the same repository scope.

Install it: bunx opencode-supermemory@latest install - or read the docs.

Frequently asked questions

Does OpenCode have any native persistent context?

Yes. It supports maintained project instructions and rules. Supermemory adds external capture and retrieval alongside those native controls.

Does the same Git remote give every teammate access to the same memories?

No. Repository identity helps select a container, but compatible credentials and authorization to the stored records are still required.

Do private tags keep content away from every service?

No. The documented redaction applies to the plugin capture path. It does not erase provider inputs, logs or copies in other integrations.