health

name	health
description	Diagnoses mem0 connectivity, API key validity, and memory read/write functionality. Use when memory operations fail, searches return empty, add_memory errors occur, MCP connection drops, or to verify the plugin is working correctly.

Mem0 Health Check

Run a diagnostic check on the mem0 plugin. Useful for troubleshooting.

Execution

Run ALL checks, then display a single summary. Do not stop on the first failure.

Check 1: API key

_KEY="${MEM0_API_KEY:-${CLAUDE_PLUGIN_OPTION_MEM0_API_KEY:-}}"
[ -n "$_KEY" ] && echo "${_KEY:0:6}..." || echo "NOT_SET"

• If NOT_SET: FAIL — "No API key configured"
• If set: PASS — the command already prints only the first 6 chars

Check 2: Identity resolution

Resolve identity using the plugin's own resolver scripts to match what hooks use:

SCRIPT_DIR="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-${CURSOR_PLUGIN_ROOT:-}}}/scripts"
source "$SCRIPT_DIR/_identity.sh" 2>/dev/null
echo "user_id=${MEM0_RESOLVED_USER_ID:-}"
echo "project_id=${MEM0_PROJECT_ID:-}"
echo "branch=${MEM0_BRANCH:-}"

If CLAUDE_PLUGIN_ROOT is not available, fall back to:

• user_id: from MEM0_USER_ID or $USER
• project_id: from MEM0_PROJECT_ID or check ~/.mem0/project_map.json for $PWD
• branch: from git branch --show-current

PASS if all three are non-empty. WARN if any falls back to defaults.

Check 3: MCP server connectivity

Call search_memories with:

• query="health check"

• filters={"AND": [{"user_id": "<active_user_id>"}, {"app_id": "<active_project_id>"}]}

• top_k=1

• If returns successfully (even empty): PASS

• If errors: FAIL — show the error message

Check 4: Memory write capability

Call add_memory with:

• text="Health check probe — safe to delete."
• user_id=<active_user_id>
• app_id=<active_project_id>
• metadata={"type": "health_check", "probe": true}
• infer=False

The response returns event_id (v3 writes are async). Call get_event_status(event_id=<event_id>) to check processing.

• If status is SUCCEEDED: PASS — extract the memory ID from the event result, then call delete_memory with that ID to clean up.
• If status is PENDING after 5 seconds: PASS (write accepted, processing delayed)
• If errors: FAIL — show the error.

Check 5: Session stats tracker

Check if the session stats file exists and is readable:

STATS_FILE="/tmp/mem0_session_stats_${USER}.json"
if [ -f "$STATS_FILE" ] && python3 -c "import json; json.load(open('$STATS_FILE'))" 2>/dev/null; then
  echo "OK"
else
  echo "FAIL"
fi

This file is created by the SessionStart hook and updated by PostToolUse hooks throughout the session. If it doesn't exist, the session hooks may not have fired yet — try sending a message first, then recheck.

Display

## mem0 health

PASS  API Key          m0-dVe...
PASS  Identity         user=kartik, project=mem0, branch=main
PASS  MCP Connection   142ms
PASS  Write/Read       write + delete OK
PASS  Session Tracker  stats file active

All checks passed.

If any check fails, add a ## Troubleshooting section with specific fix steps for each failure.

Extended mode: Memory Quality Analysis

When invoked with --deep (e.g., /mem0:health --deep), run the standard 5 checks above plus a memory quality scan.

Quality Check 1: Duplicates

Call get_memories with filters={"AND": [{"user_id": "<active_user_id>"}, {"app_id": "<active_project_id>"}]}, page_size=200. Compare all pairs within the same metadata.type group for high textual overlap (shared nouns/keywords > 60%). Report:

Potential duplicates: <N> pairs
  [mem0:<id1>] ≈ [mem0:<id2>] — both about "<shared topic>"

Quality Check 2: Stale memories

Flag memories where:

• metadata.type is session_state or compact_summary AND older than 90 days
• metadata.confidence < 0.3 AND older than 30 days

Stale candidates: <N>
  [mem0:<id>] — session_state, 142d old

Quality Check 2b: Low-confidence memories

Flag memories where metadata.confidence < 0.5 (regardless of age). Report separately from stale:

Low-confidence memories: <N>
  [mem0:<id>] — confidence=0.3, "<content preview>"

Quality Check 3: Contradictions

Within each metadata.type group, flag pairs that assert opposing facts about the same topic. Use semantic judgment — look for negation patterns, conflicting tool/framework choices, or reversed decisions.

Possible contradictions: <N>
  [mem0:<idA>] vs [mem0:<idB>] — conflicting on "<topic>"

Quality Check 4: Orphan memories

Memories with no metadata.type set, or with metadata.type not in the 17 known coding categories. These were likely written without proper tagging.

Untagged/orphan memories: <N>

Quality summary

## Memory Quality

Duplicates: <N> · Stale: <N> · Contradictions: <N> · Orphans: <N>

If all counts are 0: Memory quality: clean. If any non-zero: append Run /mem0:dream to fix.

To fix issues found by --deep, run /mem0:dream for automated consolidation (merges, prunes, conflict resolution).