Hermes Agent com Ollama: memória, ferramentas e limites

#O que é o Hermes Agent

Hermes Agent (repositório NousResearch/hermes-agent) é um agente autônomo em linha de comando, com interface TUI, gateway de mensagens (Telegram, Discord, Slack, WhatsApp, Signal) e um sistema de habilidades que se criam e aprimoram com o uso. Ele não substitui o Hermes 4, que é um modelo de linguagem: o Hermes Agent é o software que coordena as chamadas de ferramentas, a memória e o terminal, independentemente do modelo conectado.

O repositório mantém um ritmo intenso de desenvolvimento: a versão com a tag v2026.9.24 (Hermes Agent v0.21.5), publicada em 24 de setembro de 2026, reúne várias centenas de correções desde a versão anterior. O projeto é publicado sob licença MIT pela Nous Research, o que permite uso profissional sem pagamento de royalties, inclusive em uma implantação modificada.

O agente roda em um único processo de gateway capaz de atender vários canais ao mesmo tempo: terminal local, Telegram, Discord, Slack, WhatsApp e Signal compartilham a mesma memória e o mesmo histórico de conversa. Isso permite iniciar uma tarefa na sua estação de trabalho e depois acompanhá-la pelo celular, sem duplicar a configuração do modelo nem a memória de um canal para outro.

#Conectar Ollama localmente

O Hermes Agent faz o roteamento para provedores auto-hospedados compatíveis com a OpenAI (Ollama, vLLM, llama.cpp), usando o nome de provedor próprio de cada um. A documentação oficial é explícita quanto ao formato esperado: um base_url apontando para o servidor e uma chave de API vazia que serve apenas como marcador de posição.

auxiliary:
  compression:
    provider: ollama
    model: qwen3.6:27b-q4_k_m
    base_url: http://127.0.0.1:11434

Uma base_url reduzida a apenas um host:port (sem /v1) recebe automaticamente o sufixo esperado pela API compatível com a OpenAI: não é necessário adicioná-lo manualmente. Esse mesmo mecanismo funciona para vLLM e llama.cpp, basta apenas mudar o nome do provedor e a porta.

Este mesmo bloco de configuração pode ser direcionado a funções diferentes: o modelo principal de conversa, o modelo de compressão de contexto ou o modelo usado para gerar um título de sessão. Cada um pode apontar para um provedor distinto — por exemplo, um modelo Ollama local para a conversa e um modelo na nuvem mais rápido reservado às tarefas auxiliares — o que permite manter a confidencialidade na maior parte das interações, evitando ao mesmo tempo que um pequeno modelo local torne as tarefas secundárias mais lentas.

#Qual modelo para chamada de ferramentas

Hermes Agent expõe mais de 40 ferramentas (terminal, arquivos, navegador, memória, cron) que o modelo deve invocar por chamadas estruturadas, e não por uma simples descrição em texto. Um modelo Ollama que não foi treinado para chamada de ferramentas — ou uma quantização excessivamente agressiva do mesmo modelo — costuma responder com uma explicação em vez de disparar a chamada.

Modelo principal de conversa

Prefira uma variante Ollama explicitamente listada como compatível com ferramentas (marcação tools no ollama.com/library) em vez de um modelo genérico de chat.

Modelo auxiliar (títulos, compressão)

Pode continuar sendo leve: o Hermes Agent o chama após a resposta do turno principal quando usa um provedor local com um único slot, sem executar as chamadas em paralelo, para evitar que um servidor com um único slot misture as duas requisições.

Formato de identificador

Um provedor com um nome definido pode adicionar um prefixo ao identificador do modelo, por exemplo, ollama-local/qwen3.6:27b-q4_k_m; esse prefixo também se aplica quando apenas a requisição bruta (sem prefixo) chega ao servidor.

Um fato a acompanhar de perto: em um provedor local personalizado, a chamada ao modelo de título é enviada após a chegada da resposta da rodada, não ao mesmo tempo que ela. Em um servidor local que processa apenas uma requisição por vez, isso evita que uma requisição de título em JSON estruturado interrompa a geração da própria resposta — um detalhe de escalonamento raramente documentado em outros lugares.

#Memória: o que realmente persiste

A memória do Hermes Agent está baseada em arquivos de texto simples, legíveis e modificáveis diretamente: MEMORY.md e USER.md no diretório de perfil. O modelo decide, por meio de uma ferramenta dedicada, o que vale a pena armazenar neles — preferências, fatos duradouros, procedimentos aprendidos.

cat ~/.hermes/memories/MEMORY.md
cat ~/.hermes/memories/USER.md

O ponto fraco documentado pelo próprio projeto: um pequeno modelo local pode afirmar "está gravado" sem realmente ter chamado a ferramenta de escrita. A documentação oficial recomenda, para um modelo local com menos de cerca de 30 bilhões de parâmetros ou que não seja confiável ao chamar ferramentas, pedir explicitamente o uso da ferramenta de memória e depois verificar o arquivo — em vez de multiplicar as instruções no prompt.

#Segurança: oito camadas, não um muro

A Nous Research documenta um modelo de segurança com oito camadas: autorização de usuários, aprovação humana de comandos perigosos, mecanismos de proteção na gravação de arquivos, isolamento por contêiner (Docker, Singularity, Modal), filtragem das credenciais transmitidas aos servidores MCP, detecção de injeção de prompt nos arquivos de contexto, isolamento entre sessões e validação dos caminhos de trabalho das ferramentas de terminal.

A aprovação de comandos perigosos é configurada via approvals.mode no arquivo de configuração, com três modos disponíveis: automático, manual ou inteligente (modo padrão recomendado, que aprova ações de baixo risco e bloqueia as demais para validação).

