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