mem0/mem0-plugin/skills/health/SKILL.md

name, description

name	description
health	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

echo "${MEM0_API_KEY:-${CLAUDE_PLUGIN_OPTION_MEM0_API_KEY:-NOT_SET}}"

• If NOT_SET: FAIL — "No API key configured"
• If set: PASS — show first 6 chars + ... (never print the full key)

Check 2: Identity resolution

Read the active identity from the SessionStart banner or resolve manually:

• user_id: from MEM0_RESOLVED_USER_ID or $USER
• project_id: from MEM0_PROJECT_ID or current directory name
• branch: from MEM0_BRANCH or git rev-parse --abbrev-ref HEAD

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", user_id=<id>, limit=1

• filters={"AND": [{"user_id": "<id>"}, {"app_id": "<project_id>"}]}

• If returns successfully (even empty): PASS

• If errors: FAIL — show the error message

Check 4: Memory write capability

Call add_memory with:

• messages=[{"role": "user", "content": "Health check probe — safe to delete."}]
• user_id=<id>, app_id=<project_id>
• metadata={"type": "health_check", "probe": true}

If it returns a memory ID: PASS — then immediately call delete_memory with that ID to clean up. If it 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 user_id, app_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).