aide-memory in Cursor

Cursor ships with aide-memory’s full hook + MCP wiring. Some details of how hook output renders in Cursor’s UI differ from Claude Code; the agent receives the same context payload either way. Where we noted differences during testing, they’re flagged below as observed behavior, not “issues.”

For the editor-agnostic mental model see Concepts; for the capability summary see Supported Editors.

First-time setup

aide-memory init creates:

.cursor/hooks.json, hook registrations (sessionStart, preCompact, stop, beforeSubmitPrompt, preToolUse matching Read / Write / Grep / MCP:aide_*, postToolUse)
.cursor/mcp.json, MCP server entry (type: "stdio")
.cursor/rules/aide-memory.mdc, dynamically regenerated rules file with YAML frontmatter (alwaysApply: true, globs: **/*). Gitignored because it’s a derived artifact that rewrites on memory and config changes.
.aide/config.json and .aide/memories/, same as Claude Code
.ignore / .gitignore entries

⚠ Two enablement steps you’ll hit on first init

Restart Cursor. Cursor reads .cursor/mcp.json on startup only. Cmd+Q the Cursor app (don’t just close the window) and reopen.
Toggle the aide-memory MCP server ON. Cursor → Settings → MCP.

Observed runtime behavior

On first read of a file with un-recalled scoped memories. The preToolUse hook returns:

{
  "permission": "deny",
  "user_message": "aide-memory · prompting aide_recall for scoped memories (expected flow)",
  "agent_message": "2 memories for src/auth/middleware.ts not yet recalled. Call aide_recall."
}

The agent reads agent_message and calls aide_recall({paths: [...]}), then retries.

We observed during testing that hook output renders differently in Cursor’s UI compared to Claude Code: the agent receives the same context payload via agent_message, but the user-visible chrome (user_message) renders inline reliably on hard-block events; on soft-allow events it appears in the Hooks Output panel rather than chat. Either way, the agent context is consistent.

On re-read of the same path (soft). When the file has been encountered before but new memories arrived (or some IDs are still uncovered), preToolUse returns {"permission": "allow", "agent_message": "<missing-ids nudge>"}. The agent receives the nudge in context but the read isn’t blocked.

Per-Read coverage when the file is open in the editor. During testing on Cursor 3.2.11, the preToolUse:Read hook was observed not firing for files already open in the editor pane. The per-Edit safety net (preToolUse:Write) fires reliably regardless of editor state, and the rules-file injection instructs the agent to call aide_recall for any file path it’s reasoning about even when the file content is already visible. In typical (non-adversarial) workflows we observed agents following the rules-file guidance and calling aide_recall proactively even when the per-Read hook didn’t fire.

When you type a correction. The beforeSubmitPrompt hook detects correction patterns and writes a correction-pending-<sid>.txt flag. The flag is set immediately, but the user-visible reminder (“correction wasn’t stored, please call aide_remember”) fires via the next Stop hook’s followup_message rather than in-turn (Cursor’s beforeSubmitPrompt doesn’t carry an additionalContext-style channel today).

When a session starts. Cursor’s sessionStart.additional_context channel did not appear to inject content in our testing (also reported on the Cursor forum). aide-memory delivers the same content via the dynamically regenerated .cursor/rules/aide-memory.mdc (with alwaysApply: true), which Cursor staff have endorsed as the workaround. Content identical, channel different.

When the agent finishes a turn. The Stop hook emits a followup_message with the same reflection prompt Claude Code gets via systemMessage.

Rules-file regeneration

.cursor/rules/aide-memory.mdc is a derived artifact. aide-memory regenerates it atomically on:

aide-memory init and aide-memory init --force --update-rules
aide-memory config <key> <value> when the key affects session-start content (injection.*, memories.softening.threshold, etc.)
aide_remember / aide_update / aide_forget for memories that are priority: "always" or in the preferences / guidelines layer
aide-memory sync import

The file is gitignored with a header comment explaining why. If Cursor ships native session-start additionalContext support, aide-memory will narrow this file back to a static template and stop regenerating it.

Token budget

The rules file is injected on every agent turn. With defaults:

injection.preferences: 15 ≈ 450 tokens
All guidelines (typical 5-15) ≈ 100-300 tokens
Priority-always memories (typical 0-3) ≈ 0-150 tokens
Headers / formatting ≈ 100 tokens
Total ≈ 650-1000 tokens per turn

Capped by injection.maxChars (default 1200 chars ≈ 300 tokens after truncation). Rules-file content caches well in Anthropic’s prompt cache (system-prompt slot), so effective cost drops after the first turn.

To reduce the budget:

# Full disable, static rules only, no dynamic content
aide-memory config injection.enabled false
 
# Granular tune
aide-memory config injection.preferences false
aide-memory config injection.guidelines false
aide-memory config injection.maxChars 300
 
# Aggressive cap, keep everything
aide-memory config injection.maxChars 400

Troubleshooting

MCP tools don’t appear after init. Restart Cursor. If they still don’t appear, toggle the aide-memory MCP server off then on in Settings → MCP.

Disabled MCP server keeps re-enabling on restart. Reported on the Cursor forum; not specific to aide-memory.

Hook collision with another tool. Cursor runs the first hook registered per event. If another tool already wrote .cursor/hooks.json, its hook fires and ours doesn’t. aide-memory init warns on collision.

Agent doesn’t notice session-start content. Check .cursor/rules/aide-memory.mdc exists and has alwaysApply: true in the frontmatter. If missing or stale: aide-memory init --update-rules.

MCP orphan processes on restart. Cursor’s MCP process lifecycle has been reported leaking children on restart. aide-memory does PID-file cleanup on server start, so leaks are bounded. If you see multiple node dist/memory/cli.js processes, pkill -f dist/memory/cli.js is safe.

Personal vs shared preferences. aide_remember accepts a shared parameter. Default comes from memories.defaultShared (default true). Flip with aide-memory config memories.defaultShared false to default to personal/private.

Agent reads a file via @-attachment or Tab context and aide-memory doesn’t prompt. Expected: @-file attachments and Tab context pulls don’t go through preToolUse. aide-memory’s prompts are for agent-planned reads, not user-provided context.

Behavior we’ve observed during testing

Soft user_message chrome on permission: "allow" events appears in the Hooks Output panel rather than chat. The agent context arrives via agent_message either way.
beforeSubmitPrompt doesn’t carry an additional-context channel, so correction reminders ship via the next Stop hook’s followup_message instead of in-turn.
sessionStart.additional_context didn’t appear to inject content in our tests; aide-memory ships SessionStart content via the regenerated .cursor/rules/aide-memory.mdc instead.

Claude Code Codex