Cursor integration
The Cursor integration gives Cursor a persistent memory layer for coding work. It captures useful agent activity through Cursor hooks and makes past sessions available through MCP search tools. The package supports a local worker or a remote worker, while keeping Cursor separate from the Grok Bot integration.
Integration scope
The Cursor-specific package is claude-mem-cursor. It is a self-contained Cursor plugin that joins three parts of the system: event hooks for capture, an MCP connection for recall, and skills that guide setup and memory search. The package does not install or require Grok Bot. claude-mem-cursor/README.md claude-mem-cursor/…/plugin.json
The package aims to preserve useful work across sessions without making Cursor depend on one worker location. The same Cursor experience can use a worker on the local machine or a hosted MCP service. claude-mem-cursor/…/plugin.json
Event capture
Cursor hooks connect important points in the agent loop to claude-mem. Prompt submission prepares the session and context. Tool activity and file edits add observations. When the agent stops, the integration summarizes the session. claude-mem-cursor/…/hooks.json
The hook commands use the Cursor adapter so Cursor data becomes a common claude-mem session record. The adapter identifies the workspace and conversation, maps shell and MCP results into tool activity, and locates the Cursor transcript when Cursor provides it on disk. This gives later recall a stable session and project boundary. src/…/cursor.ts
The capture path is arranged around the Cursor agent lifecycle:
flowchart LR
P[Prompt submission] --> I[Session and context hooks]
I --> C[Cursor adapter]
S[Shell or MCP activity] --> C
E[File edit] --> C
C --> O[Observation capture]
T[Agent stop] --> M[Session summary]
M --> O
O --> W[Local or remote worker]
MCP memory access
The MCP manifest exposes memory to Cursor as tools rather than as prompt text alone. The local entry starts claude-mem mcp over the local process connection. The remote entry uses the hosted MCP endpoint and a bearer token. claude-mem-cursor/mcp.json
The MCP surface supports a staged recall path. A user or agent first finds likely records, then gets nearby session context, then loads selected observations. Raw tool input and output are a last resort because they can be large. The local MCP server also exposes session context, code search, and knowledge-corpus tools alongside memory recall. claude-mem-cursor/…/SKILL.md src/…/mcp-server.ts
Remote recall is read-only. Its search and context tools return data scoped to the authenticated project, while the local and worker-backed path can support the wider tool set. This keeps a shared recall link from changing stored memory. src/…/recall-mcp-server.ts src/…/recall-mcp-server.ts
Installation paths
The installation skill presents two deployment choices. The local path runs npx claude-mem install --ide cursor and connects the shipped hooks to a worker on the developer machine. The remote path selects server runtime and points installation at a hosted worker. claude-mem-cursor/…/SKILL.md
The observer that turns captured activity into memory can use remote inference or a local host-login mode. These choices are separate from worker placement, so a team can keep the worker local while using remote inference, or use a hosted worker with the remote MCP entry. The installation skill also treats a healthy worker as long-lived state rather than something to restart for each setup step. claude-mem-cursor/…/SKILL.md
Memory search behavior
The mem-search skill is the user-facing guide for questions about earlier work. It applies when a user asks whether a problem was solved before or wants the method used in an earlier session. The skill keeps the search broad at first and the expensive reads narrow at the end. claude-mem-cursor/…/SKILL.md
The search sequence has a clear purpose at each stage:
searchfinds candidate records and their IDs.timelineadds nearby session context around a candidate.get_observationsloads full details only for selected IDs.get_tool_usesretrieves original tool data only when the summaries are not enough.
Cursor writes identify their source as cursor. Reads do not hide memory from other hosts unless the user asks for a Cursor-only view. If MCP is not available, the skill sends the user back through the Cursor installation path. claude-mem-cursor/…/SKILL.md
Related integrations
Cursor is one distribution surface for the same memory product. The package-specific hooks and skills belong here, while shared hook behavior, distribution choices, and other host integrations belong in the related pages.
- Distribution integrations describes the wider set of delivery targets.
- Plugin hooks and agent modes describes shared hook and agent behavior.
- Grok Bot integration describes the separate Grok Bot package.
- Cowork integration describes the Cowork host.
- Installation and npx CLI describes the general installation command and CLI path.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the hook event names aligned with the commands accepted by the Cursor adapter. A manifest change can silently stop capture for one stage of the agent loop.
- Keep the local and remote MCP names aligned with the installation skill. The skill must direct users to the same connection that the manifest exposes.
- Keep
platformSourcehandling aligned between Cursor writes and memory-search reads. A mismatch can hide valid cross-host records or mix records when a host-specific view is expected. - Keep the staged search order aligned with the MCP tool contract. Changing result IDs or tool names can cause the skill to request large raw payloads too early.
- Keep Cursor session identity and transcript lookup rules compatible with Cursor's hook input. A change can attach observations to the wrong session or remove the stop-time summary.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The local worker is not installed or is not running | The local MCP entry cannot answer memory requests and hook capture has no local worker target | Run the Cursor install skill and check the worker before using local MCP |
| The remote MCP token is missing or invalid | Cursor can load the remote entry but cannot authenticate memory requests | Set CLAUDE_MEM_MCP_TOKEN for the selected remote service |
| A Cursor hook event name or input shape changes | Prompt context, observations, edits, or summaries stop being captured for that event | Update the Cursor hook manifest and adapter as one contract |
| Memory search skips ID filtering and requests raw tool uses first | A recall request can return very large unsummarized payloads | Follow search, timeline, get_observations, then get_tool_uses |
| Cursor session identifiers do not match the transcript path | Stop-time summaries can lose their source transcript or attach to the wrong conversation | Preserve the workspace and conversation mapping used by the Cursor adapter |
Key files
| File | Why to read it |
|---|---|
| claude-mem-cursor/…/plugin.json | Defines the Cursor package, skills, hooks, MCP manifest, and remote settings. |
| claude-mem-cursor/…/hooks.json | Shows which Cursor lifecycle events capture prompts, activity, edits, and summaries. |
| claude-mem-cursor/mcp.json | Shows the local and remote memory connections available to Cursor. |
| claude-mem-cursor/…/SKILL.md | Explains local worker, remote worker, and observer setup choices. |
| claude-mem-cursor/…/SKILL.md | Defines the safe staged workflow for recalling earlier work. |
| src/…/cursor.ts | Shows how Cursor hook input becomes a common session and observation shape. |
| src/…/mcp-server.ts | Shows the local MCP memory and context tool surface used by the local entry. |
| src/…/recall-mcp-server.ts | Shows the read-only remote recall surface used by hosted MCP access. |