supermemory/apps/docs/integrations/opencode.mdx

---
title: "OpenCode"
sidebarTitle: "OpenCode"
description: "Supermemory plugin for OpenCode. Keeps memory across coding sessions."
icon: "/images/opencode-logo.svg"
---

[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](/self-hosting/overview) — run `npx supermemory local`, then set `apiKey` / base URL in `~/.config/opencode/supermemory.jsonc` and use the API key printed on first boot.
</Tip>

## Install the plugin

```bash
bunx opencode-supermemory@latest install
```

For LLM agents (non-interactive):

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

## Authenticate

Browser login (recommended):

```bash
bunx opencode-supermemory@latest login
```

Check the connection any time:

```bash
bunx opencode-supermemory@latest status
```

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

<Tabs>
  <Tab title="macOS / Linux (zsh)">
    ```bash
    echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>
  <Tab title="macOS / Linux (bash)">
    ```bash
    echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>
  <Tab title="Windows (PowerShell)">
    ```powershell
    [System.Environment]::SetEnvironmentVariable("SUPERMEMORY_API_KEY", "sm_...", "User")
    ```
    Restart your terminal after running this.
  </Tab>
</Tabs>

The installer registers the plugin for both OpenCode V1 (`plugin`) and OpenCode 2 (`plugins`). Ensure your `~/.config/opencode/opencode.jsonc` contains:

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

## 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 2, 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
{
  "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 2: enrich native compaction and save summaries
}
```

## Logging

View plugin activity:

```bash
tail -f ~/.opencode-supermemory.log
```

## Next steps

<CardGroup cols={2}>
  <Card title="GitHub repository" icon="/images/github-icon.svg" href="https://github.com/supermemoryai/opencode-supermemory">
    Source code, issues, and detailed README.
  </Card>

  <Card title="Claude Code plugin" icon="/icons/hugeicons/source-code.svg" href="/integrations/claude-code">
    Memory plugin for Claude Code.
  </Card>
</CardGroup>