Curador

O curador é uma passada de manutenção em segundo plano sobre as skills criadas pelo agente. Ele acompanha com que frequência cada skill é vista, usada e corrigida, move as que ficaram muito tempo sem uso pelos estados ativa → parada → arquivada, e de tempos em tempos abre uma revisão curta, num modelo auxiliar, que propõe consolidações ou corrige desvios.

Ele existe para as skills criadas pelo ciclo de autoaperfeiçoamento não se acumularem para sempre. Toda vez que o agente resolve um problema novo e salva uma skill, ela cai em ~/.hermes/skills/. Sem manutenção, você acaba com dezenas de quase-duplicatas estreitas, que poluem o catálogo e desperdiçam tokens.

Por padrão (prune_builtins: true), o curador também pode arquivar skills embutidas que não são usadas (as que vêm com o repositório), depois de archive_after_days sem uso, junto das criadas pelo agente, que são a responsabilidade principal dele. Skills instaladas pelo hub (do agentskills.io) estão sempre fora do alcance. Coloque curator.prune_builtins: false para voltar ao comportamento antigo, em que só as criadas pelo agente são tocadas. O curador também nunca apaga sozinho — o pior desfecho é arquivar em ~/.hermes/skills/.archive/, o que é recuperável.

Como ele roda

O curador é disparado por uma checagem de inatividade, não por um daemon de cron. Na abertura de uma sessão de CLI, e num tique recorrente dentro da thread de cron do gateway, o Hermes confere se:

1. passou tempo suficiente desde a última execução (interval_hours, padrão de 7 dias), e
2. o agente ficou ocioso tempo suficiente (min_idle_hours, padrão de 2 horas).

Se as duas coisas são verdade, ele abre uma bifurcação de AIAgent em segundo plano — o mesmo padrão das sugestões de autoaperfeiçoamento de memória e de skills. A bifurcação roda no próprio cache de prompt e nunca toca a conversa ativa.

Comportamento na primeira execução

Numa instalação nova (ou na primeira vez que uma instalação anterior ao curador tica depois de um hermes update), o curador não roda de imediato. A primeira observação apenas grava o last_run_at como "agora" e adia a primeira passada de verdade por um interval_hours completo. Isso te dá um intervalo inteiro para revisar sua biblioteca de skills, fixar o que importa, ou desistir de vez antes de o curador encostar nela.

Se você quer ver o que o curador faria antes de ele rodar para valer, use hermes curator run --dry-run — ele produz o mesmo relatório, sem alterar nada.

Uma execução tem duas fases:

1. Transições automáticas (determinísticas, sem modelo). Skills sem uso há stale_after_days (30) viram stale; as sem uso há archive_after_days (90) vão para ~/.hermes/skills/.archive/. Essa é a poda sempre ligada — ela roda sempre que o curador está habilitado, sem custo de modelo auxiliar.
   • Skills fixadas e skills citadas por qualquer tarefa de cron (inclusive tarefas pausadas ou desabilitadas) são puladas por completo — tratadas como fixadas nas transições automáticas, para um agendamento lento ou pausado não arquivar uma skill embaixo de uma tarefa. A consolidação também reescreve as referências de skill nas tarefas de cron quando funde guarda-chuvas.
   • Skills nunca usadas (use_count == 0) ganham um piso de tolerância: elas não são arquivadas antes de terem pelo menos stale_after_days de idade. Zero usos é ausência de evidência, não prova de que a skill é descartável.
2. Consolidação por modelo (uma passada no modelo auxiliar, com teto alto de iterações — uma varredura completa costuma levar de 50 a 100 chamadas de API) — DESLIGADA por padrão. Com curator.consolidate: true, a bifurcação examina as skills criadas pelo agente, pode ler qualquer uma com skill_view, e decide, uma a uma, se mantém, corrige (com skill_manage), consolida as que se sobrepõem em guarda-chuvas de classe, ou arquiva pelo terminal. A consolidação trata a skill como um pacote inteiro: se ela tem references/, templates/, scripts/, assets/, ou links relativos para esses caminhos, o curador precisa ou mantê-la sozinha, ou realocar os arquivos de apoio e reescrever os caminhos, ou arquivar o pacote inteiro sem mudança — e não achatar só o SKILL.md dentro do references/ de outra skill.

