claude-supermemory

Persistent memory for Claude Code, powered by Supermemory

_{Conceptual overview. Some command names in the image predate the current plugin; see Commands for what's available now.}

A Claude Code plugin that gives your agent persistent memory across sessions using Supermemory. Your agent remembers what you worked on, across sessions and across projects.

Installation

Requires Node.js 18+ on your PATH. The memory hooks run as Node scripts.

/plugin marketplace add supermemoryai/claude-supermemory
/plugin install supermemory

Set your API key (get one at console.supermemory.ai), or just start a session and let browser login handle it:

export SUPERMEMORY_CC_API_KEY="sm_..."

/plugin marketplace update supermemory-plugins
/plugin install supermemory@supermemory-plugins

/plugin uninstall claude-supermemory@supermemory-plugins

Features

• Recall strip — On Claude Code 2.1.287+ in the terminal, press the changing memory headline above the prompt to browse the full returned facts one at a time

On Claude Code 2.1.250, local marketplace install/update and the SessionStart and UserPromptSubmit command hooks were verified, but claude plugin validate rejects the recall mod's classic.SessionStart event. The strip is not available on that version; other older versions and install sources have not been verified.

How it works

Claude Code supports hooks and MCP servers. supermemory registers four hooks, in lifecycle order:

SessionStart → UserPromptSubmit → PreToolUse → Stop

By default, recall is performed by the hook itself, not delegated to the model. It searches substantive prompts when authenticated, without waiting for Claude to choose a tool call. Setting recallDirective switches to advisory mode: the hook stops searching and instead tells Claude when it should decide to search on its own.

The hooks are tolerant: if Supermemory is unreachable, the API key is missing, or anything else fails, they exit cleanly without breaking your Claude Code session. A capture that fails is reported the next time a session starts.

Shared Agents memory

Claude Code, Codex, and OpenCode all generate the same container tag for a given repository, so new memories are shared:

repo_<project-name>__<remote-hash>   default container for capture and MCP memory tools
sm_scope: personal                   metadata on automatic captures

The hash is derived from the normalized Git remote, so clones share memory while same-named repositories do not collide. Repositories without a remote fall back to a local path identity. Set SUPERMEMORY_ISOLATE_WORKTREES=true to use the worktree path instead of the remote identity.

Unlike Codex, this plugin does not read older per-tool legacy containers (codex_user_*, opencode_project_*, and similar); it only ever uses the single unified identity above, overridden via the project namespace setting or the compatible repoContainerTag / SUPERMEMORY_REPO_TAG settings.

Configuration

Environment variables

Global settings (~/.supermemory-claude/settings.json)

{
  "maxProfileItems": 5,
  "signalExtraction": true,
  "signalKeywords": ["remember", "architecture", "decision", "bug", "fix"],
  "signalTurnsBefore": 3,
  "includeTools": ["Edit", "Write"]
}

Project config (.claude/.supermemory-claude/config.json)

Per-repo overrides, created manually or via the settings your team shares:

API key precedence is SUPERMEMORY_CC_API_KEY, project apiKey, then ~/.supermemory-claude/credentials.json.

{
  "apiKey": "sm_...",
  "baseUrl": "https://api.supermemory.ai",
  "namespace": "my-team-project",
  "signalExtraction": true
}

Advanced self-hosted compatibility

Hosted Supermemory uses v5 without a version choice. Existing custom REST URLs default to legacy, keeping v3 writes and v4 profiles for self-hosted servers older than 0.0.9. After upgrading the server, explicitly set SUPERMEMORY_API_VERSION=v5 or project apiVersion: "v5". The environment setting takes precedence; legacy is also an explicit rollback option for a server that still supports v3/v4. Invalid values fail closed for memory operations. There is no automatic version fallback after a failed request and no fallback to the hosted API. REST, MCP, and browser-auth URLs remain separate.

Scope precedence is project namespace, project repoContainerTag, SUPERMEMORY_REPO_TAG, then the generated identity. Keep an existing override's exact value when renaming its setting: changing the value selects another space, not a data migration. V5 scopes allow 1–100 letters, digits, underscores, hyphens, or colons; invalid scopes are rejected before any request without rewriting config or capture cursors.

Hosted Supermemory applies the same rule to legacy endpoints, so a scope with a dot, slash, or space must be renamed; the new value starts a new memory space. A self-hosted server that still accepts such a scope through v3/v4 can keep it with SUPERMEMORY_API_VERSION=legacy or project apiVersion: "legacy". There is no automatic switch or failed-write retry across protocols.

Commands

Search does not have its own command. With a key, the prompt hook searches substantive prompts. For deeper history, use the context-gatherer agent or the MCP tools. /supermemory:index saves codebase structure. For a one-off save, ask Claude to use the add_memory MCP tool. Without containerTag, the proxy defaults it to this repository's container; pass a different tag to select another space. Conversation turns are saved when a session ends.

Privacy

Automatic capture sends new conversation content to Supermemory, including tool content when configured. Before saving, an offline filter replaces common credential-shaped values (provider tokens, credential assignments, private keys, Bearer tokens, and URL credentials) with explicit [REDACTED:…] markers while keeping surrounding context. It cannot detect every secret. Existing stored memories and local transcripts are not rewritten; explicit MCP tool calls and recall queries are not filtered by this capture-only protection.

For information about how Supermemory collects, uses, and retains data, see the Supermemory Privacy Policy.

License

MIT

Development runtime

Marketplace installations need only Node 18 or later, not npm install. plugin/hooks/vendor/supermemory.cjs is the committed runtime bundle built from the exact official SDK and esbuild versions in package-lock.json. Maintainers reproduce it with npm ci && npm run build:sdk; CI rejects a stale bundle. The SDK's Apache-2.0 license is included alongside the generated bundle.