Parte 1 · O motor · O sistema com o qual aprendemos

Reverse-engineering do Hermes

O Hermes Agent é o "agente de IA que se auto-melhora" da Nous Research — uma base de código Python de mais de um milhão de linhas. Você não consegue fundir aquilo que não entende, então a fusão começou por um mapa. Esta lição é o núcleo desse mapa: o que o Hermes é, a única ideia estrutural que o torna extensível, e o loop fechado de aprendizado que virou a razão inteira de existir da fusão.

Leia primeiro (fonte primária)

NousResearch/hermes-agent — README + AGENTS.md, e o docs/hermes-complete-map.md deste repositório

Esta lição destila o hermes-complete-map.md (o mapeamento grounded do Hermes feito durante a fusão) — §1.1 (o que é), §1.2 (as duas restrições), §1.5 (o registro de ferramentas), §1.9 (toolsets + curator), §1.10 (o loop fechado) e §5 (o mini-loop + o orange-book). Cada número e cada arquivo citado aqui vem de leitura real — nada é inventado.

Leia a versão simples, ou abra a camada técnica em qualquer seção.

O que você vai conseguir fazer

Descrever o que o Hermes é — um mesmo núcleo de agente rodando em muitas superfícies — e citar suas duas restrições de design.
Explicar o registro de ferramentas por auto-descoberta (a ideia mais portável do Hermes) e por que ele importa.
Separar os três números — 87 arquivos, 30 toolsets, 64 ferramentas expostas — e dizer o que cada um mede.
Reconstruir o loop fechado de aprendizado e por que ele roda em um fork que nunca toca a conversa viva.
Citar a disciplina do mini-loop (aprenda só com vitórias ≥ 0.7; reforce, não duplique; recombine átomos provados) — que reaparece na Lição 4.

O que assumimos de você (muito pouco)

Você leu a Lição 1 e já tem a noção de cintura estreita (um núcleo pequeno e estável; a capacidade vive nas bordas).
Você não precisa saber Python — vamos ler estrutura, não sintaxe.
Termos técnicos (fork, cache, toolset, skill, registry) ficam em inglês de propósito; explicamos cada um quando aparece.

Por que se começa pelo mapa

Antes de copiar, adaptar ou mesclar qualquer coisa do Hermes para dentro do Alembic, é preciso entender o que está sendo fundido. O Hermes é grande — e "grande" engana: você não lê 1,18 milhão de linhas de cabo a rabo. Você mapeia as prioridades em profundidade, cataloga a cauda longa, e declara explicitamente até onde a fronteira de cobertura chegou.

Pense num cartógrafo chegando a um continente. Ele não pisa em cada metro quadrado: percorre os rios principais a pé, marca as cidades, e anota nas bordas "aqui há montanhas não exploradas". O mapa é honesto sobre o que viu e o que apenas catalogou.

arquivos Python (aprox.)

~1,18M

linhas de código

arquivos em tools/

chaves de toolset

Realidade de escala: o mapa não é uma leitura linha a linha de todo 1,18M de LOC — ele mergulha nas prioridades e cataloga a cauda longa, com a fronteira de cobertura declarada. Fonte: docs/hermes-complete-map.md §1, §6.

Um reverse-engineering fiel tem três zonas — e diz qual fato cai em qual.

A declaração de cobertura como contrato

O §6 do mapa lista nominalmente o que foi lido em nível de corpo, o que foi lido só em nível de docstring/assinatura (ex.: cli.py com 15.197 LOC, agent/context_compressor.py com 130KB) e o que não foi examinado. Isso transforma a honestidade em algo verificável: um leitor pode apontar exatamente onde um fato é forte (lido a fundo) e onde é uma inferência catalogada. É a mesma disciplina observed / inferred / unknown que o Alembic adota nos seus próprios mapas.

O que o Hermes é

