OpenCode Memory with the Supermemory Plugin

OpenCode doesn't remember earlier sessions on its own. It reads the instructions you write in AGENTS.md, and nothing else carries over from one session to the next. The supermemory plugin adds memory that's saved as you work and recalled on every substantive prompt, and one install covers both OpenCode 1 and OpenCode 2: bunx opencode-supermemory@latest install.

Everything below is checked against the plugin's README and our docs as of October 21, 2026.

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 for both OpenCode 1 and OpenCode 2, and adds a /supermemory-index command (/supermemory-init is an alias). Restart OpenCode, then check the connection any time with bunx opencode-supermemory@latest status. (GitHub)

If you'd rather use an API key, create one on the API keys page and set it as SUPERMEMORY_API_KEY. Or skip the terminal entirely: paste the README link into OpenCode and let the agent install it for you.

OpenCode 2 support

Since September 26, 2026, the plugin works in OpenCode 2 as well as OpenCode 1, with the same package and the same install (changelog). The installer writes both generations' config keys, so one opencode.jsonc works for both:

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

Recall, capture, the supermemory tool and its scopes behave the same on both. Three things differ on OpenCode 2:

• Recall has its own tool. It runs through a read-only supermemory_recall tool, which the installer allows so it never prompts. Saving and forgetting still go through the normal supermemory permission.
• OpenCode owns compaction. The plugin adds your project memories to OpenCode's own compaction request and saves the summary, rather than triggering compaction itself.
• Recalled context stays out of the transcript. It's attached to the request for the current prompt only.

Check that it loaded with opencode plugin list, and update it with opencode plugin update opencode-supermemory.

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 and the project's knowledge. Inspect the injected records; a displayed similarity score is not a calibrated probability that a fact is correct.
• Direct recall. By default, on every substantive prompt, the plugin searches the project's memory and adds up to five strong, fresh matches. Short prompts and commands are skipped, repeats are suppressed within a session, and recall gives up after three seconds so it never blocks the agent. Set recallMode to "advisory" if you'd rather the model decide when to search.
• Automatic capture. Completed turns are saved when the session ends or OpenCode shuts down. Set captureEveryNTurns to also save them in batches as you go; installs upgraded from an older version save every three turns. 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 the agent saves it. Add your own trigger phrases in config.
• Compaction memory. On OpenCode 1, when context hits 80%, the plugin triggers OpenCode's summarization with your project memories in the prompt and saves the summary as a memory. On OpenCode 2 it enriches OpenCode's own compaction the same way. This can preserve useful context but is not lossless capture.
• /supermemory-index. 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, Cursor and Muse Code) writes to the same shared container for a repository, derived from the repo's normalized 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. Working in several worktrees of one repo? Set SUPERMEMORY_ISOLATE_WORKTREES=true to key memory to the worktree path instead. OpenCode also still reads the containers that older versions of the OpenCode, Claude Code, Codex and Cursor plugins wrote, so upgrading needs no migration there. The Claude Code plugin doesn't read those older containers.

The coding agents page has the setup for every agent that shares this memory.

The supermemory tool

The agent gets one tool with six 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
help	List the available modes

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,

  // "direct" (default for new installs), "advisory", or "off"
  "recallMode": "direct",

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

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

  // OpenCode 2: enrich native compaction and save the summary
  "compactionEnabled": true,

  // 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: pass --disable-context-recovery to the installer, or add the one line to its config that the README shows.

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, and npx supermemory local starts one on your machine (docs). 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 plugin is free on every plan, including Free, which comes with $5 of credits a month. What it saves and searches draws on those credits (billing docs), and the pricing page has the rates.

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. The MCP page covers the server itself.

---

Start with one explicit save, retrieve it in a new session, then verify correction and removal in the same repository scope. For other agents, see the coding agents page, and for apps you build yourself, start with the quickstart.

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

Frequently asked questions

Does OpenCode have any native persistent context?

Yes. It reads the instructions in your AGENTS.md files at the start of a session, and /init writes a starter one for the repo (OpenCode docs). Supermemory adds external capture and retrieval alongside those native controls.

Does the plugin work with OpenCode 2?

Yes. Since September 26, 2026, the same package and the same install cover OpenCode 1 and OpenCode 2.

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.