Engenharia reversa do Hermes

O Hermes Agent é o "agente de IA auto-aperfeiçoável" da Nous Research — uma base de código Python de mais de um milhão de linhas. Você não pode fundir o que não entende, então a fusão começou com 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 ciclo fechado de aprendizado que se tornou a razão inteira da fusão.

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

01 · O que é o Hermes

Antes de mapear peças, fixe a forma do todo. Em uma frase: o Hermes é um agente de IA pessoal que roda o mesmo núcleo de agente em várias superfícies — uma CLI, um gateway de mensagens (Telegram, Discord, Slack e ~20 outras plataformas), uma TUI Ink/React e um app desktop Electron. Construído pela Nous Research, licença MIT.

A analogia: um cérebro, muitas bocas

Pense num atendente que é a mesma pessoa esteja você falando com ele pelo telefone, pelo balcão ou por carta. O "cérebro" (o núcleo de agente) é um só; o que muda é a superfície por onde você chega até ele. É esse desenho — núcleo único, muitas bordas — que vai ecoar no Alembic.

Seus diferenciais de destaque, nas próprias palavras dele:

• Um ciclo 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-aprimoram durante o uso; busca de sessão FTS5 com sumarização por LLM para recall entre sessões. a parte que importa para nós
• Agnóstico de modelo — Nous Portal, OpenRouter (200+ modelos) e muitos outros; troque com hermes model, sem mudanças de código.
• Vive onde você vive — um processo gateway faz ponte entre Telegram / Discord / Slack / WhatsApp / Signal / CLI, com transcrição de áudio-memo.
• Delega e paraleliza — gera subagentes isolados para fluxos paralelos.
• Roda em qualquer lugar — seis backends de terminal atrás de uma ABC: local, Docker, SSH, Singularity, Modal, Daytona.

O "roda em qualquer lugar" tem a mesma estrutura do núcleo único: uma interface abstrata (ABC) esconde seis implementações de terminal. O agente fala com a ABC; trocar de execução (local → Docker → nuvem) não muda o código que a usa.

02 · As duas restrições de design das quais tudo decorre

Quase toda decisão estranha no Hermes faz sentido quando você conhece duas restrições. Elas não são detalhes — são o motivo de o sistema ter a forma que tem. Veja as duas primeiro em linguagem simples, depois no nível preciso.

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

03 · O linchpin: a arquitetura de auto-registro de tools

Esta é a ideia estrutural mais importante e mais portátil do Hermes — a peça que mais vale clonar. Em uma linha: as tools se auto-registram no momento do import; nada mantém uma lista central de imports.

A analogia: cada funcionário se apresenta ao chegar

Imagine uma recepção onde, em vez de o gerente manter uma lista de quem trabalha lá, cada funcionário assina o livro de ponto ao entrar. Para saber quem está no prédio, basta abrir a porta de cada sala — ninguém precisa atualizar uma lista mestre. É exatamente assim que as tools entram no registro do Hermes.

No concreto: cada arquivo de tool chama registry.register(...) no nível de módulo; um passo de descoberta faz glob no diretório e importa cada arquivo, e o side-effect do import popula o registro. Acompanhe a pilha de baixo para cima:

Por que o registry.py fica embaixo da pilha, sem dependências? Porque ele é o contrato: tudo o mais depende dele, e ele não depende de nada. São quatro responsabilidades concentradas num único lugar — é isso que permite que cada tool seja só um arquivo que se anuncia.

04 · O catálogo de tools (mapa por toolset)

Como o Hermes empacota capacidade? Pelas chaves de toolset de toolsets.py — bundles nomeados que uma plataforma herda. O mapa cita explicitamente browser, memory, skills e web como exemplos dessas chaves; somados aos diferenciais que nomeiam capacidades concretas (transcrição, subagentes, busca de sessão), eles desenham o catálogo. Use o mapa abaixo como índice — cada caixa é uma família, com as portagens que cada uma rende ao Alembic na Lição 03.

