Hermes com capacete alado revisa uma planta de arquitetura de sistemas ao lado de um pinguim Linux, com uma janela colorida inspirada no Windows ao fundo.

Hermes Agent por dentro: arquitetura, harness, identidade e contexto Link para o cabeçalho

Este texto começa uma série sobre o Hermes Agent. A ideia não é traduzir a documentação oficial linha por linha, nem vender a ferramenta como solução mágica para tudo. O objetivo é mais útil: entender como o Hermes pensa, como ele monta contexto, onde entra a personalidade, o que ele guarda em memória, por que skills importam e como ele se diferencia de CLIs modernas como Codex CLI e Claude Code.

Se você ainda não instalou a ferramenta, vale começar pelo tutorial prático de instalação do Hermes Agent no Windows com WSL2 . Este artigo assume que você já entendeu o básico: Hermes é uma ferramenta de agente, roda no terminal, conversa com modelos diferentes, usa ferramentas e pode operar por canais como Telegram, Discord, Slack ou WhatsApp.

Mas a pergunta importante é outra: o que faz o Hermes ser o Hermes?

A resposta curta é: o harness.

O que esta série vai cobrir Link para o cabeçalho

Esta série tem cinco partes:

este primeiro texto explica arquitetura, harness, identidade e contexto;
o segundo mergulha em identidade e memória: SOUL.md, USER.md, MEMORY.md, session search e providers;
o terceiro mostra perfis, múltiplos agentes e isolamento de estado;
o quarto destrincha CLI, comandos, /queue, /steer, skills e autoaprendizado;
o quinto fala de gateway, segurança, Docker, containers, ACP e CLIs externas.

O fio condutor é simples: agentes modernos não são apenas modelos de linguagem. Um agente é o resultado de modelo, contexto, ferramentas, memória, permissões, interface e ciclo de execução. Troque qualquer uma dessas camadas e o comportamento muda.

É por isso que dois agentes usando um modelo parecido podem agir de maneiras muito diferentes.

Modelo, harness e agente Link para o cabeçalho

Antes de falar de Hermes, precisamos separar três palavras que costumam ser misturadas: modelo, harness e agente.

O modelo é o LLM. Ele recebe contexto e gera resposta. Pode ser um modelo via OpenAI, Anthropic, OpenRouter, Nous Portal ou outro provedor compatível. O modelo é o motor cognitivo, mas não sabe sozinho quais arquivos existem, quais comandos pode executar, qual usuário está autorizado ou como retomar uma tarefa interrompida.

O harness é a infraestrutura ao redor do modelo. É ele que monta o prompt, injeta regras do projeto, expõe ferramentas, executa comandos, coleta resultados, pede aprovação, gerencia sessão, controla memória, compacta contexto, roteia mensagens e registra logs. Em termos práticos: se o modelo é o cérebro, o harness é o corpo, o sistema nervoso, a mesa de trabalho e o conjunto de regras de segurança.

O agente é o comportamento que nasce da combinação dos dois. Modelo mais harness, mais instruções, mais ferramentas, mais permissões, mais ambiente.

Essa distinção muda a forma de avaliar qualquer ferramenta agentiva. Quando alguém diz “o Codex é melhor nisso” ou “o Claude Code respondeu diferente” ou “o Hermes parece mais persistente”, nem sempre a diferença está no modelo. Muitas vezes está no harness.

Fluxo explicativo mostrando que o modelo LLM entra no harness, que combina prompt, ferramentas, sessão, memória, permissões e limites para formar o agente em operação.

Por que o harness importa tanto Link para o cabeçalho

Pense em três ferramentas:

Codex CLI;
Claude Code;
Hermes Agent.

Todas podem trabalhar com código. Todas podem ler arquivos, raciocinar sobre uma tarefa, usar ferramentas, operar com algum modelo de permissão e produzir alterações. Também existe uma zona comum importante: as três podem se conectar a ferramentas externas por MCP ou mecanismos equivalentes, carregar instruções de projeto e transformar uma conversa em ação.