#Limites de um modelo pequeno local para este agente

Um agente com tantas ferramentas quanto o Hermes Agent exige muito da capacidade do modelo de seguir instruções: memória, planejamento, chamadas de ferramentas encadeadas e, às vezes, subagentes em paralelo. Em um modelo de 7 a 14 bilhões de parâmetros com quantização Q4_K_M, espere falhas nas chamadas de ferramentas, confirmações sem execução real e compressão de contexto mais frequente em sessões longas.

Nada disso é específico do Hermes Agent: é a limitação conhecida dos pequenos modelos quantizados diante de formatos de saída estruturados. A resposta documentada pelo projeto não é adicionar instruções, mas usar um modelo mais robusto, pelo menos na fase de configuração inicial. Depois que as entradas forem registradas na memória, um modelo mais leve poderá relê-las sem problemas, pois elas chegam diretamente ao prompt de sistema.

Os subagentes e os scripts Python que chamam as ferramentas por RPC — duas funções destacadas pelo projeto para paralelizar tarefas — dependem da mesma capacidade de seguir instruções que uma chamada simples de ferramenta. Um modelo que já tem dificuldade com uma chamada isolada terá ainda mais dificuldade para coordenar vários subagentes sem misturar seus respectivos contextos: é melhor validar o comportamento básico antes de ativar essas funcionalidades avançadas.

#Servidores MCP: catálogo e permissões

O Hermes Agent inclui um catálogo de servidores MCP revisados e integrados pela equipe da Nous Research (Linear, GitHub, Figma e Asana, entre outros), mas cada servidor permanece desativado por padrão: é necessário instalá-lo explicitamente antes que ele fique acessível ao agente. Depois que as credenciais são informadas, o Hermes Agent consulta o servidor para listar as ferramentas que ele disponibiliza e exibe uma lista com caixas de seleção, evitando ativar de uma só vez todos os recursos de um servidor de terceiros ainda pouco conhecido.

Detalhe que poucos tutoriais mencionam: para servidores MCP em modo stdio, o Hermes Agent não transmite o ambiente shell completo da máquina ao subprocesso. Apenas as variáveis explicitamente declaradas na configuração do servidor, mais um conjunto mínimo (PATH, HOME, USER, LANG, TERM, SHELL, por exemplo), são passadas; as demais variáveis de ambiente, incluindo chaves de API e tokens, são filtradas. É esse mecanismo que reduz o risco de um servidor MCP de terceiros mal auditado acessar um segredo presente no shell.

• Entender o protocolo MCP

#Subagentes: o que a delegação permite

A ferramenta delegate_task permite que o Hermes Agent delegue uma tarefa a um agente filho: cada subagente inicia sua própria conversa, com sua própria sessão de terminal, e herda apenas as ferramentas já ativadas para o agente pai — não pode conceder a si mesmo uma capacidade adicional que o pai não tenha. Apenas o resumo final do subagente é incorporado ao contexto do agente principal; as chamadas intermediárias de ferramentas nunca são incluídas, o que limita o consumo de contexto em tarefas longas e evita poluir a conversa principal com detalhes de execução.

Por padrão, até dez subagentes podem funcionar em paralelo — um limite configurável, sem limite de hardware imposto pelo software — mas a profundidade de delegação padrão permanece em 1: um subagente não pode criar outros subagentes a menos que esse comportamento seja ativado explicitamente na configuração. Em um modelo local de 7 a 14B, é melhor manter essa profundidade em 1: cada nível adicional de delegação multiplica o número de chamadas de ferramentas que precisam ser encadeadas corretamente, exatamente o ponto fraco identificado acima para modelos pequenos quantizados.

#Solução de problemas: sintomas, causa, correção

A maioria dos problemas com um endpoint local do Ollama se resume a quatro grupos de sintomas, cada um com uma causa identificável na documentação oficial, em vez de uma hipótese baseada em tentativa e erro.

O Hermes Agent detecta automaticamente os endpoints locais e amplia os limites de tempo de leitura de acordo com isso, mas um contexto volumoso em um modelo Ollama lento ainda pode exceder esse limite padrão; a documentação oficial recomenda ajustar a variável HERMES_STREAM_READ_TIMEOUT em vez de reduzir arbitrariamente o contexto enviado ao modelo.

#Instalação prática

1. 01
   Instalar Hermes Agent

   No Linux, macOS ou WSL2: curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash, depois recarregar o shell e iniciar hermes.
2. 02
   Preparar o modelo Ollama

   Verificar se o Ollama está rodando na porta 11434 e se o modelo escolhido é anunciado como compatível com chamadas de ferramentas antes de declará-lo como provedor.
3. 03
   Declarar o provedor local

   Usar hermes config set para preencher provider: ollama, o nome do modelo e base_url http://127.0.0.1:11434, com uma chave de API vazia.
4. 04
   Testar uma chamada simples de ferramenta

   Pedir uma ação verificável (listar um diretório, ler um arquivo) e confirmar no terminal que a ferramenta foi executada corretamente, não apenas descrita.
5. 05
   Verificar a memória

   Pedir explicitamente a memorização e depois abrir MEMORY.md para verificar se a entrada está lá antes de confiar no agente sobre esse ponto.

• Executar o modelo Hermes 4 localmente
• Conectar servidores MCP ao Ollama
• Agente de IA: definições e limites gerais
• Fonte: repositório oficial do Hermes Agent no GitHub
• Fonte: documentação de configuração dos provedores
• Fonte: documentação do modelo de segurança