O Hermes é um agente pessoal de IA que roda o mesmo núcleo de agente em muitas superfícies — uma CLI, um gateway de mensagens (Telegram, Discord, Slack e ~20 outras plataformas), uma TUI em Ink/React e um app desktop em Electron. Construído pela Nous Research, licença MIT. Seus diferenciais, nas palavras do próprio projeto:

Imagine um único cérebro plugado em vários corpos. O cérebro (o núcleo do agente) é o mesmo; muda só o "corpo" — o terminal, o chat do Telegram, a janela do desktop. Trocar de modelo é como trocar a fonte de energia do cérebro: hermes model e pronto, nada no código muda.

Um loop fechado de aprendizado — memória curada pelo agente com cutucadas periódicas; criação autônoma de skills após tarefas complexas; skills que se auto-melhoram durante o uso; busca de sessões com FTS5 + sumarização por LLM para recall entre sessões. a parte que importa para nós

Agnóstico a modelo — Nous Portal, OpenRouter (200+ modelos) e muitos outros; troca-se com hermes model, sem mexer no código.

Vive onde você vive — um processo de gateway faz a ponte entre Telegram / Discord / Slack / WhatsApp / Signal / CLI, com transcrição de áudios de voz.

Delega e paraleliza — gera subagents isolados para fluxos de trabalho em paralelo, e roda em qualquer lugar: seis backends de terminal atrás de uma única ABC (local, Docker, SSH, Singularity, Modal, Daytona).

Uma roda: o mesmo núcleo no centro, as superfícies nos raios. Trocar de superfície não toca o núcleo.

Agnóstico a modelo: o provedor é uma escolha de runtime, não uma reescrita.

Repare na rima com a Lição 1. Hermes e Alembic chegaram independentemente a "uma cintura estreita + um prompt estável de cache". Esse instinto compartilhado é exatamente o motivo de a fusão compor em vez de brigar — e é o fio que puxamos na Lição 3.

As duas restrições das quais tudo deriva

As duas restrições de design rio acima de tudo

1 · O cache de prompt por conversa é sagrado. Uma conversa longa reaproveita um prefixo em cache a cada turno; qualquer coisa que mute o contexto passado ou reconstrua o system prompt no meio da conversa invalida o cache e multiplica o custo. A única exceção sancionada é a compressão de contexto. 2 · O núcleo é uma cintura estreita; a capacidade vive nas bordas. Toda ferramenta de modelo é enviada em toda chamada de API — então a barra para uma nova ferramenta de núcleo é alta. Capacidade nova chega como comando de CLI + skill ou como plugin, não como superfície de núcleo.

A regra #1 explica metade do design: nada muta o contexto vivo. A escrita de aprendizado vai para fora dele.

A barra do núcleo é alta de propósito: como o schema viaja em toda chamada, a borda é onde a capacidade cresce.

Guarde istoQuase toda decisão "estranha" do Hermes — memória congelada, fork em vez de edição, ferramentas nas bordas — é consequência direta de uma destas duas restrições. Quando algo parecer arbitrário, pergunte "qual restrição isto protege?".

Por que "toda ferramenta em toda chamada" eleva a barra

Como o schema de cada ferramenta de modelo faz parte do prompt enviado a cada chamada, adicionar uma ferramenta de núcleo aumenta o tamanho (e o custo) de todas as requisições, para sempre. Daí a política: ferramenta de núcleo = 2 arquivos (o arquivo da ferramenta + uma entrada no toolset), revisada com rigor; capacidade local/custom deve vir como plugin (~/.hermes/plugins/<nome>/) e nunca tocar o núcleo (AGENTS.md:500-510).

A dobradiça: o registro de ferramentas

Esta é a ideia estrutural mais importante e mais portável do Hermes. As ferramentas se auto-registram no momento do import; nada mantém uma lista central de imports. Cada arquivo de ferramenta chama registry.register(...) em nível de módulo; uma passagem de descoberta varre o diretório e importa cada arquivo, e o efeito colateral do import popula o registro.

