Cursor IDE Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Cursor IDE Integration connects the claude-mem persistent memory system to the Cursor editor through a modular hook system. Its primary purpose is to automatically capture agent actions—such as Model Context Protocol (MCP) tool usage, shell commands, and file edits—and inject relevant context from past sessions back into the editor to ensure continuity of knowledge.
The integration operates as a bridge between Cursor's internal event system and the claude-mem Worker Service (running on port 37777). It achieves feature parity with the "Claude Code" implementation while adapting to Cursor's specific capabilities, such as automated context injection via .cursor/rules/ files.
Sources: cursor-hooks/INTEGRATION.md:3-10, cursor-hooks/PARITY.md:3-5, cursor-hooks/README.md:12-16
System Architecture
The architecture consists of a three-tier flow: the Cursor Agent triggers lifecycle events, which execute localized shell or PowerShell scripts (the hooks). these scripts then communicate with the claude-mem Worker Service via an HTTP API to perform database operations or retrieve context.
The diagram above illustrates the data flow from Cursor events through the hook scripts to the backend worker and storage layers.
Sources: cursor-hooks/INTEGRATION.md:12-58, src/services/worker-service.ts:133-146
Lifecycle Hooks and Event Mapping
Cursor events are mapped to specific hook scripts. All hooks follow a "fire-and-forget" pattern, ensuring that failures in the memory system do not block the Cursor agent's execution.
| Cursor Event | Script | Functionality |
|---|---|---|
beforeSubmitPrompt | session-init.sh | Initializes session via /api/sessions/init and handles privacy checks. |
beforeSubmitPrompt | context-inject.sh | Fetches fresh context and ensures worker readiness. |
afterMCPExecution | save-observation.sh | Captures MCP tool name, inputs, and results. |
afterShellExecution | save-observation.sh | Maps terminal commands to a "Bash" tool observation. |
afterFileEdit | save-file-edit.sh | Captures specific file paths and edit arrays. |
stop | session-summary.sh | Triggers /api/sessions/summarize and updates the context rule file. |
Sources: cursor-hooks/INTEGRATION.md:65-100, cursor-hooks/PARITY.md:8-16, cursor-hooks/REVIEW.md:46-135
Context Injection Mechanism
Unlike other integrations, Cursor does not support direct prompt modification via hooks. Instead, claude-mem utilizes the Cursor Rules system. Context is written to a specialized Markdown file (.cursor/rules/claude-mem-context.mdc) with frontmatter that forces it to be included in every chat session.
Automatic Refresh Points
Context is refreshed at three critical points to ensure maximum relevance:
- Before Prompt (
context-inject.sh): Refreshes context with observations from previous sessions before the current prompt is processed. - After Summary (Worker Auto-update): The worker service monitors registered projects and automatically overwrites the rules file once a summary is saved to the database.
- After Session End (
session-summary.sh): Serves as a fallback to capture any final observations from the completed session.
Sources: cursor-hooks/CONTEXT-INJECTION.md:3-35, src/services/worker-service.ts:98-124
MDC File Structure
The auto-generated context file uses the following format:
---
alwaysApply: true
description: "Claude-mem context from past sessions (auto-updated)"
---
# Memory Context from Past Sessions
[Context content from claude-mem]
Sources: cursor-hooks/CONTEXT-INJECTION.md:70-80, cursor-hooks/cursorrules-template.md:3-12
Data Flow and API Interaction
The integration relies on a structured sequence of HTTP calls to the local worker service.
The sequence diagram details the communication between the agent, the localized scripts, and the API service during a typical session lifecycle.
Sources: cursor-hooks/INTEGRATION.md:65-100, cursor-hooks/PARITY.md:19-70
Cross-Platform Support
The integration provides full support for both Unix-like (macOS/Linux) and Windows environments. The installer detects the platform and deploys the appropriate script types.
- macOS/Linux: Uses Bash scripts (
.sh) requiringjqandcurl. - Windows: Uses PowerShell scripts (
.ps1) executed with-ExecutionPolicy Bypass.
Project Registry
Registered projects are tracked in ~/.claude-mem/cursor-projects.json. This allows the worker to perform background updates to the .cursor/rules/ directory even when the specific IDE instance is not triggering a hook (e.g., when memory is updated from a different terminal session).
Sources: cursor-hooks/STANDALONE-SETUP.md:124-155, src/services/worker-service.ts:60-95, cursor-hooks/REVIEW.md:20-25
Configuration and Setup
Configuration for the hooks is split between the project's hooks.json and the global settings.json.
| Configuration File | Path | Key Settings |
|---|---|---|
hooks.json | .cursor/hooks.json | Mapping of event names to script commands. |
settings.json | ~/.claude-mem/settings.json | CLAUDE_MEM_WORKER_PORT (Default: 37777), Provider API keys. |
cursor-projects.json | ~/.claude-mem/cursor-projects.json | Registry of workspace paths for context auto-updates. |
Sources: cursor-hooks/INTEGRATION.md:144-155, cursor-hooks/STANDALONE-SETUP.md:38-70, src/services/worker-service.ts:40-45
Conclusion
The Cursor IDE Integration effectively bridges the gap between ephemeral chat sessions and persistent project memory. By leveraging Cursor's Rule system for context injection and a modular hook architecture for observation capture, it ensures that AI agents maintain a cumulative understanding of codebase decisions, patterns, and history without requiring manual user intervention.
Sources: cursor-hooks/README.md:10-18, cursor-hooks/REVIEW.md:175-185