diff --git a/.cursor-plugin/README.md b/.cursor-plugin/README.md
new file mode 100644
index 0000000..81b003d
--- /dev/null
+++ b/.cursor-plugin/README.md
@@ -0,0 +1,118 @@
+# MemPalace Cursor Plugin
+
+A Cursor IDE plugin that gives your agent a persistent memory system. Auto-registers the `mempalace-mcp` server (19 MCP tools), ships 5 slash commands, and provides one model-invocable skill that guides the agent through setup, mining, and search.
+
+> Hooks (auto-save + session-start memory recall) are shipped separately under `hooks/cursor/` so the plugin is safe to install in any Cursor workspace without touching the agent loop. See [Hooks](#hooks-optional) below.
+
+## Prerequisites
+
+- Python 3.9+
+- Cursor 1.7+ (plugin manifest schema requires it)
+
+## Installation
+
+### Local clone (recommended while not in the marketplace yet)
+
+Symlink (or copy) this repository into Cursor's local plugins folder:
+
+```bash
+ln -s /path/to/mempalace ~/.cursor/plugins/local/mempalace
+```
+
+Then in Cursor: Cmd-Shift-P → **Developer: Reload Window**.
+
+### Marketplace
+
+Once published, install via the Cursor marketplace panel and select `mempalace`. Required-plugin distribution from a team marketplace is also supported.
+
+## Post-Install Setup
+
+After installing the plugin, run the `init` command in a Cursor chat:
+
+```
+/mempalace-init
+```
+
+(Or just say "use the mempalace skill" — Cursor will model-invoke the bundled skill.)
+
+This installs the `mempalace` package via `uv tool` or `pip`, initializes a palace under `~/.mempalace/`, and verifies the MCP server is reachable.
+
+## Available Slash Commands
+
+| Command | Description |
+|---------------------|-----------------------------------------------------------------------------------|
+| `/mempalace-help` | Show available tools, skills, CLI commands, hooks, and architecture |
+| `/mempalace-init` | Set up MemPalace — install, configure, onboard |
+| `/mempalace-search` | Search your memories across the palace using semantic search |
+| `/mempalace-mine` | Mine projects and conversations into the palace |
+| `/mempalace-status` | Show palace overview — wings, rooms, drawer counts |
+
+> Cursor commands are global, not plugin-namespaced — that's why each slug is prefixed with `mempalace-` rather than appearing as `/help`, `/init`, etc. This keeps them collision-free with built-in or other-plugin commands.
+
+## MCP Server
+
+This plugin ships `mcp.json` at the plugin root, so Cursor auto-loads the `mempalace-mcp` server on plugin install:
+
+```json
+{
+ "mempalace": {
+ "command": "mempalace-mcp"
+ }
+}
+```
+
+All 19 MemPalace MCP tools (`mempalace_search`, `mempalace_add_drawer`, `mempalace_diary_write`, `mempalace_check_duplicate`, `mempalace_diary_read`, …) become available to the agent immediately. No manual `~/.cursor/mcp.json` edit required.
+
+If the server doesn't appear, confirm `mempalace-mcp` is on the user `$PATH`:
+
+```bash
+command -v mempalace-mcp
+```
+
+If it isn't, run `/init` (or `mempalace install` from a terminal) — `mempalace-mcp` is installed alongside the `mempalace` package.
+
+## Hooks (optional)
+
+Cursor's hooks system is configured separately from plugins (in `~/.cursor/hooks.json` or `.cursor/hooks.json`), so this plugin does **not** wire hooks itself. The MemPalace repository ships three Cursor-native hooks under [`hooks/cursor/`](../hooks/cursor/) that you install with one command.
+
+User scope — writes `~/.cursor/hooks.json`, applies to every Cursor workspace (recommended):
+
+```bash
+hooks/cursor/install.sh --scope user --variant full
+```
+
+Project scope — writes `.cursor/hooks.json` under the current project only:
+
+```bash
+hooks/cursor/install.sh --scope project --variant full
+```
+
+What you get:
+
+| Hook event | What it does |
+|----------------|-------------------------------------------------------------------------------------------------------|
+| `sessionStart` | Injects an `additional_context` recap of relevant memories scoped to the workspace wing |
+| `stop` | Counts agent turns; every N turns, emits a `followup_message` instructing a memory checkpoint |
+| `preCompact` | Synchronously mines the transcript before compaction, drops a marker so the next `stop` saves a diary |
+
+Full details: [`website/guide/cursor-hooks.md`](../website/guide/cursor-hooks.md) and [`hooks/cursor/README.md`](../hooks/cursor/README.md).
+
+## Uninstall
+
+Remove the local plugin symlink:
+
+```bash
+rm ~/.cursor/plugins/local/mempalace
+```
+
+Then in Cursor: Cmd-Shift-P → **Developer: Reload Window**.
+
+If you also installed the hooks, remove them (leaves any unrelated hooks in `hooks.json` untouched):
+
+```bash
+hooks/cursor/install.sh --scope user --uninstall
+```
+
+## Full Documentation
+
+See the main [README](../README.md) for complete documentation, architecture details, and advanced usage.
diff --git a/.cursor-plugin/commands b/.cursor-plugin/commands
new file mode 120000
index 0000000..047455e
--- /dev/null
+++ b/.cursor-plugin/commands
@@ -0,0 +1 @@
+../commands
\ No newline at end of file
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
new file mode 100644
index 0000000..7df928a
--- /dev/null
+++ b/.cursor-plugin/marketplace.json
@@ -0,0 +1,18 @@
+{
+ "name": "mempalace",
+ "owner": {
+ "name": "milla-jovovich",
+ "url": "https://github.com/MemPalace"
+ },
+ "plugins": [
+ {
+ "name": "mempalace",
+ "source": ".",
+ "description": "AI memory system — mine projects and conversations into a searchable palace. 19 MCP tools, slash commands, and a guided skill for Cursor.",
+ "version": "3.3.6",
+ "author": {
+ "name": "milla-jovovich"
+ }
+ }
+ ]
+}
diff --git a/.cursor-plugin/mcp.json b/.cursor-plugin/mcp.json
new file mode 100644
index 0000000..ca633f5
--- /dev/null
+++ b/.cursor-plugin/mcp.json
@@ -0,0 +1,7 @@
+{
+ "mcpServers": {
+ "mempalace": {
+ "command": "mempalace-mcp"
+ }
+ }
+}
diff --git a/.cursor-plugin/plugin.json b/.cursor-plugin/plugin.json
new file mode 100644
index 0000000..cf2d3ad
--- /dev/null
+++ b/.cursor-plugin/plugin.json
@@ -0,0 +1,20 @@
+{
+ "name": "mempalace",
+ "version": "3.3.6",
+ "description": "Give your AI a memory — mine projects and conversations into a searchable palace. 19 MCP tools, slash commands, and a guided skill for Cursor.",
+ "author": {
+ "name": "milla-jovovich"
+ },
+ "homepage": "https://github.com/MemPalace/mempalace",
+ "repository": "https://github.com/MemPalace/mempalace",
+ "license": "MIT",
+ "keywords": [
+ "memory",
+ "ai",
+ "rag",
+ "mcp",
+ "chromadb",
+ "palace",
+ "search"
+ ]
+}
diff --git a/.cursor-plugin/skills b/.cursor-plugin/skills
new file mode 120000
index 0000000..42c5394
--- /dev/null
+++ b/.cursor-plugin/skills
@@ -0,0 +1 @@
+../skills
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 64d66f2..03aa1b5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
---
+## [Unreleased]
+
+### Added
+
+- **Cursor IDE plugin (`.cursor-plugin/`).** Drops into `~/.cursor/plugins/local/mempalace` (or installs from the Cursor marketplace once published) and auto-registers the `mempalace-mcp` server, five slash commands (`/mempalace-help`, `/mempalace-init`, `/mempalace-mine`, `/mempalace-search`, `/mempalace-status`), and the model-invocable [`mempalace` skill](.cursor-plugin/skills/mempalace/SKILL.md) — no manual `~/.cursor/mcp.json` edit required. Plugin manifest pinned to package version 3.3.6 (test enforces match against `mempalace.version.__version__` so the two never drift). Mirrors the surface of [`.claude-plugin/`](.claude-plugin/) and [`.codex-plugin/`](.codex-plugin/) without duplicating their hook scripts: the Cursor hook scripts under [`hooks/cursor/`](hooks/cursor/) (shipped in the same release) remain the canonical install path for `stop` / `preCompact` / `sessionStart`, wired separately by [`hooks/cursor/install.sh`](hooks/cursor/install.sh). Contract tests in [`tests/test_cursor_plugin_manifest.py`](tests/test_cursor_plugin_manifest.py) cover manifest JSON validity, kebab-case naming, `..`-free relative paths, on-disk path resolution, marketplace alignment, MCP config shape (`mcpServers` wrapper required by Cursor, unlike Claude's flat `.mcp.json`), and every skill/command frontmatter — 32 tests, all pure file inspection so they run on any CI platform without Cursor itself.
+
+- **Cursor IDE hook support (`stop` / `preCompact` / `sessionStart`).** Three new bash hooks live under [`hooks/cursor/`](hooks/cursor/) and share a `lib/common.sh` helpers module. The save hook counts `stop` invocations per Cursor `conversation_id` and emits a `followup_message` every `MEMPAL_SAVE_INTERVAL` (default 15) so the agent files the session into MemPalace and writes a diary entry. The precompact hook synchronously mines the transcript before Cursor's compaction summarises it and drops a marker so the next `stop` forces a save nudge (Cursor's `preCompact` is observational-only — it cannot block or emit a `followup_message`, unlike Claude Code's `PreCompact`). The wake hook is Cursor-only: `sessionStart` returns `additional_context` telling the agent to recall scoped to the wing inferred from the workspace root. Honours the same `MEMPALACE_HOOKS_AUTO_SAVE=false` kill switch as the Claude Code hooks, plus a new `MEMPAL_DISABLE_HOOK=1` alias and a `MEMPAL_STATE_DIR` env override. Includes an opt-in installer at [`hooks/cursor/install.sh`](hooks/cursor/install.sh) with `--scope user|project`, `--variant full|minimal`, `--dry-run`, and `--uninstall` (idempotent, preserves unrelated hooks via `python3`-based JSON merge — no `jq` dependency). Example wirings live at [`examples/cursor/hooks.json`](examples/cursor/hooks.json) and [`examples/cursor/hooks.minimal.json`](examples/cursor/hooks.minimal.json); they are intentionally not placed at the repo root because Cursor auto-loads project hooks from any trusted workspace and we do not arm hooks on contributor checkout. Per-event stdin/stdout schema documented at [`hooks/cursor/STDIN_SHAPE.md`](hooks/cursor/STDIN_SHAPE.md). Walkthrough at [`website/guide/cursor-hooks.md`](website/guide/cursor-hooks.md). Coverage added in [`tests/test_cursor_hooks_shell.py`](tests/test_cursor_hooks_shell.py) and [`tests/test_cursor_hooks_install.py`](tests/test_cursor_hooks_install.py).
+
+---
+
## [3.3.6] — 2026-05-24
### Features
diff --git a/README.md b/README.md
index 48208e4..fdcaabd 100644
--- a/README.md
+++ b/README.md
@@ -165,8 +165,14 @@ system prompt:
## Auto-save hooks
-Two Claude Code hooks save periodically and before context compression:
-[mempalaceofficial.com/guide/hooks](https://mempalaceofficial.com/guide/hooks.html).
+Auto-save hooks for **Claude Code, Codex CLI, and Cursor IDE** save
+periodically and before context compression:
+
+- Claude Code + Codex →
+ [mempalaceofficial.com/guide/hooks](https://mempalaceofficial.com/guide/hooks.html)
+- Cursor IDE (adds session-start recall and a transcript snapshot before
+ compaction) →
+ [mempalaceofficial.com/guide/cursor-hooks](https://mempalaceofficial.com/guide/cursor-hooks.html)
If you are installing under time pressure, start with the
[Claude Code retention setup checklist](https://mempalaceofficial.com/guide/claude-code-retention.html):
diff --git a/commands/mempalace-help.md b/commands/mempalace-help.md
new file mode 100644
index 0000000..51b5a61
--- /dev/null
+++ b/commands/mempalace-help.md
@@ -0,0 +1,7 @@
+---
+description: Show comprehensive MemPalace help — available skills, MCP tools, CLI commands, hooks, and architecture.
+---
+
+Invoke the `mempalace` skill from this plugin and run the `help` instructions, then follow them.
+
+Concretely: run `mempalace instructions help` in a terminal, then carry out the steps it prints.
diff --git a/commands/mempalace-init.md b/commands/mempalace-init.md
new file mode 100644
index 0000000..eaf0294
--- /dev/null
+++ b/commands/mempalace-init.md
@@ -0,0 +1,12 @@
+---
+description: Set up MemPalace — install the package, initialize a palace, register the MCP server with Cursor, and verify everything works.
+---
+
+Invoke the `mempalace` skill from this plugin and run the `init` instructions, then follow them.
+
+Concretely: run `mempalace instructions init` in a terminal, then carry out the steps it prints.
+
+Cursor-specific extras after init:
+
+1. The `mempalace-mcp` server is already auto-registered by this plugin — no manual `mcp.json` edit needed.
+2. For automatic background saves and session-start memory recall, also run `hooks/cursor/install.sh --scope user` from a cloned MemPalace repo. See `website/guide/cursor-hooks.md` for the walkthrough.
diff --git a/commands/mempalace-mine.md b/commands/mempalace-mine.md
new file mode 100644
index 0000000..a15a76f
--- /dev/null
+++ b/commands/mempalace-mine.md
@@ -0,0 +1,7 @@
+---
+description: Mine projects and conversations into the MemPalace. Supports project files, conversation exports, and auto-classification.
+---
+
+Invoke the `mempalace` skill from this plugin and run the `mine` instructions, then follow them.
+
+Concretely: run `mempalace instructions mine` in a terminal, then carry out the steps it prints.
diff --git a/commands/mempalace-search.md b/commands/mempalace-search.md
new file mode 100644
index 0000000..20b2462
--- /dev/null
+++ b/commands/mempalace-search.md
@@ -0,0 +1,7 @@
+---
+description: Search your memories across the MemPalace using semantic search with wing/room filtering.
+---
+
+Invoke the `mempalace` skill from this plugin and run the `search` instructions, then follow them.
+
+Concretely: run `mempalace instructions search` in a terminal, then carry out the steps it prints. The MCP tool `mempalace_search` is also available directly from this Cursor session.
diff --git a/commands/mempalace-status.md b/commands/mempalace-status.md
new file mode 100644
index 0000000..6ab82a8
--- /dev/null
+++ b/commands/mempalace-status.md
@@ -0,0 +1,7 @@
+---
+description: Show the current state of your memory palace — wings, rooms, drawer counts, and suggestions.
+---
+
+Invoke the `mempalace` skill from this plugin and run the `status` instructions, then follow them.
+
+Concretely: run `mempalace instructions status` in a terminal, then carry out the steps it prints.
diff --git a/examples/cursor/README.md b/examples/cursor/README.md
new file mode 100644
index 0000000..7a94270
--- /dev/null
+++ b/examples/cursor/README.md
@@ -0,0 +1,110 @@
+# Cursor IDE Hooks — Example `hooks.json` Files
+
+Sample configurations for wiring the MemPalace Cursor hooks into the
+Cursor IDE. These are **examples only** — they are intentionally not
+placed at the repo root (`/.cursor/hooks.json`) because Cursor
+auto-loads project-level hooks from any trusted workspace, and the
+repo is regularly opened by contributors. We do not auto-arm hooks on
+contributor checkout.
+
+## Variants
+
+### `hooks.json` — full (recommended)
+
+Three hooks wired:
+
+- **`sessionStart`** — calls `mempal_wake_hook_cursor.sh`, which returns
+ `additional_context` telling the agent to recall scoped to the wing
+ inferred from the workspace root. Cursor-only — Claude Code has no
+ equivalent.
+- **`stop`** — calls `mempal_save_hook_cursor.sh`. Counts stop
+ invocations per conversation and emits a `followup_message` every
+ `MEMPAL_SAVE_INTERVAL` (default 15) telling the agent to file the
+ session into the palace and write a diary entry. `loop_limit: 1` is
+ defense-in-depth on top of our own loop-count check.
+- **`preCompact`** — calls `mempal_precompact_hook_cursor.sh`. Runs
+ `mempalace mine` synchronously on the transcript before compaction
+ summarises it, then drops a marker so the next `stop` forces a save
+ followup.
+
+### `hooks.minimal.json` — `stop` only
+
+Lightest install. Wires just the save hook. Use this if you don't
+want the sessionStart recall context or the preCompact transcript
+snapshot.
+
+## How to use
+
+The `$HOME` placeholder is **not** expanded by Cursor — you must
+substitute the absolute path before saving the file. Pick one:
+
+### Option A — let `install.sh` do it
+
+Project scope — writes `/.cursor/hooks.json`:
+
+```bash
+hooks/cursor/install.sh --scope project --target /path/to/your/repo
+```
+
+User scope — writes `~/.cursor/hooks.json`, applies to every Cursor workspace:
+
+```bash
+hooks/cursor/install.sh --scope user
+```
+
+The installer copies the hook scripts to `~/.mempalace/hooks/cursor/`,
+substitutes the absolute paths, and merges the entries into your
+existing `hooks.json` without clobbering unrelated hooks. See
+`install.sh --help` for `--dry-run`, `--uninstall`, and `--variant`.
+
+### Option B — copy + edit manually
+
+1. Copy the chosen example to the target location:
+ - User scope: `~/.cursor/hooks.json`
+ - Project scope: `/.cursor/hooks.json`
+2. Replace every `$HOME` with the absolute path to your home
+ directory (e.g., `/Users/you` or `/home/you`).
+3. Make sure each hook script is executable
+ (`chmod +x ~/.mempalace/hooks/cursor/mempal_*_hook_cursor.sh`).
+4. Restart Cursor, or wait for it to auto-reload the file.
+
+## Why aren't these files at the repo root?
+
+Cursor automatically loads `.cursor/hooks.json` from any trusted
+workspace. Placing a real `hooks.json` at the repo root would arm
+MemPalace's hooks on every contributor's machine the moment they open
+the repo in Cursor — which would modify their conversation behaviour
+without consent and write to `~/.mempalace/hook_state/` without
+asking. Editor configuration is sacred; opt-in only.
+
+If you actually want MemPalace's hooks armed when working on the
+MemPalace repo itself, run:
+
+```bash
+hooks/cursor/install.sh --scope project --target .
+```
+
+That will write `./.cursor/hooks.json` for the repo workspace
+specifically — but it is your decision, not ours, and the file is
+listed in `.gitignore` paths Cursor users typically already exclude.
+
+## Related: the Cursor plugin
+
+The hooks here are **only one half** of MemPalace's Cursor integration. The other half is the [`.cursor-plugin/`](../../.cursor-plugin/) folder at the repo root, which packages MemPalace's MCP server, five slash commands, and the model-invocable `mempalace` skill as a regular Cursor plugin you can drop into `~/.cursor/plugins/local/mempalace`.
+
+The two install paths are orthogonal — install whichever you want, in any order:
+
+| You want | Install |
+|---------------------------------------------------------------------------|----------------------------------------------------------|
+| MCP tools (`mempalace_search`, `mempalace_add_drawer`, …) + slash commands | The plugin — see [`.cursor-plugin/README.md`](../../.cursor-plugin/README.md) |
+| Auto-save every N turns + sessionStart memory recall | The hooks here — see Option A above |
+| Both | Install the plugin AND run `hooks/cursor/install.sh` |
+
+Hooks are deliberately **not** bundled into the plugin because Cursor's hooks system is configured per-user/per-project (in `~/.cursor/hooks.json` or `.cursor/hooks.json`), not per-plugin — so the installer here owns that file with idempotent merge semantics, while the plugin owns the MCP+commands+skill side.
+
+## See also
+
+- [`hooks/cursor/README.md`](../../hooks/cursor/README.md) — full reference for hooks
+- [`hooks/cursor/STDIN_SHAPE.md`](../../hooks/cursor/STDIN_SHAPE.md) — per-event schema with citations
+- [`website/guide/cursor-hooks.md`](../../website/guide/cursor-hooks.md) — rendered docs
+- [`.cursor-plugin/README.md`](../../.cursor-plugin/README.md) — Cursor plugin (MCP + commands + skill)
diff --git a/examples/cursor/hooks.json b/examples/cursor/hooks.json
new file mode 100644
index 0000000..93c1420
--- /dev/null
+++ b/examples/cursor/hooks.json
@@ -0,0 +1,21 @@
+{
+ "version": 1,
+ "hooks": {
+ "sessionStart": [
+ {
+ "command": "$HOME/.mempalace/hooks/cursor/mempal_wake_hook_cursor.sh"
+ }
+ ],
+ "stop": [
+ {
+ "command": "$HOME/.mempalace/hooks/cursor/mempal_save_hook_cursor.sh",
+ "loop_limit": 1
+ }
+ ],
+ "preCompact": [
+ {
+ "command": "$HOME/.mempalace/hooks/cursor/mempal_precompact_hook_cursor.sh"
+ }
+ ]
+ }
+}
diff --git a/examples/cursor/hooks.minimal.json b/examples/cursor/hooks.minimal.json
new file mode 100644
index 0000000..4dfd597
--- /dev/null
+++ b/examples/cursor/hooks.minimal.json
@@ -0,0 +1,11 @@
+{
+ "version": 1,
+ "hooks": {
+ "stop": [
+ {
+ "command": "$HOME/.mempalace/hooks/cursor/mempal_save_hook_cursor.sh",
+ "loop_limit": 1
+ }
+ ]
+ }
+}
diff --git a/hooks/README.md b/hooks/README.md
index 7722d2a..31c9ff6 100644
--- a/hooks/README.md
+++ b/hooks/README.md
@@ -2,6 +2,13 @@
These hook scripts make MemPalace save automatically. No manual "save" commands needed.
+This file covers the **Claude Code** and **Codex CLI** hooks that live
+flat under `hooks/`. For the **Cursor IDE** hooks, see
+[`hooks/cursor/README.md`](cursor/README.md) or the rendered docs at
+[`website/guide/cursor-hooks.md`](../website/guide/cursor-hooks.md). The
+two are additive and share the same `~/.mempalace/hook_state/`
+directory.
+
If you are trying to protect existing Claude Code transcripts immediately,
use the short checklist first: [`website/guide/claude-code-retention.md`](../website/guide/claude-code-retention.md).
It covers hook wiring, JSONL backup, and one-time backfill.
diff --git a/hooks/cursor/README.md b/hooks/cursor/README.md
new file mode 100644
index 0000000..53b1fac
--- /dev/null
+++ b/hooks/cursor/README.md
@@ -0,0 +1,133 @@
+# MemPalace Cursor IDE Hooks
+
+Auto-save and session-recall hooks for the [Cursor](https://cursor.com) IDE,
+matching the behaviour of the existing Claude Code + Codex hooks at the repo
+root and adding two Cursor-only capabilities (`sessionStart` recall and a
+preCompact transcript snapshot).
+
+For the rendered documentation see
+[`website/guide/cursor-hooks.md`](../../website/guide/cursor-hooks.md) or
+the published version at
+[mempalaceofficial.com/guide/cursor-hooks](https://mempalaceofficial.com/guide/cursor-hooks.html).
+
+## What's here
+
+| File | Role |
+|-------------------------------------|---------------------------------------------------------------------|
+| `lib/common.sh` | Shared bash helpers (parse, log, counter, wing inference, kill switch). Sourced by all three hooks. |
+| `mempal_save_hook_cursor.sh` | Cursor `stop` hook. Counts stop invocations per conversation, emits a `followup_message` every `SAVE_INTERVAL` (default 15) telling the agent to file the session into MemPalace. |
+| `mempal_precompact_hook_cursor.sh` | Cursor `preCompact` hook. Runs `mempalace mine` synchronously on the transcript before compaction, then drops a `.pending` marker so the next stop forces a save nudge. |
+| `mempal_wake_hook_cursor.sh` | Cursor `sessionStart` hook. Returns `additional_context` telling the agent to recall scoped to the wing inferred from the workspace root. Cursor-only — Claude Code has no equivalent. |
+| `install.sh` | Optional installer. Copies the scripts to `~/.mempalace/hooks/cursor/` and merges entries into `~/.cursor/hooks.json` (or `.cursor/hooks.json` for project scope). Supports `--dry-run` and `--uninstall`. |
+| `STDIN_SHAPE.md` | Reference. Per-event stdin / stdout schema with citations to the official Cursor docs. |
+
+## Quick install
+
+Preview first (writes nothing, prints the would-be JSON to stdout):
+
+```bash
+hooks/cursor/install.sh --scope user --dry-run
+```
+
+Apply — writes `~/.cursor/hooks.json` and copies the scripts to `~/.mempalace/hooks/cursor/`:
+
+```bash
+hooks/cursor/install.sh --scope user
+```
+
+Pass `--scope project --target ` to write `/.cursor/hooks.json` instead.
+The installer never auto-runs — it is a documented opt-in step. We do not
+modify your Cursor config on `pip install mempalace` because editor config
+is sacred and should never be touched without explicit consent.
+
+## Manual install (no installer)
+
+The minimum wiring is `stop` only. Add to `~/.cursor/hooks.json`:
+
+```json
+{
+ "version": 1,
+ "hooks": {
+ "stop": [
+ {
+ "command": "/absolute/path/to/hooks/cursor/mempal_save_hook_cursor.sh",
+ "loop_limit": 1
+ }
+ ]
+ }
+}
+```
+
+For the full triple (recommended), also wire `sessionStart` and `preCompact`
+— see [`examples/cursor/hooks.json`](../../examples/cursor/hooks.json).
+
+After editing the file, Cursor watches `hooks.json` and reloads
+automatically. If hooks still do not fire, restart Cursor and check the
+Hooks panel in Settings.
+
+## Configuration
+
+All knobs are env vars; defaults match the Claude Code hooks where
+possible so a single hook-state directory works for both editors.
+
+| Variable | Default | Purpose |
+|--------------------------------|------------------------------------|---------|
+| `MEMPAL_SAVE_INTERVAL` | `15` | Number of `stop` events between save followups. |
+| `MEMPAL_DIR` | (unset) | Optional project directory to also mine on each save. Additive — never replaces the transcript mine. |
+| `MEMPAL_PYTHON` | auto-detected | Path to a Python 3 interpreter. Fallback order: `$MEMPAL_PYTHON` → `command -v python3` → bare `python3`. Useful when Cursor is launched from a GUI on macOS and the inherited PATH lacks your installed `python3`. |
+| `MEMPAL_STATE_DIR` | `$HOME/.mempalace/hook_state` | Where the hook keeps its per-conversation counter files, pending-save markers, and `cursor_hook.log`. |
+| `MEMPAL_DISABLE_HOOK` | (unset) | Set to `1`/`true`/`yes` to disable all three hooks. Emergency kill switch. |
+| `MEMPALACE_HOOKS_AUTO_SAVE` | (unset) | Set to `false`/`0`/`no` to disable. Same semantics as the Claude Code hooks. Also honoured via `~/.mempalace/config.json` → `{"hooks": {"auto_save": false}}`. |
+
+## Debugging
+
+Everything appends to:
+
+```bash
+cat ~/.mempalace/hook_state/cursor_hook.log
+```
+
+Example log lines (ISO 8601 + event + conversation id):
+
+```
+[2026-05-27T02:16:01Z] [event=sessionStart] [conv=abc123] workspace=/Users/me/proj wing=proj
+[2026-05-27T02:21:33Z] [event=stop] [conv=abc123] counter 0 -> 1 (interval=15)
+[2026-05-27T02:42:09Z] [event=stop] [conv=abc123] counter 14 -> 15 (interval=15)
+[2026-05-27T02:42:09Z] [event=stop] [conv=abc123] TRIGGERING SAVE at counter=15
+[2026-05-27T02:42:11Z] [event=stop] [conv=abc123] loop_count>0; letting agent stop
+```
+
+When a hook can't parse its stdin (corrupt payload, future Cursor schema
+change), the raw input (capped at 4096 bytes, mode 0600) lands at:
+
+```
+~/.mempalace/hook_state/cursor_last_input.log
+~/.mempalace/hook_state/cursor_last_python_err.log
+```
+
+These are overwritten on each failure, never appended, so a repeating
+misconfiguration cannot grow disk usage.
+
+## What differs from the Claude Code hooks
+
+| Aspect | Claude Code hooks (`hooks/mempal_*.sh`) | Cursor hooks (`hooks/cursor/*.sh`) |
+|-------------------------|------------------------------------------------|-----------------------------------------------------|
+| Counter key | `session_id` | `conversation_id` (Cursor's stable per-conv id) |
+| Loop guard | `stop_hook_active` flag in stdin | `loop_count` field in stdin |
+| Counting method | Parses JSONL transcript for user messages | Counts `stop` invocations (transcript schema undoc) |
+| PreCompact behaviour | `decision: block` forces save before compaction | Pre-mine + pending-save marker (Cursor preCompact is observational-only) |
+| sessionStart | n/a (Claude Code has no equivalent) | `additional_context` injects recall guidance |
+| State dir | `$HOME/.mempalace/hook_state` (hardcoded) | Same default, plus `MEMPAL_STATE_DIR` env override |
+| Kill switch | `MEMPALACE_HOOKS_AUTO_SAVE=false` | Same, plus `MEMPAL_DISABLE_HOOK=1` alias |
+| Log file | `hook.log` | `cursor_hook.log` (kept separate to avoid cross-tool log churn) |
+
+See [`STDIN_SHAPE.md`](STDIN_SHAPE.md) for the per-event schema and
+[`website/guide/cursor-hooks.md`](../../website/guide/cursor-hooks.md) for
+the full walkthrough with diagrams.
+
+## Cost
+
+Zero extra tokens. The hooks are local bash scripts that run on your machine.
+The followup message the save hook emits is a normal user turn — it counts
+the same as any other user message and does not invoke any extra LLM call
+beyond the one the user would otherwise make.
diff --git a/hooks/cursor/STDIN_SHAPE.md b/hooks/cursor/STDIN_SHAPE.md
new file mode 100644
index 0000000..2fab0f7
--- /dev/null
+++ b/hooks/cursor/STDIN_SHAPE.md
@@ -0,0 +1,184 @@
+# Cursor Hook Stdin Shape — Reference
+
+This file documents the JSON payloads the Cursor IDE sends to the
+MemPalace hook scripts in `hooks/cursor/`. It exists so a future
+contributor does not have to re-discover the schema by writing a
+probe hook.
+
+**Source:** [`cursor.com/docs/hooks.md`](https://cursor.com/docs/hooks.md),
+fetched 2026-05-27. Cursor's hook system is documented as a stable
+v1 schema (`{"version": 1, ...}` at the top of `hooks.json`).
+
+If you suspect Cursor has changed the payload shape since that fetch
+date, re-verify against the upstream docs and update both this file
+and `hooks/cursor/lib/common.sh::mempal_parse_stdin`. The hook
+scripts deliberately ignore fields they do not consume, so adding
+new fields is non-breaking.
+
+## Common fields (all events)
+
+Every hook receives these on stdin in addition to its event-specific
+fields. Source: docs section "Common schema → Input (all hooks)".
+
+```json
+{
+ "conversation_id": "string",
+ "generation_id": "string",
+ "model": "string",
+ "hook_event_name": "string",
+ "cursor_version": "string",
+ "workspace_roots": [""],
+ "user_email": "string | null",
+ "transcript_path": "string | null"
+}
+```
+
+**Field notes (verified):**
+
+- `conversation_id` is the stable per-conversation ID. The Cursor
+ `stop` event does **not** carry a `session_id` — only
+ `conversation_id`. MemPalace keys its counter files on this. Cursor
+ `sessionStart` does carry a `session_id`, and the docs note it is
+ "same as `conversation_id`".
+- `generation_id` changes every user message. We do not use it.
+- `transcript_path` may be `null` if the user has disabled
+ transcripts in Cursor settings. The hooks degrade gracefully when
+ the value is empty.
+- `workspace_roots` is normally a single-entry array but multi-root
+ workspaces are supported; MemPalace uses index `[0]`.
+
+## Event-specific fields
+
+### `stop` (consumed by `mempal_save_hook_cursor.sh`)
+
+```json
+{
+ "status": "completed" | "aborted" | "error",
+ "loop_count": 0
+}
+```
+
+- `loop_count` indicates how many times this stop hook has already
+ triggered an automatic followup for this conversation (starts at
+ 0). When `loop_count > 0` we know our own previous `followup_message`
+ is currently being processed — the save hook returns `{}` so the
+ agent can finish. Equivalent to Claude Code's `stop_hook_active`.
+- The per-script `loop_limit` (default 5 for Cursor hooks, configurable
+ via the `loop_limit` field on the hook entry in `hooks.json`) is
+ defense-in-depth on top of our own check. The example `hooks.json`
+ in `examples/cursor/` sets `loop_limit: 1`.
+
+**Allowed output fields** (only):
+
+```json
+{ "followup_message": "" }
+```
+
+### `preCompact` (consumed by `mempal_precompact_hook_cursor.sh`)
+
+```json
+{
+ "trigger": "auto" | "manual",
+ "context_usage_percent": 85,
+ "context_tokens": 120000,
+ "context_window_size": 128000,
+ "message_count": 45,
+ "messages_to_compact": 30,
+ "is_first_compaction": true
+}
+```
+
+**Critical constraint:** preCompact is documented as **observational
+only**. It cannot block compaction and its allowed output fields are
+limited to:
+
+```json
+{ "user_message": "" }
+```
+
+There is **no** `followup_message` and **no** `decision: block` on
+this event — unlike Claude Code's `PreCompact`. MemPalace works
+around this by:
+
+1. Running `mempalace mine` synchronously inside the hook so the
+ verbatim transcript lands in the palace before compaction
+ summarises it.
+2. Dropping a `cursor_.pending` marker that the next
+ `stop` invocation reads and uses to force a save followup
+ regardless of its counter.
+
+### `sessionStart` (consumed by `mempal_wake_hook_cursor.sh`)
+
+```json
+{
+ "session_id": "",
+ "is_background_agent": true,
+ "composer_mode": "agent" | "ask" | "edit"
+}
+```
+
+`session_id` equals `conversation_id` on this event (docs are
+explicit about this).
+
+**Allowed output fields:**
+
+```json
+{
+ "env": { "": "" },
+ "additional_context": ""
+}
+```
+
+`additional_context` is the field MemPalace uses. The schema also
+accepts `continue` and `user_message` but the docs explicitly note
+"current callers do not enforce them; session creation is not
+blocked even when continue is false". We do not emit either.
+
+## Environment variables (all hooks)
+
+Cursor sets these env vars on every hook execution; the hook scripts
+fall back to them when JSON parsing fails for any reason.
+
+| Variable | Description |
+|---------------------------|---------------------------------------------------|
+| `CURSOR_PROJECT_DIR` | Workspace root (= `workspace_roots[0]`) |
+| `CURSOR_VERSION` | Cursor version string |
+| `CURSOR_USER_EMAIL` | Authenticated user email (if logged in) |
+| `CURSOR_TRANSCRIPT_PATH` | Conversation transcript path (if transcripts on) |
+| `CURSOR_CODE_REMOTE` | `"true"` if running in a remote workspace |
+| `CLAUDE_PROJECT_DIR` | Alias for `CURSOR_PROJECT_DIR` (Claude compat) |
+
+## Exit code semantics
+
+Cursor interprets command-hook exit codes as follows
+(docs "Hook Types → Command-Based Hooks → Exit code behavior"):
+
+- `0` — success, use the JSON output.
+- `2` — block the action (equivalent to `permission: "deny"`).
+- Other — hook failed; action proceeds (fail-open by default).
+
+MemPalace hooks always exit `0` and emit either `{}` (no-op) or a
+valid JSON response. We never use exit code `2`; nothing MemPalace
+does should ever block an agent action.
+
+## Working directory contract
+
+- **User hooks** (`~/.cursor/hooks.json`) run from `~/.cursor/`.
+- **Project hooks** (`.cursor/hooks.json`) run from the project root.
+
+The MemPalace hooks always resolve their sibling `lib/common.sh` via
+`BASH_SOURCE[0]` so the working directory does not matter for the
+script's own loading — only the `command` path in `hooks.json` needs
+to point at the absolute location of the script.
+
+## Transcript file format (out of scope)
+
+The format of the file at `transcript_path` is **not documented by
+Cursor** as of the fetch date above. MemPalace deliberately does not
+parse it: the save hook counts `stop` invocations (each one
+corresponds to one assistant turn) and hands the transcript to
+`mempalace mine`, which has its own normaliser layer.
+
+If you need to consume the transcript directly, probe its shape with
+a throw-away hook that does `cat > /tmp/cursor-transcript-sample.txt`
+and inspect the output — there is no shortcut.
diff --git a/hooks/cursor/install.sh b/hooks/cursor/install.sh
new file mode 100755
index 0000000..76fa319
--- /dev/null
+++ b/hooks/cursor/install.sh
@@ -0,0 +1,391 @@
+#!/bin/bash
+# MEMPALACE CURSOR HOOK INSTALLER
+#
+# Optional helper. Copies the three Cursor hook scripts to a
+# stable install location and merges entries into a Cursor
+# `hooks.json` config file — without clobbering unrelated hooks
+# already in that file.
+#
+# This is NEVER auto-invoked. Editor config is sacred; we do not
+# modify a user's hooks.json without explicit consent. The user runs
+# this script (or wires the hooks manually) as a documented opt-in.
+#
+# === USAGE ===
+#
+# hooks/cursor/install.sh [options]
+#
+# Options:
+# --scope user|project Target scope. Default: user.
+# - user: merges into ~/.cursor/hooks.json
+# - project: merges into /.cursor/hooks.json
+# --target Project root for --scope project (default: $PWD).
+# Ignored for --scope user.
+# --install-dir Where to copy the hook scripts.
+# Default: ~/.mempalace/hooks/cursor
+# --variant full|minimal Which hook set to wire.
+# - full: stop + preCompact + sessionStart
+# - minimal: stop only
+# Default: full.
+# --dry-run Print the would-be JSON to stdout, do not write
+# and do not copy scripts.
+# --uninstall Remove MemPalace entries from the target
+# hooks.json (preserves unrelated hooks).
+# Does NOT delete the installed scripts.
+# -h, --help Show this help and exit.
+#
+# === PORTABILITY ===
+#
+# Pure bash 3.2 + POSIX tools + python3 (which the hook scripts
+# themselves already require). No `jq` dependency.
+#
+# Python helpers are materialised to temp files rather than piped via
+# `$(... <<'PYEOF' ... PYEOF)` to dodge the bash 3.2.57 parser bug
+# that trips on parens nested inside a heredoc body that lives inside
+# a `$(...)` command substitution.
+
+set -e
+
+usage() {
+ sed -n '2,38p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+# ── Defaults ──────────────────────────────────────────────────────
+SCOPE="user"
+TARGET=""
+INSTALL_DIR="$HOME/.mempalace/hooks/cursor"
+VARIANT="full"
+DRY_RUN=0
+UNINSTALL=0
+
+# ── Parse args ────────────────────────────────────────────────────
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --scope)
+ shift
+ SCOPE="${1:-}"
+ ;;
+ --target)
+ shift
+ TARGET="${1:-}"
+ ;;
+ --install-dir)
+ shift
+ INSTALL_DIR="${1:-}"
+ ;;
+ --variant)
+ shift
+ VARIANT="${1:-}"
+ ;;
+ --dry-run) DRY_RUN=1 ;;
+ --uninstall) UNINSTALL=1 ;;
+ -h|--help)
+ usage
+ exit 0
+ ;;
+ *)
+ printf 'install.sh: unknown argument: %s\n' "$1" >&2
+ usage >&2
+ exit 64
+ ;;
+ esac
+ shift || true
+done
+
+case "$SCOPE" in
+ user|project) ;;
+ *)
+ printf 'install.sh: --scope must be "user" or "project" (got "%s")\n' \
+ "$SCOPE" >&2
+ exit 64
+ ;;
+esac
+
+case "$VARIANT" in
+ full|minimal) ;;
+ *)
+ printf 'install.sh: --variant must be "full" or "minimal" (got "%s")\n' \
+ "$VARIANT" >&2
+ exit 64
+ ;;
+esac
+
+# ── Resolve paths ─────────────────────────────────────────────────
+_script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" 2>/dev/null && pwd)"
+SOURCE_DIR="$_script_dir"
+
+# Resolve the Python interpreter the same way the hooks themselves do
+# so a user with a non-default Python is consistent across install +
+# runtime.
+if [ -n "${MEMPAL_PYTHON:-}" ] && [ -x "$MEMPAL_PYTHON" ]; then
+ PYTHON_BIN="$MEMPAL_PYTHON"
+else
+ PYTHON_BIN="$(command -v python3 2>/dev/null || true)"
+fi
+if [ -z "$PYTHON_BIN" ]; then
+ printf 'install.sh: python3 not found on PATH; cannot proceed.\n' >&2
+ printf 'Set $MEMPAL_PYTHON to an interpreter path or install python3.\n' >&2
+ exit 1
+fi
+
+# Determine the target hooks.json path.
+case "$SCOPE" in
+ user)
+ if [ -n "$TARGET" ]; then
+ printf 'install.sh: --target is only meaningful with --scope project; ignoring.\n' >&2
+ fi
+ TARGET_DIR="$HOME/.cursor"
+ ;;
+ project)
+ TARGET_DIR="${TARGET:-$PWD}/.cursor"
+ ;;
+esac
+TARGET_FILE="$TARGET_DIR/hooks.json"
+
+# Determine which commands the merge / uninstall logic should
+# install or remove. Paths point at the install location, NOT the
+# source repo — once the user runs install.sh they can move / delete
+# the cloned repo without breaking the wiring.
+SAVE_CMD="$INSTALL_DIR/mempal_save_hook_cursor.sh"
+PRECOMPACT_CMD="$INSTALL_DIR/mempal_precompact_hook_cursor.sh"
+WAKE_CMD="$INSTALL_DIR/mempal_wake_hook_cursor.sh"
+
+# ── Step 1: copy scripts (skipped on --dry-run / --uninstall) ─────
+if [ "$UNINSTALL" -eq 0 ] && [ "$DRY_RUN" -eq 0 ]; then
+ mkdir -p "$INSTALL_DIR/lib"
+ cp "$SOURCE_DIR/lib/common.sh" "$INSTALL_DIR/lib/common.sh"
+ cp "$SOURCE_DIR/mempal_save_hook_cursor.sh" "$INSTALL_DIR/"
+ cp "$SOURCE_DIR/mempal_precompact_hook_cursor.sh" "$INSTALL_DIR/"
+ cp "$SOURCE_DIR/mempal_wake_hook_cursor.sh" "$INSTALL_DIR/"
+ chmod +x "$INSTALL_DIR/mempal_save_hook_cursor.sh" \
+ "$INSTALL_DIR/mempal_precompact_hook_cursor.sh" \
+ "$INSTALL_DIR/mempal_wake_hook_cursor.sh"
+ printf 'install.sh: copied scripts to %s\n' "$INSTALL_DIR" >&2
+fi
+
+# ── Short-circuit: uninstall with no existing file is a no-op ─────
+#
+# Without this, the merge step would happily write an empty
+# {"version": 1, "hooks": {}} to a brand new file that the user
+# never asked us to create — surprising behaviour that the test
+# suite explicitly guards against.
+if [ "$UNINSTALL" -eq 1 ] && [ ! -f "$TARGET_FILE" ]; then
+ printf 'install.sh: nothing to uninstall (%s does not exist)\n' \
+ "$TARGET_FILE" >&2
+ exit 0
+fi
+
+# ── Step 2: merge / unmerge hooks.json via python3 ────────────────
+#
+# Materialise the merge logic to a temp .py file (see bash 3.2
+# rationale at the top of this script), then invoke it. The Python
+# script is responsible for:
+# * tolerating a missing or empty hooks.json (starts from {})
+# * preserving unrelated hook entries on install
+# * preserving unrelated hook entries on uninstall
+# * recognising MemPalace entries by basename in the `command` field
+# * idempotent install (re-running does not duplicate entries)
+
+# mktemp portability: BSD mktemp wants the template positional, GNU
+# accepts -t with a suffix. The common subset is `mktemp -t prefix`
+# (BSD picks up TMPDIR; GNU emits a path under /tmp). Both work.
+MERGE_PY="$(mktemp -t mempal-install-merge.XXXXXX)"
+trap 'rm -f "$MERGE_PY"' EXIT
+
+cat > "$MERGE_PY" <<'PYEOF'
+"""hooks.json merge helper for hooks/cursor/install.sh.
+
+Argv:
+ sys.argv[1]: path to hooks.json (may not exist)
+ sys.argv[2]: variant ("full" or "minimal")
+ sys.argv[3]: uninstall flag ("1" or "0")
+ sys.argv[4]: save_cmd absolute path
+ sys.argv[5]: precompact_cmd absolute path
+ sys.argv[6]: wake_cmd absolute path
+
+Output: prints the merged JSON to stdout. Exits 2 on a malformed
+existing config (refuses to overwrite a broken file).
+"""
+import json
+import os
+import sys
+
+target_file = sys.argv[1]
+variant = sys.argv[2]
+uninstall = sys.argv[3] == "1"
+save_cmd = sys.argv[4]
+precompact_cmd = sys.argv[5]
+wake_cmd = sys.argv[6]
+
+# Recognise our entries by basename. The three filenames below are
+# the unique product-of-our-naming convention; any entry whose command
+# ends in one of them is treated as a MemPalace entry on
+# install (so we replace rather than duplicate it) and on uninstall
+# (so we remove it without touching unrelated entries). Matching on
+# basename rather than a full-path substring lets users pick any
+# --install-dir without breaking uninstall.
+MEMPAL_BASENAMES = (
+ "mempal_save_hook_cursor.sh",
+ "mempal_precompact_hook_cursor.sh",
+ "mempal_wake_hook_cursor.sh",
+)
+
+if os.path.exists(target_file):
+ with open(target_file, "r", encoding="utf-8") as fh:
+ try:
+ cfg = json.load(fh)
+ except Exception as exc:
+ sys.stderr.write(
+ "install.sh: existing %s is not valid JSON: %s\n"
+ "Refusing to overwrite. Fix the file and retry.\n"
+ % (target_file, exc)
+ )
+ sys.exit(2)
+else:
+ cfg = {}
+
+if not isinstance(cfg, dict):
+ sys.stderr.write(
+ "install.sh: %s top level must be a JSON object; got %s\n"
+ % (target_file, type(cfg).__name__)
+ )
+ sys.exit(2)
+
+cfg.setdefault("version", 1)
+cfg.setdefault("hooks", {})
+if not isinstance(cfg["hooks"], dict):
+ sys.stderr.write(
+ "install.sh: %s 'hooks' must be a JSON object\n" % target_file
+ )
+ sys.exit(2)
+
+
+def is_mempal_entry(entry):
+ if not isinstance(entry, dict):
+ return False
+ cmd = entry.get("command", "")
+ if not isinstance(cmd, str):
+ return False
+ # Match on basename so a customised --install-dir (e.g. /opt/...,
+ # ~/.local/share/..., or anything with or without a leading dot)
+ # still round-trips through uninstall.
+ base = os.path.basename(cmd)
+ return base in MEMPAL_BASENAMES
+
+
+def filter_mempal(entries):
+ if not isinstance(entries, list):
+ return entries
+ return [e for e in entries if not is_mempal_entry(e)]
+
+
+def upsert(event, entry):
+ existing = cfg["hooks"].get(event, [])
+ if not isinstance(existing, list):
+ sys.stderr.write(
+ "install.sh: %s hooks[%s] must be a list\n" % (target_file, event)
+ )
+ sys.exit(2)
+ cleaned = [e for e in existing if not is_mempal_entry(e)]
+ cleaned.append(entry)
+ cfg["hooks"][event] = cleaned
+
+
+if uninstall:
+ for event in list(cfg["hooks"].keys()):
+ cfg["hooks"][event] = filter_mempal(cfg["hooks"][event])
+ if not cfg["hooks"][event]:
+ del cfg["hooks"][event]
+else:
+ upsert("stop", {"command": save_cmd, "loop_limit": 1})
+ if variant == "full":
+ upsert("preCompact", {"command": precompact_cmd})
+ upsert("sessionStart", {"command": wake_cmd})
+
+# Stable key order for the events MemPalace touches, then preserve
+# any unrelated event names in their original order so future Cursor
+# events we don't know about yet still round-trip.
+known_order = [
+ "sessionStart",
+ "stop",
+ "preCompact",
+ "sessionEnd",
+ "preToolUse",
+ "postToolUse",
+ "postToolUseFailure",
+ "subagentStart",
+ "subagentStop",
+ "beforeShellExecution",
+ "afterShellExecution",
+ "beforeMCPExecution",
+ "afterMCPExecution",
+ "beforeReadFile",
+ "afterFileEdit",
+ "beforeSubmitPrompt",
+ "afterAgentResponse",
+ "afterAgentThought",
+ "beforeTabFileRead",
+ "afterTabFileEdit",
+ "workspaceOpen",
+]
+
+ordered_hooks = {}
+for event in known_order:
+ if event in cfg["hooks"]:
+ ordered_hooks[event] = cfg["hooks"][event]
+for event, entries in cfg["hooks"].items():
+ if event not in ordered_hooks:
+ ordered_hooks[event] = entries
+cfg["hooks"] = ordered_hooks
+
+print(json.dumps(cfg, indent=2, sort_keys=False))
+PYEOF
+
+NEW_JSON="$("$PYTHON_BIN" "$MERGE_PY" \
+ "$TARGET_FILE" "$VARIANT" "$UNINSTALL" \
+ "$SAVE_CMD" "$PRECOMPACT_CMD" "$WAKE_CMD")"
+
+# ── Step 3: emit, write, or remove ────────────────────────────────
+if [ "$DRY_RUN" -eq 1 ]; then
+ printf 'install.sh: --dry-run; would write to %s\n' "$TARGET_FILE" >&2
+ printf '%s\n' "$NEW_JSON"
+ exit 0
+fi
+
+mkdir -p "$TARGET_DIR"
+
+# If --uninstall left an empty hooks object AND no other top-level
+# keys beyond version, remove the file entirely so the user's
+# `.cursor/` directory does not accumulate orphan configs.
+if [ "$UNINSTALL" -eq 1 ]; then
+ EMPTY_CHECK_PY="$(mktemp -t mempal-install-empty.XXXXXX)"
+ cat > "$EMPTY_CHECK_PY" <<'PYEOF'
+"""Returns "1" (non-empty) or "0" (empty) on stdout for use by the
+shell caller. 'Empty' means: no hook entries and no top-level keys
+other than 'version' / 'hooks'."""
+import json
+import sys
+
+cfg = json.load(sys.stdin)
+hooks = cfg.get("hooks", {})
+extras = [k for k in cfg.keys() if k not in ("version", "hooks")]
+print("1" if (hooks or extras) else "0")
+PYEOF
+ NON_EMPTY="$(printf '%s' "$NEW_JSON" | "$PYTHON_BIN" "$EMPTY_CHECK_PY")"
+ rm -f "$EMPTY_CHECK_PY"
+ if [ "$NON_EMPTY" = "0" ] && [ -f "$TARGET_FILE" ]; then
+ rm -f "$TARGET_FILE"
+ printf 'install.sh: removed empty %s\n' "$TARGET_FILE" >&2
+ exit 0
+ fi
+fi
+
+TMP_FILE="${TARGET_FILE}.tmp.$$"
+printf '%s\n' "$NEW_JSON" > "$TMP_FILE"
+mv "$TMP_FILE" "$TARGET_FILE"
+
+if [ "$UNINSTALL" -eq 1 ]; then
+ printf 'install.sh: removed MemPalace entries from %s\n' "$TARGET_FILE" >&2
+else
+ printf 'install.sh: wrote %s\n' "$TARGET_FILE" >&2
+ printf 'install.sh: restart Cursor (or wait for it to reload hooks.json)\n' >&2
+fi
diff --git a/hooks/cursor/lib/common.sh b/hooks/cursor/lib/common.sh
new file mode 100644
index 0000000..5af0f64
--- /dev/null
+++ b/hooks/cursor/lib/common.sh
@@ -0,0 +1,418 @@
+# shellcheck shell=bash
+# MEMPALACE CURSOR HOOK — shared helpers
+#
+# Sourced by the three Cursor hooks (stop / preCompact / sessionStart).
+# Mirrors the conventions of the existing Claude Code hook scripts
+# (hooks/mempal_save_hook.sh, hooks/mempal_precompact_hook.sh) so a
+# user who already debugs one knows how to debug the other:
+#
+# * STATE_DIR layout under ~/.mempalace/hook_state/
+# * MEMPAL_PYTHON resolution order (override → $PATH → bare python3)
+# * MEMPALACE_HOOKS_AUTO_SAVE=false kill switch (config.json fallback)
+# * sentinel-guarded Python parser via `sed -n 'Np'` (bash 3.2 safe)
+# * fail-open on internal errors: emit `{}` and log, never crash the
+# hook host
+#
+# Cursor-specific additions on top of that contract:
+#
+# * MEMPAL_DISABLE_HOOK=1 as an additional kill-switch alias
+# * MEMPAL_STATE_DIR env override for the state directory
+# * conversation_id (Cursor's stable per-conversation ID) replaces
+# Claude Code's session_id in the counter file names — Cursor `stop`
+# events do not carry a session_id, only conversation_id
+# * loop_count is the loop-prevention signal in place of Claude Code's
+# stop_hook_active flag (Cursor docs, "stop" event)
+#
+# This file is sourced, not executed, so it intentionally has no
+# shebang. The `# shellcheck shell=bash` directive above tells
+# shellcheck to treat it as bash when run standalone.
+
+# ── State directory + log path ────────────────────────────────────────
+#
+# Honour MEMPAL_STATE_DIR (additive override introduced for Cursor)
+# while keeping the default identical to the Claude Code hooks so a
+# user running both keeps a single state directory.
+MEMPAL_STATE_DIR="${MEMPAL_STATE_DIR:-$HOME/.mempalace/hook_state}"
+mkdir -p "$MEMPAL_STATE_DIR" 2>/dev/null
+MEMPAL_CURSOR_LOG="$MEMPAL_STATE_DIR/cursor_hook.log"
+
+# ── Python interpreter resolution ─────────────────────────────────────
+#
+# Same contract as the Claude Code hooks:
+# 1. $MEMPAL_PYTHON — explicit user override (absolute path)
+# 2. $(command -v python3) — first python3 on the hook's PATH
+# 3. bare "python3" — last-resort fallback
+mempal_resolve_python() {
+ local p="${MEMPAL_PYTHON:-}"
+ if [ -n "$p" ] && [ -x "$p" ]; then
+ printf '%s' "$p"
+ return 0
+ fi
+ p="$(command -v python3 2>/dev/null || true)"
+ if [ -n "$p" ]; then
+ printf '%s' "$p"
+ return 0
+ fi
+ printf '%s' "python3"
+}
+MEMPAL_PYTHON_BIN="$(mempal_resolve_python)"
+
+# ── Logging ───────────────────────────────────────────────────────────
+#
+# Lines are `[ISO8601Z] [event=...] [conv=...] message`. ISO8601 keeps
+# the format greppable across timezones (the Claude Code log uses
+# %H:%M:%S which loses the date — we improve on that here without
+# changing the existing log file).
+mempal_log() {
+ local event="${1:-?}"
+ local conv="${2:-unknown}"
+ local msg="${3:-}"
+ local ts
+ ts="$(date -u '+%Y-%m-%dT%H:%M:%SZ')"
+ printf '[%s] [event=%s] [conv=%s] %s\n' "$ts" "$event" "$conv" "$msg" \
+ >> "$MEMPAL_CURSOR_LOG" 2>/dev/null
+}
+
+# ── Kill switch ───────────────────────────────────────────────────────
+#
+# Disabled if ANY of:
+# * MEMPAL_DISABLE_HOOK is a truthy string (Cursor-prompt addition)
+# * MEMPALACE_HOOKS_AUTO_SAVE is false/0/no (Claude Code convention)
+# * ~/.mempalace/config.json has hooks.auto_save == false
+#
+# Returns 0 (true in shell) when disabled, 1 when enabled.
+mempal_is_disabled() {
+ case "${MEMPAL_DISABLE_HOOK:-}" in
+ 1|true|yes|on) return 0 ;;
+ esac
+ case "${MEMPALACE_HOOKS_AUTO_SAVE:-}" in
+ false|0|no|off) return 0 ;;
+ esac
+ local cfg="$HOME/.mempalace/config.json"
+ if [ -f "$cfg" ]; then
+ local result
+ result="$("$MEMPAL_PYTHON_BIN" - "$cfg" <<'PYEOF' 2>/dev/null
+import json, sys
+try:
+ with open(sys.argv[1]) as f:
+ cfg = json.load(f)
+ print(str(cfg.get("hooks", {}).get("auto_save", True)).lower())
+except Exception:
+ print("true")
+PYEOF
+)"
+ if [ "$result" = "false" ]; then
+ return 0
+ fi
+ fi
+ return 1
+}
+
+# ── Stdin parser ──────────────────────────────────────────────────────
+#
+# Reads Cursor's hook JSON from $1 and exports:
+# MEMPAL_CONV_ID — conversation_id, falls back to "unknown"
+# MEMPAL_LOOP_COUNT — integer (0 if absent / non-numeric)
+# MEMPAL_TRANSCRIPT — transcript_path, may be empty
+# MEMPAL_WORKSPACE — first workspace_roots entry, falls back to
+# CURSOR_PROJECT_DIR env var, then $PWD
+# MEMPAL_TRIGGER — preCompact trigger ("auto" | "manual"), empty otherwise
+# MEMPAL_STATUS — stop status ("completed" | "aborted" | "error"),
+# empty otherwise
+# MEMPAL_PARSE_OK — "1" if parser ran cleanly, "0" otherwise
+#
+# Uses the same sentinel + `sed -n 'Np'` extraction as the Claude Code
+# hooks for bash 3.2 compatibility (mapfile/readarray are unavailable
+# on macOS /bin/bash 3.2.57; #1440 regression). Each line of output is
+# pre-sanitised by the Python side to a shell-safe character set.
+mempal_parse_stdin() {
+ local input="${1:-}"
+ local parsed
+ # We invoke Python via -c with a single-quoted multi-line string
+ # rather than ``python3 - <<'PYEOF'`` because the heredoc form
+ # would shadow Python's stdin with the heredoc body, leaving
+ # ``json.load(sys.stdin)`` to read nothing and silently fail. The
+ # parser body deliberately uses only double-quoted Python strings
+ # so the surrounding bash single-quote is safe verbatim, and uses
+ # only the shell-safe character set (alphanumeric, underscore,
+ # dash, slash, dot, tilde) matching the Claude Code hook's
+ # sanitiser so a hostile transcript_path cannot splice
+ # metacharacters into the parsed output.
+ parsed="$(
+ umask 077
+ printf '%s' "$input" | "$MEMPAL_PYTHON_BIN" -c '
+import json, re, sys
+
+def safe_str(value):
+ return re.sub(r"[^a-zA-Z0-9_/.\-~]", "", str(value or ""))
+
+def safe_int(value):
+ try:
+ return str(int(value))
+ except (TypeError, ValueError):
+ return "0"
+
+try:
+ data = json.load(sys.stdin)
+except Exception:
+ sys.exit(1)
+if not isinstance(data, dict):
+ sys.exit(1)
+
+conv = safe_str(data.get("conversation_id") or data.get("session_id"))
+loop_count = safe_int(data.get("loop_count", 0))
+transcript = safe_str(data.get("transcript_path", ""))
+trigger = safe_str(data.get("trigger", ""))
+status = safe_str(data.get("status", ""))
+
+roots = data.get("workspace_roots") or []
+workspace = ""
+if isinstance(roots, list) and roots:
+ workspace = safe_str(roots[0])
+
+print("__MEMPAL_PARSE_OK__")
+print(conv)
+print(loop_count)
+print(transcript)
+print(workspace)
+print(trigger)
+print(status)
+' 2>"$MEMPAL_STATE_DIR/cursor_last_python_err.log"
+ )"
+
+ # Drop empty stderr capture on success; lock it to 0600 on failure
+ # (mirrors the privacy contract in the Claude Code hooks — the
+ # traceback can echo back transcript_path / home layout).
+ if [ -s "$MEMPAL_STATE_DIR/cursor_last_python_err.log" ]; then
+ chmod 600 "$MEMPAL_STATE_DIR/cursor_last_python_err.log" 2>/dev/null
+ else
+ rm -f "$MEMPAL_STATE_DIR/cursor_last_python_err.log" 2>/dev/null
+ fi
+
+ local marker
+ marker="$(printf '%s\n' "$parsed" | sed -n '1p')"
+ if [ "$marker" = "__MEMPAL_PARSE_OK__" ]; then
+ MEMPAL_PARSE_OK="1"
+ MEMPAL_CONV_ID="$(printf '%s\n' "$parsed" | sed -n '2p')"
+ MEMPAL_LOOP_COUNT="$(printf '%s\n' "$parsed" | sed -n '3p')"
+ MEMPAL_TRANSCRIPT="$(printf '%s\n' "$parsed" | sed -n '4p')"
+ MEMPAL_WORKSPACE="$(printf '%s\n' "$parsed" | sed -n '5p')"
+ MEMPAL_TRIGGER="$(printf '%s\n' "$parsed" | sed -n '6p')"
+ MEMPAL_STATUS="$(printf '%s\n' "$parsed" | sed -n '7p')"
+ else
+ MEMPAL_PARSE_OK="0"
+ MEMPAL_CONV_ID=""
+ MEMPAL_LOOP_COUNT="0"
+ MEMPAL_TRANSCRIPT=""
+ MEMPAL_WORKSPACE=""
+ MEMPAL_TRIGGER=""
+ MEMPAL_STATUS=""
+ fi
+
+ # Defaults and environment fallbacks. The Cursor docs guarantee
+ # CURSOR_TRANSCRIPT_PATH and CURSOR_PROJECT_DIR env vars are set
+ # for every hook execution; if JSON parsing failed for any reason
+ # (sentinel missing, malformed payload, missing interpreter) we
+ # still have a usable workspace.
+ MEMPAL_CONV_ID="${MEMPAL_CONV_ID:-unknown}"
+ case "$MEMPAL_LOOP_COUNT" in
+ ''|*[!0-9]*) MEMPAL_LOOP_COUNT="0" ;;
+ esac
+ if [ -z "$MEMPAL_TRANSCRIPT" ] && [ -n "${CURSOR_TRANSCRIPT_PATH:-}" ]; then
+ MEMPAL_TRANSCRIPT="${CURSOR_TRANSCRIPT_PATH}"
+ fi
+ if [ -z "$MEMPAL_WORKSPACE" ]; then
+ if [ -n "${CURSOR_PROJECT_DIR:-}" ]; then
+ MEMPAL_WORKSPACE="${CURSOR_PROJECT_DIR}"
+ elif [ -n "${CLAUDE_PROJECT_DIR:-}" ]; then
+ MEMPAL_WORKSPACE="${CLAUDE_PROJECT_DIR}"
+ else
+ MEMPAL_WORKSPACE="${PWD:-/}"
+ fi
+ fi
+
+ # Expand a leading ~ in the transcript path so downstream
+ # ``[ -f "$path" ]`` checks resolve correctly.
+ case "$MEMPAL_TRANSCRIPT" in
+ '~/'*) MEMPAL_TRANSCRIPT="$HOME/${MEMPAL_TRANSCRIPT#~/}" ;;
+ esac
+}
+
+# ── Defense-in-depth: dump unparseable stdin ──────────────────────────
+#
+# Same shape as the Claude Code hooks' last_input.log: bounded to 4096
+# bytes, overwritten (never appended) so a misconfiguration loop cannot
+# grow disk usage, 0600 perms because the dump mirrors the raw hook
+# payload (transcript_path reveals the user's home + project layout).
+mempal_dump_bad_input() {
+ local input="${1:-}"
+ if [ -z "$input" ]; then
+ return 0
+ fi
+ mempal_log "${2:-?}" "${MEMPAL_CONV_ID:-unknown}" \
+ "WARN: input parse failed (sentinel missing); see $MEMPAL_STATE_DIR/cursor_last_input.log + cursor_last_python_err.log"
+ (
+ umask 077
+ printf '%s' "$input" | head -c 4096 > "$MEMPAL_STATE_DIR/cursor_last_input.log"
+ )
+ chmod 600 "$MEMPAL_STATE_DIR/cursor_last_input.log" 2>/dev/null
+}
+
+# ── Counter helpers ───────────────────────────────────────────────────
+#
+# One counter file per conversation_id. Atomic write via temp file
+# inside the same directory (rename is atomic on POSIX) so concurrent
+# hook invocations cannot half-write the file. Read tolerates a
+# corrupted or empty file by returning 0, never crashing.
+_mempal_counter_path() {
+ local conv="${1:-unknown}"
+ # Sanitise the conv id one more time: it has already been through
+ # the Python sanitiser, but be defensive in case a caller passes a
+ # raw string. Strip any character outside [a-zA-Z0-9_.-].
+ local safe_conv
+ safe_conv="$(printf '%s' "$conv" | tr -cd 'a-zA-Z0-9_.-')"
+ if [ -z "$safe_conv" ]; then
+ safe_conv="unknown"
+ fi
+ printf '%s/cursor_%s.count' "$MEMPAL_STATE_DIR" "$safe_conv"
+}
+
+mempal_read_counter() {
+ local path="$1"
+ if [ ! -f "$path" ]; then
+ printf '0'
+ return 0
+ fi
+ local raw
+ raw="$(cat "$path" 2>/dev/null)"
+ case "$raw" in
+ ''|*[!0-9]*) printf '0' ;;
+ *) printf '%s' "$raw" ;;
+ esac
+}
+
+mempal_write_counter_atomic() {
+ local path="$1"
+ local value="$2"
+ case "$value" in
+ ''|*[!0-9]*) value="0" ;;
+ esac
+ local tmp="${path}.tmp.$$"
+ printf '%s' "$value" > "$tmp" 2>/dev/null || return 1
+ mv "$tmp" "$path" 2>/dev/null || {
+ rm -f "$tmp" 2>/dev/null
+ return 1
+ }
+}
+
+# ── Pending-save marker ───────────────────────────────────────────────
+#
+# Dropped by the preCompact hook (which cannot itself emit a
+# followup_message — Cursor's preCompact is observational-only) and
+# consumed by the next stop invocation so the LLM still gets a diary
+# nudge after compaction.
+_mempal_pending_path() {
+ local conv="${1:-unknown}"
+ local safe_conv
+ safe_conv="$(printf '%s' "$conv" | tr -cd 'a-zA-Z0-9_.-')"
+ if [ -z "$safe_conv" ]; then
+ safe_conv="unknown"
+ fi
+ printf '%s/cursor_%s.pending' "$MEMPAL_STATE_DIR" "$safe_conv"
+}
+
+mempal_set_pending() {
+ local conv="${1:-unknown}"
+ local path
+ path="$(_mempal_pending_path "$conv")"
+ : > "$path" 2>/dev/null || return 1
+ chmod 600 "$path" 2>/dev/null
+}
+
+mempal_consume_pending() {
+ local conv="${1:-unknown}"
+ local path
+ path="$(_mempal_pending_path "$conv")"
+ if [ -f "$path" ]; then
+ rm -f "$path" 2>/dev/null
+ return 0
+ fi
+ return 1
+}
+
+# ── Workspace → wing inference ────────────────────────────────────────
+#
+# basename(workspace_root), normalised to [a-z0-9_-]. Edge cases:
+# / → "root"
+# /path/ → trailing slash stripped, then basename
+# "/foo bar/" → "foo_bar" (spaces collapsed to underscores)
+# "" → "cursor_session"
+# "C:\\proj" → "proj" (Windows-style path; basename via tr fallback)
+#
+# We intentionally keep this in pure bash + POSIX tools so the
+# inference is identical across the hook scripts and the test suite
+# can target it as a function via `bash -c 'source ...; ...'`.
+mempal_infer_wing() {
+ local raw="${1:-}"
+ if [ -z "$raw" ]; then
+ printf 'cursor_session'
+ return 0
+ fi
+ # Strip trailing slashes (but preserve the lone "/" case).
+ while [ "$raw" != "/" ] && [ "${raw%/}" != "$raw" ]; do
+ raw="${raw%/}"
+ done
+ if [ "$raw" = "/" ]; then
+ printf 'root'
+ return 0
+ fi
+ local base="${raw##*/}"
+ # On Windows-style paths with backslashes, fall back to splitting
+ # on backslash too so we don't return the whole path verbatim.
+ case "$base" in
+ *\\*) base="${base##*\\}" ;;
+ esac
+ # Lowercase + replace anything outside [a-z0-9_-] with underscore.
+ # Collapse runs of underscores so "foo bar" doesn't become
+ # "foo__bar".
+ base="$(printf '%s' "$base" \
+ | tr '[:upper:]' '[:lower:]' \
+ | tr -c 'a-z0-9_-' '_' \
+ | tr -s '_' \
+ | sed 's/^_//; s/_$//')"
+ if [ -z "$base" ]; then
+ printf 'cursor_session'
+ return 0
+ fi
+ printf '%s' "$base"
+}
+
+# ── Transcript path validation ────────────────────────────────────────
+#
+# Mirrors hooks/mempal_save_hook.sh::is_valid_transcript_path so the
+# Cursor and Claude Code hooks reject the same shapes:
+# * non-empty
+# * .json or .jsonl suffix
+# * no .. traversal segments
+mempal_is_valid_transcript() {
+ local path="${1:-}"
+ [ -n "$path" ] || return 1
+ case "$path" in
+ *.json|*.jsonl) ;;
+ *) return 1 ;;
+ esac
+ case "/$path/" in
+ */../*) return 1 ;;
+ esac
+ return 0
+}
+
+# ── JSON emit ─────────────────────────────────────────────────────────
+#
+# Final stdout write. Uses ``printf '%s'`` instead of ``echo`` because
+# echo interprets ``-n``/``-e``/``-E`` as flags and varies in backslash
+# handling between builtin and /bin/echo (xpg_echo shopt). Matches the
+# Claude Code hook's documented rationale.
+mempal_emit() {
+ printf '%s\n' "${1:-{\}}"
+}
diff --git a/hooks/cursor/mempal_precompact_hook_cursor.sh b/hooks/cursor/mempal_precompact_hook_cursor.sh
new file mode 100755
index 0000000..6b44783
--- /dev/null
+++ b/hooks/cursor/mempal_precompact_hook_cursor.sh
@@ -0,0 +1,111 @@
+#!/bin/bash
+# MEMPALACE CURSOR PRE-COMPACT HOOK — Snapshot transcript before compaction
+#
+# Cursor "preCompact" hook. Cursor's preCompact is documented as
+# OBSERVATIONAL ONLY (cursor.com/docs/hooks.md fetched 2026-05-27):
+#
+# * It cannot block compaction.
+# * Its only output field is `user_message` (no `followup_message`,
+# no `decision: block`).
+#
+# So unlike the Claude Code PreCompact hook (which can block the AI
+# and force a save before compaction proceeds), the Cursor preCompact
+# hook can only do two useful things at this moment:
+#
+# 1. Run `mempalace mine` SYNCHRONOUSLY against the transcript file.
+# The verbatim drawers land in the palace BEFORE Cursor
+# summarises the conversation. This is the actual data-loss
+# protection — zero LLM cost, no agent interaction needed.
+#
+# 2. Drop a `.pending` marker file keyed on conversation_id. The
+# next `stop` hook reads that marker and forces a save followup
+# regardless of its counter, so the AI still gets a "write a
+# diary entry now" nudge on the very next turn.
+#
+# === INSTALL ===
+#
+# Add to ~/.cursor/hooks.json (or .cursor/hooks.json for project
+# scope) under "preCompact":
+#
+# {
+# "version": 1,
+# "hooks": {
+# "preCompact": [
+# { "command": "/absolute/path/to/mempal_precompact_hook_cursor.sh" }
+# ]
+# }
+# }
+#
+# No loop_limit is needed; preCompact is not a looping hook.
+
+_mempal_self="${BASH_SOURCE[0]:-$0}"
+_mempal_dir="$(cd "$(dirname "$_mempal_self")" 2>/dev/null && pwd)"
+# shellcheck source=lib/common.sh
+. "$_mempal_dir/lib/common.sh"
+
+# Optional additional project directory to mine before compaction
+# (parity with the Claude Code hook's MEMPAL_DIR knob).
+MEMPAL_DIR="${MEMPAL_DIR:-}"
+
+if mempal_is_disabled; then
+ mempal_emit '{}'
+ exit 0
+fi
+
+INPUT="$(cat)"
+mempal_parse_stdin "$INPUT"
+
+if [ "$MEMPAL_PARSE_OK" != "1" ]; then
+ mempal_dump_bad_input "$INPUT" "preCompact"
+ mempal_emit '{}'
+ exit 0
+fi
+
+mempal_log "preCompact" "$MEMPAL_CONV_ID" \
+ "trigger=${MEMPAL_TRIGGER:-?} transcript=$MEMPAL_TRANSCRIPT"
+
+# ── Synchronous mine ──────────────────────────────────────────────
+#
+# This intentionally blocks the hook (within Cursor's per-hook
+# timeout). Compaction is irreversible — once Cursor summarises the
+# conversation we cannot get the verbatim text back. Background-mining
+# would race the compaction.
+if command -v mempalace >/dev/null 2>&1; then
+ if mempal_is_valid_transcript "$MEMPAL_TRANSCRIPT" \
+ && [ -f "$MEMPAL_TRANSCRIPT" ]; then
+ mempalace mine "$(dirname "$MEMPAL_TRANSCRIPT")" --mode convos \
+ >> "$MEMPAL_CURSOR_LOG" 2>&1 || \
+ mempal_log "preCompact" "$MEMPAL_CONV_ID" \
+ "WARN: mempalace mine convos returned non-zero"
+ elif [ -n "$MEMPAL_TRANSCRIPT" ]; then
+ mempal_log "preCompact" "$MEMPAL_CONV_ID" \
+ "skipping invalid transcript path: $MEMPAL_TRANSCRIPT"
+ fi
+ if [ -n "$MEMPAL_DIR" ] && [ -d "$MEMPAL_DIR" ]; then
+ mempalace mine "$MEMPAL_DIR" --mode projects \
+ >> "$MEMPAL_CURSOR_LOG" 2>&1 || \
+ mempal_log "preCompact" "$MEMPAL_CONV_ID" \
+ "WARN: mempalace mine projects returned non-zero"
+ fi
+else
+ mempal_log "preCompact" "$MEMPAL_CONV_ID" \
+ "mempalace CLI not on PATH; skipping synchronous mine"
+fi
+
+# ── Drop the pending-save marker ──────────────────────────────────
+mempal_set_pending "$MEMPAL_CONV_ID" || \
+ mempal_log "preCompact" "$MEMPAL_CONV_ID" \
+ "WARN: could not write pending-save marker"
+
+# Surface a short user-visible note that compaction is about to
+# happen and we've already captured the verbatim text. user_message
+# is the only output field Cursor's preCompact accepts.
+"$MEMPAL_PYTHON_BIN" -c '
+import json
+print(json.dumps({
+ "user_message": (
+ "MemPalace: transcript snapshotted before compaction. "
+ "A diary nudge is queued for the next agent turn."
+ )
+}))
+'
diff --git a/hooks/cursor/mempal_save_hook_cursor.sh b/hooks/cursor/mempal_save_hook_cursor.sh
new file mode 100755
index 0000000..94731e6
--- /dev/null
+++ b/hooks/cursor/mempal_save_hook_cursor.sh
@@ -0,0 +1,195 @@
+#!/bin/bash
+# MEMPALACE CURSOR SAVE HOOK — Auto-save every N stop events
+#
+# Cursor "stop" hook. After every agent loop ends, this hook:
+# 1. Counts stop invocations per conversation_id (each stop ≈ one
+# assistant turn ≈ roughly one user message — see plan rationale).
+# 2. Every SAVE_INTERVAL stops, returns a followup_message telling
+# the agent to file the session into MemPalace and write a diary
+# entry. Cursor auto-submits that as the next user message.
+# 3. On the next stop, loop_count > 0 so we let the agent finish
+# without re-firing — Cursor's loop_count is the equivalent of
+# Claude Code's stop_hook_active flag.
+# 4. If the preCompact hook has left a `.pending` marker, force a
+# save followup regardless of the counter and clear the marker.
+#
+# Companion files in this directory:
+# * lib/common.sh — shared helpers (sourced)
+# * mempal_precompact_hook_cursor.sh — preCompact event
+# * mempal_wake_hook_cursor.sh — sessionStart event
+#
+# === INSTALL ===
+#
+# Recommended path: run `hooks/cursor/install.sh` from a cloned repo,
+# which copies the scripts to ~/.mempalace/hooks/cursor/ and merges
+# the wiring into your ~/.cursor/hooks.json. See hooks/cursor/README.md
+# for the full walkthrough, or website/guide/cursor-hooks.md for the
+# rendered version.
+#
+# Manual wiring (user scope: ~/.cursor/hooks.json):
+#
+# {
+# "version": 1,
+# "hooks": {
+# "stop": [
+# {
+# "command": "/absolute/path/to/mempal_save_hook_cursor.sh",
+# "loop_limit": 1
+# }
+# ]
+# }
+# }
+#
+# The `loop_limit: 1` cap is defense-in-depth — even if our own
+# loop_count check below regresses, Cursor itself will stop emitting
+# our followup after one auto-iteration.
+#
+# === KILL SWITCHES ===
+#
+# MEMPAL_DISABLE_HOOK=1 — Cursor-prompt addition
+# MEMPALACE_HOOKS_AUTO_SAVE=false — matches the Claude Code hooks
+# ~/.mempalace/config.json "hooks.auto_save": false
+#
+# Any one of these short-circuits the hook to `{}` and exits 0.
+
+# Resolve the directory this script lives in so we can source the
+# sibling lib/common.sh whether the user invoked us by absolute path,
+# by relative path, or via a symlink.
+_mempal_self="${BASH_SOURCE[0]:-$0}"
+_mempal_dir="$(cd "$(dirname "$_mempal_self")" 2>/dev/null && pwd)"
+# shellcheck source=lib/common.sh
+. "$_mempal_dir/lib/common.sh"
+
+SAVE_INTERVAL="${MEMPAL_SAVE_INTERVAL:-15}"
+case "$SAVE_INTERVAL" in
+ ''|*[!0-9]*) SAVE_INTERVAL=15 ;;
+esac
+
+# Optional additional project directory to mine on save (parity with
+# the Claude Code hook's MEMPAL_DIR knob — purely additive, never an
+# override for the transcript mine).
+MEMPAL_DIR="${MEMPAL_DIR:-}"
+
+# Kill switch — emit `{}` so Cursor proceeds with normal stop.
+if mempal_is_disabled; then
+ mempal_emit '{}'
+ exit 0
+fi
+
+INPUT="$(cat)"
+mempal_parse_stdin "$INPUT"
+
+if [ "$MEMPAL_PARSE_OK" != "1" ]; then
+ mempal_dump_bad_input "$INPUT" "stop"
+ # Fail-open: don't block the host on a parse error.
+ mempal_emit '{}'
+ exit 0
+fi
+
+mempal_log "stop" "$MEMPAL_CONV_ID" \
+ "loop_count=$MEMPAL_LOOP_COUNT status=${MEMPAL_STATUS:-?} workspace=$MEMPAL_WORKSPACE"
+
+# ── Loop-prevention ────────────────────────────────────────────────
+#
+# Cursor's loop_count indicates how many times THIS stop hook has
+# already triggered an automatic followup for this conversation
+# (starts at 0). If it is > 0, our own previous followup is currently
+# being consumed by the agent — let it finish without re-firing.
+if [ "$MEMPAL_LOOP_COUNT" -gt 0 ] 2>/dev/null; then
+ mempal_log "stop" "$MEMPAL_CONV_ID" "loop_count>0; letting agent stop"
+ mempal_emit '{}'
+ exit 0
+fi
+
+WING="$(mempal_infer_wing "$MEMPAL_WORKSPACE")"
+
+# Build the followup message once; both the pending-marker branch and
+# the threshold branch use it. Constructed via Python -c (rather than
+# a heredoc) so we can pass the inferred wing as argv[1] and so the
+# JSON encoding is correct even for wings whose name would otherwise
+# need shell quoting.
+_mempal_build_followup() {
+ "$MEMPAL_PYTHON_BIN" -c '
+import json, sys
+wing = sys.argv[1] if len(sys.argv) > 1 else "cursor_session"
+msg = (
+ "MemPalace save checkpoint. "
+ "(1) Call mempalace_check_duplicate on the key topics, decisions, "
+ "and verbatim quotes from this session. "
+ "(2) For each non-duplicate, call mempalace_add_drawer (wing="
+ + wing + ", room=, content=verbatim quote). "
+ "(3) Call mempalace_diary_write (agent_name=cursor-ide, wing="
+ + wing + ", entry=AAAK-format summary). "
+ "Then stop."
+)
+print(json.dumps({"followup_message": msg}))
+' "$WING"
+}
+
+# ── Pending-save marker from preCompact ───────────────────────────
+#
+# preCompact cannot itself emit a followup_message (Cursor docs:
+# preCompact is observational-only, output supports only user_message),
+# so it drops a marker file and we consume it here. Forces a save
+# nudge regardless of the counter.
+if mempal_consume_pending "$MEMPAL_CONV_ID"; then
+ mempal_log "stop" "$MEMPAL_CONV_ID" \
+ "consumed pending-save marker (post-compaction)"
+ _mempal_build_followup
+ exit 0
+fi
+
+# ── Normal counter path ───────────────────────────────────────────
+COUNTER_FILE="$(_mempal_counter_path "$MEMPAL_CONV_ID")"
+CURRENT="$(mempal_read_counter "$COUNTER_FILE")"
+NEXT=$((CURRENT + 1))
+mempal_write_counter_atomic "$COUNTER_FILE" "$NEXT" || {
+ mempal_log "stop" "$MEMPAL_CONV_ID" \
+ "WARN: counter write failed for $COUNTER_FILE; passing through"
+ mempal_emit '{}'
+ exit 0
+}
+
+mempal_log "stop" "$MEMPAL_CONV_ID" \
+ "counter $CURRENT -> $NEXT (interval=$SAVE_INTERVAL)"
+
+# Trigger when we hit a multiple of SAVE_INTERVAL. Modulo arithmetic
+# keeps the counter monotonically growing (no reset) so the log file
+# is greppable for total turns across a conversation.
+if [ "$((NEXT % SAVE_INTERVAL))" -ne 0 ]; then
+ mempal_emit '{}'
+ exit 0
+fi
+
+mempal_log "stop" "$MEMPAL_CONV_ID" "TRIGGERING SAVE at counter=$NEXT"
+
+# ── Background mine (best effort) ─────────────────────────────────
+#
+# Two independent targets — both run if both are set:
+# 1. transcript_path → its parent directory, --mode convos
+# 2. MEMPAL_DIR (user-configured project) → --mode projects
+#
+# Both run with stdout/stderr appended to the cursor log and are
+# backgrounded so a slow mine cannot push the hook past its
+# Cursor-configured timeout. `command -v mempalace` gates so a user
+# without the CLI on PATH (e.g. a fresh GUI-launched session) does
+# not see a noisy error.
+if command -v mempalace >/dev/null 2>&1; then
+ if mempal_is_valid_transcript "$MEMPAL_TRANSCRIPT" \
+ && [ -f "$MEMPAL_TRANSCRIPT" ]; then
+ ( mempalace mine "$(dirname "$MEMPAL_TRANSCRIPT")" --mode convos \
+ >> "$MEMPAL_CURSOR_LOG" 2>&1 ) &
+ elif [ -n "$MEMPAL_TRANSCRIPT" ]; then
+ mempal_log "stop" "$MEMPAL_CONV_ID" \
+ "skipping invalid transcript path: $MEMPAL_TRANSCRIPT"
+ fi
+ if [ -n "$MEMPAL_DIR" ] && [ -d "$MEMPAL_DIR" ]; then
+ ( mempalace mine "$MEMPAL_DIR" --mode projects \
+ >> "$MEMPAL_CURSOR_LOG" 2>&1 ) &
+ fi
+else
+ mempal_log "stop" "$MEMPAL_CONV_ID" \
+ "mempalace CLI not on PATH; skipping background mine"
+fi
+
+_mempal_build_followup
diff --git a/hooks/cursor/mempal_wake_hook_cursor.sh b/hooks/cursor/mempal_wake_hook_cursor.sh
new file mode 100755
index 0000000..d484739
--- /dev/null
+++ b/hooks/cursor/mempal_wake_hook_cursor.sh
@@ -0,0 +1,82 @@
+#!/bin/bash
+# MEMPALACE CURSOR WAKE HOOK — Session-start memory recall
+#
+# Cursor "sessionStart" hook. This is a Cursor-only capability —
+# Claude Code's third-party-hooks compatibility layer does not have
+# an equivalent event with the same "inject context into the agent's
+# initial system message" semantics.
+#
+# Behaviour:
+# 1. Parse Cursor's sessionStart payload (conversation_id /
+# session_id, is_background_agent, composer_mode, plus the
+# common workspace_roots field).
+# 2. Infer the wing from basename(workspace_roots[0]).
+# 3. Return {"additional_context": "..."} instructing the agent to
+# scope its memory recall by calling mempalace_search +
+# mempalace_diary_read with wing=.
+#
+# sessionStart is documented as fire-and-forget — Cursor does not
+# enforce a blocking response and does not consume "continue" /
+# "user_message" — but "additional_context" is honoured and added to
+# the conversation's initial system context. Verified in
+# cursor.com/docs/hooks.md (fetched 2026-05-27).
+#
+# === INSTALL ===
+#
+# Add to ~/.cursor/hooks.json (or .cursor/hooks.json for project
+# scope) under "sessionStart":
+#
+# {
+# "version": 1,
+# "hooks": {
+# "sessionStart": [
+# { "command": "/absolute/path/to/mempal_wake_hook_cursor.sh" }
+# ]
+# }
+# }
+
+_mempal_self="${BASH_SOURCE[0]:-$0}"
+_mempal_dir="$(cd "$(dirname "$_mempal_self")" 2>/dev/null && pwd)"
+# shellcheck source=lib/common.sh
+. "$_mempal_dir/lib/common.sh"
+
+if mempal_is_disabled; then
+ mempal_emit '{}'
+ exit 0
+fi
+
+INPUT="$(cat)"
+mempal_parse_stdin "$INPUT"
+
+if [ "$MEMPAL_PARSE_OK" != "1" ]; then
+ mempal_dump_bad_input "$INPUT" "sessionStart"
+ mempal_emit '{}'
+ exit 0
+fi
+
+WING="$(mempal_infer_wing "$MEMPAL_WORKSPACE")"
+
+mempal_log "sessionStart" "$MEMPAL_CONV_ID" \
+ "workspace=$MEMPAL_WORKSPACE wing=$WING"
+
+# Emit the additional_context payload via Python -c (rather than a
+# heredoc) so the JSON encoding survives wings whose name contains
+# characters that would otherwise need shell escaping, and so the
+# inferred wing arrives as an argv positional. The MCP tool names
+# referenced here are verified against mempalace/mcp_server.py:
+# mempalace_search and mempalace_diary_read both exist and accept
+# the wing parameter.
+"$MEMPAL_PYTHON_BIN" -c '
+import json, sys
+wing = sys.argv[1] if len(sys.argv) > 1 else "cursor_session"
+ctx = (
+ "MemPalace wake-up. The Cursor workspace maps to wing=" + wing + ". "
+ "Before answering anything that touches past work in this "
+ "project, call mempalace_search (wing=" + wing + ", "
+ "query=) and mempalace_diary_read "
+ "(agent_name=cursor-ide, wing=" + wing + ", last_n=10). "
+ "Use what you find verbatim where it answers the question; "
+ "never summarise the user'"'"'s own words."
+)
+print(json.dumps({"additional_context": ctx}))
+' "$WING"
diff --git a/mcp.json b/mcp.json
new file mode 100644
index 0000000..ca633f5
--- /dev/null
+++ b/mcp.json
@@ -0,0 +1,7 @@
+{
+ "mcpServers": {
+ "mempalace": {
+ "command": "mempalace-mcp"
+ }
+ }
+}
diff --git a/skills/mempalace/SKILL.md b/skills/mempalace/SKILL.md
new file mode 100644
index 0000000..9239020
--- /dev/null
+++ b/skills/mempalace/SKILL.md
@@ -0,0 +1,40 @@
+---
+name: mempalace
+description: MemPalace — mine projects and conversations into a searchable memory palace. Use when the user asks about MemPalace, memory palace, mining memories, searching memories, palace setup, wings, rooms, or drawers; or when they want to recall past work that may already be filed in their palace.
+---
+
+# MemPalace
+
+A searchable memory palace for AI — mine projects and conversations, then search them semantically.
+
+## Prerequisites
+
+Ensure `mempalace` is installed:
+
+```bash
+mempalace --version
+```
+
+If not installed (uv recommended):
+
+```bash
+uv tool install mempalace # or: pip install mempalace
+```
+
+## Usage
+
+MemPalace provides dynamic, version-correct instructions via the CLI. To get instructions for any operation:
+
+```bash
+mempalace instructions
+```
+
+Where `` is one of: `help`, `init`, `mine`, `search`, `status`.
+
+Run the appropriate instructions command, then follow the returned instructions step by step.
+
+## Cursor-specific notes
+
+- The `mempalace-mcp` server is auto-registered by this plugin. Once installed, all 19 MemPalace MCP tools (`mempalace_search`, `mempalace_add_drawer`, `mempalace_diary_write`, `mempalace_check_duplicate`, `mempalace_diary_read`, etc.) are available to the agent without any further configuration.
+- For automatic background saving every N agent turns plus session-start memory recall, also install the Cursor hooks separately by running `hooks/cursor/install.sh --scope user` from a cloned MemPalace repo. See [`website/guide/cursor-hooks.md`](../../../website/guide/cursor-hooks.md) for the full walkthrough.
+- The recommended `agent_name` when calling `mempalace_diary_write` from a Cursor session is `cursor-ide` (matches the precedent of `claude-code` and `codex`).
diff --git a/tests/test_cursor_hooks_install.py b/tests/test_cursor_hooks_install.py
new file mode 100644
index 0000000..502799f
--- /dev/null
+++ b/tests/test_cursor_hooks_install.py
@@ -0,0 +1,398 @@
+"""Contract tests for ``hooks/cursor/install.sh``.
+
+The installer's job is to merge MemPalace hook entries into a Cursor
+``hooks.json`` file without:
+
+- modifying unrelated hook entries already in the file,
+- duplicating MemPalace entries when re-run,
+- writing to disk when ``--dry-run`` is passed,
+- leaving stale MemPalace entries behind on ``--uninstall``.
+
+These four contracts are what protects a user's existing Cursor
+configuration. Tests use ``--scope project --target `` so
+the test never touches the real user `~/.cursor/`.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+INSTALL_SH = REPO_ROOT / "hooks" / "cursor" / "install.sh"
+
+pytestmark = pytest.mark.skipif(os.name == "nt", reason="install.sh is POSIX-only")
+
+
+# ── helpers ─────────────────────────────────────────────────────────
+
+
+def _run_install(
+ *args: str,
+ target: Path,
+ home: Path | None = None,
+ expected_rc: int = 0,
+) -> tuple[str, str]:
+ """Invoke install.sh with --scope project --target .
+
+ Forces ``MEMPAL_PYTHON=sys.executable`` for the same reason the
+ shell-hook tests do — ensures the JSON merge runs even if PATH on
+ a GUI-launched CI runner is missing python3. Forces a clean HOME
+ so the default --install-dir (under ~/.mempalace/hooks/cursor/)
+ lands in a sandboxed tmp tree rather than the developer's real
+ home.
+ """
+ env = {
+ "HOME": str(home) if home else "/tmp/mempal-install-test-home",
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+ "MEMPAL_PYTHON": sys.executable,
+ }
+ cmd = [
+ "bash",
+ str(INSTALL_SH),
+ "--scope",
+ "project",
+ "--target",
+ str(target),
+ *args,
+ ]
+ p = subprocess.run(
+ cmd,
+ capture_output=True,
+ text=True,
+ env=env,
+ timeout=30,
+ )
+ assert p.returncode == expected_rc, (
+ f"install.sh exited {p.returncode} (expected {expected_rc}); "
+ f"stderr={p.stderr!r}; stdout={p.stdout!r}; argv={cmd}"
+ )
+ return p.stdout, p.stderr
+
+
+def _hooks_file(target: Path) -> Path:
+ return target / ".cursor" / "hooks.json"
+
+
+def _seed(target: Path, payload: dict) -> Path:
+ cursor_dir = target / ".cursor"
+ cursor_dir.mkdir(parents=True, exist_ok=True)
+ hf = cursor_dir / "hooks.json"
+ hf.write_text(json.dumps(payload, indent=2))
+ return hf
+
+
+# ── --help and bash syntax ──────────────────────────────────────────
+
+
+def test_bash_syntax_clean():
+ p = subprocess.run(
+ ["bash", "-n", str(INSTALL_SH)],
+ capture_output=True,
+ text=True,
+ )
+ assert p.returncode == 0, f"install.sh syntax error: {p.stderr}"
+
+
+def test_help_describes_all_flags():
+ p = subprocess.run(
+ ["bash", str(INSTALL_SH), "--help"],
+ capture_output=True,
+ text=True,
+ env={
+ "HOME": "/tmp/mempal-help",
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+ },
+ timeout=10,
+ )
+ assert p.returncode == 0
+ for flag in ("--scope", "--target", "--variant", "--dry-run", "--uninstall"):
+ assert flag in p.stdout, f"--help must describe {flag}"
+
+
+def test_unknown_flag_exits_nonzero():
+ p = subprocess.run(
+ ["bash", str(INSTALL_SH), "--bogus-flag"],
+ capture_output=True,
+ text=True,
+ env={
+ "HOME": "/tmp/mempal-bogus",
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+ },
+ timeout=10,
+ )
+ assert p.returncode != 0
+
+
+# ── --dry-run contract ─────────────────────────────────────────────
+
+
+class TestDryRun:
+ def test_dry_run_does_not_write_target_file(self, tmp_path):
+ stdout, _ = _run_install("--dry-run", target=tmp_path, home=tmp_path)
+ assert not _hooks_file(tmp_path).exists(), "--dry-run must not write the target file"
+ # But it must still print valid JSON to stdout for the user to
+ # review.
+ parsed = json.loads(stdout)
+ assert parsed["version"] == 1
+ assert "hooks" in parsed
+
+ def test_dry_run_does_not_copy_scripts(self, tmp_path):
+ install_dir = tmp_path / "install-dest"
+ _run_install(
+ "--dry-run",
+ "--install-dir",
+ str(install_dir),
+ target=tmp_path,
+ home=tmp_path,
+ )
+ assert not install_dir.exists(), (
+ "--dry-run must not copy any hook scripts to the install dir"
+ )
+
+ def test_dry_run_emits_full_variant_by_default(self, tmp_path):
+ stdout, _ = _run_install("--dry-run", target=tmp_path, home=tmp_path)
+ cfg = json.loads(stdout)
+ assert set(cfg["hooks"].keys()) >= {"sessionStart", "stop", "preCompact"}
+
+ def test_dry_run_minimal_variant_only_wires_stop(self, tmp_path):
+ stdout, _ = _run_install(
+ "--dry-run",
+ "--variant",
+ "minimal",
+ target=tmp_path,
+ home=tmp_path,
+ )
+ cfg = json.loads(stdout)
+ # `stop` is the only event we touch. Anything else (including
+ # sessionStart / preCompact) should not be present unless the
+ # seed file already had it.
+ assert "stop" in cfg["hooks"]
+ assert "sessionStart" not in cfg["hooks"]
+ assert "preCompact" not in cfg["hooks"]
+
+
+# ── merge-preservation contract ────────────────────────────────────
+
+
+class TestMergePreservation:
+ def test_preserves_unrelated_hook_events(self, tmp_path):
+ _seed(
+ tmp_path,
+ {
+ "version": 1,
+ "hooks": {
+ "afterFileEdit": [
+ {"command": "/usr/local/bin/my-formatter.sh"},
+ ],
+ "beforeShellExecution": [
+ {"command": "/usr/local/bin/audit-shell.sh"},
+ ],
+ },
+ },
+ )
+ _run_install(target=tmp_path, home=tmp_path)
+ result = json.loads(_hooks_file(tmp_path).read_text())
+ assert result["hooks"]["afterFileEdit"] == [
+ {"command": "/usr/local/bin/my-formatter.sh"},
+ ], "unrelated afterFileEdit entry must survive merge"
+ assert result["hooks"]["beforeShellExecution"] == [
+ {"command": "/usr/local/bin/audit-shell.sh"},
+ ], "unrelated beforeShellExecution entry must survive merge"
+
+ def test_preserves_other_entries_on_same_event(self, tmp_path):
+ # User has their own `stop` hook. We must add MemPalace's
+ # entry alongside, not replace.
+ _seed(
+ tmp_path,
+ {
+ "version": 1,
+ "hooks": {
+ "stop": [
+ {"command": "/usr/local/bin/my-stop-hook.sh"},
+ ],
+ },
+ },
+ )
+ _run_install(target=tmp_path, home=tmp_path)
+ result = json.loads(_hooks_file(tmp_path).read_text())
+ stop_entries = result["hooks"]["stop"]
+ assert len(stop_entries) == 2, (
+ f"expected user entry + MemPalace entry; got {stop_entries!r}"
+ )
+ commands = {e["command"] for e in stop_entries}
+ assert "/usr/local/bin/my-stop-hook.sh" in commands
+ assert any("mempal_save_hook_cursor.sh" in c for c in commands)
+
+ def test_creates_target_dir_when_missing(self, tmp_path):
+ # No .cursor/ exists yet; install must create both the
+ # directory and the file.
+ assert not (tmp_path / ".cursor").exists()
+ _run_install(target=tmp_path, home=tmp_path)
+ assert _hooks_file(tmp_path).exists()
+ cfg = json.loads(_hooks_file(tmp_path).read_text())
+ assert "stop" in cfg["hooks"]
+
+ def test_refuses_to_overwrite_malformed_existing_json(self, tmp_path):
+ cursor_dir = tmp_path / ".cursor"
+ cursor_dir.mkdir(parents=True)
+ (cursor_dir / "hooks.json").write_text("{ this is not json")
+ # The merge step should fail with a non-zero exit; the file
+ # must remain untouched so the user can fix it.
+ _, stderr = _run_install(target=tmp_path, home=tmp_path, expected_rc=2)
+ assert "not valid JSON" in stderr or "Refusing to overwrite" in stderr
+ # File should be unchanged.
+ assert (cursor_dir / "hooks.json").read_text() == "{ this is not json"
+
+
+# ── idempotency contract ───────────────────────────────────────────
+
+
+class TestIdempotency:
+ def test_running_install_twice_does_not_duplicate(self, tmp_path):
+ _run_install(target=tmp_path, home=tmp_path)
+ first = json.loads(_hooks_file(tmp_path).read_text())
+ _run_install(target=tmp_path, home=tmp_path)
+ second = json.loads(_hooks_file(tmp_path).read_text())
+ assert first == second, (
+ "re-running install.sh must produce an identical config "
+ f"(idempotency); first={first!r} second={second!r}"
+ )
+ # And specifically no duplicate MemPalace entry on `stop`.
+ stop = second["hooks"]["stop"]
+ mempal_entries = [e for e in stop if "mempal_save_hook_cursor.sh" in e["command"]]
+ assert len(mempal_entries) == 1, (
+ f"re-running install must not duplicate the stop entry; got {stop!r}"
+ )
+
+
+# ── --uninstall contract ───────────────────────────────────────────
+
+
+class TestUninstall:
+ def test_uninstall_removes_only_mempalace_entries(self, tmp_path):
+ # Seed: user has their own stop hook AND an unrelated event.
+ _seed(
+ tmp_path,
+ {
+ "version": 1,
+ "hooks": {
+ "stop": [
+ {"command": "/usr/local/bin/my-stop-hook.sh"},
+ ],
+ "afterFileEdit": [
+ {"command": "/usr/local/bin/my-formatter.sh"},
+ ],
+ },
+ },
+ )
+ _run_install(target=tmp_path, home=tmp_path)
+ # MemPalace is now wired alongside the user's entries.
+ _run_install("--uninstall", target=tmp_path, home=tmp_path)
+ cfg = json.loads(_hooks_file(tmp_path).read_text())
+ # User's stop hook must remain; MemPalace's must be gone.
+ commands = {e["command"] for e in cfg["hooks"].get("stop", [])}
+ assert commands == {"/usr/local/bin/my-stop-hook.sh"}
+ # Unrelated event untouched.
+ assert cfg["hooks"]["afterFileEdit"] == [
+ {"command": "/usr/local/bin/my-formatter.sh"},
+ ]
+ # sessionStart / preCompact (which were ONLY ever wired by us)
+ # must be removed entirely since they would otherwise dangle
+ # as empty lists.
+ assert "sessionStart" not in cfg["hooks"]
+ assert "preCompact" not in cfg["hooks"]
+
+ def test_uninstall_removes_empty_file_when_no_user_hooks_remain(self, tmp_path):
+ # No pre-existing hooks; install then uninstall should leave
+ # an effectively-empty config -> file removed entirely.
+ _run_install(target=tmp_path, home=tmp_path)
+ assert _hooks_file(tmp_path).exists()
+ _run_install("--uninstall", target=tmp_path, home=tmp_path)
+ assert not _hooks_file(tmp_path).exists(), (
+ "fully-empty hooks.json after uninstall must be removed, "
+ 'not left as `{"version": 1, "hooks": {}}`'
+ )
+
+ def test_uninstall_is_safe_when_file_missing(self, tmp_path):
+ # User never installed; running uninstall must not crash.
+ assert not _hooks_file(tmp_path).exists()
+ _run_install("--uninstall", target=tmp_path, home=tmp_path)
+ # File should still not exist (and definitely should not have
+ # been created with an empty config).
+ assert not _hooks_file(tmp_path).exists()
+
+ def test_uninstall_dry_run_does_not_modify_file(self, tmp_path):
+ _seed(
+ tmp_path,
+ {
+ "version": 1,
+ "hooks": {
+ "stop": [
+ {"command": "/usr/local/bin/my-stop-hook.sh"},
+ {
+ "command": (
+ "/Users/anon/.mempalace/hooks/cursor/mempal_save_hook_cursor.sh"
+ ),
+ "loop_limit": 1,
+ },
+ ],
+ },
+ },
+ )
+ before = _hooks_file(tmp_path).read_text()
+ _run_install("--uninstall", "--dry-run", target=tmp_path, home=tmp_path)
+ after = _hooks_file(tmp_path).read_text()
+ assert before == after, "--uninstall --dry-run must not mutate the target file"
+
+
+# ── scope handling ──────────────────────────────────────────────────
+
+
+def test_project_scope_writes_to_project_dir(tmp_path):
+ # Sanity check that --scope project + --target lands the file at
+ # /.cursor/hooks.json and nowhere else.
+ home = tmp_path / "fake-home"
+ home.mkdir()
+ project = tmp_path / "fake-project"
+ project.mkdir()
+ _run_install(target=project, home=home)
+ assert (project / ".cursor" / "hooks.json").exists()
+ assert not (home / ".cursor" / "hooks.json").exists(), (
+ "--scope project must not write into HOME"
+ )
+
+
+def test_invalid_scope_rejected(tmp_path):
+ p = subprocess.run(
+ ["bash", str(INSTALL_SH), "--scope", "bogus"],
+ capture_output=True,
+ text=True,
+ env={
+ "HOME": str(tmp_path),
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+ },
+ timeout=10,
+ )
+ assert p.returncode != 0
+ assert "scope" in p.stderr.lower()
+
+
+def test_invalid_variant_rejected(tmp_path):
+ p = subprocess.run(
+ ["bash", str(INSTALL_SH), "--variant", "bogus"],
+ capture_output=True,
+ text=True,
+ env={
+ "HOME": str(tmp_path),
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+ },
+ timeout=10,
+ )
+ assert p.returncode != 0
+ assert "variant" in p.stderr.lower()
diff --git a/tests/test_cursor_hooks_shell.py b/tests/test_cursor_hooks_shell.py
new file mode 100644
index 0000000..b46f13e
--- /dev/null
+++ b/tests/test_cursor_hooks_shell.py
@@ -0,0 +1,576 @@
+"""Behavioral coverage for the Cursor hook shell scripts.
+
+Mirrors ``tests/test_hooks_shell.py`` + ``tests/test_hooks_bash_compat.py``
+in shape so a future contributor recognises the pattern. The three
+hooks live at ``hooks/cursor/`` and source ``hooks/cursor/lib/common.sh``.
+
+Covered contracts:
+
+- bash 3.2 compatibility (no ``mapfile`` / ``readarray``; ``sed -n 'Np'``
+ used for line extraction; ``bash -n`` clean).
+- Per-conversation counter increments atomically across ``stop`` calls
+ and emits a ``followup_message`` only on the configured interval.
+- ``MEMPAL_DISABLE_HOOK=1`` and ``MEMPALACE_HOOKS_AUTO_SAVE=false`` both
+ short-circuit every hook to ``{}``.
+- Malformed stdin dumps the payload to a bounded 0600 file and logs a
+ warning; the hook still exits 0 with ``{}`` so Cursor proceeds.
+- ``loop_count > 0`` short-circuits the save hook (loop-prevention).
+- A pending-save marker dropped by ``preCompact`` forces a save
+ followup on the very next ``stop`` regardless of the counter.
+- ``infer_wing_from_cwd`` handles ``/``, trailing slashes, spaces, and
+ empty input.
+- The wake hook emits ``additional_context`` referencing the inferred
+ wing.
+- The precompact hook drops a pending-save marker and emits the
+ documented ``user_message`` shape.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import stat
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+HOOKS_DIR = REPO_ROOT / "hooks" / "cursor"
+SAVE_HOOK = HOOKS_DIR / "mempal_save_hook_cursor.sh"
+PRECOMPACT_HOOK = HOOKS_DIR / "mempal_precompact_hook_cursor.sh"
+WAKE_HOOK = HOOKS_DIR / "mempal_wake_hook_cursor.sh"
+COMMON_LIB = HOOKS_DIR / "lib" / "common.sh"
+
+# All three .sh scripts, parametrised together for the source-level and
+# universal-behaviour tests. ids= keeps pytest output readable.
+ALL_HOOKS = pytest.mark.parametrize(
+ "hook",
+ [SAVE_HOOK, PRECOMPACT_HOOK, WAKE_HOOK],
+ ids=["save_hook", "precompact_hook", "wake_hook"],
+)
+
+pytestmark = pytest.mark.skipif(os.name == "nt", reason="bash hook scripts are POSIX-only")
+
+
+# ── helpers ──────────────────────────────────────────────────────────
+
+
+def _run_hook(
+ hook: Path,
+ stdin: str,
+ home: Path,
+ *,
+ extra_env: dict | None = None,
+ path_prefix: list[Path] | None = None,
+ expected_rc: int = 0,
+) -> tuple[str, str]:
+ """Invoke a hook with a controlled environment and assert exit code.
+
+ Returns ``(stdout, stderr)``. Forces ``MEMPAL_PYTHON=sys.executable``
+ so the hook always finds a Python that can ``import json`` — without
+ this, GUI-launched CI on macOS could hit a missing python3 on the
+ inherited PATH and produce spurious failures unrelated to the hook
+ logic. Forces a clean ``HOME`` so the state directory is sandboxed
+ under the test's ``tmp_path``.
+ """
+ env = {
+ "HOME": str(home),
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+ "MEMPAL_PYTHON": sys.executable,
+ }
+ if path_prefix:
+ env["PATH"] = os.pathsep.join(str(p) for p in path_prefix) + os.pathsep + env["PATH"]
+ if extra_env:
+ env.update(extra_env)
+ p = subprocess.run(
+ ["bash", str(hook)],
+ input=stdin,
+ capture_output=True,
+ text=True,
+ env=env,
+ timeout=30,
+ # Force a permissive umask so the hook's own ``umask 077`` inside
+ # parsing subshells is provably the sole reason diagnostic files
+ # end up mode 0600. Without this, an ambient restrictive umask
+ # on the CI runner would mask a regression that drops the in-hook
+ # ``umask`` line. Mirrors tests/test_hooks_bash_compat.py.
+ preexec_fn=lambda: os.umask(0o022),
+ )
+ assert p.returncode == expected_rc, (
+ f"{hook.name} exited {p.returncode} (expected {expected_rc}); "
+ f"stderr={p.stderr!r}; stdout={p.stdout!r}"
+ )
+ return p.stdout, p.stderr
+
+
+def _stop_payload(
+ *,
+ conv: str = "conv-1",
+ loop_count: int = 0,
+ transcript: str = "",
+) -> str:
+ return json.dumps(
+ {
+ "conversation_id": conv,
+ "loop_count": loop_count,
+ "status": "completed",
+ "model": "claude-sonnet-4-20250514",
+ "hook_event_name": "stop",
+ "transcript_path": transcript,
+ "workspace_roots": ["/Users/test/sampleProj"],
+ }
+ )
+
+
+def _precompact_payload(*, conv: str = "conv-1", transcript: str = "") -> str:
+ return json.dumps(
+ {
+ "conversation_id": conv,
+ "hook_event_name": "preCompact",
+ "trigger": "auto",
+ "transcript_path": transcript,
+ "workspace_roots": ["/Users/test/sampleProj"],
+ }
+ )
+
+
+def _session_start_payload(*, conv: str = "conv-1") -> str:
+ return json.dumps(
+ {
+ "conversation_id": conv,
+ "session_id": conv,
+ "hook_event_name": "sessionStart",
+ "is_background_agent": False,
+ "composer_mode": "agent",
+ "workspace_roots": ["/Users/test/sampleProj"],
+ }
+ )
+
+
+def _state_dir(home: Path) -> Path:
+ return home / ".mempalace" / "hook_state"
+
+
+def _log_text(home: Path) -> str:
+ log = _state_dir(home) / "cursor_hook.log"
+ return log.read_text() if log.exists() else ""
+
+
+# ── source-level bash 3.2 compat (matches tests/test_hooks_bash_compat.py) ──
+
+
+class TestBash32Compat:
+ @ALL_HOOKS
+ def test_bash_syntax_clean(self, hook):
+ p = subprocess.run(
+ ["bash", "-n", str(hook)],
+ capture_output=True,
+ text=True,
+ )
+ assert p.returncode == 0, f"{hook.name} syntax error: {p.stderr}"
+
+ def test_common_lib_syntax_clean(self):
+ p = subprocess.run(
+ ["bash", "-n", str(COMMON_LIB)],
+ capture_output=True,
+ text=True,
+ )
+ assert p.returncode == 0, f"common.sh syntax error: {p.stderr}"
+
+ @ALL_HOOKS
+ def test_no_bash4_array_builtins(self, hook):
+ src = "\n".join(
+ line for line in hook.read_text().splitlines() if not line.lstrip().startswith("#")
+ )
+ assert "mapfile" not in src, (
+ f"{hook.name} uses mapfile; unavailable on macOS /bin/bash 3.2 (#1440)"
+ )
+ assert "readarray" not in src, (
+ f"{hook.name} uses readarray; unavailable on macOS /bin/bash 3.2 (#1440)"
+ )
+
+ def test_common_lib_no_bash4_array_builtins(self):
+ src = "\n".join(
+ line
+ for line in COMMON_LIB.read_text().splitlines()
+ if not line.lstrip().startswith("#")
+ )
+ assert "mapfile" not in src and "readarray" not in src, (
+ "common.sh uses bash-4-only array builtins; would break macOS bash 3.2"
+ )
+
+ def test_common_lib_uses_sed_n_for_extraction(self):
+ # Defense: if a future edit swaps the sed-based parser for
+ # mapfile (the bash-4 form), this catches it at source level
+ # before any behavioural test runs. ``parse_cursor_stdin`` reads
+ # seven values (sentinel + six fields) so we expect at least
+ # seven ``sed -n 'Np'`` calls.
+ src = "\n".join(
+ line
+ for line in COMMON_LIB.read_text().splitlines()
+ if not line.lstrip().startswith("#")
+ )
+ assert src.count("sed -n '") >= 7, (
+ "common.sh must use sed -n 'Np' for POSIX-portable line extraction"
+ )
+
+
+# ── kill switches ───────────────────────────────────────────────────
+
+
+class TestKillSwitches:
+ @ALL_HOOKS
+ @pytest.mark.parametrize("value", ["1", "true", "yes", "on"])
+ def test_disable_hook_env_short_circuits(self, hook, value, tmp_path):
+ out, _ = _run_hook(
+ hook,
+ _stop_payload(),
+ tmp_path,
+ extra_env={"MEMPAL_DISABLE_HOOK": value},
+ )
+ assert json.loads(out) == {}, f"MEMPAL_DISABLE_HOOK={value} must short-circuit; got {out!r}"
+ # No state files should be created when the kill switch fires.
+ state = _state_dir(tmp_path)
+ assert not (state / "cursor_hook.log").exists() or _log_text(tmp_path) == ""
+
+ @ALL_HOOKS
+ @pytest.mark.parametrize("value", ["false", "0", "no", "off"])
+ def test_auto_save_env_short_circuits(self, hook, value, tmp_path):
+ out, _ = _run_hook(
+ hook,
+ _stop_payload(),
+ tmp_path,
+ extra_env={"MEMPALACE_HOOKS_AUTO_SAVE": value},
+ )
+ assert json.loads(out) == {}, (
+ f"MEMPALACE_HOOKS_AUTO_SAVE={value} must short-circuit; got {out!r}"
+ )
+
+ @ALL_HOOKS
+ def test_config_file_auto_save_false_short_circuits(self, hook, tmp_path):
+ cfg_dir = tmp_path / ".mempalace"
+ cfg_dir.mkdir(parents=True)
+ (cfg_dir / "config.json").write_text(json.dumps({"hooks": {"auto_save": False}}))
+ out, _ = _run_hook(hook, _stop_payload(), tmp_path)
+ assert json.loads(out) == {}, (
+ f"config.json hooks.auto_save=false must short-circuit; got {out!r}"
+ )
+
+
+# ── malformed stdin ─────────────────────────────────────────────────
+
+
+class TestMalformedStdin:
+ @ALL_HOOKS
+ def test_malformed_input_does_not_crash(self, hook, tmp_path):
+ out, _ = _run_hook(hook, "not-json garbage", tmp_path)
+ # Must still produce parseable JSON so Cursor proceeds.
+ assert json.loads(out) == {}, f"hook must emit {{}} on malformed input; got {out!r}"
+
+ @ALL_HOOKS
+ def test_malformed_input_logs_warning_and_dumps_payload(self, hook, tmp_path):
+ _run_hook(hook, "not-json garbage", tmp_path)
+ state = _state_dir(tmp_path)
+ log = (state / "cursor_hook.log").read_text()
+ assert "WARN: input parse failed" in log, (
+ f"expected parse-failure warning in log; got: {log!r}"
+ )
+ dump = state / "cursor_last_input.log"
+ assert dump.exists()
+ assert "not-json garbage" in dump.read_text()
+
+ @ALL_HOOKS
+ def test_dump_is_mode_0600(self, hook, tmp_path):
+ _run_hook(hook, "not-json garbage", tmp_path)
+ dump = _state_dir(tmp_path) / "cursor_last_input.log"
+ mode = stat.S_IMODE(dump.stat().st_mode)
+ assert mode == 0o600, f"cursor_last_input.log mode should be 0600, got {oct(mode)}"
+
+ @ALL_HOOKS
+ def test_dump_cap_at_4096_bytes(self, hook, tmp_path):
+ _run_hook(hook, "x" * 4097, tmp_path)
+ dump = _state_dir(tmp_path) / "cursor_last_input.log"
+ assert dump.stat().st_size == 4096, (
+ f"cap must be exactly 4096 bytes; got {dump.stat().st_size}"
+ )
+
+ @ALL_HOOKS
+ def test_empty_stdin_does_not_dump(self, hook, tmp_path):
+ out, _ = _run_hook(hook, "", tmp_path)
+ assert json.loads(out) == {}
+ dump = _state_dir(tmp_path) / "cursor_last_input.log"
+ assert not dump.exists(), "empty stdin must not produce a dump file"
+
+ @ALL_HOOKS
+ def test_successful_parse_leaves_no_python_err_log(self, hook, tmp_path):
+ if hook == SAVE_HOOK:
+ payload = _stop_payload()
+ elif hook == PRECOMPACT_HOOK:
+ payload = _precompact_payload()
+ else:
+ payload = _session_start_payload()
+ _run_hook(hook, payload, tmp_path)
+ err_log = _state_dir(tmp_path) / "cursor_last_python_err.log"
+ assert not err_log.exists(), "successful parse must clean up cursor_last_python_err.log"
+
+
+# ── save hook: counter + threshold ──────────────────────────────────
+
+
+class TestSaveHookCounter:
+ def test_counter_increments_across_invocations(self, tmp_path):
+ for _ in range(3):
+ out, _ = _run_hook(SAVE_HOOK, _stop_payload(conv="conv-A"), tmp_path)
+ assert json.loads(out) == {}, "below threshold must be a no-op"
+ counter_file = _state_dir(tmp_path) / "cursor_conv-A.count"
+ assert counter_file.read_text() == "3", (
+ f"counter should be 3 after 3 invocations; got {counter_file.read_text()!r}"
+ )
+
+ def test_counter_per_conversation_isolated(self, tmp_path):
+ _run_hook(SAVE_HOOK, _stop_payload(conv="conv-A"), tmp_path)
+ _run_hook(SAVE_HOOK, _stop_payload(conv="conv-A"), tmp_path)
+ _run_hook(SAVE_HOOK, _stop_payload(conv="conv-B"), tmp_path)
+ assert (_state_dir(tmp_path) / "cursor_conv-A.count").read_text() == "2"
+ assert (_state_dir(tmp_path) / "cursor_conv-B.count").read_text() == "1"
+
+ def test_threshold_emits_followup_message(self, tmp_path):
+ # Lower the interval to keep the test fast.
+ env = {"MEMPAL_SAVE_INTERVAL": "3"}
+ for _ in range(2):
+ out, _ = _run_hook(SAVE_HOOK, _stop_payload(), tmp_path, extra_env=env)
+ assert json.loads(out) == {}
+ out, _ = _run_hook(SAVE_HOOK, _stop_payload(), tmp_path, extra_env=env)
+ response = json.loads(out)
+ assert "followup_message" in response, (
+ f"third invocation must emit a followup_message; got {response!r}"
+ )
+ msg = response["followup_message"]
+ # Followup must reference the real MCP tool names (regression
+ # guard against future typos that would silently fail).
+ assert "mempalace_add_drawer" in msg
+ assert "mempalace_check_duplicate" in msg
+ assert "mempalace_diary_write" in msg
+ assert "cursor-ide" in msg, "diary entries must be tagged agent_name=cursor-ide"
+
+ def test_threshold_followup_references_inferred_wing(self, tmp_path):
+ env = {"MEMPAL_SAVE_INTERVAL": "1"}
+ # workspace_roots[0] = /Users/test/sampleProj -> wing=sampleproj
+ out, _ = _run_hook(SAVE_HOOK, _stop_payload(), tmp_path, extra_env=env)
+ msg = json.loads(out)["followup_message"]
+ assert "sampleproj" in msg, f"followup should reference inferred wing; got {msg!r}"
+
+
+# ── save hook: loop-prevention ──────────────────────────────────────
+
+
+class TestSaveHookLoopPrevention:
+ def test_loop_count_gt_zero_short_circuits(self, tmp_path):
+ out, _ = _run_hook(
+ SAVE_HOOK,
+ _stop_payload(loop_count=1),
+ tmp_path,
+ extra_env={"MEMPAL_SAVE_INTERVAL": "1"},
+ )
+ assert json.loads(out) == {}, (
+ "loop_count > 0 must short-circuit even at the trigger interval"
+ )
+ # No counter file should be written in the short-circuit path.
+ assert not (_state_dir(tmp_path) / "cursor_conv-1.count").exists()
+
+ def test_loop_count_zero_does_not_short_circuit(self, tmp_path):
+ out, _ = _run_hook(
+ SAVE_HOOK,
+ _stop_payload(loop_count=0),
+ tmp_path,
+ extra_env={"MEMPAL_SAVE_INTERVAL": "1"},
+ )
+ assert "followup_message" in json.loads(out)
+
+
+# ── save hook: pending-save marker from preCompact ──────────────────
+
+
+class TestPendingSaveMarker:
+ def test_pending_marker_forces_followup_regardless_of_counter(self, tmp_path):
+ state = _state_dir(tmp_path)
+ state.mkdir(parents=True, exist_ok=True)
+ # Drop the marker as if precompact had run.
+ (state / "cursor_conv-1.pending").write_text("")
+ out, _ = _run_hook(
+ SAVE_HOOK,
+ _stop_payload(),
+ tmp_path,
+ # SAVE_INTERVAL=1000 ensures the normal counter path would
+ # not trigger; the marker is the only reason a followup
+ # gets emitted.
+ extra_env={"MEMPAL_SAVE_INTERVAL": "1000"},
+ )
+ response = json.loads(out)
+ assert "followup_message" in response, (
+ "pending marker must force a followup even far below threshold"
+ )
+ # Marker must be consumed on read.
+ assert not (state / "cursor_conv-1.pending").exists(), (
+ "pending marker must be deleted after consumption"
+ )
+
+ def test_pending_marker_is_per_conversation(self, tmp_path):
+ state = _state_dir(tmp_path)
+ state.mkdir(parents=True, exist_ok=True)
+ (state / "cursor_conv-OTHER.pending").write_text("")
+ out, _ = _run_hook(
+ SAVE_HOOK,
+ _stop_payload(conv="conv-1"),
+ tmp_path,
+ extra_env={"MEMPAL_SAVE_INTERVAL": "1000"},
+ )
+ # conv-1 has no marker -> counter path -> no trigger -> {}.
+ assert json.loads(out) == {}
+ # conv-OTHER marker must NOT be consumed by conv-1's invocation.
+ assert (state / "cursor_conv-OTHER.pending").exists()
+
+
+# ── preCompact hook ─────────────────────────────────────────────────
+
+
+class TestPreCompactHook:
+ def test_emits_user_message(self, tmp_path):
+ out, _ = _run_hook(PRECOMPACT_HOOK, _precompact_payload(), tmp_path)
+ response = json.loads(out)
+ # Cursor's preCompact only accepts user_message; never
+ # followup_message or decision.
+ assert "user_message" in response, f"expected user_message; got {response!r}"
+ assert "followup_message" not in response
+ assert "decision" not in response
+
+ def test_drops_pending_marker(self, tmp_path):
+ _run_hook(PRECOMPACT_HOOK, _precompact_payload(conv="conv-X"), tmp_path)
+ marker = _state_dir(tmp_path) / "cursor_conv-X.pending"
+ assert marker.exists(), "preCompact must drop a pending-save marker"
+
+ def test_logs_trigger(self, tmp_path):
+ _run_hook(PRECOMPACT_HOOK, _precompact_payload(conv="conv-Y"), tmp_path)
+ log = _log_text(tmp_path)
+ assert "event=preCompact" in log
+ assert "conv=conv-Y" in log
+ assert "trigger=auto" in log
+
+
+# ── wake (sessionStart) hook ───────────────────────────────────────
+
+
+class TestWakeHook:
+ def test_emits_additional_context(self, tmp_path):
+ out, _ = _run_hook(WAKE_HOOK, _session_start_payload(), tmp_path)
+ response = json.loads(out)
+ assert "additional_context" in response, (
+ f"sessionStart must emit additional_context; got {response!r}"
+ )
+ ctx = response["additional_context"]
+ # Must reference the inferred wing AND the real MCP tools.
+ assert "sampleproj" in ctx, f"context should reference inferred wing; got {ctx!r}"
+ assert "mempalace_search" in ctx
+ assert "mempalace_diary_read" in ctx
+ assert "cursor-ide" in ctx
+
+ def test_falls_back_to_env_when_workspace_roots_missing(self, tmp_path):
+ # Cursor always provides workspace_roots, but the env-var
+ # fallback path needs coverage so a future Cursor schema
+ # change cannot silently break the wake hook.
+ payload = json.dumps(
+ {
+ "conversation_id": "conv-Z",
+ "session_id": "conv-Z",
+ "hook_event_name": "sessionStart",
+ "is_background_agent": False,
+ "composer_mode": "agent",
+ }
+ )
+ out, _ = _run_hook(
+ WAKE_HOOK,
+ payload,
+ tmp_path,
+ extra_env={"CURSOR_PROJECT_DIR": "/Users/test/envFallback"},
+ )
+ ctx = json.loads(out)["additional_context"]
+ assert "envfallback" in ctx, (
+ f"env-var fallback workspace should drive wing inference; got {ctx!r}"
+ )
+
+
+# ── infer_wing_from_cwd via direct function call ────────────────────
+
+
+def _call_infer_wing(arg: str) -> str:
+ """Source common.sh in a bash subshell and invoke mempal_infer_wing.
+
+ Returns the function's stdout. Uses bash -c so we never have to
+ pollute the test's own shell environment with the common.sh state
+ (which mkdir's directories and resolves Python paths).
+ """
+ script = f'. "{COMMON_LIB}" >/dev/null 2>&1; mempal_infer_wing "$1"'
+ # The argument is passed as a positional so it survives any shell
+ # quirks around spaces/empty values exactly as the production hook
+ # would see them.
+ p = subprocess.run(
+ ["bash", "-c", script, "_test", arg],
+ capture_output=True,
+ text=True,
+ env={
+ "HOME": "/tmp",
+ "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+ "MEMPAL_PYTHON": sys.executable,
+ },
+ timeout=10,
+ )
+ assert p.returncode == 0, f"infer_wing call failed: {p.stderr!r}"
+ return p.stdout
+
+
+class TestInferWing:
+ def test_basename_of_normal_path(self):
+ assert _call_infer_wing("/Users/me/myproject") == "myproject"
+
+ def test_strips_trailing_slash(self):
+ assert _call_infer_wing("/Users/me/myproject/") == "myproject"
+
+ def test_root_path_falls_back(self):
+ assert _call_infer_wing("/") == "root"
+
+ def test_empty_input_falls_back(self):
+ assert _call_infer_wing("") == "cursor_session"
+
+ def test_spaces_collapsed_to_underscore(self):
+ assert _call_infer_wing("/Users/me/my project") == "my_project"
+
+ def test_lowercases_uppercase_basename(self):
+ # Cursor on macOS often hands us /Users//Projects/MyApp.
+ # The wing scoping in MemPalace's MCP tools is case-sensitive,
+ # so the wake hook and save hook must produce identical wings
+ # for the same workspace — lowercasing is the simplest
+ # contract.
+ assert _call_infer_wing("/Users/me/MyApp") == "myapp"
+
+ def test_windows_style_path(self):
+ # Cursor on Windows passes C:\path\to\Project as workspace_root.
+ # The hook scripts are POSIX-only (we skip them on Windows) but
+ # WSL users may still hit a backslash-bearing path via the
+ # CURSOR_PROJECT_DIR env var when Cursor is launched from
+ # PowerShell.
+ assert _call_infer_wing(r"C:\Users\me\MyProj") == "myproj"
+
+
+# ── logging discipline ─────────────────────────────────────────────
+
+
+class TestLogging:
+ def test_log_uses_iso8601_utc_timestamps(self, tmp_path):
+ _run_hook(SAVE_HOOK, _stop_payload(), tmp_path)
+ log = _log_text(tmp_path)
+ # ISO 8601 with 'Z' suffix means UTC, locale-independent.
+ # Regression guard against switching back to %H:%M:%S which
+ # loses both the date and the timezone.
+ assert "T" in log and "Z]" in log, f"log timestamps must be ISO 8601 UTC; got: {log!r}"
diff --git a/tests/test_cursor_plugin_manifest.py b/tests/test_cursor_plugin_manifest.py
new file mode 100644
index 0000000..8393185
--- /dev/null
+++ b/tests/test_cursor_plugin_manifest.py
@@ -0,0 +1,437 @@
+"""Contract tests for ``.cursor-plugin/``.
+
+These tests protect the four things a Cursor user actually relies on
+once they install the plugin:
+
+1. The manifest (``.cursor-plugin/plugin.json``) is valid JSON, satisfies
+ Cursor's required + structural fields, and every component path it
+ declares resolves to a real on-disk target.
+2. The marketplace manifest (``.cursor-plugin/marketplace.json``) is
+ valid JSON and points at the same plugin.
+3. The MCP config (``.cursor-plugin/mcp.json``) is valid JSON, wraps
+ server entries under the documented ``mcpServers`` key, and
+ registers the ``mempalace-mcp`` binary that ships with the package.
+4. Every skill ``SKILL.md`` and command ``*.md`` parses as YAML
+ frontmatter + markdown body. Cursor derives the slash-command
+ slug from the **filename stem** (e.g. ``mempalace-help.md`` →
+ ``/mempalace-help``), so command files do NOT need a ``name``
+ frontmatter field — only ``description`` is required.
+
+Run with::
+
+ uv run pytest tests/test_cursor_plugin_manifest.py -v
+
+All tests are pure file inspection (no subprocesses, no network) and
+take milliseconds. They run on every CI platform without needing
+Cursor itself.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import pytest
+import yaml
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+PLUGIN_DIR = REPO_ROOT / ".cursor-plugin"
+MANIFEST_PATH = PLUGIN_DIR / "plugin.json"
+MARKETPLACE_PATH = PLUGIN_DIR / "marketplace.json"
+MCP_PATH = PLUGIN_DIR / "mcp.json"
+README_PATH = PLUGIN_DIR / "README.md"
+
+# Component directories: canonical location is at the plugin root (repo root),
+# NOT inside .cursor-plugin/. Cursor's default discovery requires real
+# directories at the plugin root; .cursor-plugin/ symlinks back to these.
+SKILLS_DIR = REPO_ROOT / "skills"
+COMMANDS_DIR = REPO_ROOT / "commands"
+
+# The slugs we promise to ship. The README's "Available Slash Commands"
+# table is the user-facing contract; if you add/remove a command,
+# update both the README and this list.
+EXPECTED_COMMAND_NAMES = {
+ "mempalace-help",
+ "mempalace-init",
+ "mempalace-mine",
+ "mempalace-search",
+ "mempalace-status",
+}
+
+# Per cursor.com/docs/reference/plugins: "Plugin identifier. Lowercase,
+# kebab-case (alphanumerics, hyphens, and periods). Must start and end
+# with an alphanumeric character."
+KEBAB_RE = re.compile(r"^[a-z0-9]([a-z0-9.-]*[a-z0-9])?$")
+
+# Cursor's submission checklist explicitly forbids these in manifest
+# paths: "All paths in manifest are relative and valid (no `..`, no
+# absolute paths)." Treat both as hard failures rather than warnings —
+# the marketplace review bot would reject the plugin otherwise.
+_FORBIDDEN_PATH_FRAGMENTS = ("..",)
+
+
+# ── helpers ─────────────────────────────────────────────────────────
+
+
+def _parse_frontmatter(text: str) -> tuple[dict, str]:
+ """Split a markdown file with YAML frontmatter into ``(meta, body)``.
+
+ The frontmatter must start at byte 0 with a literal ``---\\n`` and
+ close with another ``---\\n`` line. Files without frontmatter are
+ treated as having an empty ``meta`` dict so the caller can decide
+ whether that's acceptable for the file type under test.
+ """
+ if not text.startswith("---\n"):
+ return {}, text
+ end = text.find("\n---\n", 4)
+ if end == -1:
+ return {}, text
+ raw = text[4:end]
+ body = text[end + 5 :]
+ parsed = yaml.safe_load(raw) or {}
+ if not isinstance(parsed, dict):
+ raise AssertionError(f"Frontmatter parsed to {type(parsed).__name__}, expected dict")
+ return parsed, body
+
+
+def _is_safe_relative(path_str: str) -> bool:
+ """Return True iff ``path_str`` is a relative, ``..``-free path."""
+ if not isinstance(path_str, str) or not path_str:
+ return False
+ p = Path(path_str)
+ if p.is_absolute():
+ return False
+ return not any(part in _FORBIDDEN_PATH_FRAGMENTS for part in p.parts)
+
+
+# ── plugin.json ─────────────────────────────────────────────────────
+
+
+class TestPluginManifest:
+ def test_manifest_exists(self):
+ assert MANIFEST_PATH.is_file(), f"{MANIFEST_PATH} is missing"
+
+ def test_manifest_is_valid_json(self):
+ json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+
+ def test_manifest_has_required_name_field(self):
+ data = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+ assert isinstance(data.get("name"), str) and data["name"], (
+ "plugin.json must have a non-empty 'name' (only required field per Cursor schema)"
+ )
+
+ def test_manifest_name_is_kebab_case(self):
+ data = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+ assert KEBAB_RE.match(data["name"]), (
+ f"name must be lowercase kebab-case; got {data['name']!r}"
+ )
+
+ def test_manifest_has_recommended_optional_fields(self):
+ """``description`` and ``author.name`` aren't required by the
+ schema but ARE required by the submission checklist, so failing
+ early here saves a round-trip with the marketplace reviewers."""
+ data = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+ assert isinstance(data.get("description"), str) and data["description"]
+ author = data.get("author")
+ assert isinstance(author, dict) and isinstance(author.get("name"), str)
+ assert author["name"], "author.name must be non-empty"
+
+ def test_manifest_version_matches_package_version(self):
+ """plugin.json::version must track the installed package version
+ so users can tell at a glance which mempalace they're getting.
+
+ The package version lives in ``mempalace/version.py`` as the
+ single source of truth (per CLAUDE.md). When we bump there, we
+ bump here; otherwise the plugin says one thing and `pip show`
+ says another, and bug reports become harder to triage.
+ """
+ from mempalace.version import __version__ as pkg_version
+
+ data = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+ assert data.get("version") == pkg_version, (
+ f"plugin.json version ({data.get('version')!r}) must match "
+ f"mempalace.version.__version__ ({pkg_version!r})"
+ )
+
+ @pytest.mark.parametrize("field", ["skills", "commands", "mcpServers"])
+ def test_manifest_component_paths_are_safe(self, field: str):
+ """Every path the manifest declares must be relative + ``..``-free.
+
+ Cursor's submission checklist rejects ``..`` or absolute paths
+ outright. We check here so a typo doesn't fail review.
+ """
+ data = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+ value = data.get(field)
+ if value is None:
+ return # optional — if missing, default discovery kicks in
+ if isinstance(value, str):
+ paths = [value]
+ elif isinstance(value, list):
+ paths = [v for v in value if isinstance(v, str)]
+ else:
+ return # inline object form; nothing to validate path-wise
+ for p in paths:
+ assert _is_safe_relative(p), f"{field}: {p!r} must be relative and contain no '..'"
+
+ @pytest.mark.parametrize(
+ "field,expected_type",
+ [
+ ("skills", "dir"),
+ ("commands", "dir"),
+ ("mcpServers", "file"),
+ ],
+ )
+ def test_manifest_component_paths_resolve(self, field: str, expected_type: str):
+ """Every component path must point at a real on-disk target.
+
+ Use REPO_ROOT (not PLUGIN_DIR) as the resolution base because
+ Cursor resolves manifest paths against the plugin root, which
+ for our layout is the repo root (the dir containing
+ ``.cursor-plugin/``).
+ """
+ data = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+ value = data.get(field)
+ if not isinstance(value, str):
+ return # inline object form or absent
+ target = (REPO_ROOT / value).resolve()
+ if expected_type == "dir":
+ assert target.is_dir(), f"{field}={value!r} -> {target} is not a directory"
+ else:
+ assert target.is_file(), f"{field}={value!r} -> {target} is not a file"
+
+
+# ── marketplace.json ────────────────────────────────────────────────
+
+
+class TestMarketplaceManifest:
+ def test_marketplace_exists(self):
+ assert MARKETPLACE_PATH.is_file(), f"{MARKETPLACE_PATH} is missing"
+
+ def test_marketplace_is_valid_json(self):
+ json.loads(MARKETPLACE_PATH.read_text(encoding="utf-8"))
+
+ def test_marketplace_required_fields(self):
+ data = json.loads(MARKETPLACE_PATH.read_text(encoding="utf-8"))
+ assert isinstance(data.get("name"), str) and data["name"]
+ owner = data.get("owner")
+ assert isinstance(owner, dict) and isinstance(owner.get("name"), str)
+ plugins = data.get("plugins")
+ assert isinstance(plugins, list) and 1 <= len(plugins) <= 500
+
+ def test_marketplace_lists_mempalace_plugin(self):
+ """The marketplace must list our plugin, and the listed name must
+ match the actual ``plugin.json::name`` — otherwise the marketplace
+ resolver looks up ``my-plugin/.cursor-plugin/plugin.json`` and
+ gets a name mismatch, which Cursor rejects at install time.
+ """
+ data = json.loads(MARKETPLACE_PATH.read_text(encoding="utf-8"))
+ manifest = json.loads(MANIFEST_PATH.read_text(encoding="utf-8"))
+ names = {p.get("name") for p in data["plugins"] if isinstance(p, dict)}
+ assert manifest["name"] in names, (
+ f"marketplace.json plugins list does not include {manifest['name']!r}"
+ )
+
+
+# ── mcp.json ────────────────────────────────────────────────────────
+
+
+class TestMcpConfig:
+ def test_mcp_config_exists(self):
+ assert MCP_PATH.is_file(), f"{MCP_PATH} is missing"
+
+ def test_mcp_config_is_valid_json(self):
+ json.loads(MCP_PATH.read_text(encoding="utf-8"))
+
+ def test_mcp_config_wraps_servers_under_mcpservers_key(self):
+ """Per cursor.com/docs/reference/plugins#mcp-servers, the MCP
+ config file must contain server entries under a ``mcpServers``
+ key. Using the flat shape (used by Claude's ``.mcp.json``) here
+ would silently fail to register the server with Cursor.
+ """
+ data = json.loads(MCP_PATH.read_text(encoding="utf-8"))
+ assert "mcpServers" in data and isinstance(data["mcpServers"], dict), (
+ "mcp.json must wrap servers under an 'mcpServers' object"
+ )
+
+ def test_mcp_config_registers_mempalace_server(self):
+ data = json.loads(MCP_PATH.read_text(encoding="utf-8"))
+ servers = data["mcpServers"]
+ assert "mempalace" in servers, "mcp.json must register a server named 'mempalace'"
+ entry = servers["mempalace"]
+ assert isinstance(entry, dict) and isinstance(entry.get("command"), str)
+ assert entry["command"] == "mempalace-mcp", (
+ f"mempalace server command must be 'mempalace-mcp' (the binary "
+ f"shipped by the package); got {entry.get('command')!r}"
+ )
+
+
+# ── skills/ ─────────────────────────────────────────────────────────
+
+
+class TestSkills:
+ def test_skills_dir_exists(self):
+ assert SKILLS_DIR.is_dir()
+
+ def test_at_least_one_skill_present(self):
+ skill_files = list(SKILLS_DIR.glob("*/SKILL.md"))
+ assert skill_files, (
+ f"{SKILLS_DIR} must contain at least one /SKILL.md "
+ "(otherwise Cursor's discovery treats the plugin as having no skills)"
+ )
+
+ def test_mempalace_skill_exists(self):
+ assert (SKILLS_DIR / "mempalace" / "SKILL.md").is_file()
+
+ def test_each_skill_has_valid_frontmatter(self):
+ """Every SKILL.md must declare ``name`` (kebab-case) and a
+ non-empty ``description``. Skills missing these fields silently
+ fail to register in Cursor's skill picker (#1410 equivalent).
+ """
+ for skill_path in SKILLS_DIR.glob("*/SKILL.md"):
+ text = skill_path.read_text(encoding="utf-8")
+ meta, body = _parse_frontmatter(text)
+ ctx = f"{skill_path.relative_to(REPO_ROOT)}"
+ assert meta, f"{ctx}: missing YAML frontmatter"
+ assert isinstance(meta.get("name"), str) and meta["name"], (
+ f"{ctx}: 'name' must be a non-empty string"
+ )
+ assert KEBAB_RE.match(meta["name"]), (
+ f"{ctx}: name must be lowercase kebab-case; got {meta['name']!r}"
+ )
+ assert isinstance(meta.get("description"), str) and meta["description"], (
+ f"{ctx}: 'description' must be a non-empty string"
+ )
+ assert body.strip(), f"{ctx}: body must not be empty"
+
+ def test_skill_name_matches_directory(self):
+ """The skill's directory name should equal the frontmatter
+ ``name`` — Cursor displays the directory name in the picker and
+ the frontmatter name in the API; mismatches confuse both users
+ and the agent.
+ """
+ for skill_path in SKILLS_DIR.glob("*/SKILL.md"):
+ meta, _ = _parse_frontmatter(skill_path.read_text(encoding="utf-8"))
+ dir_name = skill_path.parent.name
+ assert meta.get("name") == dir_name, (
+ f"{skill_path.relative_to(REPO_ROOT)}: name={meta.get('name')!r} "
+ f"must match directory {dir_name!r}"
+ )
+
+
+# ── commands/ ───────────────────────────────────────────────────────
+
+
+class TestDefaultDiscoveryLayout:
+ """Cursor discovers plugin components from real ``commands/``,
+ ``skills/``, and ``mcp.json`` at the *plugin root* (our repo root).
+
+ These must be real directories/files — Cursor does not follow
+ symlinks for local-plugin component discovery. We verified this
+ behaviour by comparing the cached Cloudflare plugin structure
+ (all real dirs) against our earlier broken symlink-only attempt.
+ """
+
+ def test_commands_is_real_dir_at_plugin_root(self):
+ target = REPO_ROOT / "commands"
+ assert target.is_dir(), "commands/ missing at repo root"
+ assert not target.is_symlink(), (
+ "commands/ must be a real directory, not a symlink — "
+ "Cursor does not follow symlinks for local-plugin discovery"
+ )
+
+ def test_skills_is_real_dir_at_plugin_root(self):
+ target = REPO_ROOT / "skills"
+ assert target.is_dir(), "skills/ missing at repo root"
+ assert not target.is_symlink(), (
+ "skills/ must be a real directory, not a symlink — "
+ "Cursor does not follow symlinks for local-plugin discovery"
+ )
+
+ def test_mcp_json_is_real_file_at_plugin_root(self):
+ target = REPO_ROOT / "mcp.json"
+ assert target.is_file(), "mcp.json missing at repo root"
+ assert not target.is_symlink(), (
+ "mcp.json must be a real file, not a symlink — "
+ "Cursor does not follow symlinks for local-plugin discovery"
+ )
+
+
+class TestCommands:
+ def test_commands_dir_exists(self):
+ assert COMMANDS_DIR.is_dir()
+
+ def test_command_set_matches_promised_set(self):
+ """The README documents exactly five slash commands. The files
+ on disk must match that set — no more, no fewer — otherwise the
+ README is lying to users.
+
+ Cursor derives the slash-command slug from the filename stem, so
+ we compare stems, not frontmatter ``name`` values.
+ """
+ actual = {cmd_path.stem for cmd_path in COMMANDS_DIR.glob("*.md")}
+ assert actual == EXPECTED_COMMAND_NAMES, (
+ f"Command file stem set drifted from promised set. "
+ f"On disk: {sorted(actual)}. "
+ f"Expected: {sorted(EXPECTED_COMMAND_NAMES)}."
+ )
+
+ def test_each_command_has_valid_frontmatter(self):
+ """Every command file must have YAML frontmatter with a non-empty
+ ``description`` and a non-empty body.
+
+ Cursor derives the slash-command slug from the filename stem, so
+ a ``name`` field is intentionally absent — the ``description``
+ field is what Cursor shows in the command picker.
+ """
+ for cmd_path in COMMANDS_DIR.glob("*.md"):
+ text = cmd_path.read_text(encoding="utf-8")
+ meta, body = _parse_frontmatter(text)
+ ctx = f"{cmd_path.relative_to(REPO_ROOT)}"
+ assert meta, f"{ctx}: missing YAML frontmatter"
+ assert isinstance(meta.get("description"), str) and meta["description"], (
+ f"{ctx}: 'description' must be a non-empty string"
+ )
+ assert body.strip(), f"{ctx}: body must not be empty"
+
+ def test_each_command_name_prefixed_with_mempalace(self):
+ """Cursor commands are global (not plugin-namespaced), so every
+ command file must be named ``mempalace-*.md`` to avoid colliding
+ with built-in or other-plugin commands.
+
+ The slash-command slug is the filename stem, so
+ ``mempalace-help.md`` → ``/mempalace-help``.
+ """
+ for cmd_path in COMMANDS_DIR.glob("*.md"):
+ stem = cmd_path.stem
+ assert stem.startswith("mempalace-"), (
+ f"{cmd_path.relative_to(REPO_ROOT)}: filename stem {stem!r} "
+ "must be prefixed with 'mempalace-' to avoid global-namespace collisions"
+ )
+
+
+# ── README.md ───────────────────────────────────────────────────────
+
+
+class TestReadme:
+ def test_readme_exists(self):
+ assert README_PATH.is_file(), f"{README_PATH} is missing"
+
+ def test_readme_documents_every_command(self):
+ """If the README has a command table, every command we ship
+ must be listed in it. This catches the drift case where someone
+ adds a command file but forgets to update the docs."""
+ text = README_PATH.read_text(encoding="utf-8")
+ missing = [name for name in EXPECTED_COMMAND_NAMES if f"/{name}" not in text]
+ assert not missing, f"README does not document: {missing}"
+
+ def test_readme_cross_references_hooks_install_path(self):
+ """Hooks are deliberately NOT part of the plugin (they're wired
+ via hooks/cursor/install.sh). The README must tell users where
+ to go for that, otherwise users will assume the plugin already
+ installed the hooks and wonder why nothing saves.
+ """
+ text = README_PATH.read_text(encoding="utf-8")
+ assert "hooks/cursor/install.sh" in text, (
+ "README must reference hooks/cursor/install.sh so users know how to enable auto-save"
+ )
diff --git a/website/.vitepress/config.mts b/website/.vitepress/config.mts
index 6f01b40..bdd239a 100644
--- a/website/.vitepress/config.mts
+++ b/website/.vitepress/config.mts
@@ -60,6 +60,7 @@ export default withMermaid(
{ text: 'OpenClaw Skill', link: '/guide/openclaw' },
{ text: 'Local Models', link: '/guide/local-models' },
{ text: 'Auto-Save Hooks', link: '/guide/hooks' },
+ { text: 'Cursor IDE Hooks', link: '/guide/cursor-hooks' },
{ text: 'Configuration', link: '/guide/configuration' },
],
},
diff --git a/website/guide/cursor-hooks.md b/website/guide/cursor-hooks.md
new file mode 100644
index 0000000..2721dfa
--- /dev/null
+++ b/website/guide/cursor-hooks.md
@@ -0,0 +1,298 @@
+# Cursor IDE Hooks
+
+Three hooks for the [Cursor](https://cursor.com) IDE that save memories
+automatically and inject recall context at session start. No manual "save"
+commands needed.
+
+These are additive to the existing [Claude Code + Codex hooks](/guide/hooks).
+You can run both — they share the same `~/.mempalace/hook_state/`
+directory and the same kill switches.
+
+::: tip Pair this with the Cursor plugin
+The hooks here only handle the auto-save side. To also get MemPalace's
+MCP server, slash commands (`/mempalace-search`, etc.), and the
+guided `mempalace` skill, install the bundled
+[Cursor plugin](https://github.com/MemPalace/mempalace/blob/main/.cursor-plugin/README.md) —
+it's the `.cursor-plugin/` folder at the repo root, dropped into
+`~/.cursor/plugins/local/mempalace`. The plugin and the hooks are
+orthogonal: install whichever you want, in any order. The plugin
+deliberately does **not** wire hooks itself because Cursor's hooks
+system is configured per-user/per-project (in `~/.cursor/hooks.json`),
+not per-plugin.
+:::
+
+## What They Do
+
+| Hook | When It Fires | What Happens |
+|------|---------------|--------------|
+| **Wake Hook** | `sessionStart` — when a new Cursor conversation opens | Returns `additional_context` telling the agent to recall scoped to the wing inferred from the workspace root. Cursor-only — Claude Code has no equivalent. |
+| **Save Hook** | `stop` — after every agent turn | Counts stop invocations per conversation. Every 15 (default), emits a `followup_message` telling the agent to file the session into MemPalace and write a diary entry. |
+| **PreCompact Hook** | `preCompact` — right before context compaction | Runs `mempalace mine` synchronously on the transcript before compaction summarises it. Drops a pending-save marker so the next stop forces a save followup. |
+
+**Two-layer capture:** the save and precompact hooks both mine the JSONL
+transcript directly into the palace (capturing verbatim tool output — Shell
+results, search findings, build errors). The save hook also nudges the AI
+to write structured drawers and a diary entry. Belt-and-suspenders.
+
+## Install — Cursor
+
+The fastest path is the installer that ships in the repo.
+
+Preview the change first (writes nothing, just prints the would-be JSON):
+
+```bash
+hooks/cursor/install.sh --scope user --dry-run
+```
+
+User scope — applies globally, writes `~/.cursor/hooks.json`:
+
+```bash
+hooks/cursor/install.sh --scope user
+```
+
+Or project scope — only this repo, writes `/.cursor/hooks.json`:
+
+```bash
+hooks/cursor/install.sh --scope project --target /path/to/your/repo
+```
+
+The installer copies the three hook scripts to `~/.mempalace/hooks/cursor/`,
+merges the entries into your `hooks.json`, and preserves any unrelated
+hooks already in that file. Re-running is idempotent. Pass `--variant
+minimal` for the `stop`-only setup, or `--uninstall` to remove the
+MemPalace entries (leaves other hooks intact).
+
+### Manual install — `~/.cursor/hooks.json` (user scope)
+
+```json
+{
+ "version": 1,
+ "hooks": {
+ "sessionStart": [
+ { "command": "/absolute/path/to/hooks/cursor/mempal_wake_hook_cursor.sh" }
+ ],
+ "stop": [
+ {
+ "command": "/absolute/path/to/hooks/cursor/mempal_save_hook_cursor.sh",
+ "loop_limit": 1
+ }
+ ],
+ "preCompact": [
+ { "command": "/absolute/path/to/hooks/cursor/mempal_precompact_hook_cursor.sh" }
+ ]
+ }
+}
+```
+
+### Manual install — `.cursor/hooks.json` (project scope)
+
+Identical content. Project hooks load in any trusted workspace and are
+checked into version control with the project. Cloud agents also load
+project hooks.
+
+Make the scripts executable once:
+
+```bash
+chmod +x hooks/cursor/mempal_save_hook_cursor.sh \
+ hooks/cursor/mempal_precompact_hook_cursor.sh \
+ hooks/cursor/mempal_wake_hook_cursor.sh
+```
+
+Cursor watches `hooks.json` and reloads automatically after a save. If
+hooks still do not fire, restart Cursor and check the Hooks panel in
+Settings → Hooks.
+
+## Configuration
+
+All knobs are environment variables. Defaults match the Claude Code hooks
+where they overlap.
+
+- **`MEMPAL_SAVE_INTERVAL=15`** — number of `stop` events between save
+ followups. Lower = more frequent saves, higher = less interruption.
+- **`MEMPAL_STATE_DIR`** — where the hook keeps counter files, the
+ pending-save marker, and `cursor_hook.log`. Defaults to
+ `~/.mempalace/hook_state/`.
+- **`MEMPAL_DIR`** — optional project directory (code, notes, docs) to
+ also mine on each save trigger, with `--mode projects`. The transcript
+ is always mined regardless — `MEMPAL_DIR` is purely additive.
+- **`MEMPAL_PYTHON`** — path to a Python 3 interpreter. The hook's own
+ JSON parsing and the install script's JSON merge use this. Resolution
+ order: `$MEMPAL_PYTHON` → `command -v python3` → bare `python3`. Set
+ this when Cursor is launched from a GUI on macOS and the inherited
+ PATH lacks the Python where you installed MemPalace.
+- **`MEMPAL_DISABLE_HOOK=1`** — emergency kill switch. Disables all
+ three hooks; they emit `{}` and exit 0.
+- **`MEMPALACE_HOOKS_AUTO_SAVE=false`** — same effect as
+ `MEMPAL_DISABLE_HOOK=1`. Also honoured via `~/.mempalace/config.json`:
+
+ ```json
+ { "hooks": { "auto_save": false } }
+ ```
+
+## How It Works
+
+### Wake Hook (`sessionStart`)
+
+```
+Cursor opens new conversation → sessionStart fires
+ ↓
+ Hook reads workspace_roots[0]
+ ↓
+ Infers wing = basename(workspace_root)
+ ↓
+ {"additional_context": "scope recall to wing=<...>"}
+ ↓
+ Agent reads additional_context before first turn
+ ↓
+ Agent calls mempalace_search + mempalace_diary_read
+ wing-scoped on the first relevant question
+```
+
+Cursor's `sessionStart` is fire-and-forget — the agent loop does not wait
+for a blocking response and does not consume `continue` / `user_message`.
+But it does honour `additional_context`, and that is the only field
+MemPalace emits.
+
+### Save Hook (`stop` event)
+
+```
+User sends message → agent responds → Cursor fires stop hook
+ ↓
+ Hook reads loop_count from stdin
+ ↓
+ ┌─── loop_count > 0 (our own followup running) ──→ echo "{}"
+ │
+ └─── loop_count == 0
+ ↓
+ Check pending-save marker from preCompact
+ ↓
+ ┌── marker present ──→ delete + emit followup_message
+ │
+ └── no marker
+ ↓
+ Atomic counter++ for this conversation_id
+ ↓
+ ┌── counter % SAVE_INTERVAL != 0 ──→ echo "{}"
+ │
+ └── counter % SAVE_INTERVAL == 0
+ ↓
+ Background: mempalace mine
+ ↓
+ Emit {"followup_message": "save key topics..."}
+ ↓
+ Cursor auto-submits followup as next user turn
+ ↓
+ Agent files drawers + writes diary
+ ↓
+ Agent stops; stop fires again with loop_count = 1
+ ↓
+ Hook sees loop_count > 0 → echo "{}" → agent stops
+```
+
+The `loop_count > 0` short-circuit prevents infinite loops: emit once →
+agent saves → stops → we see `loop_count = 1` → we let it through. This
+is the Cursor equivalent of Claude Code's `stop_hook_active` flag. The
+`loop_limit: 1` in `hooks.json` is defense-in-depth on top.
+
+### PreCompact Hook
+
+```
+Context window near full → Cursor fires preCompact (observational)
+ ↓
+ Synchronously: mempalace mine
+ ↓
+ Drop pending-save marker for this conversation_id
+ ↓
+ {"user_message": "transcript snapshotted..."}
+ ↓
+ Compaction proceeds (we cannot block it)
+ ↓
+ Next stop event picks up the marker → forces save
+```
+
+Cursor's `preCompact` is documented as **observational only** — its only
+output field is `user_message`, with no `followup_message` and no way to
+block. That is fundamentally different from Claude Code's `PreCompact`
+which can block until the AI has saved. We work around the limitation by
+mining the verbatim transcript synchronously (zero LLM cost) and queueing
+a save nudge for the next agent turn.
+
+## Cursor-only extras
+
+The features below are not available in the Claude Code or Codex hooks
+because their hook surfaces do not expose the necessary events.
+
+- **Session-start recall via `sessionStart`.** The wake hook injects
+ wing-scoped recall guidance into the conversation's initial system
+ context, so the agent searches the palace before answering anything
+ that touches past work. Verified output field — see the [Cursor hooks
+ reference](https://cursor.com/docs/hooks.md) section "sessionStart".
+- **Per-script `loop_limit`.** Cursor's `loop_limit` (default 5,
+ configurable per script) is a hard cap on how many auto-followups
+ Cursor will issue. MemPalace sets it to `1` in the example
+ `hooks.json` as defense-in-depth on top of its own `loop_count`
+ check.
+- **Inferred wing from `workspace_roots`.** Both the wake hook and the
+ save hook use `basename(workspace_roots[0])` to scope memory
+ operations. A user with multiple Cursor workspaces gets per-project
+ wings without any manual configuration.
+
+## Debugging
+
+```bash
+cat ~/.mempalace/hook_state/cursor_hook.log
+```
+
+Example output (ISO-8601 timestamps, event + conversation id, message):
+
+```
+[2026-05-27T02:16:01Z] [event=sessionStart] [conv=abc123] workspace=/Users/me/proj wing=proj
+[2026-05-27T02:21:33Z] [event=stop] [conv=abc123] counter 0 -> 1 (interval=15)
+[2026-05-27T02:42:09Z] [event=stop] [conv=abc123] counter 14 -> 15 (interval=15)
+[2026-05-27T02:42:09Z] [event=stop] [conv=abc123] TRIGGERING SAVE at counter=15
+[2026-05-27T02:42:11Z] [event=stop] [conv=abc123] loop_count>0; letting agent stop
+[2026-05-27T03:05:44Z] [event=preCompact] [conv=abc123] trigger=auto transcript=/Users/me/.cursor/.../transcript.txt
+[2026-05-27T03:05:46Z] [event=stop] [conv=abc123] consumed pending-save marker (post-compaction)
+```
+
+When a hook can't parse its stdin (corrupt payload, future Cursor schema
+change), the raw input — capped at 4096 bytes, mode 0600 — lands at:
+
+```
+~/.mempalace/hook_state/cursor_last_input.log
+~/.mempalace/hook_state/cursor_last_python_err.log
+```
+
+Both are overwritten on each failure, never appended, so a repeating
+misconfiguration cannot grow disk usage.
+
+## Cost
+
+**Zero extra tokens.** The hooks are bash scripts that run locally. They
+do not call any API. The `followup_message` the save hook emits is a
+normal user turn — it counts the same as any other user message and does
+not invoke any extra LLM call beyond the one the user would otherwise
+make.
+
+## Known limitations
+
+- **Hooks load at session start.** Cursor watches `hooks.json` and reloads
+ the wiring when the file changes, but for the freshly-loaded hook
+ scripts to take effect on an existing conversation you usually have to
+ start a new conversation. This matches the behaviour of Claude Code's
+ hook lifecycle.
+- **`preCompact` cannot block.** See the diagram above. The
+ pending-save marker is the workaround.
+- **Transcript file format is opaque.** Cursor does not document the
+ schema of the file at `transcript_path`. MemPalace's `mempalace mine`
+ command handles it via its normaliser layer; the hooks themselves never
+ parse the transcript directly.
+
+## Related
+
+- [Auto-Save Hooks (Claude Code + Codex)](/guide/hooks) — the analogous
+ feature for those tools.
+- [`hooks/cursor/STDIN_SHAPE.md`](https://github.com/MemPalace/mempalace/blob/develop/hooks/cursor/STDIN_SHAPE.md)
+ — per-event JSON schema with citations.
+- [Claude Code Retention](/guide/claude-code-retention) — broader
+ setup checklist if you mix Cursor with Claude Code.