diff --git a/README.md b/README.md index 9edaece..b0f9ea8 100644 --- a/README.md +++ b/README.md @@ -1,70 +1,68 @@ +
+ # 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 +
-### 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 -``` +
-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 -``` +
-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.
-Instructions for LLM Agents (click to expand) +Instructions for LLM agents +
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-init` command - -#### Step 2: Verify the config +**Step 2: Verify the config** ```bash 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 { @@ -75,23 +73,14 @@ 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 { @@ -99,21 +88,13 @@ For headless environments, users can still set `SUPERMEMORY_API_KEY` manually or } ``` -#### Step 4: Verify setup - -Tell the user to restart OpenCode and run: - -```bash -bunx opencode-supermemory@latest status -``` - -If it is not connected, check: +**Step 4: Verify setup** -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` +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. -#### Step 5: Initialize codebase memory (optional) +**Step 5: Initialize codebase memory (optional)** Run `/supermemory-init` to have the agent explore and memorize the codebase. @@ -121,15 +102,12 @@ 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: +| | | +| --- | --- | +| 🧠 **Context injection**
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**
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**
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 `` content is redacted. | 🗣️ **Keyword detection**
Saying "remember", "save this", "don't forget", or a custom pattern nudges the agent to save to memory. | +| 🧭 **Codebase indexing**
`/supermemory-init` has the agent explore and memorize the codebase's structure, patterns, and conventions. | 🗜️ **Preemptive compaction**
At 80% context capacity, triggers OpenCode's summarization, injects project memories into the summary, and saves the summary itself as a memory. | +| 🔒 **Privacy**
Content wrapped in `...` is never stored. | 🔔 **Update notices**
Checks npm for a newer release on session start and surfaces a one-line notice. | ``` [SUPERMEMORY] @@ -146,101 +124,65 @@ Relevant Memories: - [82%] Build fails if .env.local missing ``` -The agent uses this context automatically - no manual prompting needed. - -### Reasoned Recall - -On **every** turn, the agent is shown a short directive asking it to silently -decide whether recalling saved memory would improve its answer to *this* -message. The model searches only when earlier work, saved conventions, or user -preferences are likely to help; trivial and self-contained messages skip the -network call. - -Recall uses the `supermemory` tool in `search` mode and is auto-approved. -Customize the directive with `recallDirective`. Set `SUPERMEMORY_DEBUG=1` to -show a `[recall-decision]` line in each reply while testing. - -### Automatic Capture - -Completed conversations are captured automatically: - -- Every `captureEveryNTurns` completed turns, OpenCode saves the new turn batch. -- Any remaining turns are flushed when the session is deleted or the OpenCode - instance shuts down. -- Synthetic plugin context is excluded and `` content is redacted. -- Stable capture IDs make repeated lifecycle events idempotent. - -### 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: +That's what the agent sees on the first message, invisible to you, used automatically +with no manual prompting needed. -1. Triggers OpenCode's summarization -2. Injects project memories into summary context -3. Saves session summary as a memory +Set `SUPERMEMORY_DEBUG=1` to show a `[recall-decision]` line in each reply while testing +recall. -This preserves conversation context across compaction events. - -### Privacy - -``` -API key is sk-abc123 -``` - -Content in `` tags is never stored. - -## 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_`, `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 { @@ -265,13 +207,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) @@ -289,9 +236,9 @@ 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: @@ -299,8 +246,8 @@ By default, new writes use: - 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 { @@ -312,18 +259,15 @@ 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 { @@ -331,7 +275,11 @@ Add to `~/.config/opencode/oh-my-opencode.json`: } ``` -## Development +Add that to `~/.config/opencode/oh-my-opencode.json`. + +
+Development +
```bash bun install @@ -347,12 +295,14 @@ Local install: } ``` -## Logs +Logs: ```bash tail -f ~/.opencode-supermemory.log ``` +
+ ## License MIT