Migrer Hermes Agent vers une nouvelle machine sans perte

Pourquoi vous n'avez qu'un seul essai pour migrer Hermes

Un Hermes Agent qui tourne, c'est bien plus que le binaire. C'est des mois d'entrées de mémoire, un SOUL.md personnalisé, une petite bibliothèque de skills sur mesure, une table cron avec les digests que vous utilisez vraiment, un index vectoriel ChromaDB que l'agent a construit en silence, et une session Telegram qui sait déjà qui vous êtes. Réinstallez Hermes sur une machine vierge et rien de tout ça ne suit. Vous vous retrouvez avec un inconnu qui partage votre nom d'utilisateur.

C'est ce scénario que ce guide combat. Que votre laptop soit sur le point de rendre l'âme, que vous passiez de Docker sur votre poste à un vrai VPS, que vous montiez de gamme votre instance Hetzner ou que vous cherchiez à restaurer une machine propre après une panne disque, la procédure est la même: capturer tout l'arbre ~/.hermes/ sur l'ancienne machine, le transférer vers la nouvelle, lancer hermes import, puis vérifier. Dans l'ordre, c'est un boulot de quinze minutes. Dans le désordre, soit vous perdez des données, soit vous passez la soirée à ré-authentifier les providers, IMAP et Telegram.

Si vous hésitez encore entre le self-hosting et une configuration managée, lisez d'abord self-hosting contre Hermes Agent managé, parce que Hermify gère les migrations à votre place et ce guide devient inutile. Si vous êtes décidé à faire tourner l'agent vous-même, la suite est pour vous.

Ce que hermes backup empaquette vraiment

La commande hermes backup produit une archive horodatée du type hermes-backup-2026-06-01-101955.zip. Elle capture le contenu de ~/.hermes/, l'endroit où Hermes stocke tout ce qui fait que votre agent est le vôtre. Sur une installation mature, cette arborescence contient:

• La base d'état (state.db et fichiers associés): la source de vérité pour les sessions, l'historique des appels d'outils et les files de tâches.
• Le vector store ChromaDB: l'index de mémoire sémantique que l'agent interroge dès qu'il a besoin de se souvenir. C'est un répertoire de fichiers binaires, pas un simple JSON, et il doit se déplacer d'un bloc.
• SOUL.md, AGENTS.md, USER.md, MEMORY.md: la personnalité, les règles de la maison, le profil utilisateur et la mémoire de long terme en prose. Ce sont de simples fichiers markdown, mais l'agent attend de les trouver à des chemins précis.
• Le répertoire skills/: chaque skill que vous avez écrit ou installé. Une skill n'est qu'un dossier avec un SKILL.md et ses fichiers, mais une skill manquante, c'est une capacité perdue sans un mot.
• Le répertoire identity/: la configuration de la persona, l'avatar et les préréglages du mode voix.
• La table cron: les tâches planifiées vivent dans ~/.hermes/, pas dans le crontab système. Les perdre, c'est votre digest du matin qui s'arrête sans prévenir.
• Les secrets et la config: config.yaml, les clés d'API providers, le token du bot Telegram, les credentials IMAP/SMTP, les secrets de signature webhooks et tout fragment .env chiffré que l'agent a consommé.

Deux flags méritent qu'on s'y arrête. hermes backup --quick saute le scan complet de fichiers et n'inclut que la config, les sessions, les clés et l'auth. C'est plus rapide et plus léger, mais ça n'emporte ni la mémoire ni les skills, donc c'est utile uniquement si vous clonez l'identité de l'agent vers une machine qui reconstruira sa mémoire depuis zéro. Pour une vraie migration, lancez hermes backup sans flag et laissez-lui le temps.

Étape 1 - Figer la source

Avant le backup, faites taire l'agent. Si Hermes écrit dans state.db pendant la création de l'archive, vous risquez de retrouver une base corrompue dans le zip.

# Si Hermes tourne en service systemd
sudo systemctl stop hermes

# Ou s'il tourne via Docker
docker compose stop hermes

# Ou si vous l'avez lancé de façon interactive, sortez proprement avec Ctrl+C dans le shell qui l'exécute

Une fois que plus rien ne tient la base d'état, faites le backup:

hermes backup
# écrit ~/.hermes/backups/hermes-backup-2026-07-18-102301.zip

Notez le chemin complet qu'il affiche. C'est le fichier que vous allez déplacer.

Étape 2 - Déplacer l'archive avec précaution

Le backup contient des secrets. Traitez-le comme une clé SSH.

• Ne le déposez pas sur un lien public, une pièce jointe Discord ou un DM Slack à vous-même.
• Préférez scp ou rsync en SSH, ou un dossier syncthing en qui vous avez déjà confiance.
• Si vous passez par un laptop en relais, supprimez la copie locale dès que le transfert est fini.

Un transfert propre d'un ancien VPS vers un nouveau ressemble à ça:

# Depuis la nouvelle machine
scp ancien-vps:~/.hermes/backups/hermes-backup-2026-07-18-102301.zip ~/

Si vous migrez d'un laptop personnel vers un VPS, faites l'inverse et poussez depuis la source. Dans les deux cas, posez le fichier dans le home de l'utilisateur cible, pas dans /tmp ni dans un chemin partagé.

Étape 3 - Installer Hermes sur la cible

