Skip to content

Hooks break on every version bump when agentmemory is wired into Claude Code outside the plugin loader #508

Closed

Description

@jonathanzhan1975

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

  1. Install agentmemory's MCP server globally in Claude Code (e.g. add to ~/.claude.json's mcpServers).

  2. Install agentmemory as a Codex plugin — scripts land at ~/.codex/plugins/cache/agentmemory/agentmemory/<VERSION>/scripts/*.mjs.

  3. Claude Code does not see agentmemory as a Claude plugin, so ${CLAUDE_PLUGIN_ROOT} from hooks/hooks.json is never resolved. To get auto-capture working, the user has to copy the hooks config into ~/.claude/settings.json with absolute paths, like:

    "SessionStart": [{ "hooks": [{ "type": "command",
      "command": "node C:/Users/Me/.codex/plugins/cache/agentmemory/agentmemory/0.9.18/scripts/session-start.mjs"
    }]}]
  4. On the next agentmemory release (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 when memory_sessions shows 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, so memory_diagnose returns 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)

  1. First-class Claude Code plugin distribution. The package already ships .claude-plugin/plugin.json — publish/list agentmemory in a Claude Code marketplace (or document claude plugin add against the npm tarball) so ${CLAUDE_PLUGIN_ROOT} is set by the harness and the version-pinned path stops being the user's problem.

  2. Stable current symlink/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.

  3. CLI helper that emits the hooks block. Add a subcommand like agentmemory print-claude-hooks that resolves the install path at runtime and prints the JSON ready to paste (or --install to merge it into ~/.claude/settings.json directly). Users re-run it after upgrades; the script can also detect version drift.

  4. 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.mjs script 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/mcp in ~/.claude.json
  • agentmemory plugin cache at 0.9.18, installed by Codex
  • 9 hook events wired up manually in ~/.claude/settings.json with absolute Windows paths

Activity

  1. jonathanzhan1975 commented on May 19, 2026

    @jonathanzhan1975
    ContributorAuthor

    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.json by hand. memory_diagnose returned all-green the whole time; MCP tools memory_save/memory_recall worked perfectly. The break was completely invisible from the diagnostic surface.

    Repro & verification:

    # Before fix
    Select-String -Path ~/.claude/settings.json -Pattern "0\.9\.18" | Measure-Object | % Count   # → 9
    Get-ChildItem ~/.codex/plugins/cache/agentmemory/agentmemory/                                # → only 0.9.20
    node ~/.codex/plugins/cache/agentmemory/agentmemory/0.9.18/scripts/session-start.mjs <<<'{}'  # → Cannot find module
    
    # After sed 0.9.18 → 0.9.20 (9 occurrences in settings.json)
    node ~/.codex/plugins/cache/agentmemory/agentmemory/0.9.20/scripts/session-start.mjs <<<'{}'  # → exit 0
    # Restart Claude Code → next SessionEnd fires `compressmem::summarize` with observationCount: 140
    # (vs 0 throughout the broken window)

    Detection signal worth exposing: a memory_diagnose --include-hook-paths check that resolves each hooks.*.command via Test-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 to diagnose — 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.

  2. added a commit that references this issue on May 22, 2026
    160f9c8
  3. added a commit that references this issue on Jul 27, 2026
    ef1d2fb
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions