Adds first-class Cursor IDE integration alongside the existing Claude
Code and Codex hook flows, so Cursor users get the same automatic
diary saves, pre-compaction transcript capture, and session-start
memory recall — without changing any default behaviour for existing
users.
What's included
---------------
Cursor hook scripts (hooks/cursor/):
- mempal_save_hook_cursor.sh — Stop event, counter +
loop_count guard, pending-save marker consumption, background
mempalace mine, followup_message emission.
- mempal_precompact_hook_cursor.sh — synchronous mine before
compaction, drops a pending_save marker, returns user_message.
- mempal_wake_hook_cursor.sh — sessionStart event,
wing-scoped recall guidance via additional_context.
- lib/common.sh — shared parsing + state helpers
(bash 3.2 safe, no heredoc-in-subshell traps).
- install.sh — idempotent installer with
--scope, --variant, --dry-run, --uninstall. Recognises existing
entries by basename so re-installs across paths work.
- STDIN_SHAPE.md, README.md — payload schemas + quick
reference.
Cursor plugin (.cursor-plugin/ + repo-root components):
- plugin.json, marketplace.json, README.md.
- skills/mempalace/SKILL.md — model-invocable skill mirroring the
Claude plugin's skill surface.
- commands/mempalace-{help,init,mine,search,status}.md — slash
commands for marketplace-published installs (filename = slug).
- mcp.json — auto-registers the mempalace MCP
server, wrapped under the documented mcpServers key.
Examples + docs:
- examples/cursor/hooks.json, hooks.minimal.json + README.
- website/guide/cursor-hooks.md + sidebar entry.
- README.md and CHANGELOG.md updates.
Tests (129 new, all green):
- tests/test_cursor_hooks_shell.py — 75 behavioural tests for
the three hook scripts: kill switches, input parsing, counter
logic, loop prevention, pending markers, wing inference, logging.
- tests/test_cursor_hooks_install.py — 19 contract tests for the
installer: dry-run, idempotent merge, basename-matched uninstall,
refusal to overwrite malformed JSON.
- tests/test_cursor_plugin_manifest.py — 35 contract tests for the
plugin: manifest validity, version sync with mempalace.version,
mcp.json shape, skill/command frontmatter, default-discovery
layout invariants.
Design notes
------------
- Local-first and zero-API by default; hooks never call external
services. Same privacy model as the existing Claude Code hooks.
- Fail-open: hook scripts deliberately do not use set -e so a broken
hook can never block the user's conversation.
- Cursor preCompact cannot block + return a followup, so we
synchronously mine the transcript and drop a pending_save marker
that the next stop hook consumes — guarantees verbatim capture
before context window compression.
- Cursor's default plugin discovery requires real commands/, skills/,
and mcp.json at the plugin root (verified against the cached
cloudflare plugin); .cursor-plugin/{commands,skills} are convenience
symlinks back to those canonical locations.
- bash 3.2 compatibility throughout: avoids heredoc-in-command-
substitution parser bugs; uses python -c for JSON parsing;
basename-matched entry recognition in install.sh.
- All changes are additive. No existing files are removed, no
existing hooks change behaviour, and no new runtime dependencies
are introduced.
Co-authored-by: Cursor <cursoragent@cursor.com>
83 lines
2.8 KiB
Bash
Executable File
83 lines
2.8 KiB
Bash
Executable File
#!/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=<inferred>.
|
|
#
|
|
# 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=<relevant keywords>) 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"
|