As chaves browser, memory, skills e web são nomeadas explicitamente no mapa (§1.9); transcrição, subagentes e busca de sessão FTS5 vêm dos diferenciais de §1.1. As "+ ~26 outras" são o restante das 30 chaves de toolset — [uncertain] o mapa não lista as 30 por nome, então só rotulamos as citadas.

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

Há uma nuance crucial em que o mapa insiste — e é a fonte de um número que é mal-citado. A auto-descoberta registra o schema de uma tool, mas a tool só é exposta a um agente se seu nome aparecer num toolset. Então três contagens diferentes descrevem três coisas diferentes — não as colapse num número só.

Sinta o funil você mesmo

Arraste para ver como a fração exposta muda. Mesmo registrando todos os arquivos, só os que estão num toolset chegam ao agente — a barra mostra a fração que de fato aparece para ele:

Resolva você: "essa tool chega ao agente?"

Você já viu a regra (registrar ≠ expor). Agora aplique-a passo a passo a um caso concreto — depois um exercício é seu. Recuperar o procedimento (não só ver o veredito) é o que fixa de verdade.

06 · O ciclo fechado de aprendizado — o "auto-aperfeiçoável", mecanicamente (§1.10)

A propriedade de destaque é concreta no código, não marketing. Após um turno, o agente pode forkar a si mesmo 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ê.

A analogia: um estagiário que toma notas depois da reunião

Pense num estagiário que, depois que a reunião acaba, relê a ata e anota no caderno da equipe o que valeu aprender — sem nunca interromper a reunião em si. A reunião (a conversa viva) segue intocada; as notas (memória durável) só são lidas na próxima reunião. É literalmente assim que o Hermes "se aperfeiçoa": de forma diferida, num fork.

As peças, cada uma concreta na fonte:

• Fork de revisão de fundo (agent/background_review.py): após um turno, spawn_background_review dispara uma thread daemon que reproduz o snapshot da conversa num AIAgent forkado e pergunta "alguma skill/memória deve ser salva ou atualizada?". Roda com uma whitelist de tools limitada a tools de memória + gerenciamento de skill apenas, e herda o system prompt em cache do pai literalmente — então acerta o mesmo prefix 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 tool.
• Curador (agent/curator.py): auto-gerencia o ciclo de vida de skills criadas pelo agente — active → stale → archived, nunca deleta, skills pinadas isentas, só skills created_by: "agent" tocadas.
• Memória vive dentro do prompt: o tier volatile do system prompt segura o snapshot de MEMORY.md + USER.md, que é exatamente por que são congelados no início da sessão — mutá-los no meio da sessão quebraria o cache.

Por que "congelar no início da sessão"? Porque a memória mora dentro do system prompt — e o system prompt é justamente o prefixo que o cache reusa. Veja onde o snapshot fica e por que ele tem de ficar imóvel durante a sessão:

E como o fork escreve memória sem invalidar o cache que ele próprio usa? Ele herda o mesmo prefixo: o revisor reaproveita o system prompt em cache do pai, então acerta o mesmo cache e suas escritas vão para o disco, não para a conversa.

O ciclo de vida do curador, como autômato

O curador nunca deleta — ele move skills entre estados. Acompanhe as transições; repare que dois estados são protegidos (skills pinadas e as não criadas pelo agente nunca entram no ciclo):

07 · A disciplina do mini-loop (§5)

O repo hermes-mini-loop é uma implementação de referência mínima da mesma ideia, e declara a disciplina como três regras — as regras que impedem um ciclo de auto-aperfeiçoamento de se afogar no próprio ruído. Sem elas, um loop que aprende de tudo rapidamente se envenena.

Segure o limite 0.7 e o "reforçar-não-duplicar" — ambos reaparecem, portados literalmente, como o portão padrão e o comportamento de dedup do ciclo do Alembic na Lição 4.

08 · Confusões comuns

Três armadilhas que aparecem sempre que alguém descreve o Hermes de memória. Cada uma vira uma das questões da revisão — guarde-as.

Como isso se encaixa

