Migra Hermes Agent su una nuova macchina senza perdere dati

Perché con Hermes hai un solo tentativo di migrazione

Un Hermes Agent che funziona è molto più del suo binario. Sono mesi di voci di memoria, un SOUL.md personalizzato, una piccola libreria di skill scritte su misura, una tabella cron con i digest che davvero usi, un indice vettoriale ChromaDB che l'agente ha costruito in silenzio, e una sessione Telegram che sa già chi sei. Reinstallalo su una macchina vuota e nulla di tutto questo lo segue. Ti ritrovi con uno sconosciuto che condivide il tuo username.

È esattamente contro questo scenario che è pensata questa guida. Se il laptop sta per morire, stai passando da Docker sul desktop a un VPS vero, alzi la classe della tua istanza Hetzner, o vuoi un ripristino su macchina pulita dopo un guasto del disco, il processo è lo stesso: cattura tutto l'albero ~/.hermes/ sulla vecchia macchina, spostalo su quella nuova, esegui hermes import, e verifica. Nel giusto ordine è un lavoro da quindici minuti. Nell'ordine sbagliato o perdi dati o passi la serata a ri-autenticare provider, IMAP e Telegram.

Se stai ancora scegliendo fra self-hosting e setup gestito, leggi prima self-hosting vs Hermes Agent gestito, perché Hermify gestisce le migrazioni al posto tuo e questa guida diventa inutile. Se hai deciso di far girare tutto da solo, vai avanti.

Cosa impacchetta davvero hermes backup

Il comando hermes backup produce un archivio con timestamp che assomiglia a hermes-backup-2026-06-01-101955.zip. Cattura il contenuto di ~/.hermes/, cioè dove Hermes tiene tutto ciò che rende il tuo agente tuo. In un'installazione matura quell'albero contiene:

• Il database di stato (state.db e file collegati): la fonte di verità per sessioni, cronologia delle chiamate agli strumenti e code dei job.
• Il vector store di ChromaDB: l'indice di memoria semantica che l'agente interroga ogni volta che deve ricordare qualcosa. È una directory di file binari, non un JSON singolo, e va spostato in blocco.
• SOUL.md, AGENTS.md, USER.md, MEMORY.md: personalità, regole della casa, profilo utente e memoria di lungo periodo in prosa. Sono markdown puro, ma l'agente si aspetta di trovarli a percorsi esatti.
• La directory skills/: ogni skill che hai scritto o installato. Una skill è solo una cartella con un SKILL.md e i suoi file, ma una skill mancante è una capacità persa in silenzio.
• La directory identity/: configurazione della persona, avatar e preset del modo voce.
• La tabella cron: le attività pianificate vivono dentro ~/.hermes/, non nel crontab di sistema. Perderle significa che il digest del mattino smette di arrivare senza dirlo.
• Segreti e config: config.yaml, chiavi API dei provider, token del bot Telegram, credenziali IMAP/SMTP, segreti di firma dei webhook e ogni frammento .env cifrato che l'agente ha consumato.

Due flag contano. hermes backup --quick salta la scansione completa dei file e include solo config, sessioni, chiavi e auth. È più veloce e più leggero, ma non porta con sé memoria o skill, quindi serve solo se stai clonando l'identità dell'agente su una macchina che ricostruirà la memoria da zero. Per una migrazione vera, esegui hermes backup senza flag e lascialo prendersi il tempo necessario.

Passo 1 - Congela la sorgente

Prima del backup, fai tacere l'agente. Se Hermes sta scrivendo attivamente su state.db mentre l'archivio si crea, rischi di ritrovarti un database corrotto dentro lo zip.

# Se fai girare Hermes come servizio systemd
sudo systemctl stop hermes

# O se lo fai girare via Docker
docker compose stop hermes

# O se lo hai lanciato in modo interattivo, esci pulito con Ctrl+C nella shell dove sta girando

Quando nulla tiene più aperto il database di stato, esegui il backup:

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

Annota il percorso completo che stampa. È il file che sposterai.

Passo 2 - Sposta l'archivio con attenzione

Il backup contiene segreti. Trattalo come una chiave SSH.

• Non caricarlo su link pubblici, allegati Discord o DM Slack a te stesso.
• Preferisci scp o rsync su SSH, oppure una cartella syncthing di cui ti fidi già.
• Se devi passare da un laptop come tappa intermedia, cancella la copia locale appena il trasferimento finisce.

Un trasferimento pulito da un vecchio VPS a uno nuovo assomiglia a questo:

# Dalla macchina nuova
scp vps-vecchio:~/.hermes/backups/hermes-backup-2026-07-18-102301.zip ~/

Se stai passando da un laptop personale a un VPS, fai il contrario e spingi dalla sorgente. In ogni caso, appoggia il file nella home dell'utente di destinazione, non in /tmp né in un percorso condiviso.

Passo 3 - Installa Hermes sul target

