/diagnose

name: diagnose
description: "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. See also: `memory-health` for the data-quality dashboard once connectivity is confirmed."
effort-level: low

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-memory` entry exists under `mcpServers`
• The `command` field points to a real Python binary
• The `args` include `--project-dir` matching 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 Codex

**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 Codex could handshake, or Codex 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_at` and 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 --f