---
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.
**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.
## 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:
```bash
echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.zshrc
source ~/.zshrc
```
```bash
echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.bashrc
source ~/.bashrc
```
```powershell
[System.Environment]::SetEnvironmentVariable("SUPERMEMORY_API_KEY", "sm_...", "User")
```
Restart your terminal after running this.
OpenCode V1 and OpenCode 2 read different keys from `~/.config/opencode/opencode.jsonc`. Use the config for the version you run:
```jsonc
{
"plugin": ["opencode-supermemory@latest"]
}
```
```jsonc
{
"plugins": ["opencode-supermemory"],
"permissions": [
{ "action": "supermemory_recall", "resource": "*", "effect": "allow" }
]
}
```
The `permissions` rule lets the read-only `supermemory_recall` tool run without prompting.
The installer writes all three keys (`plugin`, `plugins`, and `permissions`) so that one file covers both versions. OpenCode V1 refuses to start when the file has a top-level `permissions` field ("V2 permissions are not supported by OpenCode V1"), so V1 users must remove `permissions` after installing. V1 ignores `plugins` with a warning, so you can remove it too.
## 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 `` 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
Source code, issues, and detailed README.
Memory plugin for Claude Code.