📅 Release channels — stable vs beta vs nightly
Hermes Agent segue o padrão de três canais: stable (recomendado), beta (release candidates testados pela comunidade) e nightly (HEAD do main). Escolher o canal certo por máquina evita surpresa.
📊 Comparativo de canais
| Canal | Estabilidade | Novidades | Risco | Cadência típica |
|---|---|---|---|---|
| stable | Alta | Atraso de ~4-6 semanas | Baixo | Mensal |
| beta | Média-alta | Atraso de ~1-2 semanas | Médio | Quinzenal |
| nightly | Variável | Em tempo real | Alto | Diária |
Regra de ouro: prod sempre em stable. Use beta no dev/laptop. Nightly só se você quer reportar bug.
# Listar versões disponíveis em cada canal
$ pip index versions hermes-agent # stable + pre
$ pip install hermes-agent==0.9.7 # pin exato (stable)
$ pip install --pre hermes-agent # beta mais recente
$ pip install git+https://github.com/NousResearch/hermes-agent.git # nightly
# Ver canal ativo no Hermes
$ hermes version --verbose
hermes-agent 0.9.7 (stable) · python 3.12.4 · sqlite 3.46📋 Changelog discipline — ler antes de upgrade
90% dos incidentes pós-upgrade vêm de não ter lido o CHANGELOG. Ele documenta breaking changes, mudanças de config, deprecations e migrações de schema. Ler 5 minutos te economiza horas de debug.
🔍 Checklist de leitura do CHANGELOG
- •Breaking changes: tudo com
BREAKINGou!:no commit. - •Removed: features ou flags que sumiram (vai quebrar config antigo).
- •Migration: scripts de migração de schema obrigatórios.
- •Deprecated: ainda funciona, mas sai no próximo major — comece a migrar.
- •Security: CVEs corrigidas — geralmente upgrade não é opcional.
⚠️ Atenção — upgrades major com breaking changes
Upgrade de 0.x para 1.0 (ou de qualquer X.0 para Y.0) sempre vai conter quebras. Trate como migração, não como update. Nunca faça em sexta-feira, nunca direto em prod, e nunca sem backup atualizado nas últimas 24h. Reserve um bloco de 2h e siga o playbook do tópico 6.
🧪 Staging — instância paralela para testar
Staging não é "outra máquina cara". É o mesmo Hermes, em diretório separado, apontando para a key dev e uma cópia recente do memory.db. Faz toda diferença para validar update antes de tocar produção.
# Criar staging em paralelo (sem mexer no prod)
$ pipx install --suffix=-staging hermes-agent==0.9.8b1
$ export HERMES_HOME=~/.hermes-staging
$ mkdir -p $HERMES_HOME
$ cp -r ~/.hermes/skills ~/.hermes/config.yaml $HERMES_HOME/
$ sqlite3 ~/.hermes/memory.db "VACUUM INTO '$HERMES_HOME/memory.db'"
# Apontar para key dev (NUNCA prod)
$ export OPENROUTER_API_KEY="$(pass hermes/openrouter-dev)"
$ hermes-staging doctor
$ hermes-staging chat # rodar smoke test real✓ O que FAZER em staging
- ✓Testar em staging antes de promover.
- ✓Rodar suíte de smoke tests reais (suas 10 sessões típicas).
- ✓Validar
hermes doctore migrações. - ✓Deixar staging rodar 24-48h em paralelo antes de promover.
✗ O que NÃO fazer
- ✗Upgrade direto em prod "porque é só uma versão minor".
- ✗Apontar staging para a key de prod (custo + risco).
- ✗Compartilhar
memory.dbentre staging e prod. - ✗Promover sem rodar smoke tests reais.
💡 Dica — pip install hermes-agent==X.Y.Z --dry-run
Antes de aplicar update mesmo em staging, rode pip install hermes-agent==0.9.8 --dry-run para ver toda a árvore de dependências que vai mudar. 70% dos updates problemáticos não são do Hermes — são de transitive deps (pydantic, httpx, sqlalchemy) que ele puxa.
⏱️ Janela de upgrade — quando agendar
Hora ruim de upgrade existe. Terça ou quarta de manhã é a janela canônica: time inteiro disponível para suporte, fim de semana inteiro pela frente para rollback se algo escapar, e nunca sexta à tarde.
🕐 Quando agendar
- ✓Terça/quarta 10h-14h — janela ideal, suporte disponível.
- ✓Após 48h em staging sem incidente.
- ✓Quando há janela de baixo uso no seu padrão (verificar nos logs).
- ✗Sexta-feira — clássico. Não faça.
- ✗Véspera de feriado, fim de trimestre, dia de release de produto.
- ✗"Rápido aqui antes de sair" — upgrade nunca termina em 5 min.
🔙 Rollback strategy — voltar com segurança
Rollback bom é rollback ensaiado. Não dá para descobrir como reverter durante o incidente. O Hermes facilita: cada update grava snapshot em ~/.hermes/snapshots/, mas você precisa saber usar.
# Listar snapshots disponíveis
$ hermes rollback --list
2026-05-22 10:31 0.9.7 -> 0.9.8 snap-abc123 (1.2GB, retido)
2026-05-15 09:00 0.9.6 -> 0.9.7 snap-def456 (1.1GB, retido)
# Reverter para o snapshot mais recente
$ hermes rollback --to LAST --confirm
# Reverter para snapshot específico
$ hermes rollback --to snap-abc123 --confirm
# Reverter só a memória, mantendo a versão do binário
$ hermes rollback --to LAST --only memorySinais que pedem rollback
Não hesite quando vir isso
Erro novo persistente após 30 min de debug, perda de memória/skills, latência 3× acima do baseline, ou comportamento inconsistente que você não conseguiu reproduzir. Rollback primeiro, investiga depois.
Retenção de snapshots
Padrão: últimos 5 ou 30 dias
Defina snapshots.retention_days: 30 em config.yaml. Em projetos críticos suba para 90 dias. Snapshots ocupam ~tamanho do .hermes/ — verifique disco.
Ensaie rollback uma vez por mês
Como restore de backup, rollback não-ensaiado não conta
Em staging, faça upgrade fake e role rollback. Confirme que dá em < 60 segundos e que memória/skills voltam intactas.
📅 Calendário anual — quarterly review, audit, deps update
Manutenção saudável é ritmo, não heroísmo. Quatro blocos por ano de 1h-3h mantêm Hermes funcionando bem indefinidamente. Documente no calendário recorrente.
Audit completo (Janeiro · 2-3h)
Limpeza profunda do ano novo
Rotar todas as keys. Auditar custo do ano. Revisar skills instaladas (remover não usadas). Compactar memory.db (VACUUM). Atualizar Python base. Testar restore completo em máquina nova.
Minor update (Abril · 1h)
Pegar features do trimestre
Upgrade para a última minor estável (ex.: 0.9.x → 0.10.x). Atualizar deps transitivas. Rodar smoke tests. Revisar config — features novas podem trazer toggles úteis (caching, fallback).
Audit de custo + security (Julho · 1-2h)
Mid-year check
Re-rodar a auditoria do módulo 4.3 (caso real US$ 120 → 28). Verificar CVEs em deps (pip-audit). Rotar keys de novo. Validar monitores e alertas continuam disparando.
Major update window (Outubro · 2-4h)
Antes do fim de ano congelar tudo
Se houver major (1.x → 2.x) pendente, este é o trimestre. Ler todos os CHANGELOGs entre versões. Staging por 1 semana mínimo. Promoção em janela controlada com rollback ensaiado.
📊 Cadência típica de releases Nous Research
- Patch (0.9.7 → 0.9.8): a cada ~2 semanas — bugs e tweaks.
- Minor (0.9 → 0.10): a cada ~2 meses — features novas, sem quebrar API.
- Major (0.x → 1.0): ~1 por ano — breaking changes acumuladas.
- Security patches: fora do ciclo, geralmente em < 48h após CVE.
- Discord da Nous Research anuncia primeiro — bom canal para acompanhar.
# Playbook de upgrade — 10 passos (cole em runbooks/hermes-upgrade.md)
1. Ler CHANGELOG entre versão atual e alvo
2. Verificar saúde atual: hermes doctor && hermes memory stats
3. Backup fresco: hermes backup --encrypt
4. pip install hermes-agent==X.Y.Z --dry-run # ver árvore de deps
5. Criar/atualizar staging com a versão alvo
6. Rodar suíte de smoke tests reais em staging
7. Deixar staging rodando 24-48h
8. Janela: terça/quarta manhã. Avisar usuários.
9. Aplicar update em prod, rodar hermes doctor
10. Monitorar 1h, com rollback pronto: hermes rollback --to LAST✅ Resumo do Módulo
Próxima trilha:
Trilha 5 — Deploy. Levar Hermes Agent para produção: containers, orquestração, observabilidade ponta-a-ponta, escala horizontal e padrões de deploy seguro.