memeri

Telemetry — Troubleshooting

Status: ✅ Current · Last reviewed: 2026-06-18

If your symptom isn't listed here, the Connect page Health panel surfaces live diagnostics with one-click remediation buttons.

"My local actions don't show up in the timeline"

Quick check: open the Connect page. The Telemetry Health panel will tell you which path is broken.

Likely causes (in order of frequency)

  1. You're working in an unwired folder and don't have user-level Memeri config.

    • Symptom: Connect page shows Hook = never, MCP = healthy. Agent card appears but timeline is empty for local actions.
    • Fix: set up user-level config — see Telemetry — Default-On & Opt-Out, or run /memeri:init from the Claude Code window.

  2. The folder has a .claude/memeri-disabled marker.

    • Symptom: same as above, but you set this up at some point and forgot.
    • Fix: rm .claude/memeri-disabled in that folder.

  3. Hook script was clobbered in ~/.claude/settings.json.

    • Symptom: Hook was healthy yesterday, now broken or stale while MCP is still healthy. Connect page shows the hook_silent_with_active_mcp warning.
    • Fix: reinstall the hook config block. The Connect page's Telemetry Health panel has a copy-paste snippet, or run the plugin's reinstall script.

  4. jq not installed on your system.

    • Symptom: hook fires but silently fails because it can't parse JSON.
    • Fix: brew install jq / apt install jq / sudo apt-get install jq depending on your OS.

  5. Auth token expired or wrong.

    • Symptom: hook returns 401 silently and the gateway logs auth failures (you won't see this unless you check gateway logs).
    • Fix: rotate your token from Connect → Settings → Generate API token. Update ~/.claude/memeri.json with the new value.

"My agent name keeps changing"

Each Claude Code window's name is derived from a stable per-window UUID written by the reconnect proxy. If the name flips mid-session, the underlying instance_id is changing — not normal.

Likely causes

  1. Stale proxy files in /tmp.

    • The hook reads /tmp/memeri-proxy-instance-${PPID} first, falls back to -latest. If multiple Claude Code windows are running and PPID resolution lands on an older proxy's file, you get the previous window's name.
    • Fix: rm /tmp/memeri-proxy-instance-* (don't worry — running proxies will rewrite their own files).

  2. Multiple mcp-reconnect-proxy.js processes from old sessions still running.

    • Fix: pgrep -af mcp-reconnect-proxy.js to list them; pkill -f mcp-reconnect-proxy.js to clean up if your active session can be safely restarted.

  3. You're seeing two distinct agent cards, not one card flipping.

    • That's the next section.

"I have two agent cards for the same Claude Code window"

This is an instance_id mismatch. The MCP path and the local-tool path are stamping events with different identity keys.

Common cause: settings clobbered after a Claude Code update

If a Claude Code update overwrote your hook config, the local hook may be reading a stale proxy file from a previous proxy. Meanwhile, MCP reconnects with a new proxy + new UUID. Two agents.

Fix: Run /mcp to force a clean reconnect. If still split:

  1. rm /tmp/memeri-proxy-instance-*
  2. Close all Claude Code windows
  3. Reopen → only one window — confirm one agent card appears
  4. If the split persists, open the Connect page; the Health panel will show multiple_agents_same_type if it detects the issue.

Historical events stay tagged

Even after the fix, events written before are still tagged to the previous identity. Those decay off the recent Project timeline window. Don't worry about cleaning them up.

"Hook installed but events stopped coming after a Claude Code update"

Claude Code occasionally updates ~/.claude/settings.json and may clobber third-party hooks. The Memeri hook is at PostToolUse and gets removed in this case.

Symptom: Connect page shows hook_silent_with_active_mcp warning. Hook = broken, MCP = healthy.

Fix:

  1. Open ~/.claude/settings.json.
  2. Verify there's a hooks.PostToolUse block pointing at memeri-telemetry.sh (path varies by install method).
  3. If missing, reinstall: the Connect page has a copy-paste config block under "Show setup commands."
  4. Restart any open Claude Code windows.

What does each warning on the Connect page mean?

The Telemetry Health panel surfaces structured warning codes. Here's what each means and the remediation:

hook_silent_with_active_mcp

Meaning: The local-tool hook hasn't sent anything in 24h+, but MCP is healthy. Most likely cause: settings drift (hook was clobbered, jq removed, token expired).

Fix: verify ~/.claude/settings.json still has the hook block; reinstall if not.

mcp_silent_with_active_hook

Meaning: Local activity is being captured, but MCP gateway calls aren't going through. Either the gateway is down or your Claude Code MCP server isn't connected.

Fix: run /mcp to reconnect. Check gateway URL is reachable.

claude_code_hook_never

Meaning: A Claude Code agent is connected via MCP but has never sent local-tool telemetry. This is normal for the very first session before any Bash/Edit fires; it's a problem if you've been working a while.

Fix: verify your gating: open the Connect page Health panel, check user-level config is in place. Run /memeri:init --user if not.

multiple_agents_same_type

Meaning: More than one Claude Code agent has been active in the last hour. Could be legitimate (you have 3 windows open), or an instance_id drift (one window producing multiple agents).

Fix: if you have 3 windows, ignore. If you only have 1, follow "I have two agent cards for the same window" above.

"Nothing works — start over"

Hard reset:

# Remove all proxy state
rm -f /tmp/memeri-proxy-instance-*
rm -rf /tmp/memeri-edits

# Optionally remove user-level config (you'll need to recreate it)
# rm ~/.claude/memeri.json

# Close all Claude Code windows

Then:

  1. Recreate ~/.claude/memeri.json with your token (see Default-On & Opt-Out → Set up user-level enable).
  2. Open one Claude Code window.
  3. Open the Memeri Connect page — verify Hook + MCP both show healthy within 30s.

Still stuck?

  • The Connect page is the live diagnostic surface. Anything Memeri knows about your telemetry health is there.
  • Check the gateway logs (Railway dashboard) if you have access.
  • Open an issue with the output of curl -H "Authorization: Bearer <your-token>" {{PLATFORM_URL}}/api/v2/diagnostics/me | jq . — that's the full server-side picture.