# opencode-supermemory (fork)

> **Fork of [supermemoryai/opencode-supermemory](https://github.com/supermemoryai/opencode-supermemory)** with a fix for the Part ID schema validation crash introduced in OpenCode v1.2.25+.
>
> **What was fixed:** The original plugin generates message Part IDs with `supermemory-nudge-*` and `supermemory-context-*` prefixes. OpenCode v1.2.25 ([commit 090f636](https://github.com/anomalyco/opencode/commit/090f636), PR #16966) introduced strict Zod validation requiring all Part IDs to start with `prt`. This caused a `ZodError` crash in `createUserMessage()` on every message. This fork generates compliant `prt_`-prefixed IDs.
>
> Upstream issue: [supermemoryai/opencode-supermemory#28](https://github.com/supermemoryai/opencode-supermemory/issues/28)

---

OpenCode plugin for persistent memory using [Supermemory](https://supermemory.ai).

Your agent remembers what you tell it - across sessions, across projects.
## Installation

### For Humans

```bash
bunx github:pondzikk/opencode-supermemory install
```

Then get your API key from [app.supermemory.ai](https://app.supermemory.ai/?view=integrations) and set it:

```bash
export SUPERMEMORY_API_KEY="sm_..."
```

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

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

### For LLM Agents

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

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

#### Step 1: Run the installer

```bash
bunx github:pondzikk/opencode-supermemory install --no-tui
```

This will:

- Register the plugin in `~/.config/opencode/opencode.jsonc`
- Create the `/supermemory-init` command

#### Step 2: Verify the config

```bash
cat ~/.config/opencode/opencode.jsonc
```

Should contain:

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

If not, add it manually:

**JSONC:**

```jsonc
{
  "plugin": [
    "github:pondzikk/opencode-supermemory",
    // ... other plugins
  ],
}
```

**JSON:**

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

#### Step 3: Configure API key

Ask the user to get their API key from [app.supermemory.ai](https://app.supermemory.ai/?view=integrations).

Then set it via environment variable:

```bash
export SUPERMEMORY_API_KEY="sm_..."
```

Or create `~/.config/opencode/supermemory.jsonc`:

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

#### Step 4: Verify setup

Tell the user to restart OpenCode and run:

```bash
opencode -c
```

They should see `supermemory` in the tools list. If not, check:

1. 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)

Run `/supermemory-init` to have the agent explore and memorize the codebase.

</details>

## Features

### Context Injection

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

- User profile (cross-project preferences)
- Project memories (all project knowledge)
- Relevant user memories (semantic search)

Example of what the agent sees:

```
[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.

### 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-init` to explore and memorize your codebase structure, patterns, and conventions.

### Preemptive Compaction

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.

## 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     |

**Scopes:** `user` (cross-project), `project` (default)

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

## Memory Scoping

| Scope   | Tag                                    | Persists     |
| ------- | -------------------------------------- | ------------ |
| User    | `opencode_user_{sha256(git email)}`    | All projects |
| Project | `opencode_project_{sha256(directory)}` | This project |

## Configuration

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

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

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

  // 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,

  // Prefix for container tags (used when userContainerTag/projectContainerTag not set)
  "containerTagPrefix": "opencode",

  // Optional: Set exact user container tag (overrides auto-generated tag)
  "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"],

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

  // Enable semantic reranking of search results (improves relevance)
  "enableRerank": true,

  // Entity context for user memory extraction (describes the user's role/domain)
  "userEntityContext": "This is a software developer's personal context. Extract preferences, coding style, tool choices, workflow patterns, and technical decisions.",

  // Entity context for project memory extraction (describes the project domain)
  "projectEntityContext": "This is a software project's codebase context. Extract architecture decisions, file structure patterns, dependency choices, conventions, and known issues."
}
```

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

### Container Tag Selection

By default, container tags are auto-generated using `containerTagPrefix` plus a hash:

- User tag: `{prefix}_user_{hash(git_email)}`
- Project tag: `{prefix}_project_{hash(directory)}`

You can override this by specifying exact container tags:

```jsonc
{
  // Use a specific container tag for user memories
  "userContainerTag": "my-team-workspace",

  // Use a specific container tag for project memories
  "projectContainerTag": "my-awesome-project",
}
```

This is useful when you want to:

- Share memories across team members (same `userContainerTag`)
- 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

## Improvements Over Upstream

1. **Semantic Reranking** (`enableRerank: true`) — Search results are reranked for better relevance using Supermemory's native rerank API
2. **Stable Memory IDs** (`customId`) — Memories get SHA-256-based custom IDs preventing duplicate entries on re-ingestion
3. **Entity Context** (`userEntityContext`, `projectEntityContext`) — Memories are stored with entity context descriptions that improve extraction quality
4. **Native Conversation Ingestion** — Multi-turn conversations use Supermemory's `/v4/conversations` endpoint (with fallback to structured text)
5. **Soft-Delete** — Memory deletion uses `memories.forget()` (recoverable) instead of hard delete
6. **Profile Search Dedup** — On context injection, if the profile API returns embedded search results, the separate `searchMemories()` call is skipped (saves 1 API call per message)

*Note: The `prt_` prefix fix is preserved from the original fork.*

## 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`:

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

## Development

```bash
bun install
bun run build
bun run typecheck
```

Local install:

```jsonc
{
  "plugin": ["file:///path/to/opencode-supermemory"],
}
```

## Logs

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

## License

MIT