Recover Neotoma SQLite Database

When to use

Neotoma errors such as database disk image is malformed, failed PRAGMA integrity_check, or btreeInitPage / SQLITE_CORRUPT on the local SQLite file (neotoma.db or neotoma.prod.db under NEOTOMA_DATA_DIR).

Preconditions

• sqlite3 CLI on PATH (macOS usually has it).
• Stop Neotoma (MCP stdio processes, neotoma api, anything using the DB) before --recover or before swapping files.

Script (primary)

From the Neotoma repo root:

# Check only (exit 0 = ok, 2 = corrupt)
node scripts/recover_sqlite_database.js
node scripts/recover_sqlite_database.js --env production

# Write recovered copy (does not replace live DB)
node scripts/recover_sqlite_database.js --env production --recover

Or: npm run recover:db and npm run recover:db:prod -- --recover (see package.json).

Output is a sibling file like neotoma.prod.recovered-<timestamp>.db. Verify it reports PRAGMA integrity_check: ok, then manually archive the live .db/-wal/-shm and cp the recovered file to the live name.

After swap

• Inspect lost_and_found in the recovered file if present; re-ingest important rows via POST /store / MCP store using normal schemas (see prior recovery notes: note, issue, etc.).
• Prefer NEOTOMA_DATA_DIR outside iCloud-synced folders (e.g. not only under ~/Documents if Documents syncs) to reduce recurrence.

Do not

• Run --recover while Neotoma still holds the database open.
• Auto-delete the corrupt file until a good recovered copy is verified and backed up.