A consolidação é opcional

Por padrão, o curador só poda — a passada determinística marca skills como paradas e arquiva as que ficaram muito tempo sem uso. A passada opinativa de consolidação por modelo (montar guarda-chuvas, fundir skills que se sobrepõem) vem desligada porque custa tokens de modelo auxiliar em toda execução e faz mudanças estruturais amplas na sua biblioteca. Ligue com curator.consolidate: true, ou rode uma vez, sob demanda, com hermes curator run --consolidate.

Skills fixadas estão fora do alcance tanto das transições automáticas do curador quanto da própria ferramenta skill_manage do agente. Veja fixar uma skill.

Configuração

Tudo fica no config.yaml, sob curator: (não no .env — isso não é segredo). Os padrões:

curator:
  enabled: true
  interval_hours: 168          # 7 dias
  min_idle_hours: 2
  stale_after_days: 30
  archive_after_days: 90
  consolidate: false           # passada de guarda-chuva por modelo — opcional (só poda, por padrão)
  prune_builtins: true         # arquiva também as embutidas sem uso (as do hub ficam sempre de fora)

Para desligar de vez, curator.enabled: false. Para manter a poda e ligar a consolidação por modelo, curator.consolidate: true.

Rodar a revisão num modelo auxiliar mais barato

A passada de revisão do curador é uma tarefa auxiliar comum — auxiliary.curator —, ao lado de Visão, Compressão, Busca em Sessões e as outras. "Auto" significa "usar o meu modelo principal"; sobrescreva a tarefa para fixar um provedor e um modelo só para essa revisão.

Mais fácil, pelo hermes model:

hermes model                   # → "Auxiliary models — side-task routing"
                               # → escolha "Curator" → provedor → modelo

O mesmo seletor está no painel web, na aba Models.

Direto no config.yaml (equivalente):

auxiliary:
  curator:
    provider: openrouter
    model: google/gemini-3-flash-preview
    timeout: 600               # generoso — revisões podem levar vários minutos

Deixar provider: auto (o padrão) manda a revisão pelo seu modelo principal, igual a toda outra tarefa auxiliar.

Configuração antiga

Versões anteriores usavam um bloco avulso, curator.auxiliary.{provider,model}. Esse caminho ainda funciona, mas emite uma linha de log de descontinuação — migre para o auxiliary.curator acima, para o curador usar o mesmo encanamento (hermes model, aba Models do painel, base_url, api_key, timeout, extra_body) das outras tarefas auxiliares.

Linha de comando

hermes curator status         # última execução, contagens, lista de fixadas, as 5 menos usadas
hermes curator run            # dispara agora (bloqueia até terminar). Só poda, a menos que curator.consolidate: true
hermes curator run --consolidate # força a consolidação nesta execução, sobrepondo o padrão
hermes curator run --background  # dispara e esquece: roda numa thread de fundo
hermes curator run --dry-run  # só prévia — relatório, sem alterar nada
hermes curator backup         # tira um retrato manual de ~/.hermes/skills/
hermes curator rollback       # restaura o retrato mais novo
hermes curator rollback --list     # lista os retratos disponíveis
hermes curator rollback --id <ts>  # restaura um retrato específico
hermes curator rollback -y         # pula a confirmação
hermes curator pause          # para as execuções até você retomar
hermes curator resume
hermes curator pin <skill>    # nunca faz transição automática nesta skill
hermes curator unpin <skill>
hermes curator adopt <skill>    # entrega uma skill não gerenciada ao curador
hermes curator adopt --all-unmanaged   # entrega todas as não gerenciadas
hermes curator list-unmanaged   # lista as skills sem marcador de procedência
hermes curator restore <skill>  # devolve uma skill arquivada ao estado ativo
hermes curator list-archived    # lista o que está em ~/.hermes/skills/.archive/
hermes curator archive <skill>  # arquiva uma skill na hora, manualmente
hermes curator prune [--days N] # arquiva em massa as criadas pelo agente paradas há N dias (padrão 90)
hermes curator ledger           # lista o registro de auditoria de cada mudança (todos os atores)
hermes curator ledger --skill <nome> --limit 50  # filtra e pagina o registro
hermes curator rollback <id-da-entrada>  # desfaz uma mudança específica do registro
hermes curator purge [--days N] [--dry-run]  # apaga arquivadas mais velhas que o prazo (só explicitamente)

