Cursor - supermemory | Memory API for the AI era

Your agent remembers the decisions, bugs, and conventions from earlier chats instead of starting cold every time.

Install

Requires Node.js on your PATH. Installing Cursor does not put one there.

Run this in Cursor:

/add-plugin cursor-supermemory

Or install it from the Cursor Marketplace: open Customize, find Supermemory, select Install, and choose project or user scope. Restart Cursor or run Developer: Reload Window afterwards.

Authenticate

Open a new chat in Cursor and run:

/supermemory-setup

A browser window opens. Sign in to Supermemory and you are done. You can manage the plugin, change its access, or disconnect it from the Agents page in the console. As a fallback, set an API key from API Keys:

macOS / Linux (zsh)
macOS / Linux (bash)
Windows (PowerShell)

echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.zshrc
source ~/.zshrc

echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.bashrc
source ~/.bashrc

[System.Environment]::SetEnvironmentVariable("SUPERMEMORY_API_KEY", "sm_...", "User")

Restart your terminal after running this.

Restart Cursor after installing the plugin or changing credentials. Check the connection any time with /supermemory-status.

Prefer the terminal?

The slash commands just run the plugin’s CLI for you. To drive it yourself:

node "${CURSOR_PLUGIN_ROOT}/dist/cli.js" login
node "${CURSOR_PLUGIN_ROOT}/dist/cli.js" status
node "${CURSOR_PLUGIN_ROOT}/dist/cli.js" logout

CURSOR_PLUGIN_ROOT is set for plugin hooks. If it is empty in your shell, run node dist/cli.js <command> from the installed plugin directory.Credentials are stored in ~/.supermemory-cursor/credentials.json.

How it works

Layer	What it does
Session profile	Loads your persistent profile when a Cursor conversation starts
Automatic recall	Searches on substantive prompts, deduplicates results, and injects them after the first supported tool result
Incremental capture	Saves each completed turn, and retries unsaved transcript deltas at session end
MCP tools	The hosted Supermemory MCP tools, proxied over stdio with the same credentials as the hooks
Context gatherer	Fans out targeted searches before substantial work
Always-on rule	Makes the agent recall relevant history proactively

Skills and commands

Name	Type	Description
`memory-init`	Skill	Explore the codebase and initialize project memory
`memory-save`	Skill	Save an insight, decision, or solution worth keeping
`memory-search`	Skill	Search memory for past work, bugs, and decisions
`supermemory-context-gatherer`	Agent	Gather deep background before substantial work
`supermemory-index`	Command	Index codebase architecture and patterns into Supermemory
`supermemory-setup`	Command	Connect Supermemory to Cursor
`supermemory-status`	Command	Check authentication and live connectivity
`supermemory-config`	Command	Create or edit the project config file
`supermemory-logout`	Command	Disconnect Supermemory from Cursor

MCP tools

The plugin proxies the hosted Supermemory MCP server (https://mcp.supermemory.ai/mcp) over stdio, using the same credentials as the hooks. Claude Code and Codex use the same server, so all three agents see one tool set. The bundled rule, skills, and agent mainly use these:

Tool	Description
`search_memory`	Search memories in one space
`add_memory`	Save a memory
`forget_memory`	Forget outdated memories
`list_memories`	List recent memories with their IDs
`list_documents` / `get_document`	Browse and read stored documents
`list_spaces` / `who_am_i`	Resolve a named space, or report the active account and space

Pass containerTag on every call, using the tag from the <supermemory-context> block the session-start hook injects. Without it, the hosted server uses the account’s active space, and this project’s hook recall will not find the memory. Config lives in files rather than tools: see Configuration or run /supermemory-config.

Container tags

Cursor shares one repository tag with the Claude Code, Muse Code, OpenAI Codex, and OpenCode plugins, so agents working on the same repo read and write the same memory:

repo_<project_name>__<project_id>

The project ID is a stable hash of the normalized Git remote. Repositories without a remote fall back to their resolved local path. Two repos with the same directory name never collide, and different agents on the same repository share memory. The plugin still reads the former cursor_user_* and cursor_project_* tags, along with legacy tags from the other agents. New writes only use the unified repository tag. Set repoContainerTag only when you need an explicit shared override.

Configuration

Prefer to keep everything on your machine? This plugin works with self-hosted Supermemory: run npx supermemory local, then set SUPERMEMORY_API_URL="http://localhost:6767" (or baseUrl in your config file) and use the API key printed on first boot.

Environment variables

Variable	Description
`SUPERMEMORY_API_KEY`	API key (overrides all other sources)
`SUPERMEMORY_API_URL`	Override the Supermemory API base URL
`SUPERMEMORY_BASE_URL`	API base URL fallback when `SUPERMEMORY_API_URL` is unset
`SUPERMEMORY_API_VERSION`	`v5` or `legacy` REST contract; overrides config `apiVersion`
`SUPERMEMORY_MCP_URL`	Override the hosted MCP endpoint the proxy connects to
`SUPERMEMORY_REPO_TAG`	Override the unified repository container tag
`SUPERMEMORY_USER_TAG`	Legacy Cursor personal container to continue reading
`SUPERMEMORY_PROJECT_TAG`	Legacy Cursor project container to continue reading
`CURSOR_USER_EMAIL`	Used only to find legacy Cursor personal memories

Global config

~/.config/cursor/supermemory.json holds user-wide defaults and applies to all projects.

{
  "repoContainerTag": "repo_my_project__0123456789abcdef",
  "similarityThreshold": 0.55,
  "maxMemories": 10,
  "injectProfile": true,
  "signalExtraction": false,
  "signalKeywords": ["remember", "architecture", "decision", "bug", "fix"],
  "signalTurnsBefore": 3
}

Project config

.cursor/.supermemory/config.json holds per-workspace overrides and wins over global config. Add it to .gitignore if it contains an API key.

{
  "apiKey": "sm_...",
  "repoContainerTag": "repo_my_project__0123456789abcdef",
  "similarityThreshold": 0.55,
  "maxMemories": 10,
  "injectProfile": true
}

Option	Default	Description
`apiKey`	—	Project-specific API key
`baseUrl`	Supermemory API	Override the Supermemory API base URL
`apiVersion`	v5 for the hosted API, `legacy` for custom URLs	Set `v5` to use v5 with a self-hosted server 0.0.9 or newer
`repoContainerTag`	derived from normalized Git remote or project path	Override the unified repository container
`userContainerTag`	—	Legacy Cursor personal container to continue reading
`projectContainerTag`	—	Legacy Cursor project container to continue reading
`similarityThreshold`	`0.55`	Minimum similarity for prompt recall. Values below `0.55` are floored.
`maxMemories`	`10`	Max profile facts injected at session start
`injectProfile`	`true`	Whether to inject the user profile at session start
`signalExtraction`	`false`	Capture only turns containing durable-signal keywords
`signalKeywords`	`remember`, `architecture`, `decision`, `bug`, `fix`	Keywords that trigger signal-based capture
`signalTurnsBefore`	`3`	Number of nearby turns retained around a signal

Edit the file by hand, or run the /supermemory-config command.

Log out

Run /supermemory-logout in Cursor. This removes the stored credentials. Your memories in Supermemory are preserved.

Next steps

GitHub repository

Source code, issues, and detailed README.

​Install

​Authenticate

​How it works

​Skills and commands

​MCP tools

​Container tags

​Configuration

​Environment variables

​Global config

​Project config

​Log out

​Next steps

GitHub repository

Install

Authenticate

How it works

Skills and commands

MCP tools

Container tags

Configuration

Environment variables

Global config

Project config

Log out

Next steps