How-To Guide
How to Back Up and Restore Hermes Agent
Back up and restore Hermes Agent memory, profiles, sessions, skills, cron jobs, config, and credentials with the current Hermes CLI.
Quick answer
Use hermes backup for a full portable zip and hermes import <archive> to restore it. A zip on disk is not proof of success: check the backup exit code, protect credentials, and rehearse a restore away from production. Quick snapshots are local recovery points, not full migration archives. Stop writers before an import; it overwrites matching files rather than merging newer conversations.
A reliable Hermes backup must be complete, recoverable and stored outside the failure domain of the running agent. The current CLI can snapshot live SQLite databases safely, but an incomplete zip still needs investigation and a restore can replace newer work. This guide separates full archives, quick snapshots and profile exports, then defines the checks to perform before trusting a copy. If maintaining storage and recovery is the objection, compare self-hosting responsibilities with the managed FlyHermes route. This site promotes FlyHermes; managed hosting is not evidence of a particular backup retention or recovery-time guarantee.
$49/mo or $39/mo billed yearly · AI included · 14‑day guarantee
Before you start:
- ☑A current Hermes Agent install; verify with
hermes --versionandhermes doctor - ☑Enough encrypted local or off-site storage for the full Hermes home
- ☑The correct active profile confirmed with
hermes config path - ☑A maintenance window before restoring an always-on gateway
Steps
- 1
Find the active Hermes home and profile
Run
hermes config pathandhermes config env-pathbefore copying anything. The default profile normally uses~/.hermes/; named profiles live below~/.hermes/profiles/<name>/. Read the Hermes profiles guide if you operate more than one bot or environment. - 2
Create a full backup, then encrypt it separately
Run
mkdir -p ~/Backups && hermes backup -o ~/Backups/hermes-backup-$(date +%Y%m%d-%H%M%S).zip --keep 7. The zip contains sensitive state and is not encrypted by this command. Use an encrypted storage destination or encrypt the archive before off-site transfer, restrict access, and never commit it to Git. Unlike the old customhermes-YYYY-MM-DD.zipfilename, thehermes-backup-*.zippattern participates in built-in retention:--keep 7keeps the newest seven matching archives in that directory;--keep 0disables pruning. Count remote copies separately. - 3
Check completion before rotating a good copy
Read the command exit status immediately. For the documented full-backup interface,
0means every selected file was archived,1means an incomplete backup, and2means another backup is running. A partial zip is not a verified recovery point. Read skipped-file warnings and retain the last complete copy; pruning is skipped after an incomplete backup. Do not hide failure behind a later successful upload command. The official CLI backup reference documents these statuses. - 4
Export named profiles for portable, credential-free moves
Run
hermes profile export work -o work-profile.tar.gz, then restore withhermes profile import work-profile.tar.gz --name work-restored. Profile exports intentionally omit.envandauth.json, so re-add secrets through the restored profile’shermes -p work-restored config env-path. This is safer for migration than sharing a full home backup. - 5
Export session history separately when you need it
Run
hermes sessions export sessions-backup.jsonl --redactfor a machine-readable archive, orhermes sessions export --format md --newer-than 30d --redactfor human-readable files. Session exports are useful for audits and archives; durable preferences still belong in Hermes memory, not in every transcript. - 6
Take a full backup before updating production Hermes
Use
hermes update --backupon production gateways or important team profiles. To make full pre-update backups automatic, setupdates.pre_update_backup: fullin config;quickis the lightweight default andoffdisables the snapshot. The--backupflag adds a fullHERMES_HOMEzip before the pull. - 7
Test the archive in an isolated Hermes home
Use a disposable machine or VM with no production credentials, bot connections or mounted state for the full restore rehearsal. Merely setting
HERMES_HOMEis not a complete sandbox: current backup source supports_external/memory-provider entries restored relative to the OS user home. For a reviewed archive without external entries, create a fresh private directory withdrill_dir="$(mktemp -d)"; then, in that disposable environment, runHERMES_HOME="$drill_dir" hermes import /path/to/hermes-backup.zipandHERMES_HOME="$drill_dir" hermes doctor. Do not start a restored gateway during the drill: copied bot credentials could connect to production channels. Keep the drill directory private and remove it through your normal secure cleanup process only after review. - 8
Restore production state and prove the runtime
Confirm the target profile, stop the gateway and quit Desktop/dashboard processes that hold its state, then preserve the current home as a rollback copy before
hermes import /path/to/hermes-backup.zip. Import overwrites matching files;--forceonly removes the existing-installation prompt and is not a safety or merge option. Check its exit status and skipped-file warnings, runhermes doctor, then restart the intended gateway and prove one harmless reply on the real Telegram surface. An older archive can replace newer session history; an older-session warning is not itself a failed import. - 9
Automate backups without leaking secrets
For any existing backup automation, require explicit failure propagation, an encrypted off-machine destination, a retention policy and a separate restore-verification result. A file-upload success is not a backup-completion result. Keep only sanitized state in Git, never
.env,auth.json, browser cookies or raw transcripts. Document the same recovery contract when deploying Hermes on a VPS; no scheduling change is required to follow this guide. - 10
Test recall after restoring memory
After restoring the intended profile, follow the memory setup and provider guide, run
hermes memory status, start a genuinely fresh session and test one known saved fact. Inspect the matching memory file and tool receipt; file presence alone does not prove the active profile or external-provider namespace. Provider-local files, hosted-provider data and external databases need their own coverage check: do not assume every provider is covered or excluded. - 11
Preserve SQLite sidecars before session recovery
When session storage is failing, do not copy over a live
state.dbor deletestate.db-wal/state.db-shm. Close writers, preserve the database together with its sidecars, then use the session-storage recovery workflow andhermes sessions recover --inspect-onlybefore creating a separate recovered database.
Pro Tips
- 💡Use
hermes backup --quickfor critical-state local recovery and a fullhermes backupfor a portable archive with skills and sessions. Do not assume a quick snapshot migrates the entire install. Restore quick snapshots through the in-session/snapshotinterface, not an inventedhermes snapshotshell command. - 💡A full backup can contain
.env,auth.json, andstate.db. Encrypt it at rest and restrict file permissions. - 💡Use
hermes profile exportwhen moving a named profile without credentials; re-add secrets after import. - 💡Use
hermes sessions export ... --redactfor shareable transcript archives instead of copying raw session state. - 💡For Docker, back up the persistent
/opt/datavolume or the host directory mounted there; rebuilding the image does not restore state. - 💡Keep at least one restore-tested copy outside the machine that runs your gateway.
- 💡Before session repair, capture
hermes sessions statsand runhermes sessions repair --check-only; take a full backup before any command that mutates the store. - 💡Full backups deliberately omit browser login profiles, runtime downloads, SQLite sidecars and prior backup trees, but keep documented durable media/citation cache directories. Plan to reinstall runtime dependencies and reconnect browser sessions; a missing browser profile is not evidence that the backup failed.
- 💡Sources checked November 13, 2026: official backup/import CLI reference and current upstream backup implementation. Rolling docs/source may be newer than your install; check
hermes --versionand local help. This is source-verified guidance, not a claim that we restored your deployment.
Troubleshooting
❌ `hermes memory export` or `hermes memory import` is not recognized
✅ Those commands are not the current backup interface. Use hermes backup and hermes import for full state, hermes profile export/import for portable named profiles, and hermes sessions export for conversation archives.
❌ The backup is huge or appears stuck on hundreds of thousands of files
✅ Update Hermes and use the built-in hermes backup command. Current backup logic excludes the source checkout, virtual environments, node_modules, caches, checkpoints, and prior backups instead of recursively archiving regeneratable dependencies.
❌ The restored gateway starts but Telegram or Discord does not reply
✅ Run hermes doctor, verify the restored profile and secret paths, inspect hermes gateway status, then test the provider from the CLI before testing the channel. Machine-specific runtime files and stale PIDs are intentionally not restored.
❌ The profile import has no API keys or bot tokens
✅ That is expected: profile archives omit .env and auth.json. Add secrets to the imported profile through hermes -p <name> config env-path, then run a small provider and gateway smoke test.
❌ Recent conversations are missing after restore
✅ Confirm the backup was created after those sessions and that you restored the same HERMES_HOME and profile. Use hermes sessions list and a separate hermes sessions export archive to verify conversation coverage.
❌ A Docker rebuild starts with empty memory and no cron jobs
✅ The container image is disposable. Restore the persistent /opt/data volume or the exact host bind mount used for Hermes state, then run hermes doctor inside the container and test the gateway.
❌ The session picker looks empty but the database may still contain messages
✅ Run hermes sessions stats and hermes sessions repair --check-only. A scoped picker or excluded active session can look empty even when the database is healthy; back up before real repair.
❌ A zip exists but the backup exited nonzero
✅ Treat it as incomplete until the warning is resolved. Keep the last known-good off-machine copy; do not rotate it away merely because an upload succeeded. Status 2 indicates a concurrent backup rather than a complete new recovery point.
❌ A restore overwrote newer conversations
✅ Import is replacement, not a transcript merge. Preserve the current home before import and compare the archive date and session coverage. An older-backup warning can accompany exit 0; recover later work from a newer preserved copy, not by repeating the same old import.
❌ The restore drill could touch external memory-provider files
✅ Use a disposable VM or machine with no mounted production state. Current source can restore provider-declared _external/ entries relative to the user home, so HERMES_HOME alone is not a containment boundary. Inspect archive members without exposing their contents; validate provider data coverage separately.
FAQ
What does `hermes backup` include?
A full backup preserves the Hermes home: config, credentials, memory, skills, sessions, cron state, pairing data, and other durable files. It excludes the Hermes source checkout, virtual environments, caches, checkpoints, old backups, and machine-specific PID files.
Does a Hermes backup contain API keys and OAuth tokens?
A full home backup can include .env and auth.json, so encrypt it and do not commit it to Git. Named-profile exports omit those credential files by design.
How do I restore Hermes Agent?
Stop the gateway and close other state-holding surfaces, preserve a rollback copy, then run hermes import <backup.zip>. Matching files are overwritten; --force only skips confirmation. Check the exit code and warnings, inspect the intended profile with hermes doctor, and prove a real channel reply only after the production restore is accepted.
How do I back up one Hermes profile?
Run hermes profile export <name> -o <name>.tar.gz. Restore it with hermes profile import <archive> --name <new-name>, then add provider and bot secrets to the imported profile because credentials are intentionally omitted.
How do I back up Hermes sessions?
Run hermes sessions export sessions-backup.jsonl --redact for machine-readable JSONL, or use --format md for a human-readable archive. Full home backups also preserve the session database.
Should I copy `~/.hermes` while Hermes is running?
Prefer hermes backup. It creates consistent SQLite snapshots and excludes transient WAL, cache, dependency, and PID files that make a raw recursive copy unreliable or unnecessarily large.
How do I back up Hermes before an update?
Run hermes update --backup. For important installs, set updates.pre_update_backup: full and updates.backup_keep: 5 so full pre-update backups are retained automatically; the default mode is quick.
Does FlyHermes require me to manage these backups?
FlyHermes is the managed cloud route for users who do not want to own VPS storage, gateway uptime, routine updates, and restore operations. Self-hosting gives more direct control but keeps those responsibilities with you.
Is a Hermes backup zip already encrypted?
No. The backup command creates a zip archive, not an encryption layer. Full archives can contain provider credentials and conversations; use restricted permissions, encrypted storage and encrypted off-site transfer.
Is HERMES_HOME enough to isolate a restore drill?
Not for every archive. Current backup source supports external memory-provider state under _external/, restored relative to the OS user home. Use a disposable machine or VM with no production mounts or connected bot credentials and inspect provider coverage before import.
Related setup and cost guides
Hermes Agent profiles
Confirm which isolated config, memory, skills, sessions, and secrets you are backing up.
Persistent memory
Understand durable memory versus the separate session-history store.
Hermes Docker setup
Identify the `/opt/data` volume that must survive image replacement.
Hermes VPS deployment
Plan storage, permissions, remote backups, and gateway recovery on a server.
Reliable Hermes cron jobs
Automate backups with explicit status, retries, and delivery verification.