Backups e reversão

Antes de toda passada de verdade, o Hermes tira um retrato em tar.gz de ~/.hermes/skills/, em ~/.hermes/skills/.curator_backups/<iso-utc>/skills.tar.gz. Se uma passada arquivar ou consolidar algo que você não queria, dá para desfazer a execução inteira com um comando:

hermes curator rollback        # restaura o retrato mais novo (com confirmação)
hermes curator rollback -y     # pula a pergunta
hermes curator rollback --list # todos os retratos, com motivo e tamanho

A própria reversão é reversível: antes de substituir a árvore de skills, o Hermes tira outro retrato, marcado como pre-rollback to <id-do-alvo>, então uma reversão equivocada pode ser desfeita com o --id.

Também dá para tirar retratos manuais a qualquer momento, com hermes curator backup --reason "antes-da-refatoracao". O texto do --reason vai para o manifest.json do retrato e aparece no --list.

Os retratos são podados até o curator.backup.keep (padrão 5), para o disco não crescer sem controle:

curator:
  backup:
    enabled: true
    keep: 5

Coloque curator.backup.enabled: false para desligar os retratos automáticos. O comando manual hermes curator backup só funciona com backups desligados se você antes colocar enabled: true — a chave controla os dois caminhos de forma simétrica, então não há como pular sem querer o retrato anterior a uma execução que altera coisas.

O hermes curator status também lista as cinco skills menos usadas recentemente — um jeito rápido de ver o que provavelmente vira stale em seguida.

Os mesmos subcomandos existem como o comando de barra /curator, dentro de uma sessão (na CLI ou nas plataformas de gateway).

Registro de auditoria e reversão de uma edição só

Os retratos de execução inteira respondem "desfaça tudo que a última passada fez" — mas às vezes você quer saber quem mudou o quê e desfazer exatamente uma mudança. Toda alteração de skill — transições automáticas do curador, chamadas de skill_manage do agente, e os seus próprios comandos de arquivar, restaurar e apagar — acrescenta uma entrada ao registro JSONL somente-acréscimo, em ~/.hermes/skills/.curator_ledger.jsonl:

• ator — curator (bifurcação de revisão e transições automáticas), agent (chamadas de ferramenta em primeiro plano) ou user (comandos da CLI)
• ação — create, edit, patch, delete, write_file, remove_file, archive, restore, purge, rollback
• evidência — a intenção da remoção (absorbed_into, nas consolidações; vazio nas podas; e se o caminho recuperável de arquivamento cuidou disso), e o identificador da sessão que disparou, quando há
• antes e depois — manifestos de {path, sha256} por arquivo. O conteúdo é guardado por endereço de conteúdo (sem duplicar por hash), em ~/.hermes/.curator_backups/blobs/, então cem entradas tocando o mesmo arquivo inalterado custam um bloco só.

hermes curator ledger                  # as 20 entradas mais novas
hermes curator ledger --skill minha-skill --limit 50
hermes curator rollback <id-da-entrada>     # restaura o estado anterior daquela mudança

A reversão de uma entrada restaura exatamente os arquivos que aquela mudança tocou (e remove os que ela criou), a partir do armazenamento de blocos — nada mais na árvore se move. Como a reversão da árvore inteira, ela grava antes uma entrada de segurança com o estado atual e falha fechada: se a captura de segurança não puder ser escrita, nada muda. Como as remoções em primeiro plano também são registradas, o hermes curator rollback <id> consegue ressuscitar uma skill apagada de vez.