Então a comparação boa não começa em “qual delas sabe programar?”. Começa em “qual harness organiza melhor o trabalho que eu quero fazer?”.

Tema	Leitura prática
Igual	Código, arquivos, instruções, ferramentas, permissões, MCP, skills e automação.
Codex	Mais natural como agente de repo, sandbox e tarefa local de engenharia.
Claude	Mais natural como sessão de projeto, hooks, permissões e subagents.
Hermes	Mais natural como agente persistente: memória, skills, gateway, cron, backends e ACP.

O Codex CLI é muito forte como agente de desenvolvimento no workspace. Ele entra em um repositório, respeita instruções como AGENTS.md, opera com sandbox, executa tarefas de código, faz revisão e pode rodar de modo não interativo com codex exec. O harness dele favorece trabalho local em repositório, controle de permissões e iteração de engenharia.

O Claude Code é um ambiente interativo de codificação com forte foco em sessão, permissões, hooks, plugins, skills, MCP, subagents e integração com projeto. Ele lê CLAUDE.md, trabalha com modos de permissão, permite chamadas programáticas pela CLI e tem um fluxo bem rico de sessão contínua. Se o Codex parece mais “engenheiro de repo”, o Claude Code parece mais “parceiro de projeto” com uma superfície de extensão muito bem integrada.

O Hermes Agent tenta outra coisa. Ele também pode codificar, também usa ferramentas, também conversa com MCP e também pode aparecer em fluxos de editor via ACP. Mas sua tese é mais ampla: ser um agente persistente, com identidade global, memória, skills, gateway de mensagens, cron, backends de execução, plugins e delegação. Ele não quer ser apenas “a CLI que mexe no repo”. Ele quer ser um agente que continua existindo depois do terminal, conversa por canais externos e acumula procedimento.

É nesse ponto que o Hermes se diferencia. Ele combina recursos que aparecem parcialmente nos outros ambientes em uma arquitetura voltada para continuidade:

MCP e plugins ampliam a superfície de ferramentas;
skills viram procedimentos reutilizáveis, não apenas documentação solta;
memória e busca de sessões dão continuidade entre conversas;
gateway e cron permitem presença fora do terminal;
backends de execução e ACP separam onde o agente roda de onde você conversa com ele.

Isso não torna o Hermes superior a Codex CLI e Claude Code em qualquer cenário. Para um ajuste cirúrgico em um repositório, Codex CLI pode ser mais direto. Para uma sessão intensa de desenvolvimento dentro de um projeto, Claude Code pode ser mais natural. O Hermes fica mais interessante quando o trabalho precisa sobreviver ao terminal: lembrar, reutilizar procedimento, responder por canais externos, agendar tarefas e operar como um agente persistente.

É aqui que entra a ideia de valor composto. Um Hermes recém-instalado pode responder uma tarefa, mas um Hermes usado com cuidado por semanas começa a carregar sessões, memória, skills e hábitos operacionais. O ponto não é o agente “ficar mágico”; é o harness ter mais material curado para decidir melhor como trabalhar.

O resultado é que a mesma tarefa pode se transformar dependendo do harness:

no Codex CLI, “corrija esse bug” vira uma tarefa de engenharia no workspace;
no Claude Code, vira uma sessão interativa ou programática de desenvolvimento com permissões e hooks;
no Hermes, pode virar uma conversa que consulta memória, carrega skills, aciona terminal, delega para outro agente e depois salva um aprendizado.

Esse é o ponto: o harness define o formato do trabalho.

A arquitetura do Hermes em uma visão só Link para o cabeçalho

O infográfico abaixo olha para essa arquitetura por um ângulo operacional. Em vez de tratar o Hermes como apenas mais uma CLI, ele mostra entradas, camadas internas, saídas e comparação de harness ao redor de um agente persistente.

Infográfico do Hermes Agent mostrando CLI, gateway, ACP e API como entradas para o AIAgent; resposta, ação e aprendizado como saídas; camadas internas como contexto, memória, skills, ferramentas, permissões e provider; e uma comparação entre Codex CLI, Claude Code e Hermes.

