Skip to content

docs: add Cursor integration guide #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
PipDscvr wants to merge 1 commit into
base: main
Choose a base branch
from
+76 −19
Open

docs: add Cursor integration guide #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 74 additions & 17 deletions docs/integrations/coding-agents/cursor.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,18 +5,18 @@ sidebar_position: 4

# Cursor

:::note[Planned]
A packaged Cursor integration is still on the roadmap. The shared AtomicMemory MCP server works with Cursor's MCP support today, but install is source-only and manual.
:::danger[Source-only]
The Cursor integration is committed in [`plugins/cursor`](https://github.com/atomicmemory/atomicmemory-integrations/tree/main/plugins/cursor), but it is not published through a Cursor marketplace. Install it from a local clone by copying the MCP config and rule template.
:::

## Intended Shape
## How It Works

Cursor consumes memory through two surfaces:

1. **MCP tools** for `memory_search`, `memory_ingest`, and `memory_package`.
2. **Cursor rules** for always-on guidance about when to retrieve and store memory.

The packaged integration is expected to include a one-click MCP registration flow and a `.cursor/rules/atomicmemory.md` template. Until then, use the manual setup below.
The source package includes a project MCP template at `plugins/cursor/.cursor/mcp.json` and an always-on rule at `plugins/cursor/.cursor/rules/atomicmemory.mdc`.

## Build the MCP Server

Expand All @@ -41,31 +41,68 @@ The built server entrypoint is:
atomicmemory-integrations/packages/mcp-server/dist/bin.js
```

## Manual MCP Setup
## Configure Environment

Register the MCP server in Cursor's MCP settings. Because `@atomicmemory/mcp-server` is not published to npm yet, point Cursor at the local built binary:
Set these variables before launching Cursor. Cursor resolves `${env:...}` placeholders from the process environment when it starts the MCP server.

```bash
export ATOMICMEMORY_MCP_SERVER_BIN="/absolute/path/to/atomicmemory-integrations/packages/mcp-server/dist/bin.js"
export ATOMICMEMORY_API_URL="https://memory.yourco.com"
export ATOMICMEMORY_API_KEY="am_live_..."
export ATOMICMEMORY_PROVIDER="atomicmemory"
export ATOMICMEMORY_SCOPE_USER="$USER"
export ATOMICMEMORY_SCOPE_AGENT="cursor"
export ATOMICMEMORY_SCOPE_NAMESPACE="repo-or-project"
```

`ATOMICMEMORY_API_URL`, `ATOMICMEMORY_API_KEY`, and `ATOMICMEMORY_PROVIDER` are required. At least one `ATOMICMEMORY_SCOPE_*` variable must be set; `ATOMICMEMORY_SCOPE_USER` is the normal baseline.

## Project MCP Setup

Copy the template into the project root:

```bash
mkdir -p .cursor/rules
cp /absolute/path/to/atomicmemory-integrations/plugins/cursor/.cursor/mcp.json .cursor/mcp.json
cp /absolute/path/to/atomicmemory-integrations/plugins/cursor/.cursor/rules/atomicmemory.mdc .cursor/rules/atomicmemory.mdc
```

If the project already has `.cursor/mcp.json`, merge the `atomicmemory` server entry into the existing `mcpServers` object instead of replacing the file.

The template registers the locally built MCP server:

```json
{
"mcpServers": {
"atomicmemory": {
"command": "bash",
"args": ["-c", "exec node \"$ATOMICMEMORY_MCP_SERVER_BIN\""],
"type": "stdio",
"command": "node",
"args": ["${env:ATOMICMEMORY_MCP_SERVER_BIN}"],
"env": {
"ATOMICMEMORY_MCP_SERVER_BIN": "/absolute/path/to/atomicmemory-integrations/packages/mcp-server/dist/bin.js",
"ATOMICMEMORY_API_URL": "https://memory.yourco.com",
"ATOMICMEMORY_API_KEY": "am_live_...",
"ATOMICMEMORY_PROVIDER": "atomicmemory",
"ATOMICMEMORY_SCOPE_USER": "pip",
"ATOMICMEMORY_SCOPE_AGENT": "cursor",
"ATOMICMEMORY_SCOPE_NAMESPACE": "repo-or-project"
"ATOMICMEMORY_API_URL": "${env:ATOMICMEMORY_API_URL}",
"ATOMICMEMORY_API_KEY": "${env:ATOMICMEMORY_API_KEY}",
"ATOMICMEMORY_PROVIDER": "${env:ATOMICMEMORY_PROVIDER}",
"ATOMICMEMORY_SCOPE_USER": "${env:ATOMICMEMORY_SCOPE_USER}",
"ATOMICMEMORY_SCOPE_AGENT": "${env:ATOMICMEMORY_SCOPE_AGENT}",
"ATOMICMEMORY_SCOPE_NAMESPACE": "${env:ATOMICMEMORY_SCOPE_NAMESPACE}",
"ATOMICMEMORY_SCOPE_THREAD": "${env:ATOMICMEMORY_SCOPE_THREAD}"
}
}
}
}
```

`ATOMICMEMORY_MCP_SERVER_BIN`, `ATOMICMEMORY_API_URL`, `ATOMICMEMORY_API_KEY`, and `ATOMICMEMORY_PROVIDER` are required by the MCP server. At least one `ATOMICMEMORY_SCOPE_*` value must be set. `ATOMICMEMORY_SCOPE_USER` is the normal baseline; use `ATOMICMEMORY_SCOPE_NAMESPACE` for project or repo isolation.
Restart Cursor after changing MCP config or environment variables.

## Global MCP Setup

To make the MCP server available to all Cursor projects, merge the `atomicmemory` entry from `plugins/cursor/.cursor/mcp.json` into:

```text
~/.cursor/mcp.json
```

Keep the rule local by copying `.cursor/rules/atomicmemory.mdc` into projects where the agent should follow the AtomicMemory protocol.

## Available MCP Tools

Expand All @@ -79,9 +116,15 @@ Use `mode: "text"` for extractive durable facts and `mode: "verbatim"` for exact

## Cursor Rules

Add a rule at `.cursor/rules/atomicmemory.md` that mirrors the memory protocol used by the Codex and Claude Code skills:
Add a rule at `.cursor/rules/atomicmemory.mdc` that mirrors the memory protocol used by the Codex and Claude Code skills:

```md
---
description: AtomicMemory persistent memory protocol and MCP tool usage.
globs:
alwaysApply: true
---

# AtomicMemory

- Search memory with `memory_search` at the start of tasks that may depend on prior project context.
Expand All @@ -93,11 +136,25 @@ Add a rule at `.cursor/rules/atomicmemory.md` that mirrors the memory protocol u

The [Codex skill](/integrations/coding-agents/codex#memory-protocol-skill) and [Claude Code skill](/integrations/coding-agents/claude-code#the-skill) are good source material for a richer rule.

## Verify

In Cursor, open **Settings -> Tools & MCP** and confirm the `atomicmemory` server is enabled.

With Cursor CLI:

```bash
cursor-agent mcp list
cursor-agent mcp list-tools atomicmemory
```

You should see `memory_search`, `memory_ingest`, and `memory_package`.

## Troubleshooting

- **`npx @atomicmemory/mcp-server` does not work** - the MCP server is source-only for now. Build it locally and set `ATOMICMEMORY_MCP_SERVER_BIN`.
- **Scope errors** - set `ATOMICMEMORY_SCOPE_USER` or another `ATOMICMEMORY_SCOPE_*` value.
- **No memory tools in Cursor** - restart Cursor after changing MCP settings and verify the path in `ATOMICMEMORY_MCP_SERVER_BIN` is absolute.
- **Existing Cursor config was overwritten** - restore the prior file and merge only the `mcpServers.atomicmemory` object.

## See Also

Expand Down
4 changes: 2 additions & 2 deletions docs/integrations/overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,9 @@ Agents that edit code, run shells, and drive browsers need memory that survives
| [Claude Code](/integrations/coding-agents/claude-code) | 🔧 Source available¹ | Local marketplace (`plugin.json` + `SKILL.md`) | [`plugins/claude-code`](https://github.com/atomicmemory/atomicmemory-integrations/tree/main/plugins/claude-code) |
| [OpenClaw](/integrations/coding-agents/openclaw) | 🔧 Source available¹ | Local install (`openclaw.plugin.json` + `skill.yaml`) | [`plugins/openclaw`](https://github.com/atomicmemory/atomicmemory-integrations/tree/main/plugins/openclaw) |
| [Codex](/integrations/coding-agents/codex) | 🔧 Source available¹ | Local marketplace (`.codex-plugin/` + `.codex-mcp.json`) | [`plugins/codex`](https://github.com/atomicmemory/atomicmemory-integrations/tree/main/plugins/codex) |
| [Cursor](/integrations/coding-agents/cursor) | 🛠️ Planned | MCP server + `.cursor/rules` | — |
| [Cursor](/integrations/coding-agents/cursor) | 🔧 Source available¹ | Project/global MCP config + `.cursor/rules` | [`plugins/cursor`](https://github.com/atomicmemory/atomicmemory-integrations/tree/main/plugins/cursor) |

¹ Plugin manifest and skill files are committed to the integrations repo. Nothing is published to a public plugin marketplace — see each integration page for the clone-and-install steps.
¹ Integration manifests, skills, rules, and config templates are committed to the integrations repo. Nothing is published to a public plugin marketplace — see each integration page for the clone-and-install steps.

## Frameworks

Expand Down