Módulo 4.1 — Diagnóstico e atualização

🩺 hermes doctor — Checagem automática

O hermes doctor é a primeira ferramenta de qualquer plantão. Em poucos segundos ele audita Python, dependências, API keys, permissões do diretório ~/.hermes/, integridade do SQLite e conectividade com cada provedor LLM configurado. Cada item sai com ✓ (ok), ⚠ (aviso) ou ✗ (falha).

$ hermes doctor
Hermes Agent v0.9.4 — diagnóstico

[ENVIRONMENT]
  ✓ Python 3.11.7 (>= 3.10 required)
  ✓ Virtualenv ativo: ~/.hermes/venv
  ✓ Plataforma: Linux 6.14.0 (x86_64)

[CONFIG]
  ✓ Config carregada de ~/.hermes/config.yaml
  ✓ Perfil ativo: prod
  ⚠ HERMES_LOG_LEVEL não definida (usando INFO)

[CREDENTIALS]
  ✓ OPENROUTER_API_KEY presente (sk-or-v1-...c4a2)
  ✓ ANTHROPIC_API_KEY presente (sk-ant-...9e10)
  ✗ TAVILY_API_KEY ausente — skill 'web_search' não funcionará

[STORAGE]
  ✓ ~/.hermes/ permissões OK (700)
  ✓ memory.db íntegro (PRAGMA integrity_check)
  ✓ Espaço livre: 47 GiB

[CONNECTIVITY]
  ✓ openrouter.ai respondendo (142 ms)
  ✓ api.anthropic.com respondendo (98 ms)

[SKILLS]
  ✓ 14 skills instaladas, 0 com manifest inválido

Resultado: 2 avisos, 1 falha. Exit 2.

✓ O que FAZER

✓Rodar hermes doctor antes de qualquer hermes update.
✓Tratar exit 2 como bloqueante em CI (|| exit 1).
✓Anexar saída do doctor ao abrir issue no GitHub.
✓Rodar com --verbose quando algum check falhar.

✗ O que NÃO fazer

✗Ignorar ⚠ avisos — viram ✗ falhas em pouco tempo.
✗Editar ~/.hermes/ com sudo e quebrar as permissões 700.
✗Pular doctor "porque ontem funcionava".
✗Postar a saída pública com a key inteira — só os últimos 4 chars.

💡 Dica

No seu ~/.bashrc / ~/.zshrc coloque um alias: alias hdoc='hermes doctor --verbose | tee ~/.hermes/last-doctor.log'. Toda execução vira evidência arquivada.

⬆️ hermes update — Atualizar com segurança

Update no Hermes não é só pip install -U. O comando hermes update respeita o canal configurado (stable, beta, nightly), tira snapshot antes de mexer, aplica migração de schema do banco de memória quando necessário e revalida as skills instaladas. Update certo é update boring.

💡 Fluxo recomendado de upgrade

•Rodar hermes doctor (estado base limpo)
•Fazer backup (hermes backup create)
•hermes update --channel stable --dry-run (ver o plano)
•Ler CHANGELOG na URL impressa
•hermes update --channel stable (executar)
•hermes doctor de novo (validar)

$ hermes update --channel stable --dry-run
[DRY-RUN] Canal: stable
  Atual:  0.9.4
  Alvo:   0.9.7
  Snapshot que será criado: snap-2026-05-24T14-03Z
  Migrações de schema: memory.db v7 → v8 (adiciona índice em conversations.thread_id)
  Skills afetadas: 0 (todas compatíveis)
  Breaking changes: ver https://hermes-agent.nousresearch.com/docs/changelog#0-9-7

Use sem --dry-run para aplicar.

$ hermes update --channel stable
[1/5] Snapshot criado em ~/.hermes/snapshots/snap-2026-05-24T14-03Z (12 MiB)
[2/5] Baixando 0.9.7 ......... OK
[3/5] Migrando memory.db v7 → v8 ......... OK
[4/5] Revalidando skills ......... 14/14 OK
[5/5] Reinstalando comando ......... OK
Atualizado para 0.9.7. Rode 'hermes doctor' para validar.

⚠️ Atenção: não atualize durante sessão ativa

Update fecha conexões e migra schema. Se houver uma sessão de agente rodando em outro terminal, ela vai falhar no meio com erro de banco. Finalize sessões abertas antes de hermes update.

📋 Sistema de logs — Onde ficam e como ler

Hermes escreve logs estruturados JSONL: cada linha é um JSON com ts, level, module, correlation_id e msg. Rotação diária, retenção padrão de 14 dias, configurável em config.yaml.

📊 Localização dos logs por SO

Linux: ~/.hermes/logs/YYYY-MM-DD.jsonl
macOS: ~/Library/Logs/Hermes/YYYY-MM-DD.jsonl
Windows: %APPDATA%\hermes\logs\YYYY-MM-DD.jsonl
Docker: stdout (capturado via docker logs)

# Últimos 50 ERROR
$ jq -c 'select(.level == "ERROR")' ~/.hermes/logs/2026-05-24.jsonl | tail -50

