Cursor Integration

Every Cursor session starts fresh — your AI does not remember what it worked on yesterday. Claude-mem changes that. Your agent builds cumulative knowledge about your codebase, decisions, and patterns over time.

Free to Start

Works with Gemini’s free tier (1,500 req/day) — no subscription required

Automatic Capture

MCP tools, shell commands, and file edits logged without effort

Smart Context

Relevant history injected into every chat session via Cursor Rules

Works Everywhere

With or without a Claude Code subscription

No Claude Code subscription required. Use Gemini (free tier) or OpenRouter as your AI provider.

How It Works

Claude-mem integrates with Cursor through native hooks:

Cursor Agent
  │ Events (MCP, Shell, File Edits, Prompts)
  ▼
Cursor Hooks System
  ├── beforeSubmitPrompt
  ├── afterMCPExecution
  ├── afterShellExecution
  ├── afterFileEdit
  └── stop
  │ HTTP Requests
  ▼
Hook Scripts (Bash / PowerShell)
  ├── session-init.sh
  ├── context-inject.sh
  ├── save-observation.sh
  ├── save-file-edit.sh
  └── session-summary.sh
  │ HTTP API Calls
  ▼
Claude-Mem Worker Service (Port 37777)
  ├── /api/sessions/init
  ├── /api/sessions/observations
  ├── /api/sessions/summarize
  └── /api/context/inject
  │ Database Operations
  ▼
SQLite + Chroma Vector DB

Session hooks capture tool usage, file edits, and shell commands
AI extraction compresses observations into semantic summaries
Context injection loads relevant history into each new session via .cursor/rules/claude-mem-context.mdc
Memory viewer at http://localhost:37777 shows your knowledge base

Prerequisites

macOS

Bun: curl -fsSL https://bun.sh/install | bash
Cursor IDE
jq and curl: brew install jq curl

Linux

Bun: curl -fsSL https://bun.sh/install | bash
Cursor IDE
jq and curl: apt install jq curl or dnf install jq curl

Windows

Bun: powershell -c "irm bun.sh/install.ps1 | iex"
Cursor IDE
PowerShell 5.1+ (included in Windows 10/11)
Git for Windows

Installation Paths

Choose the installation method that fits your setup:

Cursor-Only (No Claude Code)
Claude Code Users
Windows

If you are using Cursor without a Claude Code subscription, follow this path.

Clone and build

git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem && bun install && bun run build

Configure your AI provider

Since you do not have Claude Code, you need to configure an AI provider for claude-mem’s summarization engine.Option A: Gemini (Recommended — Free Tier)Gemini offers 1,500 free requests per day, which is plenty for typical individual use.

mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY",
  "CLAUDE_MEM_GEMINI_MODEL": "gemini-2.5-flash-lite",
  "CLAUDE_MEM_GEMINI_RATE_LIMITING_ENABLED": true
}
EOF

Get your free API key at aistudio.google.com/apikey.Option B: OpenRouter (100+ Models)

mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
  "CLAUDE_MEM_PROVIDER": "openrouter",
  "CLAUDE_MEM_OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY"
}
EOF

Free models available on OpenRouter include google/gemini-2.0-flash-exp:free and xiaomi/mimo-v2-flash:free.Option C: Claude API (API Credits Without Claude Code)

mkdir -p ~/.claude-mem
cat > ~/.claude-mem/settings.json << 'EOF'
{
  "CLAUDE_MEM_PROVIDER": "claude",
  "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY"
}
EOF

Run the interactive setup wizard

bun run cursor:setup

The wizard detects that you do not have Claude Code, helps you choose and configure a free AI provider, installs hooks automatically, and starts the worker service.

Verify installation

bun run cursor:status
bun run worker:status

Then open http://localhost:37777 in your browser.

Restart Cursor

Restart Cursor IDE to load the new hooks. Start a coding session — context will begin being captured automatically.

If you have Claude Code installed, the plugin uses Claude’s SDK by default.

Install the plugin

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

Install Cursor hooks

# Install for all projects (recommended)
claude-mem cursor install user

# Or for the current project only
claude-mem cursor install

Restart Cursor

Restart Cursor IDE to load the hooks.

Verify

bun run cursor:status

Windows users get full support via PowerShell scripts. The installer automatically detects Windows and installs the appropriate scripts.

Enable script execution (if needed)

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Clone, build, and configure

git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem
bun install
bun run build

# Configure provider (Gemini example)
$settingsDir = "$env:USERPROFILE\.claude-mem"
New-Item -ItemType Directory -Force -Path $settingsDir

