Checkpoints e /rollback

O Hermes Agent pode fotografar o seu projeto automaticamente antes de operações destrutivas e restaurá-lo com um único comando. Os checkpoints são opcionais desde a v2 — a maioria dos usuários nunca usa /rollback, e o armazenamento no repositório-sombra não é desprezível com o tempo, então o padrão é desligado.

Habilite os checkpoints por sessão com --checkpoints:

hermes chat --checkpoints

Ou habilite globalmente no ~/.hermes/config.yaml:

checkpoints:
  enabled: true

Essa rede de segurança é movida por um Checkpoint Manager interno, que mantém um único repositório git-sombra compartilhado em ~/.hermes/checkpoints/store/ — o .git de verdade do seu projeto nunca é tocado. Todo projeto em que o agente trabalha compartilha o mesmo repositório, então o banco de objetos endereçado por conteúdo do git elimina duplicação entre projetos e entre turnos.

O que dispara um checkpoint

Os checkpoints são tirados automaticamente antes de:

• Ferramentas de arquivo — write_file e patch
• Comandos destrutivos de terminal — rm, rmdir, cp, install, mv, sed -i, truncate, dd, shred, redirecionamentos de saída (>) e git reset/clean/checkout

O agente cria no máximo um checkpoint por diretório por turno, para que sessões longas não encham tudo de fotografias.

Referência rápida

Comandos de barra dentro da sessão:

Comando	Descrição
/rollback	Lista todos os checkpoints com estatísticas de mudança
/rollback <N>	Restaura para o checkpoint N, mantendo as suas edições manuais (também desfaz o último turno da conversa)
/rollback <N> --all	Restauração completa — sobrescreve também as suas edições manuais
/rollback diff <N>	Prévia do diff entre o checkpoint N e o estado atual
/rollback <N> <arquivo>	Restaura um único arquivo a partir do checkpoint N

CLI para inspecionar e gerenciar o repositório fora de uma sessão:

Comando	Descrição
hermes checkpoints	Mostra o tamanho total, a quantidade de projetos e o detalhamento por projeto
hermes checkpoints status	O mesmo que o checkpoints sem argumentos
hermes checkpoints list	Apelido de status
hermes checkpoints prune	Força uma varredura: apaga órfãos/obsoletos, roda o GC e aplica o teto de tamanho
hermes checkpoints clear	Destrói toda a base de checkpoints (pergunta antes)
hermes checkpoints clear-legacy	Apaga só os arquivos legacy-* da migração da v1

Como os checkpoints funcionam

Em alto nível:

• O Hermes detecta quando as ferramentas estão prestes a modificar arquivos na sua árvore de trabalho.
• Uma vez por turno de conversa (por diretório), ele:
  • Resolve uma raiz de projeto razoável para o arquivo.
  • Inicializa ou reaproveita o repositório-sombra único e compartilhado em ~/.hermes/checkpoints/store/.
  • Coloca tudo em um índice por projeto, monta uma árvore e faz o commit em uma ref por projeto (refs/hermes/<project-hash>).
• Essas refs por projeto formam um histórico de checkpoints que você pode inspecionar e restaurar pelo /rollback.

flowchart LR
  user["Comando do usuário\n(hermes, gateway)"]
  agent["AIAgent\n(run_agent.py)"]
  tools["Ferramentas de arquivo e terminal"]
  cpMgr["CheckpointManager"]
  store["Repositório-sombra compartilhado\n~/.hermes/checkpoints/store/"]

  user --> agent
  agent -->|"chamada de ferramenta"| tools
  tools -->|"antes de alterar\nensure_checkpoint()"| cpMgr
  cpMgr -->|"git add/commit-tree/update-ref"| store
  cpMgr -->|"OK / pulado"| tools
  tools -->|"aplica as mudanças"| agent

Configuração

Configure no ~/.hermes/config.yaml:

checkpoints:
  enabled: false              # chave geral (padrão: false — é preciso aderir)
  max_snapshots: 20           # máximo de checkpoints por projeto (aplicado com reescrita de ref + gc)
  max_total_size_mb: 500      # teto rígido do tamanho total do repositório; os commits mais antigos caem
  max_file_size_mb: 10        # pula qualquer arquivo maior que isso

  # Manutenção automática (ligada por padrão): varre ~/.hermes/checkpoints/ na
  # inicialização e apaga as entradas de projeto cujo last_touch é mais velho que
  # retention_days. Roda no máximo uma vez a cada min_interval_hours, controlado por
  # um marcador .last_prune. Essa varredura nunca apaga entradas "órfãs" (diretório
  # de trabalho não encontrado) — um workdir ausente na inicialização é ambíguo
  # (projeto apagado vs. um volume externo não montado / compartilhamento de rede /
  # VPN ainda fora do ar), então a limpeza de órfãos só acontece pelo comando
  # explícito `hermes checkpoints prune` abaixo, com um pedido de confirmação.
  auto_prune: true
  retention_days: 7
  min_interval_hours: 24

Para desativar tudo:

checkpoints:
  enabled: false
  auto_prune: false

Com enabled: false, o Checkpoint Manager não faz nada e nunca tenta operações de git. Com auto_prune: false, o repositório cresce até você rodar hermes checkpoints prune manualmente.

Listando checkpoints

Em uma sessão da CLI:

/rollback

O Hermes responde com uma lista formatada, mostrando as estatísticas de mudança:

📸 Checkpoints for /path/to/project:

  1. 4270a8c  2026-03-16 04:36  before patch  (1 file, +1/-0)
  2. eaf4c1f  2026-03-16 04:35  before write_file
  3. b3f9d2e  2026-03-16 04:34  before terminal: sed -i s/old/new/ config.py  (1 file, +1/-1)

  /rollback <N>             restore to checkpoint N (keeps your hand-edits)
  /rollback <N> --all       full restore, overwriting your hand-edits too
  /rollback diff <N>        preview changes since checkpoint N
  /rollback <N> <file>      restore a single file from checkpoint N

Inspecionando o repositório pelo shell

hermes checkpoints

Exemplo de saída:

Checkpoint base: /home/you/.hermes/checkpoints
Total size:      142.3 MB
  store/         138.1 MB
  legacy-*       4.2 MB
Projects:        12

  WORKDIR                                                       COMMITS    LAST TOUCH  STATE
  /home/you/code/hermes-agent                                        20       2h ago  live
  /home/you/code/experiments/rl-runner                                8       1d ago  live
  /home/you/code/old-prototype                                        3       9d ago  orphan
  ...

Legacy archives (1):
  legacy-20260506-050616                           4.2 MB

Clear with: hermes checkpoints clear-legacy

Force uma varredura completa (ignora o marcador de idempotência de 24h):

hermes checkpoints prune --retention-days 3 --max-size-mb 200

Vendo as mudanças com /rollback diff

Antes de se comprometer com uma restauração, veja o que mudou desde um checkpoint:

/rollback diff 1

Isso mostra um resumo de estatísticas do diff do git, seguido do diff em si.

Restaurando com /rollback

/rollback 1

Nos bastidores, o Hermes:

1. Confirma que o commit alvo existe no repositório-sombra.
2. Tira uma fotografia pré-rollback do estado atual, para você poder "desfazer o desfazer" depois.
3. Restaura os arquivos rastreados no seu diretório de trabalho — preservando as suas edições manuais (veja abaixo).
4. Desfaz o último turno da conversa, para o contexto do agente combinar com o estado restaurado do sistema de arquivos.

As edições manuais do usuário são preservadas por padrão

O /rollback <N> restaura apenas os arquivos que o próprio Hermes mudou. Todo write_file / patch bem-sucedido registra o hash de conteúdo do arquivo em um livro-razão de escritas do agente; na hora de restaurar, qualquer arquivo cujo conteúdo atual não bate mais com o que o Hermes escreveu por último (você o editou depois, ou o Hermes nunca o tocou) é pulado em vez de sobrescrito, e aparece listado na saída:

✅ Restored to checkpoint a1b2c3d4: before write_file
↷ Kept your hand-edits: src/config.py, notes.md
Use /rollback <N> --all to restore those too.