O registro é telemetria, nunca uma trava — se a escrita de uma entrada falhar, a mudança acontece mesmo assim. Desligue com:

skills:
  ledger: false

Expurgo do arquivo por prazo

Skills arquivadas são guardadas para sempre, por padrão. Se você quer limitar o ~/.hermes/skills/.archive/, defina um prazo e expurgue explicitamente — o expurgo nunca roda sozinho, e toda skill expurgada é capturada antes no registro (com blocos), então até um expurgo deixa um rastro auditável e recuperável:

curator:
  archive_ttl_days: 180   # 0 (padrão) = nunca expurga

hermes curator purge --dry-run   # prévia do que seria apagado
hermes curator purge             # apaga o que passou do prazo (com confirmação)
hermes curator purge --days 90   # prazo diferente, só nesta vez

O que significa "criada pelo agente"

O curador gerencia apenas as skills explicitamente marcadas como criadas pelo agente, em ~/.hermes/skills/.usage.json. Uma skill se qualifica quando TODAS estas condições são verdade:

1. O nome dela não está em ~/.hermes/skills/.bundled_manifest (as embutidas do repositório).
2. O nome não está em ~/.hermes/skills/.hub/lock.json (as instaladas pelo hub).
3. A entrada dela no .usage.json tem "created_by": "agent" ou "agent_created": true.

Hoje, só a bifurcação de revisão de autoaperfeiçoamento em segundo plano grava esse marcador — quando ela cria uma skill guarda-chuva nova, durante a revisão periódica (a cada 10 turnos do agente, mais ou menos). A bifurcação roda com origem de escrita "background_review" (por tools/skill_provenance.py), que é o único caminho que dispara a chamada de mark_agent_created() no skill_manage.

Skills que o agente em primeiro plano cria por skill_manage(action="create") durante uma conversa não são marcadas — elas são consideradas dirigidas por você, e o curador as deixa em paz de propósito.

As suas skills escritas à mão NÃO são curadas

Se você criou um SKILL.md na mão, ou apontou o Hermes para um diretório externo de skills, aquela skill tem uma entrada com created_by: null (ou sem o campo). O curador não vai tocá-la. O mesmo vale para skills que o agente criou a seu pedido.

Para ver quais skills o curador de fato gerencia, rode hermes curator status. Se a contagem de criadas pelo agente for 0, nenhuma skill está sob a jurisdição dele — a passada de revisão é pulada, e o relatório vai mostrar Model: (not resolved) via (not resolved), com Duration: 0s.

Adotar skills não gerenciadas

O hermes curator status mostra uma contagem de não gerenciadas, ao lado da de gerenciadas:

curator-managed skills: 43 total  (agent-created=43  bundled=0)
  active     41
  stale       2
  archived    0

unmanaged (no provenance marker): 112 total
  pre-dates marker    34
  foreground-created  78
  never auto-staled or archived — `hermes curator adopt <name>` hands one over

Aquelas 112 são elegíveis à curadoria, mas permanentemente invisíveis ao ciclo de vida, por um de dois motivos:

• anteriores ao marcador — o registro foi escrito antes de o created_by existir, então ele não carrega sinal nenhum de procedência. A autoria é genuinamente desconhecível pelo registro.
• criadas em primeiro plano — um skill_manage(create) em primeiro plano deixou o marcador vazio de propósito, já que skills que você pede pertencem a você.

Uma biblioteca grande pode, portanto, parecer totalmente curada enquanto a maior parte dela é intocável. O adopt fecha essa lacuna por declaração:

hermes curator list-unmanaged                    # lista, com os motivos
hermes curator adopt <nome> [<nome> ...]         # entrega skills específicas
hermes curator adopt --all-unmanaged --dry-run   # prévia da lista completa
hermes curator adopt --all-unmanaged             # entrega tudo (pergunta antes)
hermes curator adopt --all-unmanaged --yes       # pula a pergunta

