aide-memory in Claude Code
Claude Code is the editor aide-memory’s reference adapter is built and tested against. Every capability in the capability summary works as designed.
First-time setup
aide-memory init writes Claude Code’s config files. Start a fresh Claude Code session after init (or restart your current one) so it picks up the new MCP server.
Files written:
.claude/settings.json, hook registrations (six events: SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact).mcp.json, MCP server pointing atdist/memory/cli.js.claude/rules/aide-memory.md, agent instructions.aide/config.json, aide-memory configuration with every public setting seeded.aide/memories/, the four layer directories.ignoreand.gitignoreentries for derived artifacts
Observed runtime behavior
On first read of a file with un-recalled scoped memories. The PreToolUse hook returns decision: "block" with a reason:
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.Plus an inline branded status line via systemMessage:
aide-memory · prompting aide_recall for scoped memories (expected flow)The agent calls aide_recall({paths: [...]}), the PostToolUse hook records the recalled memory IDs, and the agent retries the read. The first-read prompt happens once per path per session by default (tunable via hooks.read.maxBlocks).
On re-read of the same path. Tracking prevents the prompt. The hook emits a soft nudge via hookSpecificOutput.additionalContext if memories arrived since the last recall, otherwise silent.
When the agent calls aide_recall. Standard Claude Code tool-call chrome: you see the request, the response, and whatever the agent summarizes. The branded aide-memory · ... status line is reserved for hook fires, not MCP tool calls.
When you type a correction. Patterns like “no, use X instead” / “actually…” trip the UserPromptSubmit hook. By default (hooks.correction.escalate = "off") it emits a soft in-turn nudge via hookSpecificOutput.UserPromptSubmit.additionalContext:
Your prompt may contain a correction or convention worth persisting. If something here applies to future work in this project — across preferences (how you work), technical (stack facts, why-decisions), area_context (decisions for this code area), or guidelines (team rules) — call aide_remember on the matching layer. Otherwise respond as normal.The agent sees the nudge as extra context appended to your message and decides whether to store. No extra turn forced. Set hooks.correction.escalate = "block" to also write a flag so the next Stop fire reminds the agent with decision:"block" if no memory was stored.
When a session starts. The SessionStart hook injects top preferences + guidelines + priority-always memories (bounded by injection.maxChars, default 1200). On source: "resume" the hook no-ops — your prior transcript already carries the context and the recall tracking, so re-injecting would duplicate. On clear and compact it clears tracking + re-injects.
When the agent finishes a turn. The Stop hook runs on a configurable schedule (default ramps every 3 turns through turn 9, every 5 through turn 29, every 10 afterwards) and prompts:
Anything from this turn worth persisting for future sessions in this project? Could touch preferences, technical, area_context, or guidelines. If yes, call aide_remember on the matching layer. Otherwise stop.Default hooks.stop.mode = "block" delivers this prompt via decision:"block" + a friendly brand chrome (aide-memory · checkpoint — anything worth remembering?). The Claude Code TUI collapses the platform’s “Stop hook error:” label behind ctrl+o when a systemMessage is present, so the brand chrome is the primary visible line. Set hooks.stop.mode = "off" to silence scheduled prompts entirely.
Troubleshooting
Hook not firing. Verify .claude/settings.json contains a hooks key with aide-memory scripts wired to each event. If it looks stale, run aide-memory init --force to re-install.
MCP tool calls failing. Check that .mcp.json exists at the project root and points at a current dist/memory/cli.js. After aide-memory init (or any aide-memory upgrade), restart Claude Code so it picks up the new MCP config.
“PreToolUse hook returned blocking error” text looks alarming. The red wording around our decision: "block" is hardcoded in Claude Code’s TUI and can’t be customized. Our accompanying systemMessage (aide-memory · prompting aide_recall...) is the reassurance line; the block is the expected flow, not a failure.
Hook runs but agent doesn’t call aide_recall. Check the .claude/rules/aide-memory.md file is present and up-to-date. If the agent has strayed from the instructions, aide-memory init --update-rules re-writes the rule file to the canonical template.
Session-start injection seems empty. Check injection.enabled (default true) and the per-layer knobs (injection.preferences, injection.guidelines). See Configuration.
Personal vs shared preferences. aide_remember accepts a shared parameter (true writes to preferences/shared/, committed; false writes to preferences/personal/, gitignored). When the agent omits it, the default comes from memories.defaultShared in .aide/config.json (default true). Flip with aide-memory config memories.defaultShared false to default to personal/private. Per-call shared always overrides.
Platform capabilities aide-memory uses
decision: "block"+reason, prompts a file read with the agent callingaide_recallfirst.hookSpecificOutput.additionalContext, injects dynamic context into the agent’s next turn (soft nudge, session-start content, correction reminder).systemMessagetop-level field, branded inline status lines visible to the user in the chat transcript.- MCP stdio transport, the aide-memory CLI runs as an MCP server over stdio.