Skip to content
Back to search

supermemory-plugins

MarketplaceWorks with Claude CodeGitHub

Supermemory plugins for Claude Code — persistent memory across sessions and projects

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/supermemoryai/claude-supermemory with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/supermemoryai/claude-supermemory'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/supermemoryai-claude-supermemory/badge.svg)](/listings/supermemoryai-claude-supermemory)

HTML

<a href="/listings/supermemoryai-claude-supermemory"><img src="/api/listings/supermemoryai-claude-supermemory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **Requires Node.js 18+** on your PATH — the memory hooks run as Node scripts.

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

> **Already have the old `claude-supermemory` plugin installed?** It was renamed to `supermemory`, so it won't update in place. Migrate with: > > ```bash > /plugin marketplace update supermemory-plugins > /plugin install supermemory@supermemory-plugins > ``` > > Then, **only if you still have the old plugin**, remove it: > > ```bash > /plugin uninstall claude-supermemory@supermemory-plugins > ```

Set your API key (get one at [console.supermemory.ai](https://console.supermemory.ai)):

export SUPERMEMORY_CC_API_KEY="sm_..."

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 19 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "name": "supermemory-plugins",
  3. "description": "Supermemory plugins for Claude Code — persistent memory across sessions and projects",
  4. "owner": {
  5. "name": "Supermemory",
  6. "email": "support@supermemory.ai"
  7. },
  8. "plugins": [
  9. {
  10. "name": "supermemory",
  11. "source": "./plugin",
  12. "description": "Persistent memory across Claude Code sessions using Supermemory",
  13. "category": "productivity",
  14. "author": {
  15. "name": "Supermemory"
  16. }
  17. }
  18. ]
  19. }
README.md · README · 330 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # claude-supermemory
  3. **Persistent memory for Claude Code, powered by [Supermemory](https://supermemory.ai)**
  4. [![version](https://img.shields.io/github/package-json/v/supermemoryai/claude-supermemory/main?filename=plugin%2F.claude-plugin%2Fplugin.json&label=version&color=9C5C10)](https://github.com/supermemoryai/claude-supermemory)
  5. [![license](https://img.shields.io/badge/license-MIT-9C5C10)](#license)
  6. <img width="4000" height="2130" alt="Conceptual overview of Claude Code and Supermemory" src="https://github.com/user-attachments/assets/07e63ac4-b67d-457b-9029-1dc5d860e920" />
  7. <sub>Conceptual overview. Some command names in the image predate the current plugin; see <a href="#commands">Commands</a> for what's available now.</sub>
  8. </div>
  9. A Claude Code plugin that gives your agent persistent memory across sessions using
  10. [Supermemory](https://supermemory.ai). Your agent remembers what you worked on, across
  11. sessions and across projects.
  12. <div align="center">
  13. [Install](#installation) · [Features](#features) · [How it works](#how-it-works) · [Shared containers](#shared-agents-memory) · [Configuration](#configuration) · [Commands](#commands) · [Privacy](#privacy)
  14. </div>
  15. ---
  16. ## Installation
  17. > **Requires Node.js 18+** on your PATH. The memory hooks run as Node scripts.
  18. ```bash
  19. /plugin marketplace add supermemoryai/claude-supermemory
  20. /plugin install supermemory
  21. ```
  22. Set your API key (get one at [console.supermemory.ai](https://console.supermemory.ai)),
  23. or just start a session and let browser login handle it:
  24. ```bash
  25. export SUPERMEMORY_CC_API_KEY="sm_..."
  26. ```
  27. <details>
  28. <summary>Migrating from the old <code>claude-supermemory</code> plugin</summary>
  29. <br>
  30. That plugin was renamed to `supermemory`, so it won't update in place. Migrate with:
  31. ```bash
  32. /plugin marketplace update supermemory-plugins
  33. /plugin install supermemory@supermemory-plugins
  34. ```
  35. Then, only if you still have the old plugin installed, remove it:
  36. ```bash
  37. /plugin uninstall claude-supermemory@supermemory-plugins
  38. ```
  39. </details>
  40. ## Features
  41. | | |
  42. | --- | --- |
  43. | 🧠 **Direct recall**<br>When authenticated, the hook searches substantive prompts before Claude sees them and injects fresh matches. No permission prompt or MCP tool call. | 🔎 **Hosted MCP tools**<br>`search_memory`, `listSpaces`, `whoAmI`, and more are available through the same credentials as the hooks, subject to your Claude Code permissions. |
  44. | 💾 **Auto capture**<br>At the end of a session, the Stop hook saves new conversation content in the background. It asks Supermemory to retain durable context rather than transient Git state. | 🏷️ **Shared repo memory**<br>Automatic captures use the repository container shared with Codex and OpenCode and carry `sm_scope: personal` metadata. |
  45. | 🧭 **Deep multi-container search**<br>The `context-gatherer` subagent fans out several searches across a project's containers and returns a synthesized brief. | ⚙️ **Project config**<br>Per-repo settings, API keys, and container tag overrides via `.claude/.supermemory-claude/config.json`. |
  46. | 🗂️ **Codebase index**<br>`/supermemory:index` saves architecture, conventions, and how to run into this project's container. | 👋 **Session context**<br>Loads profile facts at session start and shows a welcome-back notice when you return to a project after 6+ hours. |
  47. - **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
  48. 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.
  49. ## How it works
  50. Claude Code supports hooks and MCP servers. `supermemory` registers four hooks, in lifecycle order:
  51. **`SessionStart`** → **`UserPromptSubmit`** → **`PreToolUse`** → **`Stop`**
  52. | Step | Hook | Event | What it does |
  53. | --- | --- | --- | --- |
  54. | 1 | `session-start` | `SessionStart` | Bootstraps auth and loads profile context plus a welcome-back notice. It does not install a statusline; an old auto-installed one is removed. |
  55. | 2 | `recall-directive` | `UserPromptSubmit` | Searches Supermemory directly with the prompt and injects fresh matches, deduplicated within the session. |
  56. | 3 | `recall-approve` | `PreToolUse` | Displays read-only Supermemory activity without approving calls or changing their input. |
  57. | 4 | `capture` | `Stop` | Saves the completed conversation delta in the background. |
  58. By default, recall is performed by the hook itself, not delegated to the model. It searches
  59. substantive prompts when authenticated, without waiting for Claude to choose a tool call.
  60. Setting `recallDirective` switches to advisory mode: the hook stops searching and instead
  61. tells Claude when it should decide to search on its own.
  62. The hooks are tolerant: if Supermemory is unreachable, the API key is missing, or
  63. anything else fails, they exit cleanly without breaking your Claude Code session.
  64. A capture that fails is reported the next time a session starts.
  65. ### Directory review and permissions
  66. MCP tool calls follow your Claude Code permission rules. The `PreToolUse` hook
  67. only displays recall activity and records search counts; it does not approve
  68. calls or change their input. The index and status commands do not grant blanket
  69. shell access. Direct recall and capture still run as the lifecycle hooks you
  70. enabled when installing the plugin.
  71. The MCP declaration passes `https://mcp.supermemory.ai/mcp` literally to the
  72. bundled proxy as its default endpoint. The proxy uses that argument for the
  73. standard hosted configuration, shares the hooks' authentication, and supplies
  74. the current repository's default container. Existing `SUPERMEMORY_MCP_URL`,
  75. custom API backend settings, API keys, stored credentials, and OAuth refresh
  76. remain supported. Running the proxy without the argument retains its previous
  77. endpoint resolution.
  78. The optional recall-strip mod observes `classic.SessionStart` and
  79. `classic.UserPromptSubmit`. It calls `next(e)` with the original event, reads
  80. returned memory facts for its terminal display, and returns the same result
  81. object. It does not replace the first user message, edit permission settings,
  82. register agents, or alter tool inputs. Its `ui.render` hook adds the expandable
  83. recall strip above the terminal prompt. The Directory's static policy check may
  84. still require a reviewer to confirm this pass-through behavior.
  85. The credential-related review holds require review of the existing Supermemory
  86. sign-in flow, not a replacement of users' keys. Credentials are used for the
  87. configured Supermemory API and MCP endpoints. No new `user_config` credential
  88. flow is introduced by this change. Directory acceptance and publisher ownership
  89. must be confirmed in the submission portal; local validation is not approval.
  90. ### Shared Agents memory
  91. Claude Code, Codex, and OpenCode all generate the same container tag for a given
  92. repository, so new memories are shared:
  93. ```text
  94. repo_<project-name>__<remote-hash> default container for capture and MCP memory tools
  95. sm_scope: personal metadata on automatic captures
  96. ```
  97. The hash is derived from the normalized Git remote, so clones share memory while
  98. same-named repositories do not collide. Repositories without a remote fall back to
  99. a local path identity. Linked worktrees (`git worktree add`, Conductor, Claude
  100. Squad, `claude --worktree`) resolve to the main checkout's identity, with or
  101. without a remote. Set `SUPERMEMORY_ISOLATE_WORKTREES=true` to use the worktree
  102. path instead of the remote identity.
  103. Unlike Codex, this plugin does not read older per-tool legacy containers
  104. (`codex_user_*`, `opencode_project_*`, and similar); it only ever uses the single
  105. unified identity above, overridden via the project `namespace` setting
  106. or the compatible `repoContainerTag` / `SUPERMEMORY_REPO_TAG` settings.
  107. ### Which sessions are remembered
  108. By default the hooks make no Supermemory calls (no profile, no prompt recall,
  109. no capture) for sessions nobody is typing into. They decide this only from
  110. signals Claude Code sets:
  111. | Session | Signal | Opt back in |
  112. | --- | --- | --- |
  113. | Background subagent results relayed to the main session | the `<task-notification>` turn (`origin.kind: "task-notification"` in the transcript; scheduled fires and inbox messages still count as yours) | `captureSubagents: true` / `SUPERMEMORY_CAPTURE_SUBAGENTS=true` |
  114. | `claude -p` and GitHub Action runs | `CLAUDE_CODE_ENTRYPOINT` is `claude-code-github-action`, or `sdk-cli` while that Claude Code process is itself in print mode (`CLAUDE_CODE_SESSION_ATTENDED=0`, or `-p` / `--print` / `--output-format` on older builds) | `captureHeadless: true` / `SUPERMEMORY_CAPTURE_HEADLESS=true` |
  115. Subagents never run these hooks: Claude Code fires only `SubagentStart` and
  116. `SubagentStop` inside them, so their work reaches memory only through the
  117. main session. Claude Code's own helper prompts (session titles, prompt
  118. suggestions, the auto mode classifier) never run these hooks either.
  119. An interactive `claude` that merely inherited `CLAUDE_CODE_ENTRYPOINT=sdk-cli`
  120. (for example one started from a shell a `claude -p` run spawned) stays on.
  121. Agent SDK apps (`sdk-ts`, `sdk-py`), including editors such as Zed that drive
  122. Claude Code over ACP, are treated as interactive and keep recall and capture.
  123. To keep an SDK app out of memory, run it without this plugin: leave `"user"`
  124. out of the SDK's `settingSources`, or disable the plugin for that app.
  125. Sessions started by Conductor or Vibe Kanban (`CONDUCTOR_WORKSPACE_PATH`,
  126. `CONDUCTOR_SESSION_ID` or `VK_WORKSPACE_ID` set) are real user work and stay
  127. on even though they run through `claude -p`; set `captureOrchestrated: false`
  128. or `SUPERMEMORY_CAPTURE_ORCHESTRATED=false` to turn them off. Crystal sets no
  129. such variable, so its `claude -p` sessions count as headless.
  130. For swarms that replay one task across many sessions, two local indexes in
  131. `~/.supermemory-claude` (hashes only) cut repeats:
  132. - **Opening prompt**: a session whose opening prompt (at least 200 characters)
  133. was already captured from this machine for the same container in the last 24
  134. hours saves the session with a one-line
  135. `[opening prompt already captured from this machine: <hash>]` marker in place
  136. of the prompt. Opt out with `dedupeOpeningPrompt: false` /
  137. `SUPERMEMORY_DEDUPE_OPENING_PROMPT=false`.
  138. - **Recall query**: when the exact same query (whitespace-normalized) was
  139. recalled successfully by another session for the same container in the last
  140. 10 minutes, the hook re-serves that result from `recall-cache.json` instead of calling the API. A
  141. failed or timed-out search is never cached. Opt out with `dedupeRecallQueries: false` /
  142. `SUPERMEMORY_DEDUPE_RECALL_QUERIES=false`.
  143. ## Configuration
  144. ### Environment variables
  145. | Variable | Purpose |
  146. | --- | --- |
  147. | `SUPERMEMORY_CC_API_KEY` | Your Supermemory API key (browser auth is preferred). |
  148. | `SUPERMEMORY_API_URL` | Override the Supermemory REST base URL; custom URLs default to legacy compatibility. |
  149. | `SUPERMEMORY_MCP_URL` | Override the hosted MCP endpoint (default `https://mcp.supermemory.ai/mcp`). |
  150. | `SUPERMEMORY_AUTH_URL` | Override the browser-auth base URL. |
  151. | `SUPERMEMORY_REPO_TAG` | Project-scope override; used when no project scope setting is set. |
  152. | `SUPERMEMORY_ISOLATE_WORKTREES` | Set to `true` to key the project container on the worktree path instead of the Git remote. |
  153. | `SUPERMEMORY_DEBUG` | Set to `true` to enable debug logging. |
  154. | `SUPERMEMORY_CAPTURE_SUBAGENTS` | `true`/`1`/`yes`/`on` or `false`/`0`/`no`/`off`; overrides `captureSubagents`. |
  155. | `SUPERMEMORY_CAPTURE_HEADLESS` | `true`/`1`/`yes`/`on` or `false`/`0`/`no`/`off`; overrides `captureHeadless`. |
  156. | `SUPERMEMORY_CAPTURE_ORCHESTRATED` | `true`/`1`/`yes`/`on` or `false`/`0`/`no`/`off`; overrides `captureOrchestrated`. |
  157. | `SUPERMEMORY_DEDUPE_OPENING_PROMPT` | `true`/`1`/`yes`/`on` or `false`/`0`/`no`/`off`; overrides `dedupeOpeningPrompt`. |
  158. | `SUPERMEMORY_DEDUPE_RECALL_QUERIES` | `true`/`1`/`yes`/`on` or `false`/`0`/`no`/`off`; overrides `dedupeRecallQueries`. |
  159. ### Global settings (`~/.supermemory-claude/settings.json`)
  160. ```json
  161. {
  162. "maxProfileItems": 5,
  163. "signalExtraction": true,
  164. "signalKeywords": ["remember", "architecture", "decision", "bug", "fix"],
  165. "signalTurnsBefore": 3,
  166. "includeTools": ["Edit", "Write"]
  167. }
  168. ```
  169. | Option | Description |
  170. | --- | --- |
  171. | `maxProfileItems` | Max memories in context (default: 5). |
  172. | `recallDirective` | Set to switch prompt recall from direct hook search to an advisory instruction Claude reasons over. |
  173. | `signalExtraction` | Only capture important turns (default: false). |
  174. | `signalKeywords` | Keywords that trigger capture. |
  175. | `signalTurnsBefore` | Context turns before signal (default: 3). |
  176. | `includeTools` | Tool calls to explicitly capture. |
  177. | `debug` | Enable debug logging (default: false). |
  178. | `captureSubagents` | Recall and capture for relayed background-subagent results (default: false). |
  179. | `captureHeadless` | Recall and capture for `claude -p` and GitHub Action runs (default: false). |
  180. | `captureOrchestrated` | Recall and capture for Conductor and Vibe Kanban sessions (default: true). |
  181. | `dedupeOpeningPrompt` | Replace an opening prompt of 200+ characters captured from this machine in the last 24 hours with a marker (default: true). |
  182. | `dedupeRecallQueries` | Re-serve the cached result of the same query another session recalled in the last 10 minutes (default: true). |
  183. ### Project config (`.claude/.supermemory-claude/config.json`)
  184. Per-repo overrides, created manually or via the settings your team shares:
  185. API key precedence is `SUPERMEMORY_CC_API_KEY`, project `apiKey`, then
  186. `~/.supermemory-claude/credentials.json`.
  187. ```json
  188. {
  189. "apiKey": "sm_...",
  190. "baseUrl": "https://api.supermemory.ai",
  191. "namespace": "my-team-project",
  192. "signalExtraction": true
  193. }
  194. ```
  195. | Option | Description |
  196. | --- | --- |
  197. | `apiKey` | Project-specific API key. |
  198. | `baseUrl` | Supermemory API URL. |
  199. | `namespace` | Canonical project scope, preserving the exact old container-tag value. |
  200. | `repoContainerTag` | Override the unified project container tag. Checked before `SUPERMEMORY_REPO_TAG`. |
  201. ### Advanced self-hosted compatibility
  202. Hosted Supermemory uses v5 without a version choice. Existing custom REST URLs
  203. default to `legacy`, keeping v3 writes and v4 profiles for self-hosted servers
  204. older than 0.0.9. After upgrading the server, explicitly set
  205. `SUPERMEMORY_API_VERSION=v5` or project `apiVersion: "v5"`. The environment
  206. setting takes precedence; `legacy` is also an explicit rollback option for a
  207. server that still supports v3/v4. Invalid values fail closed for memory operations.
  208. There is no automatic version fallback after a failed request and no fallback to
  209. the hosted API. REST, MCP, and browser-auth URLs remain separate.
  210. Scope precedence is project `namespace`, project `repoContainerTag`,
  211. `SUPERMEMORY_REPO_TAG`, then the generated identity.
  212. Keep an existing override's exact value when renaming its setting: changing the
  213. value selects another space, not a data migration. V5 scopes allow 1–100 letters,
  214. digits, underscores, hyphens, or colons; invalid scopes are rejected before any
  215. request without rewriting config or capture cursors.
  216. Hosted Supermemory applies the same rule to legacy endpoints, so a scope with a
  217. dot, slash, or space must be renamed; the new value starts a new memory space.
  218. A self-hosted server that still accepts such a scope through v3/v4 can keep it with
  219. `SUPERMEMORY_API_VERSION=legacy` or project `apiVersion: "legacy"`. There is no
  220. automatic switch or failed-write retry across protocols.
  221. ## Commands
  222. | Command | Description |
  223. | --- | --- |
  224. | `/supermemory:index` | Index this repo's architecture, conventions, and how to run into the project container. |
  225. | `/supermemory:status` | Show authentication status, API and MCP reachability, and the active project container. |
  226. Search does not have its own command. With a key, the prompt hook searches
  227. substantive prompts. For deeper history, use the `context-gatherer` agent or
  228. the MCP tools. `/supermemory:index` saves codebase structure. For a one-off
  229. save, ask Claude to use the `add_memory` MCP tool. Without `containerTag`,
  230. the proxy defaults it to this repository's container; pass a different tag
  231. to select another space. Conversation turns are saved when a session ends.
  232. ## Privacy
  233. Automatic capture sends new conversation content to Supermemory, including tool
  234. content when configured. Before saving, an offline filter replaces common
  235. credential-shaped values (provider tokens, credential assignments, private keys,
  236. Bearer tokens, and URL credentials) with explicit `[REDACTED:…]` markers while
  237. keeping surrounding context. It cannot detect every secret. Existing stored
  238. memories and local transcripts are not rewritten; explicit MCP tool calls and
  239. recall queries are not filtered by this capture-only protection.
  240. For information about how Supermemory collects, uses, and retains data, see the
  241. [Supermemory Privacy Policy](https://supermemory.ai/privacy/).
  242. ## License
  243. MIT
  244. ## Development runtime
  245. Marketplace installations need only Node 18 or later, not `npm install`.
  246. `plugin/hooks/vendor/supermemory.cjs` is the committed runtime bundle built from
  247. the exact official SDK and esbuild versions in `package-lock.json`. Maintainers
  248. reproduce it with `npm ci && npm run build:sdk`; CI rejects a stale bundle.
  249. The SDK's Apache-2.0 license is included alongside the generated bundle.
  250. ---
  251. <div align="center">
  252. <sub>◪ is the supermemory mark. Whenever you see it (the recall strip, notices, or Claude's answers), that information came from supermemory.</sub>
  253. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.