Alex Newman
8d485890b9
- Introduced functionality for installing, uninstalling, and checking the status of Cursor hooks. - Added a new command structure for managing hooks with detailed usage instructions. - Implemented a method to locate the cursor-hooks directory across different environments. - Updated build-hooks script to inform users about the location of Cursor hooks. This enhancement streamlines the integration of Claude-Mem with Cursor, improving user experience and accessibility of hooks.
218 lines
6.5 KiB
Markdown
218 lines
6.5 KiB
Markdown
# Claude-Mem Cursor Hooks Integration
|
|
|
|
This directory contains Cursor hooks that connect claude-mem to Cursor, enabling persistent memory across Cursor sessions.
|
|
|
|
## Overview
|
|
|
|
The hooks bridge Cursor's hook system to claude-mem's worker API, allowing:
|
|
- **Session Management**: Initialize sessions and generate summaries
|
|
- **Observation Capture**: Record MCP tool usage, shell commands, and file edits
|
|
- **Worker Readiness**: Ensure the worker is running before prompt submission
|
|
|
|
## Context Injection
|
|
|
|
Context is automatically injected via Cursor's **Rules** system:
|
|
|
|
1. **Install**: `claude-mem cursor install` generates initial context
|
|
2. **Stop hook**: Updates context in `.cursor/rules/claude-mem-context.mdc` after each session
|
|
3. **Cursor**: Automatically includes this rule in ALL chat sessions
|
|
|
|
**The context updates after each session ends**, so the next session sees fresh context.
|
|
|
|
### Additional Access Methods
|
|
|
|
- **MCP Tools**: Configure claude-mem's MCP server for `search`, `timeline`, `get_observations` tools
|
|
- **Web Viewer**: Access context at `http://localhost:37777`
|
|
- **Manual Request**: Ask the agent to search memory
|
|
|
|
See [CONTEXT-INJECTION.md](CONTEXT-INJECTION.md) for details.
|
|
|
|
## Installation
|
|
|
|
### Quick Install (Recommended)
|
|
|
|
```bash
|
|
# Install for current project
|
|
claude-mem cursor install
|
|
|
|
# Or install globally for all projects
|
|
claude-mem cursor install user
|
|
```
|
|
|
|
### Manual Installation
|
|
|
|
<details>
|
|
<summary>Click to expand manual installation steps</summary>
|
|
|
|
**Project-level** (recommended for team sharing):
|
|
```bash
|
|
# Copy hooks.json to your project
|
|
mkdir -p .cursor
|
|
cp cursor-hooks/hooks.json .cursor/hooks.json
|
|
|
|
# Copy hook scripts to your project
|
|
mkdir -p .cursor/hooks
|
|
cp cursor-hooks/*.sh .cursor/hooks/
|
|
chmod +x .cursor/hooks/*.sh
|
|
```
|
|
|
|
**User-level** (applies to all projects):
|
|
```bash
|
|
# Copy hooks.json to your home directory
|
|
cp cursor-hooks/hooks.json ~/.cursor/hooks.json
|
|
|
|
# Copy hook scripts
|
|
mkdir -p ~/.cursor/hooks
|
|
cp cursor-hooks/*.sh ~/.cursor/hooks/
|
|
chmod +x ~/.cursor/hooks/*.sh
|
|
```
|
|
|
|
</details>
|
|
|
|
### After Installation
|
|
|
|
1. **Start the worker**:
|
|
```bash
|
|
claude-mem start
|
|
```
|
|
|
|
2. **Restart Cursor** to load the hooks
|
|
|
|
3. **Verify installation**:
|
|
```bash
|
|
claude-mem cursor status
|
|
```
|
|
|
|
## Hook Mappings
|
|
|
|
| Cursor Hook | Script | Purpose |
|
|
|-------------|--------|---------|
|
|
| `beforeSubmitPrompt` | `session-init.sh` | Initialize claude-mem session |
|
|
| `beforeSubmitPrompt` | `context-inject.sh` | Ensure worker is running |
|
|
| `afterMCPExecution` | `save-observation.sh` | Capture MCP tool usage |
|
|
| `afterShellExecution` | `save-observation.sh` | Capture shell command execution |
|
|
| `afterFileEdit` | `save-file-edit.sh` | Capture file edits |
|
|
| `stop` | `session-summary.sh` | Generate summary + update context file |
|
|
|
|
## How It Works
|
|
|
|
### Session Initialization (`session-init.sh`)
|
|
- Called before each prompt submission
|
|
- Initializes a new session in claude-mem using `conversation_id` as the session ID
|
|
- Extracts project name from workspace root
|
|
- Outputs `{"continue": true}` to allow prompt submission
|
|
|
|
### Context Hook (`context-inject.sh`)
|
|
- Ensures claude-mem worker is running before session
|
|
- Outputs `{"continue": true}` to allow prompt submission
|
|
- Note: Context file is updated by `session-summary.sh` (stop hook), not here
|
|
|
|
### Observation Capture (`save-observation.sh`)
|
|
- Captures MCP tool executions and shell commands
|
|
- Maps them to claude-mem's observation format
|
|
- Sends to `/api/sessions/observations` endpoint (fire-and-forget)
|
|
|
|
### File Edit Capture (`save-file-edit.sh`)
|
|
- Captures file edits made by the agent
|
|
- Treats edits as "write_file" tool usage
|
|
- Includes edit summaries in observations
|
|
|
|
### Session Summary (`session-summary.sh`)
|
|
- Called when agent loop ends (stop hook)
|
|
- Requests summary generation from claude-mem
|
|
- **Updates context file** in `.cursor/rules/claude-mem-context.mdc` for next session
|
|
|
|
## Configuration
|
|
|
|
The hooks read configuration from `~/.claude-mem/settings.json`:
|
|
|
|
- `CLAUDE_MEM_WORKER_PORT`: Worker port (default: 37777)
|
|
- `CLAUDE_MEM_WORKER_HOST`: Worker host (default: 127.0.0.1)
|
|
|
|
## Dependencies
|
|
|
|
The hook scripts require:
|
|
- `jq` - JSON processing
|
|
- `curl` - HTTP requests
|
|
- `bash` - Shell interpreter
|
|
|
|
Install on macOS: `brew install jq curl`
|
|
Install on Ubuntu: `apt-get install jq curl`
|
|
|
|
## Troubleshooting
|
|
|
|
### Hooks not executing
|
|
|
|
1. Check hooks are in the correct location:
|
|
```bash
|
|
ls .cursor/hooks.json # Project-level
|
|
ls ~/.cursor/hooks.json # User-level
|
|
```
|
|
|
|
2. Verify scripts are executable:
|
|
```bash
|
|
chmod +x ~/.cursor/hooks/*.sh
|
|
```
|
|
|
|
3. Check Cursor Settings → Hooks tab for configuration status
|
|
|
|
4. Check Hooks output channel in Cursor for error messages
|
|
|
|
### Worker not responding
|
|
|
|
1. Verify worker is running:
|
|
```bash
|
|
curl http://127.0.0.1:37777/api/readiness
|
|
```
|
|
|
|
2. Check worker logs:
|
|
```bash
|
|
tail -f ~/.claude-mem/logs/worker-$(date +%Y-%m-%d).log
|
|
```
|
|
|
|
3. Restart worker:
|
|
```bash
|
|
cd ~/.claude/plugins/marketplaces/thedotmack
|
|
npm run worker:restart
|
|
```
|
|
|
|
### Observations not being saved
|
|
|
|
1. Monitor worker logs for incoming requests
|
|
|
|
2. Verify session was initialized via web viewer at `http://localhost:37777`
|
|
|
|
3. Test observation endpoint directly:
|
|
```bash
|
|
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"}'
|
|
```
|
|
|
|
## Comparison with Claude Code Integration
|
|
|
|
| Feature | Claude Code | Cursor |
|
|
|---------|-------------|--------|
|
|
| Session Initialization | ✅ `SessionStart` hook | ✅ `beforeSubmitPrompt` hook |
|
|
| Context Injection | ✅ `additionalContext` field | ✅ Auto-updated `.cursor/rules/` file |
|
|
| Observation Capture | ✅ `PostToolUse` hook | ✅ `afterMCPExecution`, `afterShellExecution`, `afterFileEdit` |
|
|
| Session Summary | ✅ `Stop` hook with transcript | ⚠️ `stop` hook (no transcript) |
|
|
| MCP Search Tools | ✅ Full support | ✅ Full support (if MCP configured) |
|
|
|
|
## Files
|
|
|
|
- `hooks.json` - Hook configuration
|
|
- `common.sh` - Shared utility functions
|
|
- `session-init.sh` - Session initialization
|
|
- `context-inject.sh` - Context/worker readiness hook
|
|
- `save-observation.sh` - MCP and shell observation capture
|
|
- `save-file-edit.sh` - File edit observation capture
|
|
- `session-summary.sh` - Summary generation
|
|
- `cursorrules-template.md` - Template for `.cursorrules` file
|
|
|
|
## See Also
|
|
|
|
- [Claude-Mem Documentation](https://docs.claude-mem.ai)
|
|
- [Cursor Hooks Reference](../docs/context/cursor-hooks-reference.md)
|
|
- [Claude-Mem Architecture](https://docs.claude-mem.ai/architecture/overview)
|