Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs(desktop): add Cursor to the desktop research

AkitaOnRails9227bff41ca4
diff --git a/docs/desktop/cursor.md b/docs/desktop/cursor.md
new file mode 100644
index 00000000..06731625
--- /dev/null
+++ b/docs/desktop/cursor.md
@@ -0,0 +1,88 @@
+# Cursor desktop (research notes)
+
+> Added to the RFC #878 research on 2026-10-08. Verified against Cursor's
+> official docs and the local install (`cursor-bin` 3.24.9 from the AUR,
+> Electron 42; `cursor-agent` CLI 2026.10.01). Closed source.
+
+## Product shape
+
+A VS Code-derived editor whose agent ("Agent Chat"/Composer) runs inside the
+app through bundled extensions (`cursor-agent-exec`, `cursor-agent-host`).
+The same agent is available in a terminal as `cursor agent` (from the
+desktop's `cursor` launcher) and as the standalone `cursor-agent` CLI.
+Config and agent data live in `~/.cursor/` (`projects/<workspace>/`,
+`plugins/`, `skills-cursor/`, `cli-config.json`); the Electron profile is
+`~/.config/Cursor/`.
+
+ai-memory already supports Cursor: `install-mcp --client cursor`
+(`~/.cursor/mcp.json` or `.cursor/mcp.json`) and `install-hooks --agent
+cursor` (`~/.cursor/hooks.json`, flat `{"version": 1, "hooks": {...}}`
+schema) — see `docs/mcp-install.md#cursor`.
+
+## Lifecycle hooks — which files run where
+
+Per <https://cursor.com/docs/hooks> (fetched 2026-10-08):
+
+- Sources, highest priority first: enterprise
+ (`/etc/cursor/hooks.json` on Linux), team (dashboard, Enterprise only),
+ project `.cursor/hooks.json`, user `~/.cursor/hooks.json`.
+- The desktop agent runs all four levels; the CLI runs project and user
+ hooks; cloud/background agents run project, team and enterprise hooks
+ (not user hooks) and defer `sessionStart`/`sessionEnd`.
+- Events: `sessionStart`, `sessionEnd`, `beforeSubmitPrompt`, `preToolUse`,
+ `postToolUse`, `postToolUseFailure`, shell, MCP and file before/after
+ pairs, `subagentStart`/`subagentStop`, `preCompact`, `stop`,
+ `afterAgentResponse`, `afterAgentThought`, tab hooks and `workspaceOpen`.
+ Base payload: `conversation_id`, `generation_id`, `model`, `model_id`,
+ `workspace_roots[]`, `user_email`, `transcript_path`, `hook_event_name`,
+ `cursor_version`.
+- Command hooks fail open (exit 2 blocks; `failClosed: true` opts out).
+ `sessionStart` and `sessionEnd` are fire-and-forget; `sessionEnd` reports
+ `completed`, `aborted`, `error`, `window_close` or `user_close`.
+
+**Claude Code hooks run too, by default.** Per
+<https://cursor.com/docs/reference/third-party-hooks>, Cursor loads
+`.claude/settings.local.json`, `.claude/settings.json` and
+`~/.claude/settings.json` (setting: Agents → Third-Party Imports, on by
+default), maps `PreToolUse`, `PostToolUse`, `UserPromptSubmit`
+(→ `beforeSubmitPrompt`), `Stop`, `SubagentStop`, `SessionStart`,
+`SessionEnd` and `PreCompact`, and runs every matching hook from every
+source. The page does not say which surfaces load them.
+
+**Verified live:** the running desktop app executed the operator's
+`~/.claude/settings.json` ai-memory `SessionStart` hook at launch, before
+any conversation, with Cursor's payload rather than Claude's
+(`conversation_id` and `session_id` both `"empty-state-draft"`,
+`composer_mode: "agent"`, `is_background_agent: false`, `cursor_version:
+"3.24.9"`, empty `workspace_roots`, null `transcript_path` and
+`user_email`). The hook ran as `--agent claude-code` with no `cwd`; the
+server relabels a payload carrying `cursor_version` as `cursor`
+(`agent_from_payload` in `crates/ai-memory-hooks/src/payload.rs`), and the
+#721 de-duplication drops this copy only when Cursor's own ai-memory hooks
+are also installed.
+
+## MCP
+
+`~/.cursor/mcp.json` (user) and `.cursor/mcp.json` (project); `url` for
+HTTP/SSE, `command`/`args` for stdio (<https://cursor.com/docs/mcp>). In
+the empty window the app loaded only its built-in servers
+(`cursor-app-control`, `cursor-ide-browser`, `cursor-origin`,
+`cursor-subscriptions`), not the `ai-memory` and `blender` servers in the
+operator's `~/.claude.json`: the third-party import brought the Claude
+hooks in but, at least there, not the Claude MCP servers.
+
+## Open questions (live tests)
+
+1. The payload and event set of a real desktop conversation for both the
+ native `.cursor/hooks.json` and the Claude-format hooks, including what
+ `session_id`/`cwd` the Claude-format copy gets once a workspace is open.
+2. ~~What the `empty-state-draft` session start does on the server.~~
+ Measured 2026-10-08 by replaying the spooled event against a scratch
+ server: it creates one `cursor` session with no `cwd` in the
+ `default/scratch` project, and every later launch (a new ingest key, the
+ same placeholder id) adds another `session-start` observation to that
+ same session. Clutter, not loss; whether to drop it is a product call.
+3. Where a desktop conversation's transcript lands (`transcript_path` once
+ set) and whether the `cursor-agent` CLI loads the Claude-format hooks
+ (it needs `cursor-agent login` here first).
+4. Whether a workspace window imports Claude MCP servers.
diff --git a/docs/desktop/desktop-landscape.md b/docs/desktop/desktop-landscape.md
index fa5aa555..cf83a671 100644
--- a/docs/desktop/desktop-landscape.md
+++ b/docs/desktop/desktop-landscape.md
@@ -12,6 +12,7 @@
| **ChatGPT desktop (hosted chat side)** | Hosted chat: remote MCP **plugins only** (no local config read) | Yes (remote plugins) | No (Chat-mode) | No local store (cloud) | Plugins (remote MCP + UI + events; OAuth/SIWC) | Closed | n/a |
| **Grok webapp launcher** (local wrapper) | n/a (browser) | unverified | n/a | n/a | n/a | n/a | n/a |
| **Grok Bot** (Cursor; native Electron agent) | Yes — MCP machinery in app.asar (`mcpBoxServers` in `~/.grokbot/settings.json`); format/docs **unverified** | unknown | No | No local transcript documented (cloud + leveldb UI state) | plugins evident (`plugin-logo-cache`) — undocumented | Closed (downloads.cursor.com) | n/a |
+| **Cursor** (desktop 3.24.9 + `cursor-agent` CLI) | Yes — `~/.cursor/mcp.json` / `.cursor/mcp.json` (url or command) | Yes | **Yes** — `~/.cursor/hooks.json`, `.cursor/hooks.json`, enterprise/team; also runs Claude Code hooks from `~/.claude/settings.json` by default (verified live in the desktop app) | `transcript_path` in the payload; layout unverified | Plugins, skills, MCP | Closed | n/a (CLI and app are separate surfaces of one agent) |
| **Zed** | Yes — `context_servers` in settings.json (stdio + url/OAuth); MCP extensions; forwards servers to ACP agents | Yes | No native hooks; ACP/terminal agents bring their own | Native-agent threads in Zed's DB (fragile); terminal/ACP agents use their own stores | Extension API (WASM extensions; MCP extension manifest) | **Open** (`zed-industries/zed`) | n/a (agents run in-place; no bridge needed) |
## Highlights vs RFC #878's assumptions (what changed)
diff --git a/docs/desktop/plan.md b/docs/desktop/plan.md
index 36a896b4..56f0b799 100644
--- a/docs/desktop/plan.md
+++ b/docs/desktop/plan.md
@@ -43,6 +43,9 @@ Status 2026-10-08: docs done, verification mostly done; results in
`.agents/hooks.json`.
- [x] Claude Desktop Code tab: hooks fire (from transcripts).
- [ ] Claude Desktop Cowork: one task once the VM is available.
+ - [x] Cursor desktop: runs `~/.claude/settings.json` hooks by default
+ (a launch-time `sessionStart` for a draft composer was captured).
+ - [ ] Cursor desktop: one conversation in the probe workspace.
3. Document that Claude Desktop Code-tab sessions already flow into
ai-memory, including the scratch-workspace project naming behavior:
**done** (`docs/mcp-install.md`, `docs/support-matrix.md`).
@@ -115,3 +118,7 @@ The research's best new target — not the RFC's `.mcpb`:
7. Antigravity's SessionStart mapping fires on every user turn
(`invocationNum` restarts per turn): keep, or gate per conversation?
8. Cowork capture on Linux, where tasks run in a VM.
+9. Cursor runs the operator's Claude Code hooks by default, so a Cursor
+ session reaches ai-memory twice when Cursor's own hooks are installed
+ (the #721 de-duplication covers that) and once otherwise; the
+ launch-time `empty-state-draft` session start needs handling.
diff --git a/docs/desktop/verification-2026-10.md b/docs/desktop/verification-2026-10.md
index 1c8a20cb..72162216 100644
--- a/docs/desktop/verification-2026-10.md
+++ b/docs/desktop/verification-2026-10.md
@@ -10,7 +10,7 @@
Versions: Claude Desktop 2.9939.4 (bundled Claude Code 2.1.280), Codex
desktop 26.707.31428 (community Linux build) driving Codex CLI 0.156.0,
-Antigravity CLI (`agy`) 1.3.0, Antigravity IDE 2.5.5.
+Antigravity CLI (`agy`) 1.3.0, Antigravity IDE 2.5.5, Cursor 3.24.9.
## Codex desktop
@@ -142,6 +142,22 @@ for their secrets), which settles the `.mcpb` question left open in
`install-mcp --client claude-desktop` refuses to guess a path on Linux and
needs `--config-file ~/.config/Claude/claude_desktop_config.json`.
+## Cursor (added the same day; details in `cursor.md`)
+
+- The running desktop app executed the operator's `~/.claude/settings.json`
+ ai-memory `SessionStart` hook at launch, before any conversation, with
+ Cursor's payload: `conversation_id` = `session_id` = `"empty-state-draft"`,
+ `cursor_version`, `composer_mode`, `is_background_agent`, empty
+ `workspace_roots`, null `transcript_path`. Cursor's docs say Claude Code
+ hooks load by default; this confirms it for the desktop app. The server
+ relabels such a payload as `cursor`.
+- Replayed against a scratch server, that event creates one `cursor`
+ session with no `cwd` in `default/scratch`; each later launch adds another
+ `session-start` observation to the same placeholder session.
+- The empty window loaded only Cursor's built-in MCP servers, not the
+ Claude config's `ai-memory`.
+- No conversation has run yet; `cursor-agent` is not logged in.
+
## Still unverified
| Question | What would settle it |
@@ -149,4 +165,5 @@ needs `--config-file ~/.config/Claude/claude_desktop_config.json`.
| Does the Codex desktop app pass anything at `thread/start` that disables hooks? | One prompt in the desktop app with the trusted ai-memory hooks in place, then check the hook spool or server for a `codex` session whose rollout originator is the desktop's |
| Does the Antigravity IDE run `.agents/hooks.json` / `~/.gemini/config/hooks.json`, with the same payload as the CLI? | One IDE prompt in a scratch workspace carrying a recorder `.agents/hooks.json` |
| Do host hooks and MCP servers reach Cowork's VM on Linux (and on macOS/Windows)? | One Cowork task after the VM images download, then look for hook output in its transcript |
+| Cursor: the hook set and payloads of a real desktop conversation (native and Claude-format), and where its transcript lands | One prompt in the probe workspace, which carries recorder `.cursor/hooks.json` and `.claude/settings.json` files |
| Is a per-turn Antigravity session-start acceptable, or should it be gated per conversation? | A product decision once the server-side effect of repeated session-start posts is measured |