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 install location:

# Check only (exit 0 = ok, 2 = corrupt)
npx neotoma storage recover-db
npx neotoma storage recover-db --env production

# Write recovered copy (does not replace live DB)
npx neotoma storage recover-db --env production --recover

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 store_structured using normal schemas.
• Prefer NEOTOMA_DATA_DIR outside iCloud-synced folders 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.