opencode-supermemory

OpenCode plugin for persistent memory using Supermemory.

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

Installation

For Humans

bunx opencode-supermemory@latest install

Then authenticate with Supermemory:

bunx opencode-supermemory@latest login

Check the connection any time:

bunx opencode-supermemory@latest status

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

Instructions for LLM Agents (click to expand)

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

Step 1: Run the installer

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

This will:

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

Step 2: Verify the config

cat ~/.config/opencode/opencode.jsonc

Should contain:

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

If not, add it manually:

JSONC:

{
  "plugin": [
    "opencode-supermemory",
    // ... other plugins
  ],
}

JSON:

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

Step 3: Authenticate

Run the browser authentication flow:

bunx opencode-supermemory@latest login

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

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

Step 4: Verify setup

Tell the user to restart OpenCode and run:

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)

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

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:

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

Memory Scoping

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

Configuration

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

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

  // Supermemory API base URL (point at a self-hosted instance, e.g. http://localhost:8787)
  "baseUrl": "https://api.supermemory.ai",

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

  // 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)
  "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,
}

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

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:

{
  // Continue reading a personal container made by an older version
  "userContainerTag": "my-team-workspace",

  // Override the unified container used for new writes
  "projectContainerTag": "my-awesome-project",
}

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

Usage with Oh My OpenCode

If you're using Oh My OpenCode, disable its built-in auto-compact hook to let supermemory handle context compaction:

Add to ~/.config/opencode/oh-my-opencode.json:

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

Development

bun install
bun run build
bun run typecheck

Local install:

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

Logs

tail -f ~/.opencode-supermemory.log

License

MIT