Installa Hermes sulla macchina nuova come faresti per un setup pulito. Cioè Linux, macOS, WSL2 su Windows o Termux su telefono, i target ufficialmente supportati. Segui il percorso di installazione che corrisponde a come lo farai girare a lungo termine, che sia Hermes Agent in Docker, una installazione nativa su Linux o Windows via WSL2.

Non avviare ancora l'agente. Se parte una volta con ~/.hermes/ vuoto, scrive un state.db fresco e la config di default, che collideranno con l'import del passo successivo. Installa il binario, verifica che hermes --version stampi la stessa major della macchina di origine, e fermati lì.

Passo 4 - Importa e reindicizza

Con l'archivio al suo posto e il binario installato ma non in esecuzione:

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

L'importer scompatta l'archivio dentro ~/.hermes/, ripristina il database di stato, e mette skill, memoria, cron, identity e segreti al loro posto. Alla fine, ricostruisci l'indice vettoriale in modo che la ricerca semantica ordini i risultati usando il modello corrente e non quello che la macchina di origine aveva in uso:

hermes memory reindex

Se il backup è stato preso su una versione di Hermes molto più vecchia, il payload di memoria potrebbe essere in formato legacy. In quel caso, estrai le memorie a parte con un export JSON e reimportale esplicitamente:

hermes memory import --legacy ~/memories.json

Il flag --legacy dice a Hermes di accettare il vecchio schema e di aggiornarlo al volo. hermes memory export --output ~/memories.json sull'origine è il comando gemello, utile quando vuoi migrare solo la memoria e ricostruire il resto da un'installazione pulita.

Passo 5 - Verifica prima di fidarti

Qui due comandi si guadagnano lo stipendio:

hermes doctor   # config, dipendenze, raggiungibilità dei provider, permessi su disco
hermes status   # salute del gateway, contatore di memoria, integrazioni attive

hermes doctor dovrebbe tornare verde su config, database, ChromaDB e credenziali provider. hermes status dovrebbe mostrare un contatore di voci di memoria vicino a quello che avevi sulla sorgente, l'integrazione Telegram connessa e ogni attività pianificata lunga in coda. Se uno dei due segnala qualcosa, sistemalo prima di riaccendere il gateway.

Poi avvia l'agente e mandagli da Telegram un messaggio che debba pescare dalla memoria. "Cosa avevamo deciso per il lancio del Q3?" è una buona prova. Se risponde con contesto, la memoria si è mossa. Se dice che non lo sa, prova hermes memory search "lancio Q3" dalla CLI: la memoria potrebbe essere lì e l'indice vettoriale non aver ancora finito di ricostruirsi.

I dettagli di cui nessuno ti avvisa

Anche un import pulito lascia qualche spigolo. Passa in rassegna questi punti prima di chiudere la pratica.

• I segreti cifrati hanno bisogno della loro chiave di decifratura. Se la sorgente usava un secret store cifrato (Hermes supporta pass, gnome-keyring o un keyfile), l'archivio contiene il testo cifrato ma non la chiave. Trasferisci il keyfile a parte o sblocca lo store sulla macchina nuova prima del primo avvio dell'agente.
• Le credenziali IMAP e SMTP possono chiedere nuova autenticazione. Le app password legate all'impronta di un dispositivo a volte rifiutano di autenticare da un IP nuovo. Google Workspace e Fastmail sono i sospetti abituali. Rigenera la app password se l'integrazione mail resta muta dopo l'import.
• La sessione Telegram può derivare. Il token del bot Telegram è portabile, ma se stavi anche usando una sessione in modalità utente per leggere le chat, il file di sessione può essere legato al vecchio dispositivo. Cancella ~/.hermes/telegram/session.session e lascia che l'agente si ri-autentichi al prossimo avvio.
• I job cron ripartono al prossimo tick previsto, non subito. Se il tuo daily-digest era programmato alle 07:00 e finisci la migrazione alle 07:05, scatterà solo domani. Lancialo una volta a mano con hermes cron run daily-digest per confermare che è in piedi.
• Ruota tutto ciò che l'archivio ha toccato. Anche con un trasferimento attento, un archivio con token di bot e chiavi provider è vissuto su più macchine dei soli due estremi. Se la migrazione era una risposta a una compromissione, o se l'archivio è passato per uno storage condiviso, ruota la chiave OpenAI/Anthropic/OpenRouter e fai riemettere il token del bot da BotFather.

Quando non vuoi farlo da solo

Tutto il rituale (congelare, backup, trasferire, installare, importare, reindicizzare, verificare, ruotare) è quello che un hosting gestito fa in automatico. Hermify fa girare un Hermes Agent gestito su un VPS che operiamo noi, esegue backup cifrati giornalieri e ti dà un ripristino con un clic se un VPS deve essere rimpiazzato. Nella giornata dell'utente non esiste un passo "cambio macchina", perché la macchina è un problema nostro, non tuo.

Se ti convince di più rispetto a rifare questa migrazione ogni anno o due, inizia con Hermify: il tuo agente va online su Telegram in circa un minuto, la memoria resta tua, e il prossimo cambio hardware è invisibile per te.

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