Supermemory

OpenCode plugin for persistent memory using Supermemory. Your agent remembers what you tell it, across sessions and across projects.

One package supports both OpenCode generations: OpenCode V1 loads the root entry from the plugin array, and OpenCode 2 loads opencode-supermemory/server (plus a small TUI companion for notices) from the plugins array. See OpenCode 2.

Installation

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

Or let your agent do it: paste this into OpenCode:

Install opencode-supermemory by following https://raw.githubusercontent.com/supermemoryai/opencode-supermemory/main/README.md

install, login, logout, and status are also available as in-chat commands (/supermemory-init, /supermemory-login, /supermemory-logout, /supermemory-status) once the plugin is registered.

bunx opencode-supermemory@latest install --no-tui

cat ~/.config/opencode/opencode.jsonc

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

bunx opencode-supermemory@latest login

{
  "apiKey": "sm_...",
}

Features

[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

The agent uses this context automatically - no manual prompting needed.

Direct Recall

On every substantive prompt, Supermemory directly searches the current project and injects up to five strong, fresh matches. 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.

Set recallMode to "advisory" to retain model-decided tool recall, or to "off" to disable automatic recall. recallDirective customizes advisory mode. Legacy autoRecallEveryPrompt: true maps to direct mode and false maps to advisory mode when recallMode is unset.

Automatic Capture

Completed conversations are captured automatically:

• Every captureEveryNTurns completed turns, OpenCode saves the new turn batch.
• Any remaining turns are flushed when the session is deleted or the OpenCode instance shuts down.
• Synthetic plugin context is excluded and <private> content is redacted.
• Stable capture IDs make repeated lifecycle events idempotent.

Keyword Detection

Say "remember", "save this", "don't forget" etc. and the agent auto-saves to memory.

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

Add custom triggers via keywordPatterns config.

Codebase Indexing

Run /supermemory-index to explore and memorize your codebase structure, patterns, and conventions. /supermemory-init is an alias.

Compaction Memory

On OpenCode V1, when context hits 80% capacity (compactionThreshold) the plugin triggers OpenCode's summarization, injects project memories into the summary prompt, and saves the resulting summary as a memory.

On OpenCode 2, OpenCode owns the compaction trigger and model. The plugin hooks the native compaction request to add the same project memories, then saves each successful summary as a memory. Set compactionEnabled: false to opt out on OpenCode 2.

Activity Notices and Status Footer

Supermemory shows a short native notice when it recalls memories, saves a turn, falls open because recall was unavailable, or a newer release exists. Notices never enter model context. On OpenCode V1 they are TUI toasts; on OpenCode 2 they are rendered by the opencode-supermemory/tui companion, which OpenCode loads automatically next to the server plugin.

The same TUI plugin keeps a persistent ◪ supermemory footer. It turns blue while a session is running and otherwise shows the latest recall or save activity, if any. On OpenCode V1 the installer enables it through ~/.config/opencode/tui.jsonc; on OpenCode 2 it appears in the prompt footer without extra configuration.

Set SUPERMEMORY_DEBUG=1 to show a [recall-decision] line in each reply while testing advisory recall.

OpenCode 2

OpenCode 2 uses the plural plugins config key and the new @opencode/plugin API. The installer writes both generations, so one opencode.jsonc works for opencode (V1) and OpenCode 2 side by side:

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

OpenCode 2 resolves the package's ./server export for the server plugin (id supermemory) and ./tui for the notice companion (id supermemory.tui). Verify with opencode plugin list (or v2 plugin registered in ~/.opencode-supermemory.log), and update with opencode plugin update opencode-supermemory.

What is the same on both generations:

• Direct recall on substantive prompts, advisory mode, and recallMode: "off"
• First-message profile injection, keyword nudges, and automatic capture with the same cadence, privacy redaction, and idempotent capture IDs
• The supermemory tool with identical modes, scopes, and result formatting
• Activity notices, the persistent status footer, and update checks

What differs on OpenCode 2:

• Recall runs through the read-only supermemory_recall tool (search only). The installer allows it without prompting; add, forget, and the rest stay behind the normal supermemory permission. An explicit deny for supermemory_recall is preserved.
• Compaction is native: the plugin enriches OpenCode's compaction request and saves the summary instead of triggering compaction itself (compactionEnabled).
• Recalled context is attached to the outgoing model request for the current prompt rather than persisted into the transcript.

To roll back on OpenCode 2 only, remove "opencode-supermemory" from plugins (or prefix it with -) and restart. The V1 plugin entry is unaffected.

Tool usage

The supermemory tool is available to the agent:

Scopes: user (personal memories for the current project), project (default)

Types: project-config, architecture, error-solution, preference, learned-pattern, conversation

OpenCode sends the same shared coding-agent entity context as Claude Code and Codex. Personal and project memories are distinguished with sm_scope metadata inside the shared repository container.

Memory scoping

The repository hash comes from the normalized Git origin remote, so Claude Code, Codex, Cursor, and OpenCode use the same container for the same repository. Repositories with the same name but different remotes remain isolated. Without an origin remote, OpenCode falls back to the repository's real filesystem path.

OpenCode also reads previous user_project_*, repo_<project-name>, claudecode_project_*, codex_user_*, codex_project_*, opencode_user_*, opencode_project_*, cursor_user_*, and cursor_project_* containers, so upgrading does not require a migration.

Configuration

Environment variables

~/.config/opencode/supermemory.jsonc

{
  // API key (can also use SUPERMEMORY_API_KEY env var)
  "apiKey": "sm_...",

  // Supermemory API base URL (point at a self-hosted instance, e.g. http://localhost:8787)
  "baseUrl": "https://api.supermemory.ai",

  // Min similarity for memory retrieval (0-1)
  "similarityThreshold": 0.55,

  // Max memories injected per request
  "maxMemories": 5,

  // Max project memories listed
  "maxProjectMemories": 10,

  // Max profile facts injected
  "maxProfileItems": 5,

  // Include user profile in context
  "injectProfile": true,

  // Also run a semantic search over personal memories on a session's first
  // message, not just profile + project list (default: true on upgrades,
  // false on fresh installs)
  "autoRecallEveryPrompt": true,

  // Legacy prefix retained when reading containers made by older versions
  "containerTagPrefix": "opencode",

  // Optional legacy personal container to keep reading
  "userContainerTag": "my-custom-user-tag",

  // Optional: set exact project container tag (overrides auto-generated tag)
  "projectContainerTag": "my-project-tag",

  // Extra keyword patterns for memory detection (regex)
  "keywordPatterns": ["log\\s+this", "write\\s+down"],

  // OpenCode V1: context usage ratio that triggers compaction (0-1)
  "compactionThreshold": 0.8,

  // OpenCode 2: enrich native compaction with project memories and save summaries
  "compactionEnabled": true,

  // Save completed conversation batches every N turns (0 = session end only)
  "captureEveryNTurns": 3,

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

  // Override the directive used in advisory mode
  "recallDirective": null,
}

All fields optional.

Container tag selection

By default, new writes use:

• Repository tag: repo_{project-name}__{hash(normalized-origin-remote)}
• No origin remote: repo_{project-name}__{hash(real-repository-path)}

Older {prefix}_user_* and {prefix}_project_* containers remain readable. userContainerTag is treated as a legacy personal read. You can still override the unified write container with projectContainerTag:

{
  // Continue reading a personal container made by an older version
  "userContainerTag": "my-team-workspace",

  // Override the unified container used for new writes
  "projectContainerTag": "my-awesome-project",
}

This is useful to preserve a legacy personal memory container, sync memories between machines for the same project, organize memories with your own naming scheme, or integrate with existing Supermemory container tags from other tools.

Usage with Oh My OpenCode

If you're using Oh My OpenCode, disable its built-in auto-compact hook to let supermemory handle context compaction (or pass --disable-context-recovery to install):

{
  "disabled_hooks": ["anthropic-context-window-limit-recovery"]
}

Add that to ~/.config/opencode/oh-my-opencode.json.

bun install
bun run build
bun run typecheck

// ~/.config/opencode/opencode.jsonc
{
  "plugin": ["file:///path/to/opencode-supermemory"],
  "plugins": ["/path/to/opencode-supermemory"],
}

tail -f ~/.opencode-supermemory.log

License

MIT