A documentação de arquitetura do Hermes apresenta o sistema como um conjunto de entrypoints que convergem para uma classe central chamada AIAgent.

Os entrypoints incluem:

CLI;
gateway;
ACP;
batch runner;
API server;
uso como biblioteca Python.

Essas entradas diferentes chegam ao mesmo núcleo. O Hermes não tem um “agente de Telegram” e outro “agente de CLI” completamente separados. A diferença está na camada de entrada e saída. O centro é o AIAgent, responsável pelo ciclo de conversa.

Dentro desse núcleo, três blocos são especialmente importantes, mas eles não devem ser lidos como caixinhas independentes em paralelo. O AIAgent é o orquestrador. Ele monta contexto, resolve runtime, chama o modelo, interpreta tool calls, aplica limites e persiste a sessão.

prompt builder: monta o prompt do sistema;
provider resolution: escolhe provedor, modelo, modo de API e credenciais;
tool dispatch: recebe chamadas de ferramenta do modelo e executa no runtime correto.

Ao lado disso, há:

armazenamento de sessão em SQLite com FTS5;
backends de terminal, incluindo local, Docker, SSH, Daytona, Modal, Singularity e outros;
ferramentas de arquivos, terminal, browser, web, visão, memória e MCP;
plugins;
cron;
gateway;
ACP para integração com editores.

Essa arquitetura explica por que o Hermes parece mais “plataforma de agente” do que “CLI de código”. A CLI é só uma das portas. O centro é o loop: entrada, contexto, modelo, ferramentas, observação, resposta e persistência.

O ciclo de uma sessão CLI Link para o cabeçalho

Em uma sessão tradicional, o fluxo é parecido com isto:

Usuário digita uma mensagem
  -> HermesCLI processa a entrada
  -> AIAgent carrega histórico/contexto da sessão quando aplicável
  -> prompt builder monta system prompt, memória, skills e contexto
  -> provider resolution escolhe provedor, modelo, API mode e credenciais
  -> chamada ao modelo via provider
  -> modelo responde ou pede uma ferramenta
  -> AIAgent avalia aprovação, limites e risco
  -> tool dispatch executa a ferramenta no backend correto
  -> resultado volta para o modelo
  -> resposta final é exibida
  -> Session Storage salva mensagens, metadados e tool calls

Esse é o loop básico observar, agir, observar, responder. O modelo não executa comandos diretamente. Ele pede uma ação em formato estruturado. O harness decide se aquela ação existe, se está disponível, se precisa de aprovação, onde será executada e como o resultado volta para o modelo.

Um detalhe evita confusão: o Session Storage não é o “provider”. Ele guarda histórico, mensagens, metadados, snapshot de prompt, configuração de modelo e chamadas de ferramenta. Quem consulta e combina essas peças é o AIAgent. O provider recebe a chamada já preparada para o modo correto de API, com mensagens, parâmetros e ferramentas disponíveis.

É aqui que o comportamento real nasce. Um modelo sozinho não tem terminal. O harness dá terminal. Um modelo sozinho não tem memória. O harness injeta memória. Um modelo sozinho não sabe que você prefere patches pequenos. O harness pode carregar isso de USER.md, MEMORY.md, AGENTS.md, CLAUDE.md ou SOUL.md.

Prompt builder: onde o Hermes vira uma pessoa operacional Link para o cabeçalho

No Hermes, o prompt não é uma string fixa. Ele é montado a partir de camadas:

identidade global;
memória;
skills;
contexto de projeto;
orientação de uso de ferramentas;
instruções específicas do modelo.

A camada mais interessante para entender personalidade é o SOUL.md.

SOUL.md: identidade global do agente Link para o cabeçalho

O SOUL.md é o arquivo de identidade global do Hermes. Ele vive no HERMES_HOME, normalmente ~/.hermes/SOUL.md, e define quem aquele agente é por padrão.

Na documentação do Hermes, essa camada não é tratada como detalhe cosmético. O SOUL.md entra como identidade primária, no primeiro espaço do prompt de sistema. Antes de memória, contexto de projeto e ferramentas, o Hermes precisa saber que tipo de agente ele está tentando ser.