Esta lição não é um beco sem saída — é o primeiro elo de uma cadeia que termina em código rodando dentro do Alembic. O método de engenharia reversa (esta lição) produz dois mapas; os mapas alimentam a matriz de fusão; a matriz decide o que clonar; e o que foi clonado virou os subsistemas de @alembic/hermes que você vai abrir um a um nas Lições 07–13. Siga a cadeia — clique para iluminar cada degrau.

Os elos concretos — cada um leva à lição que aprofunda aquele degrau:

• Lição 03 · A matriz de fusão — o destino direto deste mapa: é onde cada capacidade do Hermes recebe um veredito CLONE/ADAPT/MERGE/IGNORE. Sem o mapa desta lição, a matriz não tem o que decidir.
• Lição 20 · O método de engenharia reversa — generaliza o que você acabou de ver num caso só: o procedimento reusável de "ler antes de fundir", aplicável a qualquer agente, não só ao Hermes.
• Lição 21 · O framework de fusão — formaliza os quatro vereditos (CLONE / ADAPT / MERGE / IGNORE) que a matriz da Lição 03 aplica item a item.
• Lições 07–09 · MemoryStore, reviewAndLearn, UsageStore + curador — o ciclo fechado da seção 06 desta lição, já embarcado: a memória durável, o passe de revisão e o ciclo de vida do curador, agora em TypeScript testado.
• Lições 10–13 · ClarifyGateway, web, SkillStore, mídia — as outras famílias de toolset do catálogo da seção 04, cada uma virou um subsistema concreto do pacote @alembic/hermes.

Na prática

Mapa é teoria; o subsistema embarcado é executável. Aqui você inspeciona com as próprias mãos o que esta lição mapeou — primeiro provando que o subsistema clonado passa nos testes, depois vendo o loop de aprendizado escrever e ler de uma store durável real. Tudo offline, $0, determinístico.

1 · Prove o subsistema embarcado

O ciclo fechado de aprendizado da seção 06 não ficou no papel — virou o pacote @alembic/hermes. Rode a suíte dele:

# a partir da raiz do repositório
pnpm --filter @alembic/hermes test
# exercita os subsistemas que este mapa decidiu clonar:
#   memory/  learning/  curator/  clarify/  web/  skills/  media/
# saída esperada (vitest):
#   ✓ src/memory/memory-store.test.ts
#   ✓ src/learning/review.test.ts
#   ✓ src/curator/curator.test.ts
#   Test Files  N passed (N)

Os arquivos de teste existem em packages/hermes/src/<subsistema>/*.test.ts (verificado). [uncertain] o número exato de testes/arquivos varia com a versão do repo — por isso não fixamos um total aqui; rode e leia a linha Test Files.

2 · Veja o loop de aprendizado escrever e ler

A peça-âncora desta lição é o ciclo fechado: escrever em stores duráveis que a próxima sessão lê. O CLI expõe exatamente essas stores via alembic memory — cinco substores append-only (episodic, semantic, procedural, decision, transcript). Anexe um aprendizado e depois liste-o:

# anexa um registro à store "semantic" (offline, append-only JSONL)
alembic memory semantic add --agent cli --record '{"text":"87 = arquivos, 30 = chaves de toolset"}'
# saída esperada:
#   memory semantic: appended <id> (agent cli)
#     <dataDir>/memory/semantic.jsonl

# lê de volta — newest-first — o que a "próxima sessão" enxergaria
alembic memory semantic list --agent cli
# saída esperada:
#   memory semantic: 1 record(s) under <dataDir>/memory/semantic.jsonl
#     <id> [agent cli] at <timestamp>

Sinopse real (de apps/cli/src/args.ts + index.ts): alembic memory <substore> <add|list> [--agent <id>] [--dir <path>] [--record <json>] [--limit <n>]. add exige --record <json>; list aceita --agent/--limit; a store padrão é <dataDir>/memory/<substore>.jsonl. É o mesmo "MemoryStore" da Lição 07, pela borda da CLI.

Fixe os conceitos (flashcards)

Clique pra virar. Tente lembrar a resposta antes de virar — recuperação ativa fixa mais que reler.