A adoção grava o mesmo marcador created_by: agent que a bifurcação de revisão grava. Ela não zera o relógio de inatividade — uma skill adotada mantém o last_activity_at que tinha, então entregar uma biblioteca que você já parou de usar não compra uma janela nova de 90 dias. Espere que skills adotadas e paradas há muito tempo virem stale (ou archived) na passada seguinte; esse é o ponto.

A adoção é também o que destrava a melhoria autônoma. A bifurcação de revisão se recusa a corrigir uma skill que não é gerenciada pelo curador, então, se ela notar que uma das suas está desatualizada, vai dizer isso e recomendar a adoção, em vez de editar. Edições em primeiro plano, dirigidas por você, nunca são afetadas — você e o agente sempre podem editar as suas skills a pedido.

created_by é uma bandeira de política, não uma alegação de autoria

O campo se chama created_by, mas é consumido como "a curadoria autônoma pode tocar isto?" — e não "quem escreveu este arquivo". São perguntas diferentes, e para registros anteriores ao marcador a resposta sobre autoria é simplesmente irrecuperável. O nome foi mantido porque já está no disco, em todo .usage.json; leia como política. O hermes curator adopt muda a política, e não diz nada sobre quem escreveu o arquivo.

Procedência é declarada, nunca inferida

A adoção é manual de propósito. Telemetria não estabelece autoria: uma skill com milhares de patches prova que o agente a mantém, não que o agente a escreveu — o Hermes edita skills de autoria humana o tempo todo, a seu pedido. Uma heurística automática de "parece feita pelo agente, adote" acabaria arquivando algo que você escreveu à mão. O adopt recusa skills embutidas, instaladas pelo hub, externas e embutidas protegidas, que têm dono diferente de você.

As skills que SÃO criadas pelo agente seguem o ciclo completo:

• active → (30 dias sem uso) stale → (90 dias sem uso) archived
• Skills fixadas pulam todas as transições automáticas
• Arquivadas são recuperáveis com hermes curator restore <nome>

Se você quer proteger uma skill específica de ser tocada — uma escrita à mão, da qual você depende — use hermes curator pin <nome>.

Fixar uma skill

Fixar protege uma skill de ser apagada — tanto pelas passadas automáticas do curador quanto pela chamada skill_manage(action="delete") do agente. Uma vez fixada:

• O curador a pula nas transições automáticas (active → stale → archived), e a passada de revisão é instruída a deixá-la em paz.
• A ferramenta skill_manage do agente recusa o delete nela, apontando o hermes curator unpin <nome>. Patches e edições continuam passando, então o agente melhora o conteúdo de uma skill fixada conforme aparecem armadilhas, sem uma dança de fixar, desafixar e fixar de novo.

hermes curator pin <skill>
hermes curator unpin <skill>

A marca fica gravada como "pinned": true na entrada da skill em ~/.hermes/skills/.usage.json, então ela sobrevive entre sessões.

Skills citadas na lista skills: de qualquer tarefa de cron são protegidas do mesmo jeito nas transições automáticas (o curador nunca as marca como paradas nem as arquiva enquanto a referência existir), mesmo com a tarefa pausada ou desabilitada. Prefira fixar explicitamente quando você também quiser bloquear o skill_manage delete.

Só skills criadas pelo agente podem ser fixadas — o hermes curator pin recusa embutidas e instaladas pelo hub, com uma mensagem explicativa. Skills do hub nunca são alteradas pelo curador. As embutidas só são tocadas com curator.prune_builtins: true (o padrão), e mesmo assim só arquivadas depois de archive_after_days sem uso — nunca corrigidas, consolidadas nem apagadas. Coloque curator.prune_builtins: false para deixá-las totalmente de fora.

Um conjunto pequeno de embutidas protegidas é fixado no código como nunca arquivável e nunca consolidável, independentemente de curator.prune_builtins, de fixação ou do julgamento do modelo. Elas sustentam experiências importantes — a plan, por exemplo, é o que faz o comando /plan funcionar —, então arquivar uma em silêncio transformaria o comando de barra num erro de "comando desconhecido", sem sinal nenhum para você. As embutidas protegidas são filtradas da lista de candidatas, então a passada de consolidação nem chega a vê-las.

