Back Up Hermes State Before Updates and Migrations

Hermes state includes configuration, credentials, sessions, cron jobs, pairing records, skills, plugins, and memory. An application-code rollback does not restore those files. Before an update, migration, or major configuration change, create a restore point that matches the scope of the risk.

Official documentation: https://hermes-agent.nousresearch.com/docs/reference/cli-commands#hermes-backup

Choose quick or full deliberately

hermes backup --quick captures critical state such as configuration, the session database, secret/auth stores, and cron jobs. It is appropriate before routine changes and is the default pre-update safety mode in current releases. Add a label so operators can identify the reason later.

A full backup includes the broader Hermes home and takes longer. Use it before host migration, major profile restructuring, or changes to skills and plugins that are not fully represented in critical state. Hermes uses a consistent SQLite backup and excludes live WAL, shared-memory, and journal sidecars rather than copying a half-committed database view.

Backup checklist

Identify the active HERMES_HOME and profile.
Choose quick or full based on the change scope.
Label the snapshot with a neutral operational reason.
Keep archives outside the directory being replaced.
Protect backups because they may contain credentials and private sessions.
Record version, timestamp, and archive checksum.
List the archive and confirm expected critical files are present.
Test restoration in an isolated location when the change is high risk.

Distinguish backup systems

Filesystem checkpoints protect project edits and power /rollback; they are not Hermes-home backups. Skill-curator snapshots protect managed skill changes; they are not complete agent backups. Cloud-provider snapshots may preserve a remote filesystem but not active processes. Match the restoration tool to the state that was lost.

Common pitfalls

Keeping the only backup inside a directory that will be replaced.
Assuming Git contains credentials, sessions, or pairing state.
Copying a live SQLite database with inconsistent sidecars.
Uploading unencrypted archives to a public or shared location.
Skipping restore tests because archive creation returned success.
Restoring one profile over another without checking scope.

Verification steps

List available backups and identify the new snapshot.
Inspect archive metadata and file count without exposing contents publicly.
Verify the recorded checksum.
Restore into an isolated Hermes home or test profile.
Run hermes doctor, list sessions, and inspect cron/pairing state.
Delete the test restoration securely when validation is complete.