Skip to content

docs: revamp README with centered header and documented missing config/commands #84

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Dhravya merged 2 commits into from
Sep 23, 2026
+107 −114
Merged

docs: revamp README with centered header and documented missing config/commands #84

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
aadcfcc
docs: revamp README with centered header and documented missing confi…
ishaanxgupta Sep 3, 2026
a6dae54
Merge branch 'main' into docs/readme-refresh
Dhravya Sep 23, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
221 changes: 107 additions & 114 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,49 +1,60 @@
<div align="center">

# opencode-supermemory

OpenCode plugin for persistent memory using [Supermemory](https://supermemory.ai).
**Persistent memory for OpenCode, powered by [Supermemory](https://supermemory.ai)**

Your agent remembers what you tell it - across sessions, across projects.
[![npm version](https://img.shields.io/npm/v/opencode-supermemory?color=9C5C10&label=npm)](https://www.npmjs.com/package/opencode-supermemory)
[![license](https://img.shields.io/badge/license-MIT-9C5C10)](#license)
[![OpenCode](https://img.shields.io/badge/OpenCode-plugin-9C5C10)](https://github.com/supermemoryai/opencode-supermemory)

## Installation
</div>

### For Humans
OpenCode plugin for persistent memory using [Supermemory](https://supermemory.ai). Your
agent remembers what you tell it, across sessions and across projects.

```bash
bunx opencode-supermemory@latest install
```
<div align="center">

Then authenticate with Supermemory:
[Installation](#installation) · [Features](#features) · [Tool usage](#tool-usage) · [Memory scoping](#memory-scoping) · [Configuration](#configuration) · [License](#license)

```bash
bunx opencode-supermemory@latest login
```
</div>

---

Check the connection any time:
## Installation

```bash
bunx opencode-supermemory@latest status
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:
**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
```

### For LLM Agents
`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.

<details>
<summary>Instructions for LLM Agents (click to expand)</summary>
<summary>Instructions for LLM agents</summary>
<br>

If you're an LLM agent helping set up opencode-supermemory, follow these steps:

#### Step 1: Run the installer
**Step 1: Run the installer**

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

This will:
This registers the plugin in `~/.config/opencode/opencode.jsonc` and creates the
`/supermemory-init` command. Add `--disable-context-recovery` if the user also has
[Oh My OpenCode](#usage-with-oh-my-opencode) installed, to avoid its auto-compact hook
fighting with this plugin's compaction.

- Register the plugin in `~/.config/opencode/opencode.jsonc`
- Create the `/supermemory-index` command (`/supermemory-init` is an alias)
Expand All @@ -54,17 +65,7 @@ This will:
cat ~/.config/opencode/opencode.jsonc
```

Should contain:

```json
{
"plugin": ["opencode-supermemory"]
}
```

If not, add it manually:

**JSONC:**
Should contain `"plugin": ["opencode-supermemory"]`. If not, add it manually:

```jsonc
{
Expand All @@ -75,61 +76,41 @@ If not, add it manually:
}
```

**JSON:**

```json
{
"plugin": ["opencode-supermemory"]
}
```

#### Step 3: Authenticate

Run the browser authentication flow:
**Step 3: Authenticate**

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

For headless environments, users can still set `SUPERMEMORY_API_KEY` manually or create `~/.config/opencode/supermemory.jsonc`:
For headless environments, set `SUPERMEMORY_API_KEY` manually, or create
`~/.config/opencode/supermemory.jsonc`:

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

#### Step 4: Verify setup
**Step 4: Verify setup**

Tell the user to restart OpenCode and run:
Tell the user to restart OpenCode and run `bunx opencode-supermemory@latest status`. If
it's not connected, check: the user is authenticated (or `SUPERMEMORY_API_KEY` is set),
the plugin is in `opencode.jsonc`, and `~/.opencode-supermemory.log` for errors.

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

If it is not connected, check:

1. Is the user authenticated, or is `SUPERMEMORY_API_KEY` set?
2. Is the plugin in `opencode.jsonc`?
3. Check logs: `tail ~/.opencode-supermemory.log`

#### Step 5: Initialize codebase memory (optional)
**Step 5: Initialize codebase memory (optional)**

Run `/supermemory-index` to have the agent explore and memorize the codebase. `/supermemory-init` is an alias.

</details>

## Features

### Context Injection

On first message, the agent receives (invisible to user):

- Personal profile for the current project
- Project memories (all project knowledge)
- Relevant user memories (semantic search)

Example of what the agent sees:
| | |
| --- | --- |
| 🧠 **Context injection**<br>On a session's first message, the agent silently receives your profile, all project knowledge, and (if `autoRecallEveryPrompt` is on) a semantic search over personal memories. | 🔎 **Reasoned recall**<br>Every turn, the agent is shown a directive asking it to decide whether recalling memory would help before answering. It searches via the `supermemory` tool only when it decides to; the search itself is auto-approved. |
| 💾 **Automatic capture**<br>Completed turns are saved every `captureEveryNTurns` turns, with any remainder flushed when the session ends or OpenCode shuts down. Synthetic plugin context is excluded and `<private>` content is redacted. | 🗣️ **Keyword detection**<br>Saying "remember", "save this", "don't forget", or a custom pattern nudges the agent to save to memory. |
| 🧭 **Codebase indexing**<br>`/supermemory-init` has the agent explore and memorize the codebase's structure, patterns, and conventions. | 🗜️ **Preemptive compaction**<br>At 80% context capacity, triggers OpenCode's summarization, injects project memories into the summary, and saves the summary itself as a memory. |
| 🔒 **Privacy**<br>Content wrapped in `<private>...</private>` is never stored. | 🔔 **Update notices**<br>Checks npm for a newer release on session start and surfaces a one-line notice. |

```
[SUPERMEMORY]
Expand Down Expand Up @@ -189,58 +170,62 @@ Run `/supermemory-index` to explore and memorize your codebase structure, patter

When context hits 80% capacity:

1. Triggers OpenCode's summarization
2. Injects project memories into summary context
3. Saves session summary as a memory

This preserves conversation context across compaction events.

### Privacy

```
API key is <private>sk-abc123</private>
```

Content in `<private>` tags is never stored.
Set `SUPERMEMORY_DEBUG=1` to show a `[recall-decision]` line in each reply while testing
recall.

## Tool Usage
## Tool usage

The `supermemory` tool is available to the agent:

| Mode | Args | Description |
| --------- | ---------------------------- | ----------------- |
| `add` | `content`, `type?`, `scope?` | Store memory |
| `search` | `query`, `scope?` | Search memories |
| `profile` | `query?` | View user profile |
| `list` | `scope?`, `limit?` | List memories |
| `forget` | `memoryId`, `scope?` | Delete memory |
| Mode | Args | Description |
| --- | --- | --- |
| `add` | `content`, `type?`, `scope?` | Store memory |
| `search` | `query`, `scope?` | Search memories |
| `profile` | `query?` | View user profile |
| `list` | `scope?`, `limit?` | List memories |
| `forget` | `memoryId`, `scope?` | Delete memory |
| `help` | none | List available modes |

**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.
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

## Memory Scoping
| Scope | Tag | Metadata |
| --- | --- | --- |
| User | `repo_{project-name}__{repository-hash}` | `sm_scope: "personal"` |
| Project | `repo_{project-name}__{repository-hash}` | `sm_scope: "project"` |

| Scope | Tag | Metadata |
| ------- | ------------------------------------------- | ----------------------- |
| User | `repo_{project-name}__{repository-hash}` | `sm_scope: "personal"` |
| Project | `repo_{project-name}__{repository-hash}` | `sm_scope: "project"` |
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.

The repository hash comes from the normalized Git `origin` remote, so Claude
Code, Codex, 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_*`,
and `opencode_project_*` containers, so upgrading does not require a migration.
`opencode_project_*`, `cursor_user_*`, and `cursor_project_*` containers, so upgrading
does not require a migration.

## Configuration

Create `~/.config/opencode/supermemory.jsonc`:
### Environment variables

| Variable | Purpose |
| --- | --- |
| `SUPERMEMORY_API_KEY` | Your Supermemory API key (takes precedence over the config file). |
| `SUPERMEMORY_API_URL` / `SUPERMEMORY_BASE_URL` | Override the Supermemory API base URL. |
| `SUPERMEMORY_AUTH_URL` | Override the browser-auth base URL. |
| `SUPERMEMORY_AUTH_TIMEOUT` | Browser-auth timeout in milliseconds (default 5 minutes). |
| `SUPERMEMORY_REPO_TAG` | Explicit project-container override, checked before the config value. |
| `SUPERMEMORY_ISOLATE_WORKTREES` | Set to `true` to key the project container on the worktree path instead of the Git remote. |
| `SUPERMEMORY_DEBUG` | Set to show `[recall-decision]` lines and enable debug logging. |

### `~/.config/opencode/supermemory.jsonc`

```jsonc
{
Expand All @@ -265,13 +250,18 @@ Create `~/.config/opencode/supermemory.jsonc`:
// 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)
// Optional: set exact project container tag (overrides auto-generated tag)
"projectContainerTag": "my-project-tag",

// Extra keyword patterns for memory detection (regex)
Expand All @@ -289,18 +279,18 @@ Create `~/.config/opencode/supermemory.jsonc`:
}
```

All fields optional. Env var `SUPERMEMORY_API_KEY` takes precedence over config file.
All fields optional.

### Container Tag Selection
### 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`:
`userContainerTag` is treated as a legacy personal read. You can still override the
unified write container with `projectContainerTag`:

```jsonc
{
Expand All @@ -312,26 +302,27 @@ the unified write container with `projectContainerTag`:
}
```

This is useful when you want to:

- Preserve a legacy personal memory container
- Sync memories between different machines for the same project
- Organize memories using your own naming scheme
- Integrate with existing Supermemory container tags from other tools
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](https://github.com/code-yeongyu/oh-my-opencode), disable its built-in auto-compact hook to let supermemory handle context compaction:

Add to `~/.config/opencode/oh-my-opencode.json`:
If you're using [Oh My OpenCode](https://github.com/code-yeongyu/oh-my-opencode),
disable its built-in auto-compact hook to let supermemory handle context compaction
(or pass `--disable-context-recovery` to `install`):

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

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

<details>
<summary>Development</summary>
<br>

```bash
bun install
Expand All @@ -347,12 +338,14 @@ Local install:
}
```

## Logs
Logs:

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

</details>

## License

MIT
Loading