Se você quer uma garantia mais forte que "sem remoção" — congelar o conteúdo de uma skill por completo, enquanto o agente ainda a lê —, edite o ~/.hermes/skills/<nome>/SKILL.md direto, no seu editor. A fixação protege da remoção por ferramenta, não do seu próprio acesso ao sistema de arquivos.

Telemetria de uso

O curador mantém um arquivo auxiliar em ~/.hermes/skills/.usage.json, com uma entrada por skill:

{
  "my-skill": {
    "use_count": 12,
    "view_count": 34,
    "last_used_at": "2026-04-24T18:12:03Z",
    "last_viewed_at": "2026-04-23T09:44:17Z",
    "patch_count": 3,
    "last_patched_at": "2026-04-20T22:01:55Z",
    "created_at": "2026-03-01T14:20:00Z",
    "state": "active",
    "pinned": false,
    "archived_at": null
  }
}

Os contadores sobem quando:

• view_count: o agente chama skill_view na skill.
• use_count: a skill é carregada no prompt de uma conversa.
• patch_count: um skill_manage patch/edit/write_file/remove_file roda nela.

Skills embutidas e do hub são explicitamente excluídas das escritas de telemetria.

Relatórios por execução

Toda execução do curador escreve um diretório com carimbo de tempo em ~/.hermes/logs/curator/:

~/.hermes/logs/curator/
└── 20260429-111512/
    ├── run.json      # legível por máquina: fidelidade completa, estatísticas, saída do modelo
    └── REPORT.md     # resumo legível por pessoas

O REPORT.md é um jeito rápido de ver o que uma execução fez — quais skills mudaram de estado, o que o revisor disse, quais ele corrigiu. Bom para auditar sem precisar procurar no agent.log.

Sem candidatas? O relatório mostra (not resolved)

Quando o curador não tem nenhuma skill criada pelo agente para revisar, a passada de revisão é pulada por completo. O cabeçalho do relatório vai mostrar Model: (not resolved) via (not resolved), com Duration: 0s — isso não indica erro de configuração nem falha em resolver o modelo. Significa apenas que não havia candidatas, então nenhum modelo foi invocado. A fase de transições automáticas roda e reporta as contagens normalmente.

Mapa de renomeações no resumo

Se uma execução consolidou várias skills sob um guarda-chuva (ou fundiu quase-duplicatas), o resumo mostrado no fim inclui um mapa explícito de renomeações, com cada par nome-antigo → nome-novo aplicado. Isso vem além das linhas de transição por skill, então, quando uma onda de renomeações acontece, você as identifica de relance, sem precisar comparar o JSON. A dica também aparece no hermes curator pin, para você fixar o nome do guarda-chuva na hora, se quiser travar o rótulo novo.

Restaurar uma skill arquivada

Se o curador arquivou algo que você ainda quer:

hermes curator restore <nome-da-skill>

Isso devolve a skill de ~/.hermes/skills/.archive/ para a árvore ativa e volta o estado dela para active. A restauração é recusada se uma skill embutida ou do hub tiver sido instalada com o mesmo nome nesse meio-tempo (ela sombrearia a de cima).

Desligar por ambiente

O curador vem ligado. Para desligar:

• Só num perfil: edite o ~/.hermes/config.yaml (ou a configuração do perfil ativo) e coloque curator.enabled: false.
• Só numa execução: hermes curator pause — a pausa sobrevive entre sessões; use o resume para reabilitar.

O curador também se recusa a rodar se o min_idle_hours não passou, então numa máquina de trabalho ativa ele naturalmente só age nos períodos calmos.

Veja também

• Sistema de Skills — como as skills funcionam e o ciclo de autoaperfeiçoamento que as cria
• Memória — uma revisão paralela, em segundo plano, que mantém a memória de longo prazo
• Catálogo de Skills Embutidas