/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).