docs / guides

Backups and recovery

The layers that protect your data, the recovery phrase, local snapshots, encrypted archives, plain exports, and how to recover from common mistakes.

botdb keeps several independent copies of your data without extra setup. This page explains each layer and how to recover from common situations.

Layers

Layer	What it protects against	Where
Local copies	Losing a device or a remote	Every device and agent has the full database.
Remotes	Losing all devices (with the recovery phrase)	Encrypted batches and snapshots on each remote.
History	Bad writes, accidental deletes	The change log in each local copy.
Local snapshots	A damaged local copy, mistakes found later	`~/.botdb/backups/<db-id>/`, encrypted.
Cloud backups	Mistakes that already synced everywhere, losing every device’s history	One a day per database on botdb cloud, encrypted.
Archives	Everything above failing	One encrypted file you keep wherever you like.
Trash	Removing the wrong database	Kept for 30 days.

Recovery phrase

The 24-word phrase shown by botdb login is your vault’s master secret. With it and a remote that holds your vault, botdb login --restore brings back every database. Without it, a new machine can’t decrypt anything.

botdb vault phrase     # show the phrase again (asks for confirmation; --yes skips it)
botdb vault verify     # type it back to check the copy you wrote down
botdb vault status     # vault id, key storage, whether the phrase was verified

Warning: Nobody can recover a lost phrase. If you lose the phrase and every device that has your vault, your data is gone. Keep the phrase offline, for example on paper or in a password manager you can reach without this machine.

Automatic local snapshots

As you use botdb, it takes an encrypted snapshot of each database, including the vault catalog, at most once a day. Snapshots run as part of background maintenance after writes, botdb sync, botdb login --restore and the MCP server.

Files: ~/.botdb/backups/<db-id>/<timestamp>.snap (or under BOTDB_HOME).
Encrypted with the database’s own key, and include the full change history.
Retention: the newest snapshot of each of the last 7 days that have one, plus the newest of each of the last 4 ISO weeks.

botdb backup ls                                          # database, time, size, file
botdb backup restore ~/.botdb/backups/3f9a.../20261013T091500123Z.snap

Restoring a .snap file merges it into the existing database with the normal merge rules: it fills in changes and history the current copy is missing, but doesn’t undo newer changes such as deletes. The database must already be on this device (join or restore it first). To roll the data back to an earlier state, use botdb revert.

Cloud backups

botdb cloud keeps a daily encrypted backup of each database, and of your vault catalog. You don’t need to set anything up: once a day, after a sync, one of your devices uploads an encrypted snapshot (the same kind of file as a local snapshot, history included). botdb cloud can’t read it.

One backup per day: the first upload of the day is kept, later ones that day are ignored. A backup never changes once it’s taken.
Retention: the 7 most recent days that have a backup, plus the newest of each of the 4 most recent weeks. Older ones are deleted.
Backups don’t count toward your storage limit. Deleting a database from botdb cloud (botdb trash empty --remote) deletes its backups too.
Devices with read-only access don’t upload backups. Folder remotes don’t keep them, and nor do relays that don’t support them.

botdb backup ls --remote                       # database, day, time, size, remote
botdb backup restore --remote -d movies        # the newest backup
botdb backup restore --remote -d movies --at 3d   # the newest from 3 days ago or earlier

Restoring merges the backup into the database, like a local snapshot: it brings back changes and history this copy lost, but keeps newer changes. To put the data back the way it was when the backup was taken, follow it with the botdb revert command it prints:

botdb revert -d movies --at 2026-10-14T09:12:03.120Z

-d vault restores the vault catalog, which holds your database list and their keys.

Plain exports

To take data out of botdb, or hand it to another tool, export it unencrypted:

botdb export -d movies --type sqlite --out movies.sqlite   # plain SQLite, no sync metadata
botdb export -d movies > movies.json                        # JSON: {"watched": [...], ...}
botdb export -d movies --type csv --table watched --out watched.csv

Recovering from common situations

Situation	What to do
Deleted or overwrote rows	`botdb history <table>` to find when, then `botdb revert --at <time> --table <table>`.
An agent made a mess	`botdb revert --at 30m` restores the whole database as of 30 minutes ago.
History is gone too	`botdb backup restore --remote -d <db> --at <time>`, then the `botdb revert` it prints.
Dropped a table	`botdb revert --at <time>` recreates it with its rows.
Removed a database	`botdb trash ls`, then `botdb trash restore <db>` within 30 days.
New or replacement machine	`botdb login --restore` with your phrase and remote.
Lost every device	`botdb login --restore` on a new machine, then `botdb backup restore <archive>` if your remotes are gone too.
A remote lost its data	Nothing is lost: botdb notices on the next sync and pushes everything again.

Reverts are new changes, not rewrites. They sync to every device, show up in history, and can themselves be reverted.

Times for --at and --since accept 30s, 30m, 2h, 3d, 1w (ago), now, @<unix-ms>, RFC 3339, YYYY-MM-DD and YYYY-MM-DD HH:MM[:SS] (local time).