How to back up Hermes Agent safely
A practical guide to protecting ~/.hermes with consistent snapshots, client-side encryption, offsite storage, retention, and restore tests.
Hermes Agent becomes more valuable as it accumulates memory, skills, sessions, profiles, and scheduled work. Most of that state lives under ~/.hermes. A laptop failure can therefore erase more than an application install: it can erase the history that made the agent useful to you.
A safe backup plan has five parts: a consistent snapshot, encryption before upload, storage away from the original machine, a retention policy you understand, and a restore test. Missing any one of those parts leaves a gap.
1. Start with a consistent Hermes snapshot
Do not copy a live SQLite database with a generic file copier and assume it is recoverable. Hermes includes a native backup command that knows how to capture its state safely. A quick snapshot is useful for frequent recovery points; a full backup captures the broader installation state.
hermes backup --quick -o hermes-quick.zip
hermes backup -o hermes-full.zipOn one measured multi-profile installation, a full archive was about 303 MB after compression, while quick snapshots averaged about 104 MB. Your installation may be smaller or larger depending on session history, profiles, and local assets.
2. Encrypt before the archive leaves the machine
Hermes state may contain conversations, user preferences, configuration, and credentials. Transport encryption alone is not enough because the storage provider would still receive plaintext. Encrypt the finished archive locally with a key controlled by you.
HermesBackup uses age with an X25519 key pair. The public recipient can encrypt unattended nightly backups. The private identity decrypts restores and never needs to reach the server. This separation is useful for automation: the scheduled backup path can create encrypted archives without holding a secret capable of decrypting old ones.
Save the recovery key away from the computer being protected. If the machine and the only copy of the key fail together, zero-knowledge storage cannot recover the backup.
3. Send ciphertext offsite
A second copy on the same SSD protects against accidental edits, but not disk failure, theft, fire, or a destructive operating-system event. Offsite means the backup lands in a separate failure domain.
HermesBackup uploads encrypted blobs directly to private Cloudflare R2 storage through short-lived presigned URLs. Backup bytes do not stream through the application Worker. The service records operational metadata such as ciphertext size, digest, label, and timestamp, but not plaintext or a private key.
4. Choose retention before storage fills
Keeping every backup forever eventually fills any quota. Decide whether a full quota should stop and alert, or whether the client may remove the oldest recovery points. The safer default is to stop loudly because it cannot delete history unexpectedly. Rotation is reasonable when you knowingly prefer continuous recent coverage.
With a measured 303 MB full backup, a 2 GB allowance holds roughly six independent full archives. Quick snapshots at 104 MB fit roughly nineteen times. Mixed schedules and different installations produce different counts, so monitor actual usage instead of relying on estimates.
5. Test the restore path
An upload is not proof of recovery. Periodically download a backup, verify its ciphertext digest, decrypt it in a temporary location, and inspect the archive. The strongest drill uses a clean machine or isolated environment and confirms Hermes starts with the expected memories, skills, sessions, profiles, and configuration.
Write down the restore sequence next to the recovery key. During a real failure, the operator should not need the lost machine to discover the instructions.
Frequently asked questions
What Hermes files should I back up?
Use the native Hermes backup command rather than choosing individual live files. It captures the state needed for recovery while avoiding replaceable runtimes and caches.
Is a local Hermes snapshot enough?
No. A local snapshot helps with software mistakes but shares the computer’s disk, theft, and disaster risks. Keep an encrypted copy offsite.
How often should Hermes Agent be backed up?
A practical starting point is a daily quick backup and a weekly full backup. Adjust the schedule to how quickly your agent changes and how much history you need.
How do I know a Hermes backup works?
Perform a restore drill: download, verify the ciphertext digest, decrypt locally, import on a clean environment, and confirm the agent starts with expected state.