✦
Hermes Agent
Open navigation menu

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

Run hermes backup -o ~/Backups/hermes-$(date +%F).zip for a full Hermes home backup and restore it with hermes import <archive>. Use hermes profile export/import for credential-free named-profile moves and hermes sessions export ... --redact for transcript archives. Encrypt full backups because they can contain .env, OAuth credentials, and session data, then prove the archive by importing it into a separate HERMES_HOME before you need it.

A reliable Hermes backup is more than a copy of memory files. It must preserve the active profile’s config, skills, sessions, cron jobs, pairing state, and any credentials required to reconnect providers and gateways. The current CLI already has purpose-built hermes backup, hermes import, profile export/import, and session export commands. Use those instead of copying a live SQLite database or relying on obsolete hermes memory export examples. If maintaining encrypted backups, restore drills, VPS storage, and gateway recovery is work you do not want, compare the managed FlyHermes path with self-hosting Hermes.

Deploy Hermes faster with FlyHermes

Managed cloud · API costs included · Skill library · Cancel anytime

Before you start:

  • ☑A current Hermes Agent install; verify with hermes --version and hermes 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. 1

    Find the active Hermes home and profile

    Run hermes config path and hermes config env-path before 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. 2

    Create a full encrypted off-site backup

    Run mkdir -p ~/Backups && hermes backup -o ~/Backups/hermes-$(date +%F).zip. The archive includes configuration, skills, sessions, cron state, memory, and credentials while excluding the Hermes source checkout and regeneratable caches. Because .env and auth.json can be included, treat the zip like a password vault: encrypt the destination and never commit it to Git.

  3. 3

    Export named profiles for portable, credential-free moves

    Run hermes profile export work -o work-profile.tar.gz, then restore with hermes profile import work-profile.tar.gz --name work-restored. Profile exports intentionally omit .env and auth.json, so re-add secrets through the restored profile’s hermes -p work-restored config env-path. This is safer for migration than sharing a full home backup.

  4. 4

    Export session history separately when you need it

    Run hermes sessions export sessions-backup.jsonl --redact for a machine-readable archive, or hermes sessions export --format md --newer-than 30d --redact for human-readable files. Session exports are useful for audits and archives; durable preferences still belong in Hermes memory, not in every transcript.

  5. 5

    Take a full backup before updating production Hermes

    Use hermes update --backup on production gateways or important team profiles. To make full pre-update backups automatic, set updates.pre_update_backup: full in config; quick is the lightweight default and off disables the snapshot. The --backup flag adds a full HERMES_HOME zip before the pull.

  6. 6

    Test the archive in an isolated Hermes home

    Before trusting the backup, run rm -rf /tmp/hermes-restore-test && mkdir -p /tmp/hermes-restore-test && HERMES_HOME=/tmp/hermes-restore-test hermes import ~/Backups/hermes-YYYY-MM-DD.zip --force, then inspect it with HERMES_HOME=/tmp/hermes-restore-test hermes doctor. A backup is not verified until a separate directory can read it.

  7. 7

    Restore production state and prove the runtime

    Stop the gateway, preserve the current home as a rollback copy, run hermes import /path/to/hermes-backup.zip, then run hermes doctor. Restart with hermes gateway start and test the real Telegram, Discord, or other delivery surface. A connected process is not enough; prove one end-to-end reply.

  8. 8

    Automate backups without leaking secrets

    Schedule a local script that writes hermes backup archives to an encrypted destination, prunes old copies, and exits non-zero if creation or restore verification fails. Monitor the job through Hermes cron scheduling. For Git-based state backups, version only sanitized memory, skills, cron definitions, and config—never .env, auth.json, browser cookies, or raw transcripts.

Pro Tips

  • 💡Use hermes backup --quick for a fast critical-state snapshot; use a full hermes backup for disaster recovery.
  • 💡A full backup can contain .env, auth.json, and state.db. Encrypt it at rest and restrict file permissions.
  • 💡Use hermes profile export when moving a named profile without credentials; re-add secrets after import.
  • 💡Use hermes sessions export ... --redact for shareable transcript archives instead of copying raw session state.
  • 💡For Docker, back up the persistent /opt/data volume 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 stats and run hermes sessions repair --check-only; take a full backup before any command that mutates the store.

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.

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, keep a rollback copy of the current home, run hermes import <backup.zip>, then run hermes doctor, restart the gateway, and prove one real channel reply.

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.

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.

Related Guides

fix hermes desktop after updatehermes agent profiles guidepersistent memoryset up hermes memoryupdate hermes agent