Installez Hermes sur la nouvelle machine comme pour une installation propre. Ça veut dire Linux, macOS, WSL2 sous Windows ou Termux sur téléphone, les cibles officiellement supportées. Suivez le chemin d'installation qui correspond à votre déploiement à long terme, que ce soit Hermes Agent dans Docker, une installation native sous Linux ou Windows via WSL2.

Ne lancez pas encore l'agent. S'il démarre une fois avec un ~/.hermes/ vide, il va écrire un state.db neuf et une config par défaut, qui vont entrer en collision avec l'import à l'étape suivante. Installez le binaire, vérifiez que hermes --version affiche la même version majeure que la machine source, et arrêtez-vous là.

Étape 4 - Importer et réindexer

Avec l'archive en place et le binaire installé mais à l'arrêt:

hermes import ~/hermes-backup-2026-07-18-102301.zip

L'importeur décompresse l'archive dans ~/.hermes/, restaure la base d'état, puis remet en place les skills, la mémoire, les tâches cron, l'identité et les secrets. À la fin, reconstruisez l'index vectoriel pour que la recherche sémantique classe les résultats avec le modèle courant et non avec celui qu'utilisait la machine source:

hermes memory reindex

Si le backup a été pris sur une version de Hermes bien plus ancienne, le payload de mémoire peut utiliser un format legacy. Dans ce cas, extrayez les mémoires séparément avec un export JSON et réimportez-les explicitement:

hermes memory import --legacy ~/memories.json

Le flag --legacy demande à Hermes d'accepter l'ancien schéma et de le migrer à la volée. hermes memory export --output ~/memories.json sur la source est la commande jumelle, utile quand vous ne voulez migrer que la mémoire et reconstruire le reste depuis une installation propre.

Étape 5 - Vérifier avant de faire confiance

Deux commandes gagnent leur place ici:

hermes doctor   # config, dépendances, accessibilité des providers, permissions disque
hermes status   # santé de la gateway, compteur de mémoire, intégrations actives

hermes doctor doit revenir en vert sur la config, la base, ChromaDB et les credentials providers. hermes status doit afficher un compteur d'entrées de mémoire proche de ce que vous aviez sur la source, l'intégration Telegram connectée, et toutes les tâches planifiées longues en file. Si l'un ou l'autre signale un souci, corrigez avant de rallumer la gateway.

Ensuite, lancez l'agent et envoyez depuis Telegram un message qui exige un rappel de mémoire. "Qu'est-ce qu'on avait décidé pour le lancement du Q3 ?" est un bon test. S'il répond avec du contexte, la mémoire a migré. S'il dit qu'il ne sait pas, essayez hermes memory search "lancement Q3" en CLI: la mémoire est peut-être là, mais l'index vectoriel n'a pas encore fini de se reconstruire.

Les pièges que personne ne signale

Même un import propre laisse des angles rugueux. Passez ces points avant de considérer la migration bouclée.

• Les secrets chiffrés ont besoin de leur clé de déchiffrement. Si la machine source utilisait un coffre de secrets chiffré (Hermes supporte pass, gnome-keyring ou un keyfile), l'archive contient le texte chiffré mais pas la clé. Transférez le keyfile séparément ou déverrouillez le coffre sur la nouvelle machine avant le premier lancement de l'agent.
• Les credentials IMAP et SMTP peuvent redemander une auth. Les app passwords liées à l'empreinte d'un appareil refusent parfois de s'authentifier depuis une nouvelle IP. Google Workspace et Fastmail sont les cas classiques. Régénérez l'app password si l'intégration mail reste muette après l'import.
• La session Telegram peut dériver. Le token du bot Telegram est portable, mais si vous utilisiez aussi une session en mode utilisateur pour lire des chats, le fichier de session peut être lié à l'ancien appareil. Supprimez ~/.hermes/telegram/session.session et laissez l'agent se ré-authentifier au prochain démarrage.
• Les jobs cron reprennent au prochain tick prévu, pas immédiatement. Si votre daily-digest était programmé à 07:00 et que vous finissez la migration à 07:05, il ne repartira que demain. Déclenchez-le une fois à la main avec hermes cron run daily-digest pour prouver qu'il fonctionne.
• Rotatez tout ce que l'archive a touché. Même avec un transfert soigneux, une archive contenant tokens de bot et clés provider a existé sur plus de machines que les deux points. Si la migration répondait à une compromission, ou si l'archive est passée par un stockage partagé, régénérez la clé OpenAI/Anthropic/OpenRouter et refaites délivrer le token du bot chez BotFather.

Quand vous ne voulez pas faire tout ça vous-même

Tout le rituel (figer, backup, transférer, installer, importer, réindexer, vérifier, rotater) est ce qu'un hébergement managé fait tout seul. Hermify fait tourner un Hermes Agent managé sur un VPS que nous opérons, prend des sauvegardes chiffrées quotidiennes et propose une restauration en un clic si un VPS doit être remplacé. Dans la journée d'un utilisateur, il n'y a pas d'étape "je déménage sur une nouvelle machine", parce que la machine est notre problème, pas le vôtre.

Si vous préférez ça à relancer cette migration tous les ans ou deux, commencez avec Hermify: votre agent est en ligne sur Telegram en une minute environ, votre mémoire reste la vôtre, et le prochain changement de matériel est invisible pour vous.

Sources

• How to Backup and Restore Hermes Agent Memory - hermes-agent.ai
• How to backup and migrate Hermes Agent server - Tool Navigators
• Hermes Agent backups: state.db, skills, identity - LumaDock
• Backup Hermes Agent - j3ffyang, Medium
• CLI Commands Reference - Hermes Agent official docs