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 at dist/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
• .ignore and .gitignore entries 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. It injects a nudge:

BEFORE doing anything else, store this correction via aide_remember with layer=preferences and scope=<current area>. Confirm after storing.

The agent calls aide_remember in the same turn.

When a session starts or resumes. The SessionStart hook injects top preferences + guidelines + priority-always memories (bounded by injection.maxChars, default 1200). It also re-fires after context compaction.

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 worth remembering? Call aide_remember if this turn produced a decision, correction, or non-obvious finding.

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 calling aide_recall first.
• hookSpecificOutput.additionalContext, injects dynamic context into the agent’s next turn (soft nudge, session-start content, correction reminder).
• systemMessage top-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.