supermemory/apps/docs/integrations/cursor.mdx

---
title: "Cursor"
sidebarTitle: "Cursor"
description: "cursor-supermemory: persistent memory across your Cursor chats"
icon: "/images/cursor-logo.svg"
---

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

## Install

<Note>
Requires [Node.js](https://nodejs.org) on your `PATH`. Installing Cursor does not put one there.
</Note>

Run this in Cursor:

```
/add-plugin cursor-supermemory
```

Or install it from the [Cursor Marketplace](https://cursor.com/marketplace/supermemory): 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](https://console.supermemory.ai/agents) in the console.

As a fallback, set an API key from [API Keys](https://console.supermemory.ai/keys):

<Tabs>
  <Tab title="macOS / Linux (zsh)">
    ```bash
    echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.zshrc
    source ~/.zshrc
    ```
  </Tab>
  <Tab title="macOS / Linux (bash)">
    ```bash
    echo 'export SUPERMEMORY_API_KEY="sm_..."' >> ~/.bashrc
    source ~/.bashrc
    ```
  </Tab>
  <Tab title="Windows (PowerShell)">
    ```powershell
    [System.Environment]::SetEnvironmentVariable("SUPERMEMORY_API_KEY", "sm_...", "User")
    ```
    Restart your terminal after running this.
  </Tab>
</Tabs>

Restart Cursor after installing the plugin or changing credentials.

Check the connection any time with `/supermemory-status`.

<Accordion title="Prefer the terminal?" icon="/icons/hugeicons/command-line.svg">
The slash commands just run the plugin's CLI for you. To drive it yourself:

```bash
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`.
</Accordion>

## 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](/supermemory-mcp/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](#configuration) or run `/supermemory-config`.

## Container tags

Cursor shares one repository tag with the [Claude Code](/integrations/claude-code), [Muse Code](/integrations/muse-code), [OpenAI Codex](/integrations/codex), and [OpenCode](/integrations/opencode) plugins, so agents working on the same repo read and write the same memory:

```text
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

<Tip>
**Prefer to keep everything on your machine?** This plugin works with [self-hosted Supermemory](/self-hosting/overview): 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.
</Tip>

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

```json
{
  "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.

```json
{
  "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

<Card title="GitHub repository" icon="/images/github-icon.svg" href="https://github.com/supermemoryai/cursor-supermemory">
  Source code, issues, and detailed README.
</Card>