Hooks

Hooks are the core of aide-memory’s capture-and-recall system. The agent does not call them; the editor does. They fire automatically at the right lifecycle moments so capture and recall happen without anyone needing to invoke them by hand. The rules file written at init also nudges the agent to call aide_remember when corrections or decisions surface, so capture isn’t purely hook-driven.

Overview

Six hooks fire across the session lifecycle, plus one optional git hook for sync.

Read / Edit hook (PreToolUse)

Files: scripts/hooks/pre-read-recall.sh, scripts/hooks/pre-edit-recall.sh

Fires before the agent reads or edits a file. The hook counts memories scoped to that path and shows a breakdown by layer and topic:

19 memories for src/auth/middleware.ts (5 technical, 8 area_context, 4 preferences, 2 guidelines), topics: JWT, middleware, validation. Call aide_recall if results not already in this conversation.

The hook never dumps memory content; only counts, layers, and topic keywords. The agent decides whether to call aide_recall to fetch actual memories.

Session-scoped behavior (with hooks.read.maxBlocks: 1, the default):

• First read of a path with un-recalled scoped memories: blocks until the agent calls aide_recall
• After recall: subsequent reads of the same path are silent, or soft-nudged if some scoped memories still haven’t been recalled (either new memories arrived since the last recall, or some IDs were left uncovered)
• Tracking lives at .aide/cache/recalled-paths-{session_id}.txt
• Directory prefix matching applies: recalling src/auth/ covers src/auth/middleware.ts

All configurable:

• hooks.read.maxBlocks: 1 (default), 0 disables the read hook entirely
• hooks.edit.maxBlocks: 1 (default), 0 disables the edit hook entirely
• memories.softening.threshold: 10 (default), below this total-memory count, hard blocks become soft nudges so new projects don’t feel hostile

Special case: if the agent tries to read a raw .aide/memories/ JSON file directly, the hook warns:

memory_file_direct_read: You are reading a raw memory file. Use aide_recall for structured context.

Track-recall hook (PreToolUse:aide_recall)

File: scripts/hooks/track-recall.sh

Fires before the agent calls aide_recall. Writes the recalled paths to .aide/cache/recalled-paths-{session_id}.txt so the read hook stops blocking on those paths for the rest of the session.

SessionStart hook

File: scripts/hooks/session-start-clear.sh

Fires when the editor starts, resumes, or clears a session.

On Claude Code (native channel): injects top-N preferences + guidelines + priority-always memories into the agent’s starting context, bounded by injection.maxChars (default 1200).

On Cursor (workaround channel): the same content is delivered via a dynamically-regenerated .cursor/rules/aide-memory.mdc file rather than the broken sessionStart.additional_context channel (Cursor #158452, staff-confirmed).

Either way, the hook also cleans up stale recalled-paths-* tracking files from ended sessions while preserving the current session’s file.

Stop hook (periodic reflection)

File: scripts/hooks/stop-remember.sh

Fires when the agent finishes a turn. Runs on a configurable schedule so the prompt feels right at every session length:

Default hooks.stop.schedule:
  Phase 1 (turns 1 through 9):  every 3 turns   (dense, fresh decisions)
  Phase 2 (turns 10 through 29): every 5 turns  (mid-session)
  Phase 3 (turns 30+):          every 10 turns  (long session)

When it does fire, the hook prompts the agent:

Anything worth remembering? Call aide_remember if this turn produced a decision, correction, or non-obvious finding.

Override via:

aide-memory config hooks.stop.schedule '[{"every":5}]'         # every 5, forever
aide-memory config hooks.stop.schedule '[{"every":999999}]'    # effectively off

UserPromptSubmit hook (correction detection)

File: scripts/hooks/detect-correction.sh

Fires when you send a message. Scans the message for three pattern families and injects a soft nudge (never blocking, since blocking on UserPromptSubmit would reject your message entirely):

Only the first matching pattern fires. The hook does not store anything itself; it tells the agent what was detected and prompts the appropriate aide_remember call.

Disable with aide-memory config hooks.correction.enabled false.

PreCompact hook

Fires before manual /compact and auto-compact. Clears the session’s tracking files (recalled-paths-<sid>.txt, stop-count-<sid>.txt, correction-pending-<sid>.txt) so the post-compact turn re-prompts cleanly. After compaction the agent’s context no longer contains previous tool results, so paths must be re-recalled on the next read.

Configurable: hooks.precompact.mode = "cleanup" (default) clears the tracking. "off" preserves the tracking across compaction (useful if you compact frequently and don’t want to re-prompt every time).

post-checkout git hook

Installed to: .git/hooks/post-checkout

Fires after git checkout or git pull (branch checkout, not file checkout). Rebuilds the SQLite cache from the JSON memory files. Runs in the background, never blocks git operations. Timeout can be adjusted by editing the installed .git/hooks/post-checkout.

Session-scoped tracking

All recall tracking is session-scoped via session_id (from hook stdin JSON). Each session gets its own tracking file at .aide/cache/recalled-paths-{session_id}.txt:

• Different sessions (e.g., multiple terminal tabs) track independently
• SessionStart cleans up stale tracking files from ended sessions
• PreCompact clears the current session’s file (context loss means paths must be re-recalled)

Disabling individual hooks

Each hook can be disabled or tuned independently:

# Silence the Stop reflection prompt (effectively, by setting a huge interval)
aide-memory config hooks.stop.schedule '[{"every":100}]'
 
# Disable correction detection
aide-memory config hooks.correction.enabled false
 
# Disable the file-read nudge and blocking
aide-memory config hooks.read.maxBlocks 0
 
# Disable the file-edit nudge and blocking
aide-memory config hooks.edit.maxBlocks 0
 
# Preserve tracking across compaction (don't re-prompt every /compact)
aide-memory config hooks.precompact.mode off
 
# Silence the pre-search nudge entirely
aide-memory config hooks.search.mode off
 
# Hard-block grep on a search-relevant query (instead of soft default)
aide-memory config hooks.search.mode block

Or hide the user-facing aide-memory · ... lines while keeping all hook behavior:

aide-memory config hooks.visible false

Per-editor delivery differences

Both editors get the same hook content; the channel differs.

Claude Code: hookSpecificOutput.additionalContext for soft nudges; decision: "block" + reason for hard blocks; systemMessage for the user-visible aide-memory · ... chrome inline in chat. SessionStart fires natively. SessionStart re-fires after compaction.

Cursor: agent_message for soft nudges; permission: "deny" for hard blocks; user_message for inline chrome on hard-block (Cursor 3.2.11 renders this in chat on deny but not on allow); followup_message for Stop nudges. SessionStart content ships via the regenerated .cursor/rules/aide-memory.mdc because the native sessionStart channel is broken upstream.

See Supported Editors for the full per-event mapping.

Rules files

aide-memory init writes a rules file for each supported editor. The file teaches the agent when to call each MCP tool and how to format memories.

Rules files are safe to regenerate at any time:

aide-memory init --update-rules

This rewrites the rules files with the latest templates each time you run it; safe to run repeatedly.