É como um quadro de avisos em que cada cartaz se prega sozinho ao entrar na sala. Ninguém mantém uma "lista mestra de cartazes" — você abre a porta (a descoberta), e cada cartaz já se afixa no lugar. Adicionar um cartaz novo é só trazê-lo para a sala.

tools/registry.py — o efeito colateral do import# cada arquivo de ferramenta, em nível de módulo:
registry.register(
    name="web_search",
    toolset="web",
    schema=SCHEMA, handler=run, check_fn=is_available,
)

# a descoberta, uma vez, no boot:
def discover_builtin_tools():
    for f in glob("tools/*.py"):
        importlib.import_module(f)   # o import dispara o register()

Esboço fiel ao mapa (§1.5 / tools/registry.py:57-70, :234); nomes reduzidos para clareza. Todos os handlers devem retornar uma string JSON (AGENTS.md:538).

A pilha invertida: o registry não depende de ninguém (na base); os entry points dependem de tudo (no topo).

A diferença prática: sem lista central, adicionar uma ferramenta é largar um arquivo na pasta — a descoberta faz o resto.

Faça sua aposta antes de virar a página

Se um arquivo se auto-registra ao ser importado, quantos arquivos a base precisa editar para adicionar uma ferramenta de núcleo nova que o agente realmente enxergue?

Dois. O arquivo da ferramenta (que se auto-registra no import) e uma entrada no toolset em toolsets.py — porque registrar não é o mesmo que expor. É exatamente esta distinção que vira a próxima seção.

87 / 30 / 64 — três números, três significados

Há uma nuance crucial que o mapa faz questão de cravar — e é a origem de um número muito mal citado. A auto-descoberta registra o schema de uma ferramenta, mas a ferramenta só fica exposta a um agente se o nome dela aparecer num toolset em toolsets.py. Então três contagens diferentes descrevem três coisas diferentes.

Infográfico com três colunas-card: 87 arquivos de ferramenta em tools, 30 chaves de toolset em toolsets.py, e 64 ferramentas expostas ao agente segundo o orange-book — com a legenda registrar não é expor.

Três contagens, três medidas. "Quantas ferramentas o Hermes tem?" não tem resposta única — depende do que você conta.

Contagem	O que ela realmente mede
87	arquivos de ferramenta em `tools/*.py` (verificado com `ls \| wc -l`). Inclui arquivos de infra como `registry.py`, scanners de segurança e helpers compartilhados — nem todos são ferramentas voltadas ao agente.
30	chaves de toolset em `toolsets.py` (`browser`, `memory`, `skills`, `web`, …) — os pacotes nomeados dos quais uma plataforma herda.
"64 ferramentas"	O número que o material de aprendizado orange-book cita para ferramentas voltadas ao agente. Mantemos a distinção arquivo/ferramenta explícita em vez de colapsar as três numa só.

Registrado não basta: o toolset é o portão de exposição. É por isso que 87 ≠ 64.

arquivos de ferramenta