Também há um detalhe operacional importante: o SOUL.md é carregado a partir do HERMES_HOME, não do diretório atual do projeto. Se ele não existir, o Hermes cria um arquivo inicial. Se já existir, não sobrescreve. Se estiver vazio, ele cai para a identidade padrão. Isso evita que cada repositório mude, sem querer, a personalidade global do agente.

Isso é diferente de uma regra de projeto. Uma regra de projeto diz algo como:

Use TypeScript estrito.
Rode os testes antes de finalizar.
Não edite o diretório generated/.

Uma identidade global diz algo como:

Você é um parceiro técnico cuidadoso, direto e curioso.
Prefere investigar antes de alterar arquivos.
Explica riscos sem dramatizar.
Quando houver ambiguidade, pergunta antes de executar ações irreversíveis.

O SOUL.md responde à pergunta “quem é este agente?”. O AGENTS.md, .hermes.md ou CLAUDE.md respondem à pergunta “como trabalhar neste projeto?”.

Misturar as duas coisas deixa o agente confuso. Se você coloca detalhes de um repositório dentro do SOUL.md, essa instrução vai acompanhar o Hermes em outros contextos onde talvez não faça sentido. Se você coloca personalidade dentro do AGENTS.md, ela fica presa ao projeto e pode conflitar com outras regras.

Um jeito útil de pensar nisso é chamar o SOUL.md de contrato operacional. Ele pode dizer qual é o papel do agente, como ele fala em conversas privadas, como escreve para público externo, quando deve discordar, quais evidências precisa trazer antes de discordar e quais ações sempre exigem aprovação. Esse uso aparece em relatos práticos de usuários avançados, como Tony Simons, mas precisa de cuidado: contrato operacional não é lista de tarefas.

Prioridades vivas, projetos ativos, histórico de decisões e detalhes que mudam toda semana tendem a envelhecer mal dentro do SOUL.md. Se a informação é pessoal e estável, pode caber em USER.md. Se é lembrança operacional densa, pode caber em MEMORY.md. Se é regra de repositório, fica melhor em AGENTS.md, .hermes.md ou equivalente.

Como dar personalidade sem estragar o agente Link para o cabeçalho

Um bom SOUL.md deve ser estável, curto e operacional.

Exemplo ruim:

Você é um gênio absoluto, nunca erra, responde tudo com ironia e sempre executa
qualquer comando sem perguntar.

Esse texto é ruim porque combina vaidade, estilo invasivo e autorização perigosa. Um agente com ferramentas não deve ser incentivado a fingir certeza nem a atropelar aprovação.

Exemplo melhor:

Você é um assistente técnico sênior, cuidadoso e colaborativo.
Investiga antes de alterar arquivos.
Quando executa uma tarefa, prioriza mudanças pequenas, verificáveis e reversíveis.
Explica incertezas com clareza.
Discorde quando houver evidência de risco, escopo inchado ou objetivo mal definido.
Em tarefas de código, respeita instruções locais do projeto acima de preferências genéricas.

Esse tipo de identidade influencia tom e postura sem sequestrar a execução.

Essa parte da discordância é mais importante do que parece. Um bom SOUL.md não manda o agente ser contrariado por esporte. Ele manda discordar quando há motivo, exemplo, risco ou alternativa melhor. O objetivo não é criar um personagem grosseiro; é impedir que o agente vire uma máquina cara de concordar com tudo.

Context files: regras do projeto Link para o cabeçalho

Além do SOUL.md, o Hermes descobre arquivos de contexto do projeto.

A documentação lista estes arquivos principais:

.hermes.md ou HERMES.md;
AGENTS.md;
CLAUDE.md;
.cursorrules;
.cursor/rules/*.mdc.

Existe uma prioridade: o Hermes carrega apenas um tipo principal de contexto de projeto por sessão, seguindo a ordem documentada. O SOUL.md é independente e sempre entra como identidade global.

Isso importa muito. Se o projeto tiver .hermes.md, ele ganha prioridade sobre AGENTS.md. Se não tiver, AGENTS.md pode ser usado. Se não tiver, CLAUDE.md pode entrar. A ideia é permitir interoperabilidade com ecossistemas modernos sem transformar o prompt em um acúmulo de regras concorrentes.

AGENTS.md no Hermes Link para o cabeçalho

O AGENTS.md é especialmente importante porque também é usado por outras ferramentas, como Codex. No Hermes, ele pode funcionar como arquivo de instruções de projeto: estrutura, comandos, estilo de código, restrições, validações e cuidados.

Um bom AGENTS.md diz coisas como:

Antes de editar, rode a suíte de testes relevante.
Use pnpm, não npm.
Não altere arquivos em migrations/ sem aprovação.
Componentes React devem seguir o padrão de src/components/ui.

Isso não é personalidade. É contrato de trabalho.

Comparando o fluxo de contexto: Hermes, Codex e Claude Code Link para o cabeçalho

Agora dá para comparar com mais precisão.

No Hermes, o contexto nasce de quatro fontes fortes:

identidade global em SOUL.md;
contexto de projeto em .hermes.md, AGENTS.md, CLAUDE.md ou equivalentes;
memória persistente em MEMORY.md e USER.md;
skills carregadas quando fazem sentido.

O Hermes também pode ser acionado pelo gateway, por cron ou por ACP. Isso significa que o contexto não está preso ao terminal onde você digitou a tarefa.

No Codex CLI, o fluxo é mais centrado no repositório e na execução local. Você entra em um workspace, fornece uma tarefa, o Codex lê instruções como AGENTS.md, opera sob uma política de sandbox e aprovação e entrega uma alteração ou análise. O contexto principal é o estado do repo, a tarefa e as regras locais.

No Claude Code, o fluxo é centrado em sessão de projeto, CLAUDE.md, configurações, ferramentas permitidas, hooks, plugins, MCP e modos de permissão. Ele tem uma experiência muito forte de “parceiro de desenvolvimento dentro de um projeto”, com recursos de automação e integração.

A diferença não é “um sabe programar e outro não”. A diferença é o harness.

Provider resolution: modelo não é só nome de modelo Link para o cabeçalho

Outra peça importante é a resolução de provider. O Hermes não só guarda “usar modelo X”. Ele precisa resolver:

qual provedor será usado;
qual modelo;
qual modo de API;
qual chave ou credencial;
qual fallback se o provedor falhar;
como lidar com OAuth, endpoints compatíveis e aliases.

Isso importa porque o Hermes tenta ser multi-provedor. O mesmo prompt pode ir para provedores diferentes, mas o harness precisa adaptar formato de mensagens, ferramentas e credenciais. A documentação de arquitetura cita três modos de API no núcleo: chat completions, Codex responses e Anthropic messages.

Na prática, isso significa que “trocar de modelo” não é apenas trocar uma string. Pode mudar formato de ferramenta, contexto disponível, streaming, limites e comportamento de fallback.

Tool dispatch: a mão do agente Link para o cabeçalho

O sistema de ferramentas é a parte que permite que o Hermes faça coisas.

A documentação fala em dezenas de ferramentas e toolsets. Há ferramentas de:

terminal;
arquivos;
busca web;
browser;
visão;
memória;
execução de código;
delegação;
MCP;
processos em background.

O detalhe importante é que as ferramentas são organizadas em toolsets. Isso permite ligar e desligar capacidades por plataforma, sessão ou modo. Um Hermes rodando no gateway pode ter um conjunto diferente de ferramentas de um Hermes rodando no ACP dentro de um editor.

Essa é uma boa prática de harness: não dar todas as ferramentas para todas as situações.

Session storage: memória da conversa não é memória permanente Link para o cabeçalho

O Hermes salva sessões em SQLite com FTS5. Isso significa que conversas passadas podem ser pesquisadas, resumidas e recuperadas.

Mas isso não é a mesma coisa que MEMORY.md.

Sessão é histórico. Memória é contexto curado. Histórico responde “falamos disso em algum momento?”. Memória responde “isso é importante o suficiente para estar sempre disponível?”.

Essa diferença será o centro do segundo artigo.

Gateway: quando a CLI sai do terminal Link para o cabeçalho

O gateway é uma das peças que mais diferenciam o Hermes de uma CLI tradicional. Ele é um processo de longa duração que conecta plataformas de mensagem ao mesmo núcleo do agente.

Em vez de você abrir o terminal e digitar hermes, o gateway recebe uma mensagem do Telegram, Discord, Slack, WhatsApp, Email ou outro canal, autoriza o usuário, resolve a sessão, cria ou retoma um AIAgent, executa a conversa e entrega a resposta pelo canal.

É aqui que o Hermes começa a parecer um agente pessoal persistente.

Também é aqui que os riscos aumentam. Um agente com gateway, terminal e ferramentas precisa de segurança séria. Falaremos disso no quinto post.

ACP: o Hermes dentro do editor Link para o cabeçalho

ACP significa Agent Client Protocol. É um protocolo para conectar agentes de codificação a editores e clientes compatíveis.

No Hermes, hermes acp inicia o agente como servidor ACP via stdio/JSON-RPC. Isso permite que um editor compatível renderize mensagens, tool activity, diffs, comandos de terminal, aprovações e streaming.

O ponto importante é que ACP não transforma o Hermes em Codex, nem transforma Codex em Hermes. ACP é uma ponte de interface. O harness continua importando.

Se você usa Hermes via ACP, está usando o harness do Hermes em uma experiência de editor. Se usa Codex via ACP, continua usando o harness do Codex. Se usa Claude Code via ACP, continua usando o harness do Claude Code.

Essa distinção evita uma confusão comum: interoperabilidade não apaga identidade operacional.

Quando o Hermes não é a ferramenta certa Link para o cabeçalho

Hermes pode codificar, mas nem toda tarefa de código precisa passar por ele.

Se você quer uma alteração cirúrgica em um repositório local, com foco em sandbox, revisão e execução direta, Codex CLI pode ser o caminho mais natural.

Se você quer uma sessão interativa de desenvolvimento com Claude Code, usando CLAUDE.md, hooks, permissões, plugins e subagents, talvez faça sentido abrir Claude Code diretamente.

Se você quer um agente persistente, com memória, skills, gateway, cron e multi-canal, Hermes começa a brilhar.

O truque é parar de escolher por marca e começar a escolher por harness.

Checklist mental Link para o cabeçalho

Antes de configurar o Hermes, responda:

Qual é a identidade global que este agente deve ter?
Quais regras pertencem ao projeto, não ao agente?
O que precisa ser memória permanente?
Quais ferramentas ele realmente deve usar?
Ele precisa de gateway ou só CLI?
Ele precisa codificar diretamente ou pode chamar outra CLI especializada?
Qual sandbox ou backend limita melhor o risco?

Essas perguntas valem mais do que sair instalando skill, plugin e provider sem direção.

Conclusão Link para o cabeçalho

O Hermes Agent é melhor entendido como um harness completo para agentes persistentes. A CLI é uma face dele. O gateway é outra. O ACP é outra. O cron é outra. O centro é o mesmo: um AIAgent que monta contexto, resolve provider, chama ferramentas, salva sessão e opera dentro das fronteiras configuradas.

A diferença entre Hermes, Codex CLI e Claude Code não está apenas em modelo. Está em como cada ferramenta organiza o trabalho.

O Codex CLI tende a parecer um engenheiro de repo porque seu harness favorece workspace, sandbox e tarefa de código. O Claude Code tende a parecer um parceiro interativo de desenvolvimento porque seu harness favorece sessão, permissões, hooks e projeto. O Hermes tende a parecer um agente persistente porque seu harness favorece identidade, memória, skills, gateway e automação.

No próximo post, vamos abrir a parte mais delicada dessa história: memória. O que o Hermes guarda, onde guarda, quando deve guardar e por que lembrar demais pode ser tão perigoso quanto esquecer tudo.

Hermes Agent por dentro: arquitetura e harness