# Todas as linhas de uma sessão específica
$ jq -c 'select(.correlation_id == "sess_8f3e2a")' ~/.hermes/logs/*.jsonl

# Tempo médio por chamada de tool
$ jq -r 'select(.event=="tool_call") | "\(.tool) \(.duration_ms)"' \
    ~/.hermes/logs/2026-05-24.jsonl \
  | awk '{s[$1]+=$2; n[$1]++} END {for (t in s) print t, s[t]/n[t]"ms"}'

# Streaming em tempo real
$ tail -f ~/.hermes/logs/$(date +%F).jsonl | jq .

💡 Dica — shipping para Loki

Para times com mais de uma máquina, vale subir Grafana Loki e apontar um Promtail para ~/.hermes/logs/. Você ganha busca cross-host e dashboards em minutos. Alternativas: Datadog, Elastic, ou um simples vector.dev.

🐛 Modo debug — DEBUG=1 e além

Quando o agente "faz coisa estranha", você precisa ver o prompt exato que foi enviado e a resposta crua do LLM. As variáveis de ambiente abaixo abrem o capô.

Sintoma

Usuário relata: "o agente respondeu em inglês mesmo eu pedindo PT-BR"

Sem debug, você ficaria adivinhando se foi a system prompt, o modelo, ou um tool injetando texto.

Ativar debug e reproduzir

HERMES_DEBUG=1 HERMES_TRACE=prompts hermes chat

Agora cada prompt enviado vira um bloco no log, com system, contexto, ferramentas e mensagem do usuário.

Achar a causa

Log mostra: skill web_search injetou contexto com "Reply in English"

A skill veio do marketplace com um template hardcoded em inglês. Causa identificada em 3 minutos, não em 3 horas.

Fix e validação

Override do template em ~/.hermes/skills/web_search/overrides.yaml

Reproduzir o caso, conferir o novo prompt com debug ainda ativo, depois desligar a variável em produção.

⚠️ Atenção

Logs em modo debug podem conter conteúdo de mensagens, system prompts e (por padrão) nomes de tools. Não envie esses logs por email/chat sem sanitizar. O Hermes mascara tokens nas variáveis sensíveis, mas não inspeciona o corpo das mensagens.

⚡ Performance — Latência, tokens, cache

Três alavancas dominam custo e latência: escolha de modelo, tamanho de contexto e prompt caching. Ignorar a terceira é deixar 60-80% de economia na mesa.

📊 Dados — impacto típico de cada alavanca

Prompt caching ativado: redução de 60-80% no custo de tokens repetidos (system prompt, ferramentas).
Streaming on: TTFB (time-to-first-byte) cai de ~4s para ~600ms percebidos.
Janela de contexto enxuta (compactação): latência p95 cai 30-50% em sessões longas.
Modelo certo para a tarefa: trocar Opus por Haiku em classificação simples corta custo 90%.
Batching de embeddings: 100 docs em 1 chamada vs 100 chamadas = 10× mais rápido.

# Ver métricas da última sessão
$ hermes stats --last
Sessão sess_8f3e2a (42 min)
  Turnos:           38
  Tokens entrada:   184.3k (cache hit: 71%)
  Tokens saída:     12.8k
  Latência p50:     820ms
  Latência p95:     2.4s
  Custo total:      US$ 0.34
  Tools chamadas:   web_search(4) read_file(11) write_file(2)

💡 Dica — perfis por carga

Crie perfis em ~/.hermes/profiles/: um fast.yaml com modelo barato + janela curta para classificação, e um deep.yaml com modelo top + ferramentas completas para investigação. Use hermes --profile fast e --profile deep conforme a tarefa.

🔄 Rollback — Desfazendo update problemático

Todo update grava um snapshot em ~/.hermes/snapshots/. Voltar é uma linha. Snapshots contêm versão dos binários, schema do banco e cópia da memória no momento do upgrade — você não perde dados gerados depois, eles são re-migrados na direção contrária se possível.

$ hermes snapshots list
snap-2026-05-24T14-03Z   v0.9.4 → v0.9.7   12 MiB   hoje 14:03
snap-2026-05-20T09-12Z   v0.9.3 → v0.9.4   11 MiB   há 4 dias
snap-2026-05-12T18-44Z   v0.9.0 → v0.9.3   10 MiB   há 12 dias

$ hermes rollback --to LAST --dry-run
[DRY-RUN] Vai voltar para v0.9.4
  Memória atual será mesclada com snapshot (3-way merge)
  Schema migrará v8 → v7 (drop do índice thread_id; sem perda de dados)
  Skills serão revalidadas contra v0.9.4

$ hermes rollback --to LAST
Rollback completo. Versão atual: 0.9.4.
Rode 'hermes doctor' para validar.

✓ Rollback seguro quando…

✓Versão nova quebrou skill crítica
✓Latência piorou >2× sem motivo claro
✓Schema novo está corrompendo escrita
✓Você precisa de tempo para investigar com calma

✗ Rollback NÃO resolve quando…

✗Problema é em API key (rollback não muda key)
✗Provedor LLM está fora do ar
✗Banco já estava corrompido antes
✗Skill custom foi reescrita depois do snapshot

💡 Dica — política de retenção

Padrão guarda os últimos 5 snapshots. Para CI/CD e equipes maiores, ajuste em config.yaml: snapshots.retain: 20. Disco é barato; reverter para 3 versões atrás é caro sem snapshot.

✅ Resumo do Módulo

✓

hermes doctor é o primeiro passo — em qualquer suspeita, rode antes de qualquer outra ação.

✓

Update tem ritual: doctor → backup → dry-run → CHANGELOG → executar → doctor de novo.

✓

Logs JSONL em ~/.hermes/logs/ com jq resolvem 80% dos bugs.

✓

HERMES_DEBUG=1 mostra o prompt exato; é a ferramenta para sair de adivinhação.

✓

Prompt caching + perfis derrubam custo e latência sem reescrever nada.

✓

Rollback existe e é uma linha — use sem culpa quando o update piorar as coisas.

Próximo módulo:

4.2 — 💾 Backup, segurança e monitoramento. Como proteger memória, rotar API keys, isolar o agente e detectar incidentes antes que eles virem manchete na fatura.

← Voltar para Trilha Próximo: 4.2 →