Para forçar a restauração completa clássica, que reverte tudo — inclusive as suas próprias edições —, acrescente --all:

/rollback 1 --all

Se o livro-razão estiver vazio (um repositório criado antes desse recurso, ou o Hermes ainda não escreveu nenhum arquivo no projeto), o /rollback recorre automaticamente à restauração completa.

Restauração de um único arquivo

Restaure só um arquivo de um checkpoint, sem afetar o resto do diretório:

/rollback 1 src/broken_file.py

Proteções de segurança e desempenho

• Disponibilidade do git — se o git não for encontrado no PATH, os checkpoints são desativados de forma transparente.
• Escopo de diretório — o Hermes pula diretórios amplos demais (a raiz /, o diretório pessoal $HOME).
• Tamanho do repositório — diretórios com mais de 50.000 arquivos são pulados.
• Teto de tamanho por arquivo — arquivos maiores que max_file_size_mb (padrão de 10 MB) ficam de fora da fotografia. Isso evita engolir sem querer conjuntos de dados, pesos de modelo ou mídia gerada.
• Teto de tamanho total do repositório — quando o repositório passa de max_total_size_mb (padrão de 500 MB), o commit mais antigo de cada projeto é descartado em rodízio até ficar abaixo do teto.
• Poda de verdade — o max_snapshots é aplicado reescrevendo a ref por projeto e rodando git gc --prune=now depois, para que objetos soltos não se acumulem.
• Fotografias sem mudança — se não houve mudança desde a última fotografia, o checkpoint é pulado.
• Erros não fatais — todos os erros dentro do Checkpoint Manager são registrados em nível de debug; as suas ferramentas continuam rodando.

Onde os checkpoints ficam

~/.hermes/checkpoints/
  ├── store/                 # repositório git bare único e compartilhado
  │   ├── HEAD, objects/     # internos do git (compartilhados entre projetos)
  │   ├── refs/hermes/<hash> # ponta da branch por projeto
  │   ├── indexes/<hash>     # índice git por projeto
  │   ├── projects/<hash>.json  # workdir + created_at + last_touch
  │   └── info/exclude
  ├── .last_prune            # marcador de idempotência da poda automática
  └── legacy-<ts>/           # repositórios-sombra por projeto anteriores à v2, arquivados

Cada <hash> é derivado do caminho absoluto do diretório de trabalho. Normalmente você nunca precisa mexer nisso manualmente — use hermes checkpoints status / prune / clear no lugar.

Migração a partir da v1

Antes da reescrita da v2, cada diretório de trabalho ganhava o seu próprio repositório git-sombra completo, direto em ~/.hermes/checkpoints/<hash>/. Aquele layout não conseguia eliminar duplicação de objetos entre projetos e tinha um podador que, documentadamente, não fazia nada — o repositório crescia sem limite.

Na primeira execução da v2, quaisquer repositórios-sombra anteriores à v2 são movidos para ~/.hermes/checkpoints/legacy-<timestamp>/, para o novo layout de repositório único começar limpo. O histórico antigo do /rollback continua acessível se você inspecionar o arquivo legado manualmente com o git; quando tiver certeza de que não precisa mais dele, rode:

hermes checkpoints clear-legacy

para recuperar o espaço. Os arquivos legados também são varridos pelo auto_prune depois de retention_days.

Boas práticas

• Habilite os checkpoints só quando você precisar deles — hermes chat --checkpoints ou enabled: true por perfil.
• Use /rollback diff antes de restaurar — veja o que vai mudar para escolher o checkpoint certo.
• Use /rollback em vez de git reset quando quiser desfazer apenas as mudanças feitas pelo agente.
• Dê uma olhada em hermes checkpoints status de vez em quando, se você usa checkpoints com frequência — ele mostra quais projetos estão ativos e quanto o repositório está custando.
• Combine com worktrees do Git para segurança máxima — mantenha cada sessão do Hermes na sua própria worktree/branch, com os checkpoints como camada extra.

Para rodar vários agentes em paralelo no mesmo repositório, veja o guia de worktrees do Git.

---