claude-mem/cursor-hooks/INTEGRATION.md

# Claude-Mem ↔ Cursor Integration Architecture

## Overview

This integration connects claude-mem's persistent memory system to Cursor's hook system, enabling:
- Automatic capture of agent actions (MCP tools, shell commands, file edits)
- Context retrieval from past sessions
- Session summarization for future reference

## Architecture

```
┌─────────────┐
│   Cursor    │
│   Agent     │
└──────┬──────┘
       │
       │ Events (MCP, Shell, File Edits, Prompts)
       │
       ▼
┌─────────────────────────────────────┐
│      Cursor Hooks System             │
│  ┌────────────────────────────────┐ │
│  │ beforeSubmitPrompt             │ │
│  │ afterMCPExecution              │ │
│  │ afterShellExecution            │ │
│  │ afterFileEdit                  │ │
│  │ stop                           │ │
│  └────────────────────────────────┘ │
└──────┬──────────────────────────────┘
       │
       │ HTTP Requests
       │
       ▼
┌─────────────────────────────────────┐
│   Hook Scripts (Bash)               │
│  ┌────────────────────────────────┐ │
│  │ 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 Database                    │
│   + Chroma Vector DB                 │
└─────────────────────────────────────┘
```

## Event Flow

### 1. Prompt Submission Flow

```
User submits prompt
    ↓
beforeSubmitPrompt hook fires
    ↓
session-init.sh
    ├─ Extract conversation_id, project name
    ├─ POST /api/sessions/init
    └─ Initialize session in claude-mem
    ↓
context-inject.sh
    ├─ GET /api/context/inject?project=...
    └─ Fetch relevant context (for future use)
    ↓
Prompt proceeds to agent
```

### 2. Tool Execution Flow

```
Agent executes MCP tool or shell command
    ↓
afterMCPExecution / afterShellExecution hook fires
    ↓
save-observation.sh
    ├─ Extract tool_name, tool_input, tool_response
    ├─ Map to claude-mem observation format
    ├─ POST /api/sessions/observations
    └─ Store observation in database
```

### 3. File Edit Flow

```
Agent edits file
    ↓
afterFileEdit hook fires
    ↓
save-file-edit.sh
    ├─ Extract file_path, edits
    ├─ Create "write_file" observation
    ├─ POST /api/sessions/observations
    └─ Store file edit observation
```

### 4. Session End Flow

```
Agent loop ends
    ↓
stop hook fires
    ↓
session-summary.sh
    ├─ POST /api/sessions/summarize
    └─ Generate session summary for future retrieval
```

## Data Mapping

### Session ID 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 unavailable |

### Tool Mapping

| Cursor Event | Claude-Mem Tool Name | Input Format |
|-------------|---------------------|--------------|
| `afterMCPExecution` | `tool_name` from event | `tool_input` as JSON |
| `afterShellExecution` | `"Bash"` | `{command: "..."}` |
| `afterFileEdit` | `"write_file"` | `{file_path: "...", edits: [...]}` |

### Project Mapping

| Source | Target | Notes |
|--------|--------|-------|
| `workspace_roots[0]` | Project name | Basename of workspace root directory |

## API Endpoints Used

### Session Management
- `POST /api/sessions/init` - Initialize new session
- `POST /api/sessions/summarize` - Generate session summary

### Observation Storage
- `POST /api/sessions/observations` - Store tool usage observation

### Context Retrieval
- `GET /api/context/inject?project=...` - Get relevant context for injection

### Health Checks
- `GET /api/readiness` - Check if worker is ready

## Configuration

### Worker Settings
Located in `~/.claude-mem/settings.json`:
- `CLAUDE_MEM_WORKER_PORT` (default: 37777)
- `CLAUDE_MEM_WORKER_HOST` (default: 127.0.0.1)

### Hook Settings
Located in `hooks.json`:
- Hook event names
- Script paths (relative or absolute)

## Error Handling

### Worker Unavailable
- Hooks poll `/api/readiness` with 30 retries (6 seconds)
- If worker unavailable, hooks fail gracefully (exit 0)
- Observations are fire-and-forget (curl errors ignored)

### Missing Data
- Empty `conversation_id` → use `generation_id`
- Empty `workspace_root` → use `pwd`
- Missing tool data → skip observation

### Network Errors
- All HTTP requests use `curl -s` (silent)
- Errors redirected to `/dev/null`
- Hooks always exit 0 to avoid blocking Cursor

## Limitations

1. **Context Injection**: Cursor's `beforeSubmitPrompt` doesn't support prompt modification. Context must be retrieved via:
   - MCP tools (claude-mem provides search tools)
   - Manual retrieval from web viewer
   - Future: Agent SDK integration

2. **Transcript Access**: Cursor hooks don't provide transcript paths, limiting summary quality compared to Claude Code integration.

3. **Session Model**: Uses `conversation_id` which may not perfectly match Claude Code's session model.

4. **Tab Hooks**: Currently only supports Agent hooks. Tab (inline completion) hooks could be added separately.

## Future Enhancements

- [ ] Enhanced context injection via MCP tools
- [ ] Support for `beforeTabFileRead` and `afterTabFileEdit` hooks
- [ ] Better error reporting and logging
- [ ] Integration with Cursor's agent SDK
- [ ] Support for blocking/approval workflows
- [ ] Real-time context injection via agent messages

## Testing

### Manual Testing

1. **Test session initialization**:
   ```bash
   echo '{"conversation_id":"test-123","workspace_roots":["/tmp/test"],"prompt":"test"}' | \
     ~/.cursor/hooks/session-init.sh
   ```

2. **Test observation capture**:
   ```bash
   echo '{"conversation_id":"test-123","hook_event_name":"afterMCPExecution","tool_name":"test","tool_input":{},"result_json":{}}' | \
     ~/.cursor/hooks/save-observation.sh
   ```

3. **Test context retrieval**:
   ```bash
   curl "http://127.0.0.1:37777/api/context/inject?project=test"
   ```

### Integration Testing

1. Enable hooks in Cursor
2. Submit a prompt
3. Execute some tools
4. Check web viewer: `http://localhost:37777`
5. Verify observations appear in database

## Troubleshooting

See [README.md](README.md#troubleshooting) for detailed troubleshooting steps.