@"
{
  "CLAUDE_MEM_PROVIDER": "gemini",
  "CLAUDE_MEM_GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
}
"@ | Out-File -FilePath "$settingsDir\settings.json" -Encoding UTF8

Run the interactive setup

bun run cursor:setup

Start the worker and verify

bun run worker:start
bun run cursor:status

What gets installed on Windows:

Script	Purpose
`common.ps1`	Shared utilities
`session-init.ps1`	Initialize session on prompt
`context-inject.ps1`	Inject memory context
`save-observation.ps1`	Capture MCP/shell usage
`save-file-edit.ps1`	Capture file edits
`session-summary.ps1`	Generate summary on stop

Hooks are configured to invoke PowerShell with -ExecutionPolicy Bypass so scripts run without additional configuration.

npm Scripts Reference

All commands are run from the claude-mem repository directory:

Command	Description
`bun run cursor:setup`	Interactive setup wizard — configures provider and installs hooks
`bun run cursor:install`	Install Cursor hooks for the current project
`bun run cursor:install -- user`	Install Cursor hooks for all projects (user-level)
`bun run cursor:uninstall`	Remove Cursor hooks
`bun run cursor:status`	Check hook installation status
`bun run worker:start`	Start the worker service in the background
`bun run worker:stop`	Stop the worker service
`bun run worker:restart`	Restart the worker service
`bun run worker:status`	Check worker status
`bun run worker:logs`	View worker logs (last 50 lines)

Hook Mappings

The hooks.json file installed in .cursor/ maps Cursor events to bash (or PowerShell) scripts:

Cursor Hook	Script	Purpose
`beforeSubmitPrompt`	`session-init.sh`	Initialize claude-mem session using `conversation_id`
`beforeSubmitPrompt`	`context-inject.sh`	Ensure worker is running; refresh context file
`afterMCPExecution`	`save-observation.sh`	Capture MCP tool usage
`afterShellExecution`	`save-observation.sh`	Capture shell command execution
`afterFileEdit`	`save-file-edit.sh`	Capture file edits as `write_file` observations
`stop`	`session-summary.sh`	Generate summary + update context file for next session

{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [
      { "command": "./cursor-hooks/session-init.sh" },
      { "command": "./cursor-hooks/context-inject.sh" }
    ],
    "afterMCPExecution": [
      { "command": "./cursor-hooks/save-observation.sh" }
    ],
    "afterShellExecution": [
      { "command": "./cursor-hooks/save-observation.sh" }
    ],
    "afterFileEdit": [
      { "command": "./cursor-hooks/save-file-edit.sh" }
    ],
    "stop": [
      { "command": "./cursor-hooks/session-summary.sh" }
    ]
  }
}

Context Injection

Context is automatically injected via Cursor’s Rules system — no manual steps required after installation.

How the Context File Works

The file at .cursor/rules/claude-mem-context.mdc has alwaysApply: true set in its frontmatter, so Cursor includes it in every chat session automatically.

---
alwaysApply: true
description: "Claude-mem context from past sessions (auto-updated)"
---

# Memory Context from Past Sessions

[Your context from claude-mem appears here]

---
*Updated after last session.*

When Context Updates

Context is refreshed at three points per session for maximum freshness:

Before each prompt (context-inject.sh)

When you submit a prompt, context-inject.sh runs. It fetches the latest context from /api/context/inject and rewrites .cursor/rules/claude-mem-context.mdc. Cursor reads this file before passing it to the LLM.

After summary completes (worker auto-update)

Immediately after a summary is saved to the database, the worker checks if the project is registered for Cursor and writes the updated context file automatically — no hook involved.

After session ends (session-summary.sh)

When the agent loop ends, the stop hook runs session-summary.sh, which generates a session summary and then writes a fresh context file as a fallback to ensure nothing was missed.

Data Mapping

Cursor Field	Claude-Mem Field	Notes
`conversation_id`	`contentSessionId`	Stable across turns, used as primary session identifier
`generation_id`	(fallback)	Used if `conversation_id` is unavailable
`workspace_roots[0]`	Project name	Basename of workspace root directory

Additional Context Access Methods

MCP Tools

Configure claude-mem’s MCP server in Cursor for search(query, project, limit), timeline(anchor, depth_before, depth_after), and get_observations(ids) tools.

Web Viewer

Browse your full memory at http://localhost:37777 — search, filter by project, view timelines.

Provider Comparison

Provider	Cost	Rate Limit	Best For
Gemini	Free tier	1,500 req/day	Individual use, getting started
OpenRouter	Pay-per-use + free models	Varies by model	Model variety, high volume
Claude SDK	Included with Claude Code	Unlimited	Claude Code subscribers