Tudo em tools/*.py — inclusive infra e helpers que o agente nunca chama.

tools/*.py · ls | wc -l = 87

Clique nas abas: cada número acende uma faixa diferente. Registrar ≠ expor.

Por que isso importa para o mapa. "Quantas ferramentas o Hermes tem?" não tem uma resposta única — depende de você contar arquivos, chaves de toolset ou ferramentas expostas. Um reverse-engineering fiel declara as três e o que cada uma mede, em vez de escolher a mais redonda.

Cuidado"87 = o número de ferramentas" é a confusão clássica. 87 é o número de arquivos. Se alguém citar "87 ferramentas", o sinal é que copiou um número sem checar a fronteira de exposição.

O loop fechado de aprendizado

A propriedade-manchete — "se auto-melhora" — é concreta no código, não marketing. Depois de um turno, o agente pode se forkar para revisar o que acabou de acontecer e decidir se algo vale a pena lembrar — e as escritas caem em stores duráveis que a próxima sessão lê.

É como um diário escrito por um sósia que herda suas memórias e revisa seu dia depois que você já dormiu. Ele não acorda você nem reescreve o que você viveu (a conversa viva); só anota no diário. Quando você acorda amanhã (a próxima sessão), o diário já está atualizado.

Infográfico do loop fechado: um turno do usuário dispara um background review fork em daemon thread com whitelist de memory e skill, que escreve em durable stores (MEMORY.md, USER.md, skills do agente) geridas pelo curator, e uma seta tracejada mostra a próxima sessão recarregando o snapshot, sem nunca tocar a conversa viva.

O loop fechado, fim a fim: turno → fork de revisão → escrita durável → curator → a próxima sessão carrega o snapshot atualizado. A conversa viva nunca é tocada.

As peças, cada uma concreta no código:

Fork de revisão em segundo plano (agent/background_review.py): depois de um turno, spawn_background_review dispara uma daemon thread que reexecuta o snapshot da conversa num AIAgent forkado e pergunta "alguma skill/memória deve ser salva ou atualizada?". Roda com uma whitelist de ferramentas limitada a memory + gerenciamento de skill apenas, e herda o system prompt em cache do pai verbatim — então atinge o mesmo prefixo de cache e nunca toca a conversa viva.
Cutucadas de skill: o loop incrementa um contador _iters_since_skill e cutuca o modelo a persistir uma skill após iterações suficientes de chamada de ferramentas (agent/conversation_loop.py:644-648).
Curator (agent/curator.py): auto-gerencia o ciclo de vida das skills criadas pelo agente — ativa → obsoleta → arquivada, nunca deleta, skills fixadas são exceção, só skills com created_by: "agent" são tocadas.
A memória vive dentro do prompt: a camada volatile do system prompt guarda o snapshot da MEMORY.md + USER.md, que é exatamente por que elas são congeladas no início da sessão — mutá-las no meio quebraria o cache.

O curator é conservador: ele rebaixa, nunca apaga — e só mexe nas skills que o próprio agente criou.

A memória não é um banco consultado a cada turno: é um snapshot dentro do prompt, congelado para o cache sobreviver.

em uma frase

O fork é um clone que só pode escrever no diário (memory/skills). Ele lê o que aconteceu, decide o que guardar, escreve — e some. Sua conversa não muda; o ganho aparece amanhã.

o que o fork herda e o que ele pode

O fork herda do pai o runtime vivo (provider/model/base_url/credenciais/system prompt em cache), por isso bate no mesmo prefixo de cache e na mesma autenticação. A whitelist de ferramentas é restrita a memory + skill-management; tudo o mais é removido. É a contraparte de produção da implementação de referência hermes-mini-loop (§5.1).

A frase para levar à Lição 3

Para o Alembic, este loop inteiro — fork-após-turno → auto-revisão sob whitelist de memory/skill → escrita em stores duráveis → ciclo de vida do curator → a próxima sessão lê o snapshot atualizado — é o CLONE conceitual de maior valor, e ele compõe de forma limpa com o pipeline de validator/gates já existente do Alembic.

Não-bloqueante por design: a resposta sai na hora; o aprendizado acontece à parte, depois.

Exemplo guiado · seguindo um aprendizado da escrita até a próxima sessão

Você termina um turno em que o agente descobriu o comando exato para buildar seu projeto. O turno responde normalmente — nada de especial acontece na conversa.

run_conversation chama spawn_background_review: nasce uma daemon thread com um AIAgent forkado, herdando o prompt em cache.

O fork relê o snapshot e pergunta "vale uma skill/memória?". Com a whitelist memory+skill, ele grava o comando de build na MEMORY.md (ou cria uma skill).

O curator marca a skill nova como active e passa a acompanhar seu uso. A conversa viva e seu cache seguem intactos.

Agora você: abra a próxima sessão e peça o build. De onde vem a resposta — do modelo "lembrando", ou do snapshot recarregado no system prompt? (Do snapshot: a melhoria é real, mas adiada à carga da próxima sessão.)

A disciplina do mini-loop

O repositório hermes-mini-loop é uma implementação de referência mínima da mesma ideia, e ele enuncia a disciplina em três regras — as regras que impedem um loop auto-melhorante de se afogar no próprio ruído.

Regra	O que ela previne
Aprenda só com vitórias (score ≥ 0.7)	Sedimentar lições de turnos falhos ou de baixa confiança. Só sucessos validados viram memória durável.
Reforce, não duplique	Reencontrar o mesmo fato deve fortalecer a entrada existente, não anexar uma quase-cópia que incha o store limitado.
Recombine átomos provados	Skills novas são compostas de peças já validadas, em vez de inventadas do zero — melhoria por recombinação.

O portão 0.7 em ação: a vitória sobe e se funde por hash (reforça); o resto é descartado.

"Recombine átomos provados" é literal: o produto cartesiano de top-3 × top-3, no máximo 9 — nunca geração livre.

Segure o limiar 0.7 e o "reforce-não-duplique" — os dois reaparecem, portados verbatim, como o portão padrão e o comportamento de dedup do loop do Alembic na Lição 4.

O pipeline do mini-loop, um "tick" por invocação

get_winning_experiments filtra score >= 0.7 AND dry_run = 0 e ainda descarta linhas em que o scorer falhou (não se aprende de erro do scorer). persist_patterns usa ON CONFLICT(pattern_hash) DO UPDATE SET score = MAX(score, excluded.score), occurrences = occurrences + 1 — reencontrar reforça, nunca duplica, e o score é monotonicamente não-decrescente. A exploração é por recombinação limitada: produto cartesiano top-3 headers × top-3 footers, no máximo 9 candidatos. É o kernel mecânico por trás da manchete "se auto-melhora", em miniatura.

Confusões comuns

"O Hermes é um gateway de modelos." O gateway dele é um gateway de mensagens (Telegram/Discord/…), não de modelos. O papel de provedor de modelo está distribuído entre providers/ + plugins/model-providers/ + um proxy local compatível com OpenAI — um subsistema inteiramente diferente.

"O revisor em segundo plano muda a conversa atual." Não — é um fork. Ele escreve em stores duráveis; a conversa viva e seu cache de prompt nunca são mutados. "Se auto-melhora" é literal, porém adiado: a melhoria aparece na carga da próxima sessão.

"87 = o número de ferramentas." 87 é o número de arquivos em tools/. A exposição é controlada pelas 30 chaves de toolset; o orange-book conta ~64 ferramentas voltadas ao agente. Três números, três significados.

A confusão #1: o "gateway" do Hermes é de mensagens, não de modelos. Quem serve o modelo é outro subsistema.

Flashcard

Por que o fork de revisão herda o prompt em cache do pai?

clique para virar

Para bater no mesmo prefixo de cache (custo baixo) e na mesma autenticação — escrevendo em stores duráveis sem reconstruir nem tocar o contexto vivo.

Flashcard

Registrar uma ferramenta é o mesmo que expô-la ao agente?

clique para virar

Não. A auto-descoberta registra o schema (87 arquivos); a ferramenta só fica exposta se seu nome aparecer num toolset (30 chaves).

Flashcard

O que o limiar 0.7 do mini-loop previne?

clique para virar

Sedimentar lições de turnos falhos ou de baixa confiança. Só vitórias validadas (≥ 0.7) endurecem em memória durável.

Flashcard

Quais skills o curator gerencia — e o que ele nunca faz?

clique para virar

Só as created_by: "agent" (fixadas são exceção). Move ativa→obsoleta→arquivada; nunca deleta — o máximo é arquivar.

Recapitulando

Cinco slides — passe com as setas do teclado ou os botões. Cada um é uma ideia para levar à Lição 3.

Slide 1 · A regra de ouro

Não se funde o que não se entende

A fusão começou por um mapa — não por uma cópia. E o mapa é honesto: mergulho profundo nas prioridades, catálogo da cauda longa, fronteira de cobertura declarada.

Slide 2 · Duas restrições

Cache sagrado + cintura estreita

Tudo deriva de duas regras: o cache de prompt por conversa é sagrado e a capacidade vive nas bordas. Quando algo parece arbitrário, pergunte qual restrição ele protege.

Slide 3 · A dobradiça

Ferramentas que se auto-registram

Cada arquivo chama register() no import; a descoberta varre o diretório. Registrar ≠ expor — daí 87 arquivos, 30 toolsets, 64 ferramentas expostas.

Slide 4 · O loop fechado

Fork → escreve → próxima sessão

Um fork em daemon thread se auto-revisa sob whitelist de memory/skill e escreve em stores duráveis. A conversa viva nunca é tocada; o ganho aparece amanhã.

Slide 5 · A disciplina

0.7 · reforce, não duplique

Aprenda só com vitórias (≥ 0.7), reforce em vez de duplicar, recombine átomos provados. Esse limiar e essa dedup voltam verbatim na Lição 4.

Slide 1 / 5 Use ← →

Em uma frase, para você mesmo: "O Hermes se auto-melhora porque um ____ se auto-revisa sob uma whitelist de ____, escreve em ____ duráveis, e a ____ sessão lê o snapshot atualizado — sem nunca tocar o ____ de prompt." Se você consegue preencher as cinco lacunas, está pronto para a Lição 3.

Verifique

Revisão cumulativa

Três perguntas. A pontuação corre conforme você responde.

1. No Hermes, qual é a relação entre o 87 e o 30?

Correto: b. A auto-descoberta registra o schema (87 arquivos, muitos deles infra/helpers), mas uma ferramenta só fica exposta se seu nome estiver num toolset (30 chaves). As "64 ferramentas" do orange-book são ainda um terceiro número — as voltadas ao agente.

2. Por que a revisão em segundo plano roda num agente forkado, em daemon thread, com whitelist só de memory/skill?

Correto: d. A restrição #1 (o cache é sagrado) proíbe mutar a conversa viva. Um fork herda o prompt em cache verbatim, escreve em stores duráveis e deixa o turno principal intacto — então "se auto-melhora" é real, mas adiado à próxima sessão.

3. A regra "aprenda só com vitórias (score ≥ 0.7)" do mini-loop existe para prevenir o quê?

Correto: c. Um loop que aprende de tudo se envenena rápido. O piso de 0.7 (mais "reforce, não duplique" e "recombine átomos provados") mantém só vitórias validadas — e esse limiar exato é portado para o portão do Alembic na Lição 4.

Acertos: 0/3

As cinco coisas para nunca esquecer desta lição

Não se funde o que não se entende — o mapa vem primeiro, e ele declara a própria fronteira de cobertura.
Duas restrições governam tudo: o cache de prompt é sagrado e a capacidade vive nas bordas.
Ferramentas se auto-registram no import; registrar ≠ expor (87 arquivos, 30 toolsets, 64 expostas).
O loop fechado é um fork que escreve em stores duráveis sem tocar a conversa viva — auto-melhoria real, mas adiada.
A disciplina que evita o envenenamento: 0.7 · reforce-não-duplique · recombine átomos provados.

Pergunta para a Lição 3: se o loop fechado do Hermes é o CLONE de maior valor, onde exatamente ele se encaixa no pipeline de gates do Alembic — e o que precisa mudar para o "0.7" e o "reforce-não-duplique" valerem lá também? É isso que a matriz de fusão responde, item a item.