Repository navigation
Description
Summary
When agentmemory is used with Claude Code while installed via a non-Claude-plugin path (the most common case today: MCP server registered globally via npx @agentmemory/mcp, hook scripts coming from the Codex plugin cache), users have to reference the hook scripts by absolute path in ~/.claude/settings.json. That path embeds the package version, and every Codex (or npm) update silently breaks all hooks.
Repro
-
Install agentmemory's MCP server globally in Claude Code (e.g. add to
~/.claude.json'smcpServers). -
Install agentmemory as a Codex plugin — scripts land at
~/.codex/plugins/cache/agentmemory/agentmemory/<VERSION>/scripts/*.mjs. -
Claude Code does not see agentmemory as a Claude plugin, so
${CLAUDE_PLUGIN_ROOT}fromhooks/hooks.jsonis never resolved. To get auto-capture working, the user has to copy the hooks config into~/.claude/settings.jsonwith absolute paths, like:"SessionStart": [{ "hooks": [{ "type": "command", "command": "node C:/Users/Me/.codex/plugins/cache/agentmemory/agentmemory/0.9.18/scripts/session-start.mjs" }]}]
-
On the next
agentmemoryrelease (e.g. 0.9.19), the cache directory changes to.../0.9.19/scripts/. All 9 hooks now point at a non-existent path. No error surfaces to the user — auto-capture just silently stops, and they only notice whenmemory_sessionsshows no real sessions.
Why it's hard to notice
- Hook failures in Claude Code don't crash the session; they just don't fire.
- The MCP tools (
memory_save,memory_recall, …) keep working perfectly, somemory_diagnosereturns all-green. From the user's perspective everything looks healthy, even though session auto-capture has been dead since the last upgrade.
Fix ideas (rough order of preference)
-
First-class Claude Code plugin distribution. The package already ships
.claude-plugin/plugin.json— publish/list agentmemory in a Claude Code marketplace (or documentclaude plugin addagainst the npm tarball) so${CLAUDE_PLUGIN_ROOT}is set by the harness and the version-pinned path stops being the user's problem. -
Stable
currentsymlink/junction in the install layout. Have the installer (Codex side, or a postinstall in the npm package) maintain~/.codex/plugins/cache/agentmemory/agentmemory/current/→ active version. Then settings.json can reference.../current/scripts/...and survive upgrades. On Windows this needs a directory junction (mklink /J) since symlinks require admin. -
CLI helper that emits the hooks block. Add a subcommand like
agentmemory print-claude-hooksthat resolves the install path at runtime and prints the JSON ready to paste (or--installto merge it into~/.claude/settings.jsondirectly). Users re-run it after upgrades; the script can also detect version drift. -
Docs + warning. At minimum, README should call out this footgun explicitly for users who wire the MCP standalone, recommend option 3 above, and have the
session-start.mjsscript log a deprecation/wrong-path warning if it detects it's being run from an older cache directory than the currently installed version.
Happy to send a PR for option 3 (the CLI helper) if that direction sounds right — it's the smallest change that unblocks the immediate pain while options 1/2 are figured out.
Environment
- OS: Windows 11
- Claude Code with agentmemory MCP via
npx @agentmemory/mcpin~/.claude.json - agentmemory plugin cache at
0.9.18, installed by Codex - 9 hook events wired up manually in
~/.claude/settings.jsonwith absolute Windows paths
Activity
jonathanzhan1975 commentedon May 19, 2026
Bumping with fresh data — hit the same break today on 0.9.18 → 0.9.20.
Quantified impact: all 9 hook events (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PreCompact, SubagentStop, Notification, Stop, SessionEnd) silently dead between the version bump and the moment I happened to audit
~/.claude/settings.jsonby hand.memory_diagnosereturned all-green the whole time; MCP toolsmemory_save/memory_recallworked perfectly. The break was completely invisible from the diagnostic surface.Repro & verification:
Detection signal worth exposing: a
memory_diagnose --include-hook-pathscheck that resolves eachhooks.*.commandviaTest-Path(or equivalent on POSIX) would catch this in < 1 second and could slot into the existing health output as a "hook-paths" category. That's a strictly additive change todiagnose— happy to PR it as a lightweight complement to the bigger Option 3 (agentmemory print-claude-hooks/--install).For Option 3 itself — is that direction still on the table? If yes I can put together a PR. Currently have 4 open agentmemory PRs in flight (#517 IME, #528 lifecycle, #529 viewer, #538 graph backfill) so this would slot in naturally.
Environment matches the original report: Windows 11, Codex plugin path, manual settings.json wiring.
fix(claude-code): --with-hooks for MCP-standalone users (closes rohit…
fix(claude-code): --with-hooks for MCP-standalone users (closes rohit…