Start with Gemini’s free tier. It handles typical individual usage well. Switch to OpenRouter or Claude SDK if you need higher limits.

Comparison with Claude Code Integration

Feature	Claude Code	Cursor
Session initialization	`SessionStart` hook	`beforeSubmitPrompt` hook
Context injection	`additionalContext` field (immediate)	Auto-updated `.cursor/rules/` file
Observation capture	`PostToolUse` hook	`afterMCPExecution`, `afterShellExecution`, `afterFileEdit`
Session summary	`Stop` hook with transcript	`stop` hook (no transcript access)
MCP search tools	Full support	Full support (if MCP configured)
Context persistence	Session only	File-based (persists across IDE restarts)

Troubleshooting

Worker not starting

# Check if port is already in use
lsof -i :37777

# Force restart
bun run worker:stop && bun run worker:start

# Check logs
bun run worker:logs
# Or view the log file directly
tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log

Hooks not firing

Restart Cursor IDE after installation
Check hooks are installed: bun run cursor:status
Verify hooks.json exists in .cursor/ (project-level) or ~/.cursor/ (user-level)
Check Cursor Settings → Hooks tab for configuration errors
Verify scripts are executable:
```
chmod +x ~/.cursor/hooks/*.sh
```

No context appearing

Ensure worker is running: bun run worker:status
Confirm worker responds: curl http://127.0.0.1:37777/api/readiness
Check for existing observations: visit http://localhost:37777
Verify your API key is configured correctly in ~/.claude-mem/settings.json

Observations not being saved

Test the observation endpoint directly:

curl -X POST http://127.0.0.1:37777/api/sessions/observations \
  -H "Content-Type: application/json" \
  -d '{"contentSessionId":"test","tool_name":"test","tool_input":{},"tool_response":{},"cwd":"/tmp"}'

Rate limiting on Gemini free tier

If you hit the 1,500 requests/day limit:

Wait until the next day (limit resets at midnight Pacific)
Switch to OpenRouter with a paid or free model
Upgrade to a paid Gemini plan

Windows: “Execution of scripts is disabled”

Run PowerShell as Administrator:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine

Windows: Worker not responding

Check if port 37777 is in use:

Get-NetTCPConnection -LocalPort 37777

Next Steps

Gemini Setup Guide

Step-by-step guide to configure Gemini’s free tier

OpenRouter Setup Guide

Configure OpenRouter for 100+ model options

Configuration Reference

All available settings and options

Troubleshooting

Common issues and solutions

Platform Integrations

Free to Start

Automatic Capture

Smart Context

Works Everywhere

How It Works

Prerequisites

Installation Paths

npm Scripts Reference

Hook Mappings

Context Injection

How the Context File Works

When Context Updates

Data Mapping

Additional Context Access Methods

MCP Tools

Web Viewer

Provider Comparison

Comparison with Claude Code Integration

Troubleshooting

Worker not starting

Hooks not firing

No context appearing

Observations not being saved

Rate limiting on Gemini free tier

Windows: “Execution of scripts is disabled”

Windows: Worker not responding

Next Steps

Gemini Setup Guide

OpenRouter Setup Guide

Configuration Reference

Troubleshooting

Build docs developers (and LLMs) love

Platform Integrations

Free to Start

Automatic Capture

Smart Context

Works Everywhere

​How It Works

​Prerequisites

​Installation Paths

​npm Scripts Reference

​Hook Mappings

​Context Injection

​How the Context File Works

​When Context Updates

​Data Mapping

​Additional Context Access Methods

MCP Tools

Web Viewer

​Provider Comparison

​Comparison with Claude Code Integration

​Troubleshooting

​Worker not starting

​Hooks not firing

​No context appearing

​Observations not being saved

​Rate limiting on Gemini free tier

​Windows: “Execution of scripts is disabled”

​Windows: Worker not responding

​Next Steps

Gemini Setup Guide

OpenRouter Setup Guide

Configuration Reference

Troubleshooting

Build docs developers (and LLMs) love

How It Works

Prerequisites

Installation Paths

npm Scripts Reference

Hook Mappings

Context Injection

How the Context File Works

When Context Updates

Data Mapping

Additional Context Access Methods

Provider Comparison

Comparison with Claude Code Integration

Troubleshooting

Worker not starting

Hooks not firing

No context appearing

Observations not being saved

Rate limiting on Gemini free tier

Windows: “Execution of scripts is disabled”

Windows: Worker not responding

Next Steps