> ## Documentation Index
> Fetch the complete documentation index at: https://supermemory.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode

> Supermemory plugin for OpenCode. Keeps memory across coding sessions.

[OpenCode-Supermemory](https://github.com/supermemoryai/opencode-supermemory) is an OpenCode plugin that gives your AI persistent memory across sessions. Your agent remembers what you worked on — across sessions, across projects.

> [!TIP]
>
> **Prefer to keep everything on your machine?** This plugin works with [self-hosted Supermemory](https://supermemory.ai/docs/self-hosting/overview.md) — run `npx supermemory local`, then set `apiKey` / base URL in `~/.config/opencode/supermemory.jsonc` and use the API key printed on first boot.

## Install the plugin

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bunx opencode-supermemory@latest install
```

For LLM agents (non-interactive):

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bunx opencode-supermemory@latest install --no-tui
```

## Authenticate

Browser login (recommended):

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bunx opencode-supermemory@latest login
```

You can manage the plugin, change its access, or disconnect it from the [Agents page](https://console.supermemory.ai/agents) in the console.

Check the connection any time:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
bunx opencode-supermemory@latest status
```

Or set an API key manually from the [API Keys](https://console.supermemory.ai/keys) page in the console:

> [tab] macOS / Linux (zsh)
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.zshrc
> source ~/.zshrc
> ```

> [tab] macOS / Linux (bash)
>
> ```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.bashrc
> source ~/.bashrc
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
> [System.Environment]::SetEnvironmentVariable("SUPERMEMORY_API_KEY", "sm_...", "User")
> ```
>
> Restart your terminal after running this.

The installer adds Supermemory to `~/.config/opencode/opencode.jsonc`. This one config works on both OpenCode v1 and v2:

```jsonc theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "plugin": ["opencode-supermemory@latest"],
  "plugins": ["opencode-supermemory"],
  "permission": { "supermemory_recall": "allow" }
}
```

If OpenCode won't start after an older install, run the installer again to update your config.

## How it works

Once installed, the plugin runs automatically:

* **Context Injection** — On a session's first message, your profile facts are injected into the agent's context.
* **Direct Recall** — On every substantive prompt, the plugin searches the current project and injects up to five fresh matches. Set `recallMode` to `"advisory"` to let the agent decide when to search, or `"off"` to disable it.
* **Automatic Capture** — Completed turns are saved every `captureEveryNTurns` turns (fresh installs use `0`, which saves only at the end), and any remainder is flushed when the session ends or OpenCode shuts down.
* **Keyword Detection** — Phrases like "remember" or "save this" nudge the agent to save to memory.
* **Smart Compaction** — On OpenCode v1, sessions are summarized at 80% context capacity; on OpenCode v2, the plugin enriches native compaction. Both save the summary as a memory.
* **Privacy Protection** — Content within `<private>` tags never persists.

### Memory scopes

Both scopes write to one repository container, `repo_{project-name}__{repository-hash}`, shared with the Claude Code, Codex, and Cursor plugins. `sm_scope` metadata keeps them apart.

| Scope | Description |
| - | - |
| `user` | Personal memories for the current project |
| `project` | Project knowledge for the current project (default) |

### Memory types

| Type | Description |
| - | - |
| `project-config` | Project configuration and setup details |
| `architecture` | Codebase structure and design patterns |
| `error-solution` | Problems encountered and their fixes |
| `preference` | User preferences and coding style |
| `learned-pattern` | Patterns discovered during sessions |
| `conversation` | Important conversation context |

## Commands

The installer adds these in-chat commands:

| Command | Description |
| - | - |
| `/supermemory-index` | Explore and index your codebase structure into memory (`/supermemory-init` is an alias) |
| `/supermemory-login` | Authenticate with Supermemory in the browser |
| `/supermemory-logout` | Clear stored credentials |
| `/supermemory-status` | Show the Supermemory connection status |

## Tools

The agent has access to a `supermemory` tool with these modes:

| Mode | Parameters | Function |
| - | - | - |
| `add` | content, type?, scope? | Store information |
| `search` | query, scope? | Find relevant memories |
| `profile` | query? | View user preferences |
| `list` | scope?, limit? | Display stored items |
| `forget` | memoryId, scope? | Remove memory |
| `help` | none | List available modes |

## Configuration

Create `~/.config/opencode/supermemory.jsonc`:

```jsonc theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
{
  "apiKey": "sm_...",              // Or use SUPERMEMORY_API_KEY / browser login
  "baseUrl": "https://api.supermemory.ai", // Or SUPERMEMORY_API_URL (self-hosted)
  "similarityThreshold": 0.55,     // Minimum match score (0-1)
  "maxMemories": 5,                // Memories per injection
  "maxProjectMemories": 10,        // Project memory listings
  "maxProfileItems": 5,            // Profile facts injected
  "injectProfile": true,           // Include user preferences in context
  "projectContainerTag": "my-project-tag", // Optional: override the repository container
  "keywordPatterns": ["log\\s+this"],      // Extra auto-save triggers
  "recallMode": "direct",          // "direct", "advisory", or "off"
  "captureEveryNTurns": 3,         // Save completed turns every N turns (0 = session end only)
  "compactionThreshold": 0.80,     // OpenCode v1: context usage ratio for summarization
  "compactionEnabled": true        // OpenCode v2: enrich native compaction and save summaries
}
```

## Logging

View plugin activity:

```bash theme={"theme":{"light":"github-light-default","dark":"github-dark-default"}}
tail -f ~/.opencode-supermemory.log
```

## Next steps

> [card] [GitHub repository](https://github.com/supermemoryai/opencode-supermemory)
>
> Source code, issues, and detailed README.

> [card] [Claude Code plugin](https://supermemory.ai/docs/integrations/claude-code.md)
>
> Memory plugin for Claude Code.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.