Agent skill
diagnose
Check memory system health and troubleshoot connectivity issues. Use when memory commands aren't working, at session start if something seems wrong, or when user asks about memory status.
Install this agent skill to your Project
npx add-skill https://github.com/kbanc85/claudia/tree/main/template-v2/.claude/skills/diagnose
SKILL.md
Diagnose
System health check for Claudia's memory infrastructure. Run this when:
- Memory commands seem unavailable
- Session context isn't loading
- User asks "is my memory working?"
- Something feels off with persistence
Process
Step 1: Check .mcp.json Configuration
Read the project's .mcp.json file and verify:
- A
claudia-memoryentry exists undermcpServers - The
commandfield points to a real Python binary - The
argsinclude--project-dirmatching the current directory
cat .mcp.json 2>/dev/null || echo "No .mcp.json found"
If .mcp.json is missing or has no claudia-memory entry, the daemon was never configured. Fix:
npx get-claudia .
If the Python binary in the command field doesn't exist:
# Check if venv exists
ls -la ~/.claudia/daemon/venv/bin/python 2>/dev/null || echo "Daemon venv not found"
Step 1b: Check Active MCP Servers
List all active MCP servers (entries without _disabled prefix):
python3 -c "
import json
c = json.load(open('.mcp.json'))
servers = c.get('mcpServers', {})
active = [k for k, v in servers.items() if not k.startswith('_')]
stdio = [k for k in active if servers[k].get('type', 'stdio') == 'stdio']
http = [k for k in active if servers[k].get('type') == 'http']
print(f'Active servers ({len(active)}): {chr(44).join(active)}')
print(f' stdio: {chr(44).join(stdio) or \"none\"}')
print(f' http: {chr(44).join(http) or \"none\"}')
"
Step 2: Run Preflight Check
The daemon has a built-in preflight validator that tests all 11 startup steps:
# Extract the Python path from .mcp.json and run preflight
VENV_PYTHON=$(python3 -c "import json; c=json.load(open('.mcp.json')); print(c.get('mcpServers',{}).get('claudia-memory',{}).get('command',''))" 2>/dev/null)
if [[ -n "$VENV_PYTHON" && -x "$VENV_PYTHON" ]]; then
"$VENV_PYTHON" -m claudia_memory --preflight --project-dir "$PWD"
else
echo "Cannot find daemon Python binary. Re-run: npx get-claudia ."
fi
If the preflight file exists, read it for structured results:
cat ~/.claudia/daemon-preflight.json 2>/dev/null
Step 3: Check Session Manifest
The daemon writes a manifest when it successfully enters the MCP loop:
cat ~/.claudia/daemon-session.json 2>/dev/null || echo "No session manifest (daemon never started)"
If the manifest exists, check whether the process is still alive:
PID=$(python3 -c "import json; print(json.load(open('$HOME/.claudia/daemon-session.json')).get('pid',''))" 2>/dev/null)
if [[ -n "$PID" ]]; then
ps -p "$PID" > /dev/null 2>&1 && echo "Daemon running (PID $PID)" || echo "Daemon died (PID $PID no longer running)"
fi
Step 4: Check Standalone Daemon
curl -s http://localhost:3848/status 2>/dev/null || echo "Standalone daemon not running (this is normal if using MCP-only mode)"
Step 5: Check Database Directly
ls -la ~/.claudia/memory/*.db 2>/dev/null || echo "No database files found"
# If database exists, check record counts
for db_file in ~/.claudia/memory/*.db; do
[[ -f "$db_file" ]] || continue
echo "Database: $db_file"
sqlite3 "$db_file" "SELECT 'memories: ' || COUNT(*) FROM memories; SELECT 'entities: ' || COUNT(*) FROM entities;" 2>/dev/null || echo " Cannot query (may be locked)"
done
Step 6: Check Embedding Model
ollama list 2>/dev/null | grep -E "minilm|nomic|mxbai" || echo "No embedding model found (memory works without it, but vector search is disabled)"
Step 7: Report Results
Format the diagnosis as:
---
**Memory System Diagnosis**
| Component | Status | Details |
|-----------|--------|---------|
| .mcp.json config | ✅/❌ | [daemon entry present/missing] |
| Active MCP servers | ✅/⚠️ | [list of active servers] |
| Daemon Python binary | ✅/❌ | [path exists/missing] |
| Preflight | ✅/❌ | [all passed / N failures] |
| Session manifest | ✅/❌ | [running/died/never started] |
| Standalone daemon | ✅/❌/➖ | [healthy/not running] |
| Database | ✅/❌ | [path, record counts] |
| Embedding model | ✅/❌ | [model name or "not found"] |
**Overall:** [Healthy / Degraded / Not Connected]
[If issues found, show the specific fix from preflight results]
---
Common Issues and Fixes
Issue: "MCP server failed" in Claude Code
Most likely cause: The daemon crashes during startup before reaching the MCP handshake.
Fix: Run the preflight check to see exactly which step fails:
~/.claudia/daemon/venv/bin/python -m claudia_memory --preflight --project-dir "$PWD"
If preflight shows fixable issues, try auto-repair:
~/.claudia/daemon/venv/bin/python -m claudia_memory --repair --project-dir "$PWD"
Issue: Tools not in palette but no error
Cause: Daemon started but exited before Claude Code could handshake, or Claude Code closed stdin too early.
Fix: Check the session manifest:
cat ~/.claudia/daemon-session.json
- If missing: daemon never reached the MCP loop (run preflight)
- If present with
exited_at: daemon started and exited cleanly (check stdin_type, should be "pipe") - If present without
exited_atand PID is dead: daemon crashed after starting
Issue: Preflight shows db_connect FAIL
Cause: Database is locked by another process.
Fix:
# Find processes using the database
lsof ~/.claudia/memory/*.db 2>/dev/null
# Or try auto-repair
~/.claudia/daemon/venv/bin/python -m claudia_memory --repair --project-dir "$PWD"
Issue: Preflight shows schema_load FAIL
Cause: The claudia-memory package is corrupted or incompletely installed.
Fix:
~/.claudia/daemon/venv/bin/pip install --force-reinstall claudia-memory
Or re-run the installer:
npx get-claudia .
Issue: Preflight shows sqlite_vec WARN
Cause: sqlite-vec extension not installed. Memory works without it, but vector search is disabled.
Fix:
~/.claudia/daemon/venv/bin/pip install sqlite-vec
Issue: Daemon venv not found
Cause: Fresh install or venv was deleted.
Fix:
npx get-claudia .
This recreates the venv and installs the daemon.
Issue: Wrong project directory
Cause: .mcp.json has a different --project-dir than expected.
Fix:
Check the args in .mcp.json:
python3 -c "import json; c=json.load(open('.mcp.json')); print(c['mcpServers']['claudia-memory']['args'])"
The --project-dir should match your current working directory. Re-run npx get-claudia . from the correct directory to fix it.
Issue: Python 3.10+ not found
Cause: System Python is too old for the daemon.
Fix: Install Python 3.10+ from python.org, Homebrew (brew install python@3.12), or your package manager.
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
map-connections
Scan context files to extract entities and relationships into the memory system. Triggers on "who knows who?", "network graph", "map my connections", "extract relationships".
inbox-check
Lightweight inbox triage across all configured email accounts. Dispatches fast subagent to fetch, then reviews with judgment. Use when user says "check my inbox", "any new emails?", "check email".
growth-check
Periodic reflection on development, skills, learning, and progress toward goals. Triggers on "am I growing?", "development check", "personal growth review".
feedback
Send feedback, ideas, or bug reports about Claudia. Opens a pre-filled GitHub Discussion with system context. Use when user says "feedback", "suggestion", "report a bug", "feature request", or "I have an idea".
draft-reply
Draft an email response with tone matching the relationship context. Shows draft for approval before sending. Use when user says "draft a reply", "respond to this email", "write a response to [person]", or shares an email and asks for help replying.
brain
Launch the Brain Visualizer, a real-time 3D view of memory and relationships. Triggers on "show your brain", "visualize memory", "open the brain", "memory graph".
Didn't find tool you were looking for?