zaxy: Skill for Claude Code

Store doctor — Zaxy memory incident response

Prime directive: .eventloom/*.jsonl is the hash-chained source of truth — never edit or delete it. Everything under .eventloom/projections/ is a rebuildable projection: the fix is almost always move aside + rebuild, and "move aside" is reversible, so it never needs permission-level caution.

Second directive: never open a suspect store in your main process. A corrupt store can hang ~2 minutes and then segfault whatever opened it. All probes below run in timeout-wrapped subprocesses.

1. Triage — gather without touching

cd <workspace>
grep -E '^EVENTLOOM_PATH|^PROJECTION_BACKEND' .env 2>/dev/null
ls -la .eventloom/ && ls -la .eventloom/projections/
pgrep -af "zaxy serve"

For each serve PID, establish ownership before judging it:

tr '\0' '\n' < /proc/<PID>/environ | grep EVENTLOOM_PATH

Only PIDs bound to THIS store are suspects. Never kill serve processes belonging to other workspaces.

2. Read the signature

Observation	Diagnosis
Multiple serve PIDs, same EVENTLOOM_PATH	Orphaned multi-owner (writers corrupt the WAL)
Tiny embedded.kuzu (KBs) + large .kuzu.wal (100KB+)	Orphan-WAL corruption; open throws RuntimeError ... wal_record.cpp ... UNREACHABLE_CODE
Huge embedded.kuzu (100s of MB) vs small JSONL logs + tiny clean WAL	Bloat variant — open hangs ~2min then segfaults; bypasses the self-heal (native crash, no Python exception)
Checkout "hangs" / MCP disconnects repeatedly	Either of the above; do steps 3-4 before theorizing
Checkout works but returns only hook.stop/reminder noise	Not corruption — capture gap; go to step 7

Sanity anchor: a healthy projection for ~500KB of JSONL is ~tens of KB.

3. Rule out the library (30s, subprocess)

timeout 30 python - <<'PY'
import tempfile, os, faulthandler; faulthandler.enable()
import ladybug
d = tempfile.mkdtemp()
db = ladybug.Database(os.path.join(d, "fresh.kuzu"))
conn = ladybug.Connection(db)
conn.execute("CREATE NODE TABLE T(id INT64, PRIMARY KEY(id))")
print("FRESH DB OK — ladybug native is healthy; the problem is the store file")
PY

Fresh DB fails too ⇒ broken native install (reinstall zaxy-memory / ladybug), stop here. Fresh DB fine ⇒ the store is the patient.