How CursorHooksInstaller Integrates Claude-Mem Memory with the Cursor IDE

The CursorHooksInstaller bridges Claude-Mem's persistent memory into the Cursor IDE by installing MCP server configurations, unified CLI hooks, and auto-updating context files that inject historical session data into every prompt.

The thedotmack/claude-mem repository provides a persistent memory layer for AI-assisted development. The CursorHooksInstaller service, implemented in src/services/integrations/CursorHooksInstaller.ts, automates the integration between Claude-Mem's memory store and the Cursor editor's hook system, ensuring your AI assistant retains context across sessions.

Architecture Overview

The integration follows a seven-step pipeline that transforms Claude-Mem's memory into Cursor-readable context files.

Detection and Targeting

The installer supports three installation scopes: project, user, and enterprise. The detectPlatform() and getTargetDir() functions determine the correct target directory based on the operating system and scope:

• Project scope: Creates .cursor/ in the project root
• User scope: Uses ~/.cursor/ (macOS/Linux) or %USERPROFILE%\.cursor\ (Windows)
• Enterprise scope: Targets system-wide directories on managed machines

Project Registration

The registerCursorProject() function maintains a JSON registry at cursor-projects.json in the global data directory. This registry maps project names to workspace paths and installation timestamps, enabling the Claude-Mem worker to identify which projects require context updates.

MCP Server Configuration

The configureCursorMcp() function writes an mcp.json configuration file that registers Claude-Mem as a Model Context Protocol (MCP) server. This configuration points to plugin/scripts/mcp-server.cjs, exposing Claude-Mem tools to Cursor's hook system via the MCP protocol.

Hook Installation

The installCursorHooks() function generates a hooks.json file that wires Cursor events to the unified CLI. Each hook command invokes bun <worker-service.cjs> hook cursor <command>, supporting five lifecycle events:

• session-init: Initializes memory for new sessions
• context: Retrieves relevant historical context
• observation: Records IDE observations to memory
• file-edit: Tracks file modifications
• summarize: Generates session summaries

Context File Generation

For project-level installations, setupProjectContext() attempts to contact the running Claude-Mem worker via HTTP at /api/context/inject?project=<name>. If the worker responds, the returned markdown content is written to .cursor/rules/claude-mem-context.mdc. If the worker is offline, a placeholder file is created instead.

Auto-Update Mechanism

When Claude-Mem finishes a session, it calls updateCursorContextForProject(projectName, port). This function fetches the latest memory snippet from the worker and atomically overwrites claude-mem-context.mdc, ensuring every new Cursor Chat or Tab receives up-to-date context.

Key Implementation Details

The CursorHooksInstaller.ts Service

The core service file src/services/integrations/CursorHooksInstaller.ts exports the main installation logic. Key functions include:

• installCursorHooks(scope: InstallScope): Orchestrates the full installation pipeline
• uninstallCursorHooks(scope: InstallScope): Removes all configuration files and registry entries
• checkCursorHooksStatus(scope: InstallScope): Returns installation state and file paths

Context Update Mechanism

The updateCursorContextForProject() function in src/utils/cursor-utils.ts handles atomic writes to prevent corruption during IDE reloads. It uses temporary file creation followed by atomic rename operations to ensure claude-mem-context.mdc is never in a partially written state when Cursor reads it.

Installation and Usage

Install Claude-Mem integration for your current project:

npx claude-mem cursor install

This executes installCursorHooks('project'), creating ./.cursor/hooks.json and ./.cursor/rules/claude-mem-context.mdc.

Install for all projects under your user account:

npx claude-mem cursor install --scope user

Remove the integration:

npx claude-mem cursor uninstall user

This triggers uninstallCursorHooks('user'), deleting ~/.cursor/hooks.json, the context file, and the registry entry.

Summary

• CursorHooksInstaller automates the bridge between Claude-Mem and Cursor IDE through src/services/integrations/CursorHooksInstaller.ts.
• The integration supports project, user, and enterprise scopes via detectPlatform() and getTargetDir().
• MCP configuration in mcp.json exposes Claude-Mem tools to Cursor's hook system.
• Unified CLI hooks in hooks.json route Cursor events through worker-service.cjs to the memory store.
• Atomic context updates via updateCursorContextForProject() keep .cursor/rules/claude-mem-context.mdc synchronized with the latest session data.

Frequently Asked Questions

How does CursorHooksInstaller detect where to install the configuration files?

The installer uses detectPlatform() to identify the operating system and getTargetDir() to resolve the appropriate Cursor configuration directory. For project scope, it targets ./.cursor/; for user scope, it uses ~/.cursor/ on Unix systems or %USERPROFILE%\.cursor\ on Windows; enterprise scope targets system-wide directories.

What is the purpose of the claude-mem-context.mdc file?

The .cursor/rules/claude-mem-context.mdc file contains markdown-formatted context extracted from Claude-Mem's persistent memory store. Cursor automatically injects this file into every AI prompt, allowing the IDE to reference previous coding sessions, architectural decisions, and project-specific knowledge without manual context copying.

How does the integration update context after each Claude-Mem session?

When a session ends, Claude-Mem calls updateCursorContextForProject(projectName, port) from src/utils/cursor-utils.ts. This function fetches the latest memory snippet via HTTP from the worker service at /api/context/inject, then atomically overwrites the claude-mem-context.mdc file to ensure Cursor always reads complete, up-to-date context.

Can I use CursorHooksInstaller for multiple projects simultaneously?

Yes. The registerCursorProject() function maintains a cursor-projects.json registry that tracks all installed projects. Each project receives its own context file and hooks configuration, while the unified worker service handles context isolation between projects based on the project name parameter passed in hook commands.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}