Introducing a new way to review your PRs.

Read the announcement

thedotmack / claude-mem

Persistent Context Across Sessions for Every Agent – Captures everything your agent does during sessions, compresses it with AI, and injects relevant context back into future sessions. Works with Claude Code, OpenClaw, Codex, Gemini, Hermes, Copilot, OpenCode + More

View on GitHub

47 documents · Updated Nov 20, 2026

docs / cursor-integration

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:

  1. search finds candidate records and their IDs.
  2. timeline adds nearby session context around a candidate.
  3. get_observations loads full details only for selected IDs.
  4. get_tool_uses retrieves 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

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.

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 platformSource handling 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

TriggerConsequenceGuard
The local worker is not installed or is not runningThe local MCP entry cannot answer memory requests and hook capture has no local worker targetRun the Cursor install skill and check the worker before using local MCP
The remote MCP token is missing or invalidCursor can load the remote entry but cannot authenticate memory requestsSet CLAUDE_MEM_MCP_TOKEN for the selected remote service
A Cursor hook event name or input shape changesPrompt context, observations, edits, or summaries stop being captured for that eventUpdate the Cursor hook manifest and adapter as one contract
Memory search skips ID filtering and requests raw tool uses firstA recall request can return very large unsummarized payloadsFollow search, timeline, get_observations, then get_tool_uses
Cursor session identifiers do not match the transcript pathStop-time summaries can lose their source transcript or attach to the wrong conversationPreserve the workspace and conversation mapping used by the Cursor adapter

Key files

FileWhy to read it
claude-mem-cursor/…/plugin.jsonDefines the Cursor package, skills, hooks, MCP manifest, and remote settings.
claude-mem-cursor/…/hooks.jsonShows which Cursor lifecycle events capture prompts, activity, edits, and summaries.
claude-mem-cursor/mcp.jsonShows the local and remote memory connections available to Cursor.
claude-mem-cursor/…/SKILL.mdExplains local worker, remote worker, and observer setup choices.
claude-mem-cursor/…/SKILL.mdDefines the safe staged workflow for recalling earlier work.
src/…/cursor.tsShows how Cursor hook input becomes a common session and observation shape.
src/…/mcp-server.tsShows the local MCP memory and context tool surface used by the local entry.
src/…/recall-mcp-server.tsShows the read-only remote recall surface used by hosted MCP access.