Objetivos

Ao terminar este módulo você vai conseguir:

• explicar, com suas palavras, o que é inteligência artificial e o que não é;
• diferenciar programa tradicional, aprendizado de máquina e rede neural;
• entender por que os modelos atuais "aprendem" com dados em vez de serem programados regra por regra;
• reconhecer as limitações básicas: erro, viés e falta de memória própria.

Não há laboratório de terminal neste módulo. Ele é leitura e reflexão.

1. Uma definição que serve para o dia a dia

Inteligência artificial é o nome dado a programas de computador que fazem tarefas que, quando feitas por pessoas, exigiriam alguma forma de inteligência: entender um texto, reconhecer um rosto, traduzir uma frase, decidir o próximo lance de um jogo, escrever um e-mail.

A palavra "inteligência" engana um pouco. Nenhum desses programas pensa como uma pessoa. O que eles fazem é encontrar padrões em uma quantidade enorme de exemplos e usar esses padrões para produzir uma resposta plausível para uma entrada nova. Guarde essa frase, porque ela explica quase tudo que vem depois no curso: IA é reconhecimento de padrões em escala.

2. Três maneiras de fazer um computador resolver um problema

Programa tradicional

Um programador escreve regras explícitas. Se a temperatura passar de 30 graus, ligue o ventilador. Se o CPF tiver 11 dígitos e o dígito verificador bater, aceite. O computador só faz o que foi escrito.

Isso funciona muito bem quando as regras são conhecidas e poucas. Funciona mal quando as regras são difíceis de escrever. Tente descrever em regras como reconhecer um gato numa foto. Orelhas pontudas? Um cachorro também tem. Bigodes? Há gatos de perfil. A lista de exceções nunca termina.

Aprendizado de máquina

Em vez de escrever as regras, o programador mostra ao computador milhares de exemplos já rotulados (esta foto é gato, esta não é) e deixa um algoritmo ajustar números internos até que ele acerte a maioria. O resultado é um modelo: um conjunto de números que, dado uma entrada, produz uma saída.

A palavra "aprendizado" significa só isso: ajustar números para reduzir o erro nos exemplos. Não há compreensão. Há ajuste estatístico.

Redes neurais e aprendizado profundo

Uma rede neural é um tipo específico de modelo, organizado em camadas de unidades simples que fazem multiplicações e somas. O nome vem de uma inspiração distante nos neurônios biológicos, mas a semelhança para por aí. "Profundo" quer dizer que há muitas camadas.

Quanto mais camadas e mais dados, mais padrões sutis a rede consegue capturar. Foi isso que, a partir de 2012, fez a IA dar um salto em reconhecimento de imagem, fala e depois texto.

3. Uma analogia para fixar

Pense em alguém aprendendo a identificar vinhos. Um sommelier iniciante recebe uma lista de regras: acidez alta e cor clara indicam uva X. Isso é o programa tradicional.

Agora pense em alguém que prova três mil vinhos com o rótulo à vista. Com o tempo, a pessoa passa a reconhecer a uva pelo gosto sem conseguir explicar exatamente como. Isso é aprendizado de máquina. A pessoa não decorou regras, ajustou seu "paladar" com exemplos.

A limitação aparece junto: se essa pessoa só provou vinhos europeus, vai errar feio com um vinho de uva brasileira desconhecida. Um modelo só sabe o que havia nos dados em que foi treinado.

4. Treinamento e inferência

Dois momentos muito diferentes na vida de um modelo:

Treinamento é a fase cara. Dura dias ou meses em milhares de placas gráficas, consome os exemplos e produz o conjunto de números do modelo (os "pesos"). Só empresas e laboratórios com muito dinheiro treinam modelos grandes do zero.

Inferência é o uso. Você envia uma entrada, o modelo passa os números pelas camadas e devolve a saída. É isso que acontece quando você conversa com um assistente. Cada pergunta é uma inferência. A inferência é barata se comparada ao treinamento, mas não é gratuita, e esse custo é o que se paga por "token" nos serviços comerciais. O módulo 2 explica token.

Importante: durante a inferência o modelo não aprende nada. Os pesos não mudam. Se o assistente "lembra" do que você disse ontem, não foi o modelo que aprendeu, foi um sistema em volta dele que guardou e reenviou a informação. O Hermes é exatamente um sistema desses, e o módulo 8 mostra como ele faz isso.

5. Tipos de IA que você vai encontrar

Os modelos de linguagem (os LLMs) são o tipo que importa para o Hermes. Eles geram texto e, com um truque que o módulo 3 explica, podem também executar ações.

6. O que a IA faz mal

Um especialista em agentes precisa saber onde o modelo falha, porque é aí que o sistema em volta precisa compensar.

Alucinação. O modelo produz uma resposta com aparência de verdade que é falsa. Ele não "mente": ele gera a continuação mais provável, e às vezes a mais provável está errada. Um agente bom verifica com ferramentas (rodar o comando, ler o arquivo) em vez de confiar na memória do modelo.

Viés. O modelo reproduz os padrões dos dados de treinamento, inclusive os injustos.

Falta de memória. Já explicado: o modelo não guarda nada entre conversas por conta própria.

Limite de contexto. O modelo só consegue "olhar" uma quantidade limitada de texto de cada vez. O módulo 2 trata disso em detalhe, e o Hermes gasta bastante engenharia para lidar com esse limite.

Confiança excessiva. O modelo responde com o mesmo tom quando sabe e quando não sabe. Cabe ao sistema e ao usuário desconfiar.

7. Breve linha do tempo

• 1950: Alan Turing propõe a pergunta "máquinas podem pensar?" e um teste para avaliar isso.
• 1956: o termo "inteligência artificial" é cunhado em uma conferência em Dartmouth.
• Décadas de 1970 e 1980: sistemas baseados em regras, bons em domínios estreitos, caros de manter.
• 2012: redes neurais profundas vencem com folga uma competição de reconhecimento de imagem. Começa a era atual.
• 2017: é publicada a arquitetura Transformer, base de todos os grandes modelos de linguagem de hoje.
• 2022: assistentes de conversa baseados em LLM chegam ao público geral.
• 2024 em diante: os modelos passam a chamar ferramentas de forma confiável e surgem os agentes autônomos. O Hermes Agent é lançado pela Nous Research em fevereiro de 2026.

Leia mais

• Vídeo "Mas o que é uma rede neural?" da série de Grant Sanderson (3Blue1Brown), com legendas em português. É a melhor introdução visual que existe.
• Capítulo 1 do livro "Inteligência Artificial" de Stuart Russell e Peter Norvig, se quiser a visão acadêmica.
• A lista completa de vídeos está em recursos/videos.md.

Objetivos

• Explicar o que um LLM faz a cada passo: prever o próximo token.
• Entender token, janela de contexto, prompt e temperatura.
• Saber o que é o prompt de sistema e por que ele é tão importante para o Hermes.
• Entender por que modelos cobram por token e como o contexto afeta custo e qualidade.

1. A tarefa única: prever o próximo pedaço

Um modelo de linguagem grande (LLM, de large language model) foi treinado com uma única tarefa: dado um trecho de texto, prever qual é o próximo pedaço. Trilhões de vezes, em texto da internet, livros, código.

Para gerar uma resposta inteira, ele repete essa tarefa em laço. Prevê um pedaço, cola no fim do texto, prevê o próximo, e assim por diante até produzir um sinal de parada. Toda resposta de um assistente de IA foi construída pedaço por pedaço desse jeito.

Isso explica várias coisas que parecem estranhas:

• Por que ele às vezes começa bem e se perde: cada pedaço depende dos anteriores, e um erro no meio contamina o resto.
• Por que ele "inventa": a continuação mais provável nem sempre é verdadeira.
• Por que ele é bom em formato: imitar o jeito de um e-mail, de um código, de uma lista é exatamente o que "prever a continuação" treina.

2. Token: a unidade de tudo

O "pedaço" tem nome: token. Um token não é uma palavra nem uma letra. É um fragmento de texto definido por um dicionário fixo do modelo. Em inglês, uma palavra comum costuma ser um token. Em português, uma palavra costuma virar dois ou três tokens, porque o dicionário foi montado com mais texto em inglês. Código também gasta tokens com espaços e símbolos.

Regra prática: 1.000 tokens correspondem a cerca de 700 palavras em inglês, ou 500 a 600 em português.

Tudo no mundo dos LLMs é medido em tokens:

• O preço dos serviços é por milhão de tokens de entrada e de saída.
• O limite de quanto o modelo consegue "ver" de uma vez é em tokens.
• A velocidade é medida em tokens por segundo.

3. A janela de contexto

O modelo só consegue processar uma quantidade máxima de tokens de cada vez. Esse máximo é a janela de contexto. Nela precisam caber, juntos, o prompt de sistema, o histórico da conversa, os resultados de ferramentas e a resposta que está sendo gerada.

Pense na janela como a mesa de trabalho de alguém. Tudo que está sobre a mesa pode ser consultado. O que não cabe na mesa não existe para o modelo naquele momento. Ele não tem gaveta própria. Se a conversa cresce além da mesa, alguma coisa precisa sair.

Tamanhos atuais variam de 32 mil a mais de um milhão de tokens. O Hermes exige um mínimo de 64 mil tokens de contexto para funcionar, porque um agente precisa de espaço para instruções, descrições de ferramentas e resultados de comandos. Essa é uma das primeiras coisas que o Hermes verifica ao iniciar, e um motivo comum de falha com modelos locais mal configurados.

Dois efeitos práticos que você vai sentir no Hermes:

Custo. A cada mensagem nova, o sistema reenvia todo o contexto ao modelo. Uma conversa longa fica cara porque cada turno paga a conversa inteira de novo. Os provedores aliviam isso com cache de prefixo: se o começo do contexto é idêntico ao da chamada anterior, cobram menos por ele. O Hermes é projetado para preservar esse cache, e o módulo 13 mostra como.

Compressão. Quando a conversa se aproxima do limite, o Hermes resume o meio dela para liberar espaço. Isso se chama compressão de contexto e acontece sozinho a partir de 50% da janela.

4. Prompt, prompt de sistema e mensagens

Prompt é o texto que você envia ao modelo. Em um assistente de conversa, o prompt é estruturado em mensagens com papéis:

O prompt de sistema é a peça mais importante de qualquer agente. Ele diz ao modelo qual é sua identidade, o que pode fazer, o que deve evitar, quais arquivos de projeto existem, o que lembra do usuário. No Hermes, esse prompt é montado em camadas a partir de arquivos como SOUL.md, AGENTS.md, MEMORY.md e USER.md. O módulo 6 mostra cada um, e o módulo 13 mostra a montagem.

5. Temperatura e esforço de raciocínio

Ao prever o próximo token, o modelo calcula uma probabilidade para cada token possível. A temperatura controla o quanto ele escolhe o mais provável ou arrisca alternativas. Temperatura baixa dá respostas mais previsíveis, útil para código e tarefas de agente. Temperatura alta dá mais variedade, útil para texto criativo.

Modelos recentes têm também um modo de raciocínio: antes de responder, geram um texto interno de "pensamento" que não é mostrado, ou é mostrado à parte. Isso melhora tarefas difíceis e custa tokens extras. O Hermes expõe esse controle como esforço de raciocínio, com níveis que vão de none a ultra, configuráveis por modelo e até por tarefa agendada.

6. Chamada de ferramentas: o truque que transforma texto em ação

Um LLM só produz texto. Como um agente consegue rodar um comando ou ler um arquivo?

O truque é combinar com o modelo um formato. O sistema descreve, no prompt de sistema, uma lista de ferramentas disponíveis, cada uma com nome e parâmetros em um esquema (JSON Schema). Quando o modelo decide que precisa de uma ferramenta, em vez de responder em prosa ele produz um bloco estruturado: nome da ferramenta e argumentos. O sistema lê esse bloco, executa a ferramenta de verdade, e devolve o resultado como uma mensagem de papel tool. O modelo então continua, agora com o resultado à vista.

Esse ciclo se chama chamada de ferramentas (tool calling ou function calling). Modelos treinados para isso produzem o bloco no formato certo com confiabilidade. Modelos pequenos ou antigos tentam imitar e erram o formato, o que faz um agente falhar. Por isso o módulo 14 insiste em escolher modelos locais com suporte a ferramentas.

7. De onde vêm os modelos

O Hermes é agnóstico: você escolhe o provedor e troca quando quiser com um comando. Isso é uma decisão de projeto importante e será repetida no módulo 4.

8. Resumo em uma frase

Um LLM é uma função que recebe uma lista de tokens e devolve o próximo token mais provável; tudo o resto, incluindo memória, ferramentas e personalidade, é construído em volta dele por um sistema como o Hermes.

Leia mais

• Vídeo "Como os LLMs funcionam" (3Blue1Brown, série sobre Transformers, com legendas).
• Artigo "Attention Is All You Need" (2017), se quiser conhecer a origem. Não é leitura obrigatória.
• Página oficial do Hermes sobre configuração de modelos: https://hermes-agent.nousresearch.com/docs/user-guide/configuring-models

Objetivos

• Diferenciar chat, assistente com ferramentas e agente autônomo.
• Descrever o laço de um agente: pensar, agir, observar, repetir.
• Conhecer as peças que todo agente moderno tem: ferramentas, memória, contexto, segurança.
• Entender o que é MCP e o que são skills, em termos gerais, antes de ver como o Hermes implementa.

1. Três níveis de autonomia

Chat. Você pergunta, o modelo responde em texto. Nada acontece fora da conversa. Se você pede "crie um arquivo", ele descreve como criar.

Assistente com ferramentas. O modelo pode chamar uma ou duas ferramentas por pedido, como buscar na web ou consultar um calendário. A iniciativa continua sendo sua a cada passo.

Agente. Você dá um objetivo. O sistema deixa o modelo decidir quais ferramentas chamar, em qual ordem, quantas vezes, observando cada resultado, até considerar o objetivo cumprido. "Descubra por que os testes falham e corrija" pode gerar vinte chamadas de ferramenta sem que você intervenha.

O Hermes é um agente. E, dentro dessa categoria, é um agente que roda no seu servidor, conversa com você por mensageria, tem memória e cria suas próprias rotinas reutilizáveis.

2. O laço do agente

Todo agente roda uma variação deste ciclo:

1. Monta o prompt: sistema + histórico + ferramentas disponíveis
2. Chama o modelo
3. O modelo respondeu com texto final?
     sim -> entrega ao usuário e para
     não -> o modelo pediu ferramentas
4. Executa as ferramentas pedidas
5. Anexa os resultados ao histórico
6. Volta ao passo 1

Cada volta é uma iteração. Agentes impõem um limite de iterações para não rodar para sempre. No Hermes o limite padrão é 500 por conversa, e os subagentes têm um limite próprio menor.

Esse laço simples é responsável pela diferença de qualidade entre um chat e um agente. O modelo não precisa acertar de primeira: ele roda o comando, vê o erro, tenta de novo. É o mesmo que uma pessoa faz.

3. As peças

Ferramentas

Funções que o sistema expõe ao modelo: executar comando no terminal, ler e editar arquivos, buscar na web, controlar um navegador, analisar imagem, enviar mensagem. Quanto mais ferramentas, mais o agente pode fazer, e mais tokens o prompt gasta descrevendo todas elas. Por isso os agentes agrupam ferramentas em conjuntos que podem ser ligados ou desligados. No Hermes esses conjuntos se chamam toolsets.

Contexto de projeto

Arquivos de instrução que o agente lê ao começar: convenções do projeto, comandos de teste, portas, o que não fazer. A convenção mais difundida é um arquivo AGENTS.md na raiz do projeto. O Hermes lê esse arquivo e também CLAUDE.md e .cursorrules, para compatibilidade com outras ferramentas.

Memória

Como o modelo não guarda nada, o agente precisa de um lugar para guardar fatos entre conversas e de um mecanismo para reinjetá-los no prompt. Há dois estilos:

• memória curada: poucos fatos importantes, sempre presentes no prompt;
• busca em histórico: todas as conversas ficam gravadas e o agente procura nelas quando precisa.

O Hermes usa os dois. O módulo 8 mostra.

Procedimentos reutilizáveis

Além de fatos, um agente se beneficia de "receitas": como abrir um PR neste projeto, como publicar no servidor de homologação. Guardar isso como texto que o agente carrega sob demanda é o que o mercado chama de skill. Existe um padrão aberto para o formato, o agentskills.io, e o Hermes o segue. O módulo 9 é inteiro sobre isso.

Segurança

Um agente com terminal pode apagar arquivos. Todo agente sério tem:

• aprovação humana para comandos perigosos;
• opção de rodar em contêiner isolado;
• controle de quem pode falar com ele quando está exposto em um chat.

O Hermes tem oito camadas de segurança, descritas no módulo 7.

Integração com o mundo externo

Para não reescrever um conector para cada serviço, surgiu em 2024 o MCP (Model Context Protocol), um protocolo aberto para servidores de ferramentas. Um servidor MCP do GitHub, por exemplo, expõe ferramentas para abrir issues e PRs; qualquer agente que fale MCP as usa. O Hermes fala MCP e ainda aceita plugins em Python para o que o MCP não cobre. Módulo 12.

4. Subagentes e orquestração

Um agente pode criar outros agentes para tarefas paralelas ou para isolar contexto. Pesquisar três assuntos ao mesmo tempo, cada um em uma conversa limpa, e receber só os resumos de volta economiza tokens no agente principal. O Hermes chama isso de delegação, e tem ainda um quadro Kanban onde vários agentes com perfis distintos pegam tarefas de uma fila compartilhada. Módulo 11.

5. Agentes que aprendem

A maioria dos agentes é igual no primeiro e no centésimo dia de uso. A proposta central do Hermes é diferente: ele tem um ciclo de aprendizado que, depois de uma tarefa complexa, salva o procedimento como skill, corrige skills existentes quando algo dá errado, anota fatos sobre você e seu ambiente em memória, e periodicamente revisa a biblioteca de skills para remover duplicatas. Isso não é o modelo aprendendo (os pesos nunca mudam). É o sistema acumulando texto útil que entra no prompt das próximas conversas. Mas o efeito prático é um agente que fica melhor com o tempo.

6. Onde os agentes falham

• Objetivo vago. "Melhore o projeto" não dá ao agente critério de parada. Objetivos verificáveis ("faça o pytest passar") funcionam.
• Contexto ausente. Um subagente ou uma tarefa agendada começa do zero e precisa receber tudo no pedido.
• Excesso de ferramentas. Prompt inchado, modelo confuso, custo alto.
• Confiança cega. Aprovar tudo sem ler. O módulo 7 ensina quando usar o modo de aprovação automática e quando não.
• Modelo fraco. Modelos pequenos dizem "salvei na memória" sem chamar a ferramenta de memória. A documentação do Hermes alerta que isso é comum abaixo de uns 30 bilhões de parâmetros.

Leia mais

• Vídeos: Attekita Dev, "Hermes Agent: eu testei e não é só hype!" (português, 19 min) e Tina Huang, "Hermes Agent Fundamentals In 29 Minutes" (inglês). Links em recursos/videos.md.
• Especificação aberta de skills: https://agentskills.io/specification
• Página oficial sobre arquitetura do Hermes, para ver as peças com nome de arquivo: https://hermes-agent.nousresearch.com/docs/developer-guide/architecture

Objetivos

• Saber o que o Hermes é, quem o faz e sob qual licença.
• Conhecer o mapa de componentes: núcleo do agente, gateway, ferramentas, skills, memória, cron.
• Entender as decisões de projeto que o diferenciam: agnóstico a modelo, roda no seu servidor, aprende com o uso.
• Saber ler o mapa da documentação oficial.

1. O que é

O Hermes Agent é um agente de IA de código aberto, escrito em Python, criado pela Nous Research e lançado em fevereiro de 2026 sob licença MIT. A descrição oficial é "o agente que cresce com você": ele tem um ciclo de aprendizado embutido que cria skills a partir da experiência, melhora essas skills durante o uso, mantém memória entre sessões e busca em conversas passadas.

Três frases da própria documentação resumem a proposta:

• ele vive no seu servidor (ou na sua máquina), não em uma nuvem de terceiros;
• ele lembra do que aprende;
• fica mais capaz quanto mais tempo roda.

A Nous Research é um laboratório conhecido por modelos abertos da família Hermes (Hermes 4 em 70B e 405B parâmetros). O agente leva o mesmo nome, mas não exige esses modelos: funciona com mais de 300 modelos de dezenas de provedores.

2. Mapa de componentes

Pense no Hermes como um prédio com cinco andares.

+-----------------------------------------------------------+
|  Entradas: CLI / TUI, Desktop, Gateway de mensagens, ACP  |
|            (Telegram, Discord, WhatsApp, Slack, e-mail...)|
+-----------------------------------------------------------+
|  Núcleo: AIAgent (laço de conversa, montagem do prompt,   |
|          chamada ao modelo, execução de ferramentas,      |
|          compressão, fallback de provedor)                |
+-----------------------------------------------------------+
|  Ferramentas: 70+ em 28 toolsets (terminal, arquivos,     |
|          web, navegador, visão, memória, delegação,       |
|          cron, MCP, plugins)                              |
+-----------------------------------------------------------+
|  Conhecimento: SOUL.md, AGENTS.md, MEMORY.md, USER.md,    |
|          skills/, busca em sessões (SQLite + FTS5)        |
+-----------------------------------------------------------+
|  Execução: backends de terminal (local, Docker, SSH,      |
|          Modal, Daytona, Singularity, Vercel Sandbox)     |
+-----------------------------------------------------------+

Cada andar tem um módulo deste curso:

3. Decisões de projeto que importam

Agnóstico a modelo

O Hermes conversa com provedores por três modos de API: o formato de chat completions compatível com OpenAI (usado por quase todo mundo, inclusive Ollama), o formato Responses da OpenAI e a API nativa da Anthropic. Trocar de provedor é um comando, hermes model, sem mudar nada no resto. Você pode ainda definir uma cadeia de fallback: se o modelo principal falhar por limite de taxa ou erro de servidor, o próximo da lista assume.

Roda onde você quiser

A documentação cita três alvos: um VPS de cinco dólares, um cluster de GPU, ou infraestrutura sem servidor. O gateway é um único processo em segundo plano que conecta todas as plataformas de mensagem, mantém sessões, executa o cron e entrega mensagens. Instalar como serviço do sistema é um comando.

Separação de segredos e configuração

Chaves de API e tokens ficam em ~/.hermes/.env. Tudo que não é segredo fica em ~/.hermes/config.yaml. O comando hermes config set sabe para qual arquivo cada valor vai. Essa separação facilita backup, migração e versionamento.

Prompt estável

O prompt de sistema é montado uma vez no início da sessão e congelado. Memória salva no meio da conversa só aparece no prompt na sessão seguinte. Isso parece uma limitação, mas é uma escolha deliberada para preservar o cache de prefixo do provedor e reduzir custo. Você vai esbarrar nisso no módulo 8 e entender a razão no módulo 13.

Segurança em camadas

Autorização de usuários no gateway, aprovação de comandos perigosos, lista de bloqueio fixa que nem o modo "faça tudo" desliga, isolamento por contêiner, filtro de credenciais para subprocessos MCP, varredura de arquivos de contexto contra injeção de prompt, isolamento entre sessões e sanitização de entrada.

Aprende com o uso

Depois de uma tarefa, uma revisão em segundo plano pode salvar memória ou criar e corrigir skills. Um curador periódico marca skills sem uso como obsoletas e as arquiva. Uma linha do tempo (/journey) mostra tudo que foi aprendido e permite apagar ou editar.

4. Formas de usar

5. Nous Portal e o Tool Gateway

A Nous oferece uma assinatura chamada Nous Portal. Uma única autenticação OAuth dá acesso a mais de 300 modelos (Claude, GPT, Gemini, DeepSeek, Qwen, Kimi, GLM, Grok e outros) e ao Tool Gateway, que fornece busca na web, geração de imagem, texto para fala e navegador em nuvem sem chaves separadas. O comando hermes setup --portal configura tudo de uma vez.

Não é obrigatório. Você pode usar sua própria chave da Anthropic, OpenAI, OpenRouter, ou um modelo local via Ollama sem pagar nada. O Hermes em si é gratuito; o que custa é o uso do modelo que você escolher. Este curso usa modelo local nos laboratórios do módulo 14 e deixa a escolha de provedor para você no módulo 5.

6. O mapa da documentação

A documentação em https://hermes-agent.nousresearch.com/docs tem estas seções, e vale decorar a estrutura porque você vai voltar a ela:

• Getting Started: instalação, quickstart, suporte a plataformas, trilha de aprendizado.
• User Guide: CLI, TUI, configuração, sessões, perfis, segurança, e a subseção Features (ferramentas, memória, skills, MCP, voz, personalidade, arquivos de contexto, cron, delegação, Kanban, goals, hooks, navegador, visão).
• Messaging: uma página por plataforma.
• Integrations: provedores de modelo e Nous Portal.
• Guides: tutoriais passo a passo (bot de briefing diário, assistente de equipe no Telegram, Ollama local, revisão de PR no GitHub, voz, SOUL.md).
• Developer Guide: arquitetura, laço do agente, montagem do prompt, compressão, internals do gateway, banco de sessões, como adicionar ferramentas, provedores, adaptadores de plataforma, skills, plugins.
• Reference: comandos da CLI, comandos de barra, variáveis de ambiente, catálogo de ferramentas, toolsets, MCP, modelos, skills, FAQ.

Há também dois arquivos pensados para IA: /llms.txt (índice) e /llms-full.txt (toda a documentação em um único texto). Este curso foi montado a partir do segundo.

7. Comparação rápida com outras ferramentas

O Hermes não substitui um assistente de código dentro do editor; ele pode até delegar para o Claude Code ou o Codex por meio de skills embutidas. Ele ocupa o lugar do "funcionário de IA" que fica ligado, recebe pedidos pelo chat e executa rotinas.

Leia mais

• Página inicial da documentação e trilha oficial: https://hermes-agent.nousresearch.com/docs/getting-started/learning-path
• Repositório: https://github.com/NousResearch/hermes-agent
• Vídeos: palestra de Sam Herring (Nous Research) na Arize Observe 2026 e Otávio Miranda, "Hype ou tem algo útil no Hermes Agent?". Links em recursos/videos.md.
• Post de lançamento e data oficial na página de releases da Nous: https://nousresearch.com/releases

Objetivos

• Instalar o Hermes no Linux com o instalador oficial.
• Escolher um provedor de modelo e entender os três modos do hermes setup.
• Ter uma conversa funcional no terminal e saber usar os comandos de barra básicos.
• Retomar sessões, atualizar e diagnosticar.

Este é o primeiro módulo com terminal. Reserve duas horas e faça com calma.

1. O que o instalador faz

O comando abaixo baixa um script e o executa. Ele clona o código-fonte em ~/.hermes/hermes-agent, instala a ferramenta uv e delega a preparação do ambiente a um gerenciador chamado PM, que fornece Python fixado, Node.js, npm, ripgrep e FFmpeg. O instalador seleciona os extras all, então ACP, voz e integrações já vêm.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc

Se você usa zsh, troque o segundo comando por source ~/.zshrc.

Windows nativo usa PowerShell:

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

Android com Termux tem um pacote APT separado, e macOS e Windows têm também um instalador do aplicativo Desktop que inclui a CLI. O instalador de macOS só funciona em Apple Silicon.

Depois de instalar, confirme:

hermes --version
hermes doctor

O hermes doctor é o diagnóstico. Rode sempre que algo parecer errado.

2. Onde as coisas ficam

~/.hermes/
├── hermes-agent/   # código-fonte clonado
├── config.yaml     # configuração (não secreta)
├── .env            # chaves e tokens
├── auth.json       # credenciais OAuth
├── SOUL.md         # identidade do agente
├── memories/       # MEMORY.md e USER.md
├── skills/         # skills instaladas e criadas
├── cron/           # tarefas agendadas
├── sessions/       # sessões do gateway
├── state.db        # banco SQLite de sessões
└── logs/           # errors.log, gateway.log (segredos são redigidos)

O módulo 6 explica cada arquivo. Por enquanto só saiba que tudo está em ~/.hermes.

3. Escolher o provedor

Esta é a decisão mais importante da instalação. Há três caminhos.

Caminho A: hermes setup

O assistente interativo oferece três modos na primeira execução:

O Blank Slate escreve uma lista explícita de toolsets por plataforma, então nada que você não escolheu carrega, nem depois de atualizar.

Caminho B: hermes model

Só escolhe provedor e modelo, sem passar pelo resto. Serve para trocar depois também.

hermes model

Provedores listados na documentação incluem Nous Portal, OpenAI (inclusive assinatura ChatGPT ou Codex por código de dispositivo), Anthropic (OAuth com plano Max ou chave de API), OpenRouter, Google AI Studio, xAI, DeepSeek, NVIDIA NIM, GitHub Copilot, Hugging Face, AWS Bedrock, Azure Foundry, Alibaba DashScope, Kimi, MiniMax, Z.AI, Ollama Cloud, LM Studio e um endpoint personalizado para qualquer API compatível com OpenAI (vLLM, SGLang, Ollama local, llama.cpp).

Caminho C: definir direto

hermes config set model anthropic/claude-opus-4.6
hermes config set OPENROUTER_API_KEY sk-or-...

O primeiro vai para config.yaml, o segundo para .env. O comando sabe a diferença.

O requisito de contexto

Qualquer modelo precisa ter pelo menos 64.000 tokens de contexto. Modelos menores são rejeitados na inicialização. Modelos hospedados cumprem com folga. Modelos locais precisam de ajuste, como o módulo 14 mostra.

Sugestão para o curso

Para os módulos 5 a 13, use um modelo hospedado de boa qualidade. A documentação recomenda que o primeiro contato seja com um modelo forte, porque modelos fracos falham em chamar ferramentas e dão a impressão de que o Hermes está quebrado. Para o módulo 14, use um modelo local pelo Ollama, que já está na sua máquina.

Se não quiser assinar nada agora, a página oficial "Run Nemotron 3 Ultra Free" descreve um caminho gratuito via NVIDIA NIM. O link está em recursos/leituras.md.

4. O primeiro chat

hermes          # CLI clássica
hermes --tui    # interface moderna, recomendada pela documentação

As duas compartilham sessões, comandos e configuração. Você verá um banner com o modelo, as ferramentas e as skills disponíveis.

Use um pedido específico e fácil de verificar:

Olhe o diretório atual e me diga qual parece ser o arquivo principal do projeto.

Qual o uso de disco aqui? Mostre os cinco maiores diretórios.

O que sucesso significa, segundo a documentação: o banner mostra seu modelo, o Hermes responde sem erro, ele consegue usar uma ferramenta quando precisa, e a conversa continua por mais de um turno. Se isso funcionou, a parte mais difícil passou.

Se der erro, não adicione nada antes de resolver. Essa é a regra de ouro do quickstart oficial: um chat limpo primeiro, só depois gateway, cron, skills, voz ou roteamento.

5. Comandos de barra essenciais

Digite / e pressione Tab para ver todos. Os que você usará desde o primeiro dia:

Toda skill instalada vira também um comando de barra com o nome dela.

6. Entrada, interrupção e colagem

• Nova linha sem enviar: Alt+Enter ou Ctrl+J funcionam em qualquer terminal. Shift+Enter só em terminais que mandam a tecla distinta (Kitty, foot, WezTerm, Ghostty, ou VS Code com protocolo Kitty ativado).
• Colar um bloco de várias linhas: a CLI detecta e envia como uma única mensagem.
• Interromper: digite uma nova mensagem e Enter, ou Ctrl+C uma vez. Ctrl+C duas vezes em dois segundos força saída.
• Colar imagem da área de transferência: Ctrl+V. O agente usa visão para analisar.

7. Modo de consulta única

Para usar o Hermes em scripts ou pedir uma coisa só:

hermes chat -q "Resuma este repositório em cinco linhas"
hermes chat --toolsets "web,terminal" -q "..."
hermes chat -s nome-da-skill -q "..."

Com -q o Hermes roda um turno e sai. Comandos perigosos nesse modo são negados por padrão (configurável, módulo 7).

8. Sessões

Cada conversa vira uma sessão gravada em ~/.hermes/state.db.

hermes -c                 # retoma a sessão mais recente deste terminal
hermes -c "meu projeto"   # retoma pelo título
hermes --resume <id>      # retoma por id
hermes sessions list      # lista as últimas 20
hermes sessions list --platform telegram

Um detalhe útil: o -c sem argumento é por terminal. Dois painéis lado a lado retomam cada um sua própria conversa, porque o Hermes deixa um marcador em ~/.hermes/terminal-sessions/ identificando o terminal.

Confira agora que hermes -c traz de volta a conversa que você acabou de ter. O quickstart oficial pede isso antes de seguir.

9. Atualizar e diagnosticar

hermes update          # atualiza o código-fonte (faz backup rápido antes)
hermes update --check  # só verifica
hermes doctor          # diagnóstico
hermes config check    # procura opções faltando ou seleções obsoletas

A CLI avisa no banner quando há versão nova, consultando o GitHub no máximo uma vez a cada 24 horas.

10. Falhas comuns do primeiro dia

A ordem de recuperação recomendada pela documentação: hermes doctor, hermes model, hermes setup, hermes sessions list, hermes --continue, hermes gateway status.

Leia mais

• Quickstart oficial: https://hermes-agent.nousresearch.com/docs/getting-started/quickstart
• Instalação: https://hermes-agent.nousresearch.com/docs/getting-started/installation
• CLI: https://hermes-agent.nousresearch.com/docs/user-guide/cli
• TUI: https://hermes-agent.nousresearch.com/docs/user-guide/tui
• Vídeos: Metics Media Brasil, "Tutorial Completo e Guia de Configuração" (setembro de 2026) e Masterclass 1 de Tonbi's AI Garage, que é o vídeo embutido no quickstart oficial. Links em recursos/videos.md.

Objetivos

• Saber qual arquivo faz o quê dentro de ~/.hermes.
• Dominar config.yaml, .env e os comandos hermes config.
• Escrever um SOUL.md e um AGENTS.md úteis.
• Entender perfis e quando usar mais de um.
• Fazer backup e migrar para outra máquina.

1. A pergunta que todo iniciante faz

"Eu disse uma coisa ao agente e ele esqueceu." "Qual arquivo é o cérebro dele?" "Editei o SOUL.md e ele não sabe meu nome." A documentação tem uma página só para isso, chamada "Which file does what", e a tabela dela é a espinha dorsal deste módulo.

Um atalho mental da própria documentação:

• SOUL.md é quem o agente é.
• USER.md é quem você é, e o agente mantém.
• MEMORY.md é o que o agente aprendeu, e ele mesmo mantém.
• AGENTS.md é o que o projeto precisa.

Só um tipo de arquivo de projeto é carregado por sessão, o primeiro que existir nesta ordem: .hermes.md, AGENTS.override.md, AGENTS.md, CLAUDE.md, .cursorrules. O SOUL.md é sempre carregado à parte.

2. Por que "ele esqueceu o que eu acabei de dizer"

A memória (MEMORY.md e USER.md) entra no prompt como uma foto tirada no início da sessão. Quando o agente salva algo no meio da conversa, o arquivo em disco muda na hora, mas o prompt não é refeito. A informação aparece na próxima sessão. Isso é proposital: refazer o prompt destruiria o cache de prefixo do provedor e encareceria cada turno. Dentro da sessão atual o agente ainda usa o que você disse, porque está no histórico.

O mesmo vale para edições em SOUL.md ou AGENTS.md com uma sessão aberta: reinicie a sessão (/new) para que valham.

3. config.yaml e .env

Regra: segredos em .env, todo o resto em config.yaml. Se o mesmo valor estiver nos dois, config.yaml vence para o que não é segredo.

hermes config              # mostra a configuração atual
hermes config edit         # abre config.yaml no editor
hermes config get model
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config unset terminal.backend
hermes config check        # opções faltando e seleções obsoletas
hermes config migrate      # adiciona interativamente o que falta
hermes config set OPENROUTER_API_KEY sk-or-...   # vai para .env

O config.yaml aceita referência a variável de ambiente com a sintaxe ${NOME}, útil para não colocar segredo no YAML:

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}

Se a variável não existir, o texto fica como está e o Hermes registra um aviso.

O Hermes guarda cópias do config.yaml em backups/config/ antes de reescrevê-lo e quando ele deixa de parsear. Se você quebrar o YAML, ele usa a última cópia boa e avisa a cada início até você consertar.

Trechos de config.yaml que você vai mexer cedo

model:
  default: "anthropic/claude-sonnet-4.6"
  provider: "anthropic"

terminal:
  backend: local        # local | docker | ssh | modal | daytona | vercel_sandbox | singularity
  timeout: 180

approvals:
  mode: smart           # smart | manual | off

memory:
  memory_enabled: true
  user_profile_enabled: true
  write_approval: false

display:
  memory_notifications: on   # off | on | verbose

skills:
  external_dirs:
    - ~/.agents/skills

mcp_servers: {}

plugins:
  enabled: []

Cada bloco é detalhado no módulo correspondente. O arquivo de exemplo labs/exemplo-config.yaml tem uma versão comentada.

4. Escrevendo um SOUL.md

Serve para voz e identidade duráveis: tom, nível de franqueza, como lidar com incerteza, o que evitar. Não serve para caminhos de arquivo, convenções de repositório ou instruções de uma tarefa.

Um exemplo que a documentação dá:

```markdown

Personality

You are a pragmatic senior engineer with strong taste. You optimize for truth, clarity, and usefulness over politeness theater.

Style

• Be direct without being cold
• Prefer substance over filler
• Push back when something is a bad idea
• Admit uncertainty plainly

What to avoid

• Sycophancy
• Hype language ```

Pode ser escrito em português. O conteúdo entra sem nenhum texto em volta, na primeira posição do prompt, depois de uma varredura de segurança e de um corte de tamanho proporcional ao contexto do modelo. Se o arquivo estiver vazio, o Hermes usa a identidade padrão embutida, que pede respostas diretas, sem enrolação e com tamanho proporcional ao pedido.

Veja labs/exemplo-SOUL.md para um modelo em português.

5. Escrevendo um AGENTS.md

Coloque na raiz do projeto. Conteúdo típico: arquitetura, comandos de teste e build, portas, convenções, o que nunca fazer.

```markdown

Contexto do projeto

Backend FastAPI com SQLAlchemy em /backend. Frontend Next.js 14 em /frontend. Banco PostgreSQL 16. Deploy via Docker Compose.

Convenções

• Python segue PEP 8 com type hints.
• Toda rota devolve JSON no formato {data, error, meta}.
• Testes em tests/ com pytest.

Nunca

• Editar arquivos de migração à mão. Use Alembic.
• Commitar .env.local. ```

Em um repositório git, o Hermes carrega uma cadeia: o AGENTS.md da raiz primeiro e depois os de cada pasta intermediária até o diretório de trabalho, com os mais específicos por último. Fora de um repositório, só o diretório atual é lido; pais nunca são consultados, justamente para que um arquivo plantado em /tmp ou em $HOME não vaze para sessões alheias.

Subpastas são descobertas aos poucos: quando o agente lê um arquivo em backend/, o backend/AGENTS.md é injetado naquele momento. Isso evita inchar o prompt inicial e preserva o cache.

Se quiser instruções pessoais diferentes das commitadas, crie AGENTS.override.md ao lado (normalmente no .gitignore). Ele é carregado em vez do AGENTS.md.

Todo arquivo de contexto passa por varredura contra injeção de prompt antes de entrar.

6. Perfis

Um perfil é um HERMES_HOME separado: configuração, segredos, memória, skills, sessões e cron próprios. Serve para ter um agente de trabalho e um pessoal, ou vários bots com personalidades distintas.

hermes profile create trabalho
hermes profile create pesquisa --no-skills
hermes profile list
hermes -p trabalho                # abre o perfil
trabalho chat                     # alias criado pelo perfil
trabalho gateway start

Memória é por perfil. A documentação avisa: nunca aponte dois processos de agente para o mesmo home, porque as escritas automáticas de memória vão se misturar. Dê a cada agente seu perfil.

7. Backup e migração

hermes backup                  # exporta a instalação inteira
hermes profile export <nome>   # exporta um único perfil

A FAQ oficial explica a diferença entre os dois e como restaurar em outra máquina. Antes de qualquer hermes update, um snapshot rápido dos arquivos de estado é feito automaticamente em state-snapshots/; a opção updates.pre_update_backup: full faz um zip do home inteiro.

8. Sessões e o banco de estado

Tudo vai para ~/.hermes/state.db, um SQLite com busca de texto completo. Cada sessão guarda id, plataforma de origem, usuário, título, modelo, foto do prompt de sistema, mensagens completas, contagem de tokens e sessão pai (quando houve compressão).

hermes sessions list
hermes sessions optimize   # compacta o índice sem apagar nada
hermes sessions prune      # apaga sessões antigas encerradas

Os dois últimos recusam rodar enquanto outro processo Hermes (gateway, Desktop, dashboard, cron) estiver com o banco aberto. Pare o processo ou use --force.

Leia mais

• Qual arquivo faz o quê: https://hermes-agent.nousresearch.com/docs/user-guide/which-file-does-what
• Configuração: https://hermes-agent.nousresearch.com/docs/user-guide/configuration
• Arquivos de contexto: https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files
• Personalidade: https://hermes-agent.nousresearch.com/docs/user-guide/features/personality
• Perfis: https://hermes-agent.nousresearch.com/docs/user-guide/profiles
• Sessões: https://hermes-agent.nousresearch.com/docs/user-guide/sessions

Objetivos

• Conhecer as ferramentas embutidas e os toolsets.
• Escolher o backend de terminal certo: local, Docker, SSH ou nuvem.
• Entender as oito camadas de segurança e configurar a aprovação de comandos.
• Saber quando o modo YOLO é aceitável e o que nem ele desliga.

1. Ferramentas e toolsets

Ferramentas são funções que o modelo pode chamar. O Hermes tem mais de 70, organizadas em 28 toolsets. As categorias:

hermes tools                            # configura toolsets por plataforma, interativo
hermes chat --toolsets "web,terminal"   # sessão só com esses

Toolsets comuns: web, search, terminal, file, browser, vision, image_gen, skills, tts, todo, memory, session_search, cronjob, code_execution, delegation, clarify, messaging, debugging, safe. Há presets por plataforma (hermes-cli, hermes-telegram) e toolsets dinâmicos por servidor MCP (mcp-<nome>).

Cada ferramenta ocupa tokens no prompt com seu esquema. Desligar o que você não usa barateia cada turno. O comando hermes prompt-size mostra, offline, quanto o prompt fixo pesa.

2. Processos em segundo plano

A ferramenta terminal aceita background=true e devolve um id de sessão. A ferramenta process então lista, consulta, espera, lê o log, mata ou envia entrada. Com pty=true o agente roda programas interativos, inclusive outros assistentes de código como o Claude Code. Resultados de processos concluídos ficam guardados por até sete dias (os 64 mais recentes) e só a conversa que os iniciou consegue lê-los.

3. Backends de terminal

O backend decide onde os comandos rodam.

terminal:
  backend: docker
  docker_image: python:3.11-slim
  container_cpu: 1
  container_memory: 5120
  container_disk: 51200
  container_persistent: true

No Docker o Hermes sobe um único contêiner de longa duração no primeiro uso e roteia todas as chamadas de terminal, arquivo e execute_code por docker exec nele. Pacotes instalados e diretório atual persistem de uma chamada para outra, através de /new e de subagentes, enquanto o processo Hermes viver. Com container_persistent: true, /workspace e /root sobrevivem a reinícios do Hermes.

Todo contêiner roda endurecido: sistema de arquivos raiz somente leitura, todas as capacidades Linux removidas, sem escalada de privilégio, limite de 256 processos, isolamento completo de namespaces.

Para SSH:

terminal:
  backend: ssh

# ~/.hermes/.env
TERMINAL_SSH_HOST=servidor.exemplo.com
TERMINAL_SSH_USER=usuario
TERMINAL_SSH_KEY=~/.ssh/id_ed25519

O problema do .bashrc

O agente roda o shell de forma não interativa. Inicializações pesadas (nvm, prompts que consultam rede) deixam cada comando lento, e blocos que esperam um terminal (read, tmux attach, menus) travam até o timeout. A correção é a guarda padrão no topo do .bashrc:

case $- in
  *i*) ;;
  *) return;;
esac
# tudo pesado abaixo desta linha

Se os comandos do agente demoram logo depois de funcionarem no seu terminal, suspeite primeiro disso.

Proxy de saída para Docker

Para que o contêiner nunca veja suas chaves reais, há um proxy de injeção de credenciais: o contêiner recebe tokens opacos que só funcionam atrás de um daemon local. Configure com hermes egress setup && hermes egress start. Por ora é só para Docker.

4. As oito camadas de segurança

1. Autorização de usuário no gateway: listas de permitidos e pareamento por código. Módulo 10.
2. Aprovação de comandos perigosos: humano no circuito.
3. Segurança de escrita em arquivos: lista de negação e sandbox opcional para write_file e patch.
4. Isolamento em contêiner.
5. Filtro de credenciais para subprocessos MCP.
6. Varredura de arquivos de contexto contra injeção de prompt.
7. Isolamento entre sessões; caminhos de cron endurecidos contra path traversal.
8. Sanitização de entrada: diretório de trabalho validado contra lista permitida.

5. Aprovação de comandos

Antes de executar, o Hermes compara o comando com uma lista de padrões perigosos. Se bater, pede aprovação.

approvals:
  mode: smart              # smart | manual | off
  timeout: 300             # segundos esperando sua resposta
  cron_mode: deny          # deny | approve, para tarefas agendadas
  single_query_mode: deny  # para hermes chat -q
  unattended_mode: deny    # para webhook e servidor de API

Padrões que disparam, entre outros: rm -r, chmod 777, mkfs, dd if=, DROP TABLE, DELETE FROM sem WHERE, redirecionar para /etc/, systemctl stop, kill -9 -1, curl ... | sh, bash -c, python -e, find -delete, docker stop/kill, qualquer coisa que mate o próprio gateway.

No terminal a pergunta aparece assim:

  DANGEROUS COMMAND: recursive delete
      rm -rf ~/old-project
      [o]nce  |  [s]ession  |  [a]lways  |  [d]eny

once libera uma vez, session libera o padrão até o fim da sessão, always grava em command_allowlist no config.yaml para sempre, deny bloqueia (padrão se você não responder dentro do timeout). Em mensageria você responde yes/no no chat.

Dica da documentação: comece com session. Só use always depois de ver o padrão várias vezes. O comando hermes approvals suggest minera seu histórico de aprovações e propõe entradas para a lista.

Dentro de contêiner (Docker, Singularity, Modal, Daytona, Vercel) a verificação é pulada, porque o contêiner é a fronteira.

6. YOLO e o que ele não desliga

hermes --yolo, /yolo na sessão ou HERMES_YOLO_MODE=1 pulam toda aprovação. Um banner vermelho e um marcador na barra de status lembram que está ligado. Use só em ambiente descartável.

Mesmo com YOLO, approvals.mode: off ou cron em modo approve, há um piso fixo que nunca executa: rm -rf / e variantes, fork bomb, mkfs em dispositivo raiz montado, dd zerando disco físico, curl de URL para sh no topo do sistema de arquivos. Não há flag de override. Se um fluxo legítimo precisa disso, rode fora do agente.

Você pode criar seu próprio piso com approvals.deny, uma lista de globs que bloqueia antes de YOLO:

approvals:
  deny:
    - "git push --force*"
    - "dd if=* of=/dev/*"

Sempre entre aspas, porque um * solto quebra o YAML. A documentação avisa que isso é política de comando, não sandbox: para contenção de verdade, use contêiner e permissões do sistema.

Há também uma guarda que não se desliga nem com force=True: o agente não consegue parar ou reiniciar o gateway supervisionado de dentro dele, nem matar processos Python por nome, porque o gateway é um processo Python.

7. Sudo

Em sessão interativa, comandos com sudo abrem um prompt de senha mascarado, guardado durante a sessão. Em mensageria ou cron não há canal seguro para senha; a alternativa é SUDO_PASSWORD no .env da máquina do agente. Nunca mande senha pelo chat.

8. Variáveis de ambiente para sandboxes

Skills que declaram required_environment_variables têm esses valores repassados automaticamente para terminal e execute_code, inclusive em Docker e Modal. Para outras variáveis, use terminal.env_passthrough no config.yaml. No Docker há ainda terminal.docker_forward_env, e tudo que for encaminhado fica visível para os comandos do contêiner.

Leia mais

• Ferramentas: https://hermes-agent.nousresearch.com/docs/user-guide/features/tools
• Segurança: https://hermes-agent.nousresearch.com/docs/user-guide/security
• Docker: https://hermes-agent.nousresearch.com/docs/user-guide/docker
• Referência de ferramentas e toolsets: https://hermes-agent.nousresearch.com/docs/reference/tools-reference

Objetivos

• Entender os dois arquivos de memória e seus limites.
• Saber o que vai para memória, o que vai para skill e o que não vai para lugar nenhum.
• Usar a busca em sessões.
• Controlar o que o agente salva com write_approval.
• Conhecer a linha do tempo de aprendizado e os provedores externos de memória.

1. O modelo esquece; o sistema lembra

O módulo 1 deixou claro: os pesos do modelo nunca mudam durante o uso. Toda "memória" é texto que o Hermes guarda em disco e reinjeta no prompt. Entender isso evita frustração e explica os limites.

2. Os dois arquivos

Os dois vivem em ~/.hermes/memories/ e entram no prompt de sistema como bloco congelado no início da sessão, com cabeçalho mostrando a ocupação:

MEMORY (your personal notes) [67% — 1,474/2,200 chars]
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed

As entradas são separadas por §. O agente vê a porcentagem e sabe quando está cheio.

O limite é pequeno de propósito. Memória não compacta sozinha: quando uma escrita ultrapassaria o limite, a ferramenta devolve erro com as entradas atuais e quanto precisa liberar, e o agente consolida ou remove na mesma rodada antes de tentar de novo.

3. A ferramenta memory

O agente usa três ações:

• add: nova entrada;
• replace: substitui uma entrada inteira, localizada por um trecho único (old_text);
• remove: remove uma entrada localizada por trecho único.

Não existe read: o conteúdo já está no prompt. O replace troca a entrada inteira pelo content novo; o old_text só serve para encontrá-la.

Dois alvos: memory (notas do agente) e user (perfil).

4. O que salvar e o que não salvar

Salva, sem você pedir:

• preferências suas ("prefiro TypeScript") vão para user;
• fatos do ambiente ("servidor roda Debian 12 com PostgreSQL 16") vão para memory;
• correções ("não use sudo com docker, usuário está no grupo docker");
• convenções do projeto;
• trabalho concluído com data;
• pedidos explícitos ("lembre que a rotação de chave é mensal").

Não salva:

• trivialidades ("usuário perguntou sobre Python");
• o que se acha com uma busca;
• despejos de dados, logs, blocos grandes de código;
• caminhos temporários e contexto de depuração de uma vez só;
• o que já está em SOUL.md ou AGENTS.md.

Entradas boas são densas: "Projeto ~/code/api usa Go 1.22, sqlc, router chi. Testes com 'make test'. CI no GitHub Actions." Entradas ruins são vagas ("usuário tem um projeto") ou narrativas longas.

Duplicatas exatas são rejeitadas em silêncio. Toda entrada passa por varredura contra injeção de prompt e exfiltração antes de ser aceita, porque vai parar no prompt de sistema.

5. "Eu pedi para lembrar e ele esqueceu"

A documentação lista a ordem de verificação, e o primeiro item explica a maioria dos casos:

1. A escrita aconteceu? Memória só persiste quando o modelo chama a ferramenta. "Anotei na memória" em texto não é uma chamada. Abra o arquivo: cat ~/.hermes/memories/MEMORY.md. Modelos locais pequenos (abaixo de uns 30 bilhões de parâmetros) e modelos fracos em chamada de ferramentas fazem isso com frequência. A solução é um modelo melhor para a configuração inicial; depois que as entradas existem, um modelo menor as lê bem.
2. A escrita ficou em espera? Com write_approval: true, escritas fora da CLI interativa aguardam /memory approve.
3. Você está no mesmo perfil? hermes -p trabalho lê ~/.hermes/profiles/trabalho/memories/.
4. A memória está ligada? memory.memory_enabled: false remove a ferramenta.
5. A foto é congelada. Salvo agora, visível na próxima sessão.

Duas coisas que não fazem o agente lembrar: variáveis no .env e fatos mencionados de passagem sem pedido de salvar. Para um local que o agente precisa em toda execução de uma tarefa recorrente, uma skill costuma ser melhor casa que a memória: carrega só quando é relevante e não disputa os 2.200 caracteres.

6. Sessões precisam de fronteiras

O sistema de memória é desenhado em torno do momento em que uma sessão termina. Na CLI isso acontece sozinho a cada invocação. Em Telegram e Discord uma conversa é uma única sessão contínua que sobrevive a reinícios e reboots. Se você nunca dá /new, a conversa roda por semanas como uma sessão só: fica cara (a compressão roda repetidamente) e o ciclo esquecer, recuperar da memória, buscar no histórico quase nunca dispara.

Prática: dê /new em fronteiras naturais, tarefa concluída, mudança de assunto, começo do dia.

7. Busca em sessões

Além da memória curada, toda conversa de todas as plataformas fica em ~/.hermes/state.db com índice de texto completo (FTS5). A ferramenta session_search devolve mensagens reais, sem resumo por LLM, em cerca de 20 ms, e permite rolar para frente e para trás dentro da sessão encontrada.

O prompt de sistema instrui o agente a usar session_search quando você menciona algo de uma conversa passada, antes de pedir para repetir.

8. Controlando as escritas

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
  write_approval: false

Com write_approval: true, na CLI interativa cada escrita pergunta antes; em mensageria, scripts e na revisão em segundo plano, as escritas ficam em espera:

/memory pending
/memory approve <id>     # ou all
/memory reject <id>
/memory approval on

É a resposta para "o agente salvou uma suposição errada sobre mim".

Desligar os dois arquivos (memory_enabled e user_profile_enabled em false) remove a ferramenta do esquema e o texto de orientação do prompt. Um provedor externo configurado em memory.provider continua com suas próprias ferramentas.

9. A revisão em segundo plano

Depois de um turno, uma revisão de autoaperfeiçoamento pode salvar memória ou corrigir uma skill. É o ciclo de aprendizado do Hermes: correções repetidas e lições duráveis viram entradas de memória ou skills. Por padrão aparece uma linha curta no chat ("Memory updated"). Controle com:

display:
  memory_notifications: on    # off | on | verbose

verbose mostra uma prévia do que mudou. A configuração só afeta a notificação; a revisão continua rodando.

10. A linha do tempo de aprendizado

hermes journey (ou /journey na TUI e no Desktop) mostra tudo que o Hermes aprendeu em ordem cronológica: skills salvas e entradas de memória, com uma animação opcional (--play). É também onde você poda:

hermes journey list
hermes journey delete <node>     # skill é arquivada, memória é removida
hermes journey edit <node>       # abre no $EDITOR

11. Provedores externos de memória

O sistema de memória é plugável. O catálogo de plugins traz, entre outros, o Honcho (Plastic Labs), que adiciona um modelo do usuário construído por raciocínio após cada conversa, resumo de sessão e perfis separados por agente. Instalação:

hermes plugins install honcho
hermes memory setup

Há também Mem0, Hindsight e outros. Quando dois agentes precisam compartilhar memória, o caminho recomendado é um provedor externo, nunca o mesmo home.

Leia mais

• Memória: https://hermes-agent.nousresearch.com/docs/user-guide/features/memory
• Provedores de memória: https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers
• Honcho: https://hermes-agent.nousresearch.com/docs/user-guide/features/honcho
• Sessões: https://hermes-agent.nousresearch.com/docs/user-guide/sessions

Objetivos

• Entender o que é uma skill, o padrão aberto e a divulgação progressiva.
• Usar skills embutidas e instalar do Skills Hub.
• Escrever uma skill do zero no formato SKILL.md.
• Usar /learn para gerar skills a partir de documentação ou de uma tarefa feita.
• Entender o curador e a decisão entre skill, memória, ferramenta e plugin.

1. O que é uma skill

Uma skill é um documento de instruções que o agente carrega sob demanda quando uma tarefa combina com ela. É um arquivo SKILL.md com nome, descrição curta e um procedimento passo a passo, opcionalmente acompanhado de scripts, referências e modelos. O Hermes segue o padrão aberto agentskills.io, então skills escritas para outras ferramentas servem, e vice-versa.

A documentação chama isso de memória procedural: memória guarda fatos, skill guarda procedimentos.

Todas ficam em ~/.hermes/skills/, a fonte de verdade. Na instalação as skills embutidas são copiadas do repositório; skills do Hub e as criadas pelo agente vão para o mesmo lugar. O agente pode modificar ou apagar qualquer uma.

2. Divulgação progressiva

Skills não incham o prompt. Três níveis:

Nível 0: skills_list()           -> nome, descrição e categoria de todas (~3 mil tokens)
Nível 1: skill_view(nome)        -> conteúdo completo
Nível 2: skill_view(nome, path)  -> um arquivo de referência específico

O agente lê as descrições de graça e só carrega o corpo quando precisa. O prompt de sistema traz um índice <available_skills> e a instrução de consultá-lo antes de responder.

3. Usando skills

Toda skill instalada vira comando de barra:

/github-pr-workflow crie um PR para a refatoração de auth
/pdf extraia as tabelas de ~/docs/contrato.pdf
/excalidraw                       # só carrega e deixa o agente perguntar o que você quer

Pode encadear até cinco no começo da mensagem:

/github-pr-workflow /test-driven-development corrija a issue #123 e abra um PR

O parse para no primeiro token que não é skill, então caminhos que começam com / não são engolidos.

Em conversa normal o agente escolhe a skill certa sozinho quando a tarefa combina. Você não precisa invocar.

Skills embutidas que valem conhecer (catálogo de outubro de 2026): github, pdf, docx, xlsx, powerpoint, google-workspace, notion, obsidian, arxiv, youtube-content, maps, claude-code, codex, computer-use, hermes-agent (ensina o próprio Hermes a se configurar), hermes-agent-skill-authoring, humanizer, codebase-inspection, requesting-code-review, simplify-code. A lista completa está na referência oficial.

4. O Skills Hub

hermes skills browse
hermes skills search kubernetes
hermes skills install openai/skills/k8s
hermes skills list
hermes skills uninstall k8s

O argumento de instalação é um slug fonte/caminho. Toda instalação passa por varredura de segurança em quarentena; o Hermes grava URL de origem, hash do conteúdo, versão do scanner e resultado em skills/.hub/lock.json. Instalações de URL ou GitHub copiam só o SKILL.md e os arquivos que ele referencia em references/, templates/, scripts/, assets/ e examples/.

Opcionalmente há uma segunda opinião com o NVIDIA SkillEvaluator (detecção de PII, unicode escondido, lint de scripts, licenças), apenas consultiva.

Se quiser um perfil sem skills embutidas: hermes skills opt-out para parar o semeamento futuro, --remove para apagar as não modificadas, hermes profile create nome --no-skills para começar vazio.

5. O formato SKILL.md

```markdown

name: minha-skill description: Descrição curta, até 60 caracteres version: 1.0.0 platforms: [linux, macos] # opcional metadata: hermes: tags: [python, automacao] category: devops requires_toolsets: [terminal] # só aparece se o toolset estiver ativo fallback_for_toolsets: [web] # só aparece se o toolset NÃO estiver ativo config: # configurações não secretas em config.yaml - key: minha.pasta description: "Pasta de dados" default: "~/dados" prompt: "Onde ficam os dados?" required_environment_variables: # segredos, pedidos com segurança no carregamento - name: MINHA_API_KEY prompt: Chave da API help: Obtenha em https://exemplo.com required_for: acesso à API

Título

When to Use

Quando o agente deve carregar esta skill.

Procedure

1. Passo um
2. Passo dois

Pitfalls

• Falhas conhecidas e como contornar.

Verification

Como confirmar que funcionou.

Pontos que importam:

- A descrição é o que o agente vê de graça. Curta e específica.
- `platforms` esconde a skill em sistemas incompatíveis.
- `requires_*` e `fallback_for_*` controlam quando ela aparece. A skill embutida `duckduckgo-search` usa `fallback_for_toolsets: [web]`: só aparece quando não há chave de busca na web.
- Variáveis de ambiente declaradas são pedidas com segurança quando a skill carrega na CLI local, nunca em chat, e são repassadas automaticamente para `terminal` e `execute_code`, inclusive em Docker.
- Configurações não secretas vão para `skills.config` no `config.yaml`; `hermes config migrate` pergunta as que faltam e o valor resolvido é injetado quando a skill carrega.

Estrutura de pasta:

~/.hermes/skills/devops/deploy-k8s/ ├── SKILL.md ├── references/ ├── templates/ ├── scripts/ ├── examples/ └── assets/ ```

6. Entrega de mídia a partir de skills

Se a resposta contém um caminho absoluto para um arquivo de mídia, o gateway remove o caminho do texto e envia o arquivo nativamente (foto no Telegram, anexo no Discord). A diretiva [[as_document]] força envio como documento, preservando os bytes originais (o Telegram recomprime fotos). [[audio_as_voice]] transforma áudio em mensagem de voz.

7. Aprendendo com /learn

/learn transforma qualquer fonte em skill sem você escrever o SKILL.md:

/learn o cliente REST em ~/projetos/sdk, foco em auth e paginação
/learn https://docs.exemplo.com/api/quickstart
/learn como eu acabei de publicar o servidor de homologação
/learn registrar despesa: abrir o portal, Novo > Despesa, anexar recibo, enviar
/learn ~/livros/designing-data-intensive-applications.pdf

O agente coleta o material com as ferramentas que já tem e escreve a skill seguindo os padrões da casa. Fontes grandes (livro, pilha de artigos, pasta de documentação) viram uma skill de base de conhecimento: um SKILL.md enxuto com os modelos mentais e um índice, mais um arquivo destilado por capítulo em references/, carregados sob demanda. Rodar /learn de novo sobre o mesmo tema incorpora o material na skill existente em vez de duplicar.

Funciona igual na CLI, no gateway, na TUI e no dashboard, porque é o próprio agente que faz o trabalho. A escrita final usa skill_manage, então o gate de aprovação se aplica se estiver ligado.

8. O agente criando skills sozinho

Depois de resolver um problema novo, o agente pode salvar o procedimento com skill_manage (criar, corrigir, escrever arquivo, remover, apagar). A dica da documentação: se uma tarefa tem cinco passos ou mais e você vai repetir, diga "salve o que você acabou de fazer como uma skill chamada deploy-staging". Na próxima vez, /deploy-staging.

Para aprovar antes de gravar: skills.write_approval: true.

9. O curador

Skills criadas pelo agente se acumulam. O curador é uma manutenção em segundo plano que:

1. marca como stale as skills sem uso por 14 dias e arquiva em ~/.hermes/skills/.archive/ as sem uso por 30 (determinístico, sem LLM);
2. opcionalmente (curator.consolidate: true) roda uma revisão com modelo auxiliar que funde skills sobrepostas e corrige derivas.

Roda quando passaram 7 dias desde a última execução e o agente está ocioso há 2 horas. Na primeira instalação ele espera um intervalo inteiro antes de agir. Nunca apaga: o pior caso é arquivar, e hermes curator restore <skill> traz de volta. Skills fixadas (hermes curator pin) e as referenciadas por cron ficam fora.

hermes curator status
hermes curator run --dry-run
hermes curator pin minha-skill
hermes curator list-archived
hermes curator rollback

10. Skill, memória, ferramenta ou plugin?

A documentação pede: antes de escrever uma ferramenta, pergunte se não deveria ser uma skill.

11. Pastas externas e precedência

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/compartilhado/skills-da-equipe

Se o mesmo nome existir em mais de um lugar, a precedência é projeto, depois ~/.hermes/skills/, depois skills.create_dir, depois external_dirs. Pastas externas não são protegidas contra escrita: se o processo puder gravar, o agente pode alterar.

Leia mais

• Sistema de skills: https://hermes-agent.nousresearch.com/docs/user-guide/features/skills
• Criando skills: https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills
• Curador: https://hermes-agent.nousresearch.com/docs/user-guide/features/curator
• Catálogo embutido: https://hermes-agent.nousresearch.com/docs/reference/skills-catalog
• Padrão aberto: https://agentskills.io/specification
• Vídeos: Masterclass 4 (Skills), Derek Cheung sobre /learn e /goal, e Maestros da IA, "Essas 11 skills valem a pena" (português). Links em recursos/videos.md.

Objetivos

• Entender o que o gateway é e como roteia mensagens para o agente.
• Criar um bot no Telegram e conectá-lo ao Hermes com lista de usuários permitidos.
• Conhecer o pareamento por código e o canal "home".
• Instalar o gateway como serviço.
• Saber o que muda em grupos, no Discord e no WhatsApp.

1. O que é o gateway

O gateway é um único processo em segundo plano que conecta todas as plataformas configuradas, mantém uma sessão por chat, executa o agendador de cron (a cada 60 segundos) e entrega mensagens, inclusive voz. Plataformas suportadas em outubro de 2026: Telegram, Discord, Slack, WhatsApp (via web e via Cloud API), Signal, SMS, e-mail, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), Photon, QQ, Yuanbao, Microsoft Teams, Google Chat, LINE, ntfy, IRC, SimpleX, webhooks e um servidor de API compatível com OpenAI.

O fluxo de uma mensagem:

evento na plataforma -> adaptador -> MessageEvent -> GatewayRunner._handle_message()
  -> autorização -> recupera a sessão do chat -> AIAgent.run_conversation() -> entrega

Os adaptadores ficam em gateway/platforms/ (embutidos) e plugins/platforms/ (plugins). Cada plataforma tem recursos diferentes; a tabela oficial mostra quem tem voz, imagem, arquivo, thread, reação, indicador de digitação e streaming. Telegram tem tudo menos reações; Discord e Slack têm tudo.

2. Pré-requisito

Um chat funcionando na CLI. Se hermes não responde no terminal, o gateway não vai responder no Telegram.

3. Telegram passo a passo

Criar o bot

1. No Telegram, abra @BotFather.
2. Envie /newbot.
3. Escolha um nome de exibição e um nome de usuário terminado em bot.
4. Guarde o token, algo como 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ. Quem tem o token controla o bot; se vazar, /revoke no BotFather.

Opcional no BotFather: /setdescription, /setabouttext, /setuserpic, /setcommands (um menu inicial útil é help, new, sethome), /setinline para habilitar o seletor de comandos pesquisável.

Descobrir seu ID numérico

O Hermes controla acesso por ID numérico, não por nome de usuário. Mande qualquer mensagem para @userinfobot e ele responde com o número.

Configurar

Caminho interativo:

hermes gateway setup

Escolha Telegram, informe o token e os IDs permitidos.

Caminho manual, em ~/.hermes/.env:

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789

Vários usuários: separe por vírgula.

O dashboard e o Desktop têm um botão "Create with QR" que cria o bot, detecta seu ID e grava tudo sozinho.

Rodar

hermes gateway            # em primeiro plano, bom para testar
hermes gateway status

Mande uma mensagem para o bot. Deve responder em segundos.

4. Quem pode falar com o bot

A ordem de verificação do gateway:

1. flag de liberar todos por plataforma (DISCORD_ALLOW_ALL_USERS=true);
2. lista de aprovados por pareamento;
3. lista por plataforma (TELEGRAM_ALLOWED_USERS);
4. lista global (GATEWAY_ALLOWED_USERS);
5. flag global de liberar todos (GATEWAY_ALLOW_ALL_USERS=true);
6. padrão: negar.

Se não houver nenhuma lista e nenhuma flag, todos são negados e o gateway avisa no log.

Regra que a documentação repete e este curso também: nunca ligue GATEWAY_ALLOW_ALL_USERS=true em um bot com acesso ao terminal.

Pareamento por código

Em vez de coletar IDs, deixe o bot distribuir códigos. Um desconhecido manda mensagem, recebe um código de 8 caracteres, e você aprova no terminal:

hermes pairing approve telegram XKGH5N7P

O comportamento para desconhecidos é configurável:

unauthorized_dm_behavior: pair     # pair | ignore | decline
whatsapp:
  unauthorized_dm_behavior: ignore

pair é o padrão em plataformas de chat; e-mail usa ignore por padrão. decline manda uma recusa curta e ignora o remetente por 24 horas.

Comandos para administradores e usuários

Plataformas com lista por usuário aceitam dois níveis: administradores (allow_admin_from) veem todos os comandos de barra; usuários comuns só os listados em user_allowed_commands, mais /help e /whoami. Isso vai no bloco extra: da plataforma no config.yaml.

5. Grupos no Telegram

Bots têm "modo de privacidade" ligado por padrão: em grupo só veem comandos com /, respostas diretas a eles e mensagens de serviço. Para ver tudo, desligue em BotFather (/mybots, Bot Settings, Group Privacy) e remova e readicione o bot ao grupo, ou torne o bot administrador do grupo.

Para o bot observar a conversa sem responder a tudo:

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

Mensagens sem menção entram na sessão como contexto observado, marcadas com nome e id, e o agente só age quando mencionado ou respondido.

6. Canal home e entrega proativa

/sethome no chat que você quer como principal. Resultados de cron e mensagens proativas vão para lá. Sem home, o agente não tem para onde mandar.

7. Sessões em mensageria

Uma conversa por chat, contínua, que sobrevive a reinício do gateway e reboot da máquina. Compressão cuida do tamanho. Não há reset diário automático; /new é com você. O módulo 8 explicou por que isso importa para a memória.

Aprovação de comandos perigosos em chat: o bot envia o comando e espera yes/no.

/verbose controla quanto da atividade de ferramentas aparece no chat. Em mensageria, new costuma ser o melhor.

8. Rodar como serviço

hermes gateway install                 # serviço de usuário (systemd no Linux, launchd no macOS)
sudo hermes gateway install --system   # serviço de sistema, sobe no boot
hermes gateway start
hermes gateway stop
hermes gateway status

No Linux, o serviço de usuário é systemctl --user ... hermes-gateway. Lembre a guarda do módulo 7: o agente não consegue parar o próprio gateway de dentro.

9. Discord, WhatsApp e os outros

Discord: crie uma aplicação em discord.com/developers, pegue o token do bot, configure DISCORD_BOT_TOKEN e DISCORD_ALLOWED_USERS (IDs de 18 dígitos). Suporta canais de voz, reações e threads.

WhatsApp: há dois caminhos, o adaptador via web (pareamento por QR) e a Cloud API oficial da Meta. A FAQ explica como rodar vários agentes em um único número com vinculação por chat.

E-mail: IMAP e SMTP; o agente pode ter o próprio endereço.

Cada plataforma tem uma página oficial com os passos. O hermes gateway setup cobre as principais.

10. Vários perfis, um gateway

Com perfis (módulo 6) você pode ter um bot por perfil, cada um com seu token, memória e personalidade. A página "multi-profile gateways" descreve um gateway multiplexado que serve vários perfis em um processo, com segredos isolados por perfil.

Leia mais

• Gateway: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/
• Telegram: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/telegram
• Discord: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/discord
• WhatsApp: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/whatsapp
• Segurança (autorização): https://hermes-agent.nousresearch.com/docs/user-guide/security
• Tutorial oficial "Team Telegram assistant": https://hermes-agent.nousresearch.com/docs/guides/team-telegram-assistant
• Vídeos: Thon Silva, "Como instalar o Hermes Agent do zero na VPS + Telegram" e Masterclass 2 (VPS, Telegram, Discord). Links em recursos/videos.md.

Objetivos

• Criar tarefas agendadas por linguagem natural, por comando de barra e pela CLI.
• Escrever prompts autocontidos para cron.
• Usar /goal para o agente iterar sozinho até um critério verificável.
• Delegar subtarefas em paralelo com delegate_task.
• Saber o que é o Kanban e quando ele faz sentido.
• Construir o bot de briefing diário do tutorial oficial.

1. Cron no Hermes

Um cron job do Hermes não é um script de shell agendado. É uma tarefa de agente: na hora marcada, um AIAgent novo é criado, as skills anexadas são carregadas, o prompt é executado e o resultado é entregue a um destino. Os jobs ficam em ~/.hermes/cron/jobs.json e o agendador roda dentro do gateway (tick a cada 60 segundos). Sem gateway rodando, nada dispara.

O que um job pode fazer:

• rodar uma vez ou de forma recorrente;
• ser pausado, retomado, editado, disparado à mão e removido;
• carregar zero, uma ou várias skills;
• entregar no chat de origem, em arquivo local ou em uma plataforma configurada;
• rodar sem agente (no_agent): um script na hora marcada, saída entregue como está, sem LLM;
• disparar por evento externo via rota de webhook.

Criar

Em conversa:

Toda manhã às 9h, verifique as novidades do Hacker News sobre IA e me mande um resumo no Telegram.

Comando de barra:

/cron add "in 30m" "Me lembre de checar o build"
/cron add "every 2h" "Verifique o status do servidor"
/cron add "0 9 * * *" "Resuma os feeds" --skill blogwatcher

CLI:

hermes cron create "every 1h" "Resuma itens novos do feed" --skill blogwatcher --name "Feeds"
hermes cron create "every 1d at 09:00" "Audite PRs abertos" --workdir /home/eu/projetos/acme
hermes cron create "every 1h" "Poste o digest" --paused --paused-reason "Aguardando revisão"

Aceita expressões cron, "every 2h", "in 30m", "every 1d at 09:00" e timestamps ISO.

Gerenciar

hermes cron list
hermes cron pause <id-ou-nome>
hermes cron resume <id-ou-nome>
hermes cron run <id-ou-nome>        # dispara no próximo tick
hermes cron remove <id-ou-nome>
hermes cron edit <id> --schedule "every 4h"
hermes cron edit <id> --prompt "Nova tarefa"
hermes cron edit <id> --add-skill maps
hermes cron edit <id> --remove-skill blogwatcher
hermes cron status
hermes pause          # parada de emergência global; hermes resume libera

Nomes funcionam no lugar do id, sem diferenciar maiúsculas. Se dois jobs têm o mesmo nome, o comando recusa e lista os ids.

Qual modelo roda o job

Na hora do disparo: pin por job, depois cron.model no config.yaml, depois o modelo principal do hermes model. Jobs sem pin seguem o modelo principal, então trocar o modelo do chat troca a frota de cron. Para fixar: hermes cron edit <id> --pin. O esforço de raciocínio também pode ser fixado por job (--reasoning-effort high).

Validação antes de rodar

Antes de montar qualquer coisa, o agendador confere se a chave do provedor resolve, se as skills anexadas têm o que precisam, se o destino de entrega tem credenciais e se os servidores MCP nomeados responderam. Se falhar, o job fica blocked_config, um único alerta é enviado e nenhuma chamada de LLM é feita. Um job mal configurado nunca gasta tokens.

Segurança

Sessões de cron não podem criar outros crons (evita laços). Comandos perigosos em cron são negados por padrão (approvals.cron_mode: deny). Jobs rodam sem AGENTS.md a menos que você passe --workdir.

2. A regra de ouro: prompts autocontidos

Um job roda em sessão nova, sem memória da conversa em que foi criado. O prompt precisa ter tudo.

Ruim:

Faça meu briefing de sempre.

Bom:

Busque na web as notícias das últimas 24 horas sobre agentes de IA e modelos abertos.
Encontre pelo menos 5 artigos. Resuma os 3 mais importantes: título claro,
resumo de 2 frases e URL. Tom profissional. Termine com a contagem de artigos.

3. Tutorial: bot de briefing diário

O guia oficial "Daily Briefing Bot" é o laboratório deste módulo. Pré-requisitos: gateway rodando como serviço, busca na web configurada (chave Firecrawl ou Tool Gateway do Nous Portal), Telegram com /sethome feito. Sem mensageria, use deliver: "local" e leia em ~/.hermes/cron/output/.

Passos:

1. Teste o prompt à mão em hermes até gostar do formato.
2. Crie o job com /cron add "0 8 * * *" "<seu prompt>" ou pedindo em linguagem natural.
3. Rode hermes cron run <id> para testar sem esperar as 8h.
4. Refine o prompt com hermes cron edit.

Variações do guia: vários temas em um briefing, anexar skills como youtube-content ou arxiv, entregar em mais de uma plataforma.

4. Goals: iterar até terminar

/goal dá ao Hermes um objetivo permanente dentro da sessão. Depois de cada turno, um modelo juiz avalia se a última resposta satisfez o objetivo. Se não, o Hermes injeta um prompt de continuação e segue, até atingir o objetivo, você pausar, ou o orçamento de turnos (20 por padrão) acabar.

/goal Corrija todos os erros de lint em src/ e garanta que `ruff check` passa

Você verá "Goal set (20-turn budget)", depois "Continuing toward goal (1/20): ..." e por fim "Goal achieved" ou "Goal paused".

Objetivos vagos geram julgamentos vagos. Diga o que "pronto" significa, como provar, o que não quebrar e quando parar. Um gate com pytest é a forma mais simples de tornar isso verificável.

Use /goal quando você diria "continue" três vezes. Para tarefas de um turno, não precisa.

5. Delegação: subagentes

delegate_task cria agentes filhos com contexto isolado, as mesmas ferramentas e terminal próprio. Só o resumo final volta para o pai. Chamadas de nível superior rodam em segundo plano: o Hermes devolve um identificador na hora e posta o resultado depois como mensagem nova.

Tarefa única:

delegate_task(
    goal="Descobrir por que os testes falham",
    context="Erro: assertion em test_foo.py linha 42. Projeto em /home/eu/app, Python 3.11."
)

Lote paralelo (até 10 ao mesmo tempo por padrão):

delegate_task(tasks=[
    {"goal": "Pesquisar tema A", "context": "..."},
    {"goal": "Pesquisar tema B", "context": "..."},
    {"goal": "Corrigir o build", "context": "Raiz do projeto: /home/eu/app"}
])

A regra crítica, em destaque na documentação: subagentes não sabem nada. Começam com conversa vazia. Só recebem goal e context. Um delegate_task(goal="Corrija o erro") sem contexto é inútil. A única exceção é que o filho recebe os arquivos de contexto do projeto (AGENTS.md e similares) quando o pai tem um diretório de trabalho resolvido.

Opções úteis: output_schema (JSON Schema que a resposta deve seguir; o pai valida e dá uma rodada de correção), images (até 8 imagens para tarefas visuais).

Orçamento: cada filho tem até delegation.max_iterations iterações (50 por padrão). Processos em segundo plano do filho morrem quando ele termina; se algo precisa continuar, inicie no pai.

Padrões de uso, do guia "delegation patterns": pesquisa paralela, revisão e correção em contexto limpo, refatoração grande que inundaria o contexto do pai.

6. Kanban: vários agentes, um quadro

O Kanban é um quadro de tarefas durável em ~/.hermes/kanban.db, compartilhado entre perfis. Cada cartão é despachado a um processo trabalhador completo, com identidade própria (um perfil), sessão própria e orçamento próprio. Cartões têm dependências, responsáveis e passagens de bastão. Há um disjuntor para falhas consecutivas.

Quando usar cada coisa:

O tutorial oficial do Kanban traz quatro histórias (desenvolvedor solo, fazenda de agentes, pipeline por papéis com retentativa, disjuntor) com capturas do dashboard.

7. Hooks, webhooks e eventos

Jobs podem disparar por webhook (cron_job em uma rota) no momento em que algo acontece, como um comentário em PR. O guia "GitHub PR review agent" monta um revisor automático assim. O módulo 12 trata de hooks em geral.

Leia mais

• Cron: https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
• Tutorial do briefing: https://hermes-agent.nousresearch.com/docs/guides/daily-briefing-bot
• Goals: https://hermes-agent.nousresearch.com/docs/user-guide/features/goals
• Delegação: https://hermes-agent.nousresearch.com/docs/user-guide/features/delegation
• Kanban: https://hermes-agent.nousresearch.com/docs/user-guide/features/kanban e o tutorial em kanban-tutorial
• Revisor de PR no GitHub: https://hermes-agent.nousresearch.com/docs/guides/github-pr-review-agent

Objetivos

• Conectar servidores MCP locais e remotos.
• Escrever um plugin mínimo que adiciona uma ferramenta e um hook.
• Conhecer os quatro sistemas de hooks e quando usar cada um.
• Entender a fronteira de confiança de cada mecanismo de extensão.

1. Os três caminhos para estender o Hermes

A documentação pede que você prefira skill, depois MCP, depois plugin. Adicionar ferramenta embutida no código do Hermes (tools/ e toolsets.py) é só para quem está contribuindo com o projeto; o módulo 13 mostra como, por curiosidade.

2. MCP

MCP (Model Context Protocol) é um protocolo aberto para servidores de ferramentas. O Hermes descobre as ferramentas de cada servidor na inicialização e as registra como se fossem nativas, em um toolset dinâmico mcp-<nome>.

Servidor local (stdio):

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/eu/projetos"]
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

Servidores HTTP remotos entram no mesmo bloco com URL. Há filtro por servidor para expor só as ferramentas que você quer. Resources e prompts do servidor, quando existem, ganham wrappers utilitários.

Para quem vem do Claude Code: o bloco mcpServers do ~/.claude.json mapeia para mcp_servers, e hermes import-agent claude-code migra tudo, inclusive skills e instruções. A sintaxe ${env:VAR} do Cursor também é aceita.

Há um catálogo de servidores MCP revisados pela Nous com instalação em um comando, e o /reload-mcp reconstrói as ferramentas sem reiniciar (com confirmação, porque invalida o cache de prompt).

Segurança: subprocessos MCP recebem um ambiente filtrado, não o seu ambiente inteiro. Credenciais vão pelo env: do servidor.

3. Plugins

Um plugin é uma pasta em ~/.hermes/plugins/ com um manifesto e código Python.

~/.hermes/plugins/hello-world/
├── plugin.yaml
└── __init__.py

plugin.yaml:

name: hello-world
version: "1.0"
description: Plugin mínimo de exemplo

__init__.py:

import json

def register(ctx):
    schema = {
        "name": "hello_world",
        "description": "Devolve uma saudação para o nome informado.",
        "parameters": {
            "type": "object",
            "properties": {"name": {"type": "string", "description": "Nome"}},
            "required": ["name"],
        },
    }

    def handle_hello(params, **kwargs):
        name = params.get("name", "Mundo")
        return json.dumps({"success": True, "greeting": f"Olá, {name}!"})

    ctx.register_tool(name="hello_world", toolset="hello_world",
                      schema=schema, handler=handle_hello)

    def on_tool_call(tool_name, params, result):
        print(f"[hello-world] ferramenta chamada: {tool_name}")

    ctx.register_hook("post_tool_call", on_tool_call)

Regras que valem para toda ferramenta: o handler devolve string JSON (json.dumps), nunca dict; erros voltam como {"error": "..."}, nunca como exceção; o handler recebe (params, **kwargs).

Plugins são descobertos mas desligados por padrão. Para ativar:

plugins:
  enabled:
    - hello-world

Ou hermes plugins enable hello-world. Reinicie o Hermes e o modelo já pode chamar hello_world.

O que um plugin pode registrar, pelo objeto ctx:

• ferramentas (register_tool), hooks (register_hook), comandos de barra (register_command), subcomandos da CLI (register_cli_command);
• skills empacotadas (register_skill, acessíveis como plugin:skill);
• uma plataforma de chat nova (register_platform);
• provedor de geração de imagem ou vídeo, motor de compressão de contexto, backend de terminal, driver de uso de computador, transporte de aprovação;
• chamadas de LLM com as credenciais do usuário (ctx.llm.complete);
• chamada a servidores MCP (ctx.call_mcp).

Provedores de memória e de modelo usam carregadores próprios em plugins/memory/<nome>/ e plugins/model-providers/<nome>/.

Fontes de descoberta, em ordem (a última vence em colisão de nome): embutidos no repositório, ~/.hermes/plugins/, .hermes/plugins/ do projeto (precisa de HERMES_ENABLE_PROJECT_PLUGINS=true), entry points pip, Nix.

Instalar de um repositório:

hermes plugins install dono/repo
hermes plugins install dono/repo --ref <sha completo de 40 caracteres>
hermes plugins
hermes plugins disable nome

Pinos exigem SHA completo e imutável; tags e branches são recusados.

4. Hooks

Quatro sistemas, com propósitos diferentes:

Erros em hooks são isolados e logados, não derrubam o agente. Mas hooks não são todos passivos: um hook pre_tool_call de shell pode bloquear a ferramenta e falha fechado se estourar o tempo.

Hook de gateway

# ~/.hermes/hooks/meu-hook/HOOK.yaml
name: meu-hook
description: Registra toda atividade do agente
events:
  - agent:start
  - agent:end
  - agent:step

# ~/.hermes/hooks/meu-hook/handler.py
import json
from datetime import datetime
from pathlib import Path

LOG = Path.home() / ".hermes" / "hooks" / "meu-hook" / "activity.log"

async def handle(event_type: str, context: dict):
    with open(LOG, "a") as f:
        f.write(json.dumps({"ts": datetime.now().isoformat(),
                            "event": event_type, **context}) + "\n")

A função precisa se chamar handle, pode ser async ou não. Eventos: gateway:startup, session:start, session:end, session:reset, session:compress, agent:start, agent:step, agent:end, reaction:added, reaction:removed, command:* (curinga para qualquer comando de barra).

Modelo de confiança: colocar os dois arquivos na pasta é o opt-in. Não há lista de habilitação, plugins.enabled não se aplica, e o handler.py roda no processo do gateway com todo o acesso dele. Leia o código antes de colocar na pasta, como faria com um plugin.

5. Fronteiras de confiança, resumidas

• Skills do Hub passam por varredura de segurança e quarentena.
• Plugins são desligados até você habilitar; subprocessos MCP recebem ambiente filtrado.
• Hooks de gateway e hooks de shell são confiáveis por posicionamento: quem escreve no seu ~/.hermes já pode rodar código como você.
• Plugins de projeto exigem uma variável de ambiente explícita, para que clonar um repositório estranho não execute código.

Leia mais

• MCP: https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp
• Guia "Use MCP with Hermes": https://hermes-agent.nousresearch.com/docs/guides/use-mcp-with-hermes
• Plugins: https://hermes-agent.nousresearch.com/docs/user-guide/features/plugins
• Construindo um plugin: https://hermes-agent.nousresearch.com/docs/developer-guide/plugins/
• Hooks: https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks
• Adaptadores de plataforma: https://hermes-agent.nousresearch.com/docs/developer-guide/adding-platform-adapters

Objetivos

• Navegar o repositório e saber onde cada coisa vive.
• Entender o laço de conversa do AIAgent turno a turno.
• Entender a montagem do prompt em três camadas e por que a ordem importa para o cache.
• Conhecer a compressão de contexto em dois estágios.
• Usar o Hermes como biblioteca Python.
• Saber como uma ferramenta embutida é registrada.

Este módulo pressupõe leitura de código Python. Se você não programa, leia as seções 1, 2, 3 e 5 para o entendimento conceitual e pule o resto.

1. Mapa do repositório

hermes-agent/
├── run_agent.py              # fachada AIAgent
├── cli.py                    # entrada da CLI
├── model_tools.py            # coleta de esquemas e despacho de ferramentas
├── hermes_state.py           # banco de sessões (SQLite + FTS5)
├── toolsets.py               # definição dos toolsets
├── batch_runner.py           # processamento em lote
├── agent/                    # laço, prompt, compressão, cache
│   ├── conversation_loop.py  # corpo do run_conversation()
│   ├── turn_*.py             # fases do turno: preparo, chamada, erro, overflow, truncamento, recuperação
│   ├── tool_executor.py      # execução e interceptação de ferramentas
│   ├── prompt_builder.py     # montagem do prompt de sistema
│   ├── system_prompt.py      # camadas e dicas por plataforma
│   ├── context_engine.py     # interface de gestão de contexto
│   ├── context_compressor.py # compressor padrão
│   ├── prompt_caching.py     # marcadores de cache Anthropic
│   └── auxiliary_client.py   # cliente para tarefas auxiliares (visão, resumo)
├── hermes_cli/               # subcomandos, autenticação, setup, runtime_provider.py
├── tools/                    # 70+ ferramentas; registry.py; approval.py
├── gateway/                  # run.py, run_turn.py, platforms/
├── plugins/                  # platforms/, memory/, context_engine/, model-providers/
├── acp_adapter/              # servidor do protocolo para editores
├── cron/                     # agendador
├── skills/                   # skills embutidas por categoria
├── website/docs/             # a documentação
└── tests/                    # cerca de 25 mil testes

O código está em ~/.hermes/hermes-agent na sua máquina. Para contribuir, a página "Contributing" descreve o fluxo com source ./activate e scripts/run_tests.sh.

2. Três entradas, um núcleo

CLI (cli.py), gateway (gateway/run.py) e ACP (acp_adapter/) convergem em run_agent.py, que expõe a classe AIAgent. A mesma classe serve todas as superfícies. Esse é o princípio "núcleo agnóstico de plataforma".

Fluxo na CLI: entrada do usuário, HermesCLI.process_input(), AIAgent.run_conversation(), montagem do prompt, resolução do provedor, chamada à API, laço de ferramentas, resposta, exibição, gravação da sessão.

Fluxo no cron: tick do agendador, carrega jobs vencidos, cria um AIAgent novo, injeta skills, executa, entrega, atualiza estado.

3. O laço, turno a turno

run_conversation()
  1. gera task_id se não veio
  2. anexa a mensagem do usuário ao histórico
  3. constrói ou reusa o prompt de sistema em cache (prompt_builder.py)
  4. verifica se precisa comprimir antes (> 50% do contexto)
  5. monta as mensagens no formato da API
       chat_completions: formato OpenAI como está
       codex_responses: converte para itens do Responses
       anthropic_messages: converte via anthropic_adapter.py
  6. injeta camadas efêmeras (avisos de orçamento, pressão de contexto)
  7. aplica marcadores de cache se for Anthropic
  8. chamada interrompível à API
  9. lê a resposta:
       tool_calls -> executa, anexa resultados, volta ao passo 5
       texto -> grava sessão, descarrega memória se preciso, devolve

Duas entradas públicas:

response = agent.chat("Corrija o bug em main.py")          # devolve string
result = agent.run_conversation(user_message="...", task_id="t1")   # devolve dict com messages e final_response

Formato interno de mensagens

Tudo usa o formato OpenAI por dentro, independente do provedor:

{"role": "system", "content": "..."}
{"role": "user", "content": "..."}
{"role": "assistant", "content": "...", "tool_calls": [...]}
{"role": "tool", "tool_call_id": "...", "content": "..."}

Regras de alternância que o laço impõe, porque os provedores rejeitam histórico malformado: nunca dois assistant seguidos, nunca dois user seguidos, só tool pode repetir (resultados paralelos).

Chamadas interrompíveis

A requisição HTTP roda em uma thread enquanto a thread principal espera por três coisas: resposta pronta, evento de interrupção, timeout. Se você manda mensagem nova ou /stop, a thread da API é abandonada e nenhuma resposta parcial entra no histórico.

Execução de ferramentas

Uma chamada roda na thread principal. Várias rodam em paralelo em um ThreadPoolExecutor, exceto ferramentas interativas como clarify, que forçam sequência. Os resultados voltam na ordem original das chamadas.

Para cada chamada: resolve o handler em tools/registry.py, dispara o hook pre_tool_call, verifica se é comando perigoso (tools/approval.py) e espera aprovação se for, executa, dispara post_tool_call, anexa o resultado.

Quatro ferramentas são interceptadas em agent/tool_executor.py antes de chegar ao registro, porque mexem no estado do agente: todo, memory, session_search, delegate_task.

Orçamento e fallback

Orçamento padrão de 500 iterações por agente (agent.max_turns); subagentes têm o próprio, limitado por delegation.max_iterations (50). Ao chegar a 100%, o agente para e devolve um resumo.

Quando o modelo principal falha com 429, 5xx, 401 ou 403, o laço percorre fallback_providers em ordem; em 401/403 tenta renovar a credencial antes. Tarefas auxiliares (visão, compressão, extração web) têm cadeias de fallback próprias em auxiliary.*.

4. Modos de API e resolução de provedor

Ordem de resolução: argumento explícito api_mode, detecção por provedor, heurística pela URL base, padrão chat_completions.

hermes_cli/runtime_provider.py mapeia (provedor, modelo) para (api_mode, api_key, base_url), cobrindo mais de 18 provedores, fluxos OAuth e pools de credenciais.

5. Montagem do prompt

O prompt de sistema em cache tem três camadas, nesta ordem (agent/system_prompt.py):

1. estável: identidade (SOUL.md ou padrão), orientação sobre ferramentas e modelo, briefing de operação;
2. contexto: system_message do chamador, arquivos de projeto (.hermes.md, AGENTS.md, CLAUDE.md, .cursorrules), snapshot do workspace git, instruções do operador, dicas da plataforma;
3. volátil: índice de skills, foto da MEMORY.md, foto da USER.md, bloco de provedor externo de memória, linha com data, sessão, modelo e provedor, e por fim o bloco de ambiente (host, home, diretório atual).

A ordem é pensada para o cache de prefixo: tudo que muda pouco vem primeiro, tudo que muda por sessão vem por último. Sessões do mesmo projeto em worktrees diferentes compartilham um prefixo longo. O prompt não muda no meio da sessão; só /model e eventos explícitos o refazem.

Um prompt montado parece com isto, em versão simplificada da documentação:

# identidade (SOUL.md)
# orientação de ferramentas (memória é exceção estreita; procedimentos vão em skills; use session_search)
# reforço de uso de ferramentas (só para modelos GPT/Codex)
# bloco do Honcho, se ativo
# system_message opcional
# foto de MEMORY
# foto de USER
# índice de skills (<available_skills>)
# arquivos de contexto do projeto
# data e sessão
# dica da plataforma ("você está em um terminal, evite markdown")

Dicas por plataforma podem ser estendidas ou substituídas no config.yaml com platform_hints.<plataforma>.append|replace, sem quebrar o cache.

Para subagentes (skip_context_files), o SOUL.md não é carregado e a identidade padrão é usada.

6. Compressão em dois estágios

mensagem chega -> higiene de sessão do gateway (85% do contexto, estimativa grosseira, rede de segurança)
              -> ContextCompressor do agente (50%, tokens reais da API, sistema principal)

A higiene do gateway (gateway/run_turn.py) existe para pegar sessões que cresceram entre turnos, como uma noite inteira de Telegram. Só dispara com quatro ou mais mensagens.

O compressor do agente (agent/context_compressor.py) roda dentro do laço com contagem real de tokens. Ao comprimir: descarrega memória para o disco primeiro, resume os turnos do meio, preserva as últimas N mensagens intactas (compression.protect_last_n, 20 por padrão), mantém pares chamada/resultado juntos, gera um novo id de sessão filho (linhagem).

A contagem usa uma "âncora de uso": os tokens de entrada e saída reportados pelo provedor na última resposta, mais uma estimativa só do que foi anexado desde então. Isso evita comprimir por estimativa errada. Há também micro-compactação e poda de resultados de ferramenta grandes.

O motor é plugável (context.engine): o padrão é compressor; plugins podem oferecer alternativas como gestão sem perda.

7. Banco de sessões

hermes_state.py mantém um SQLite com FTS5: sessões, mensagens, turnos e índices de busca. Rastreia linhagem (pai e filho entre compressões), isola por plataforma, escreve de forma atômica com tratamento de contenção. O modo de journal padrão é WAL; em montagens de rede ou virtiofs use delete (database.journal_mode).

8. Hermes como biblioteca

from run_agent import AIAgent

agent = AIAgent(model="anthropic/claude-sonnet-4.6", quiet_mode=True)
print(agent.chat("Qual a capital da França?"))

Sempre quiet_mode=True ao embutir, senão a CLI imprime spinners. Rode a partir do checkout preparado (cd ~/.hermes/hermes-agent && source ./activate); não há wheel publicado.

Controles úteis:

AIAgent(model=..., enabled_toolsets=["web"], quiet_mode=True)       # só web
AIAgent(model=..., disabled_toolsets=["terminal"], quiet_mode=True)  # tudo menos terminal
AIAgent(model=..., ephemeral_system_prompt="Você é um tutor de SQL.", quiet_mode=True)
AIAgent(model=..., save_trajectories=True, quiet_mode=True)          # grava JSONL em formato ShareGPT

Conversa de vários turnos: passe conversation_history=result["messages"] da chamada anterior. O agente copia a lista, não a altera.

Lote: python batch_runner.py --input prompts.jsonl --output results.jsonl, um task_id e ambiente isolado por prompt.

9. Como uma ferramenta embutida é registrada

Só para contribuição ao núcleo; para uso próprio, plugin (módulo 12). Dois arquivos: tools/minha_tool.py com handler, esquema, função de verificação e registry.register(...), e toolsets.py para colocar o nome em um toolset. Qualquer arquivo em tools/ com registry.register() no nível superior é descoberto automaticamente.

from tools.registry import registry

def check_weather_requirements() -> bool:
    return bool(os.getenv("WEATHER_API_KEY"))

def weather_tool(location: str, units: str = "metric") -> str:
    ...
    return json.dumps({"location": location, "temp": 22, "units": units})

WEATHER_SCHEMA = {"name": "weather", "description": "...", "parameters": {...}}

registry.register(
    name="weather", toolset="weather", schema=WEATHER_SCHEMA,
    handler=lambda args, **kw: weather_tool(args.get("location", ""), args.get("units", "metric")),
    check_fn=check_weather_requirements, requires_env=["WEATHER_API_KEY"],
)

Se check_fn devolver False, a ferramenta some silenciosamente do esquema. Handlers assíncronos usam is_async=True.

10. Callbacks

O AIAgent aceita callbacks que as superfícies usam para progresso em tempo real: tool_progress_callback, thinking_callback, reasoning_callback, clarify_callback, step_callback, stream_delta_callback, tool_gen_callback, status_callback. É por eles que a CLI mostra o spinner e o gateway manda "digitando".

Leia mais

• Arquitetura: https://hermes-agent.nousresearch.com/docs/developer-guide/architecture
• Laço do agente: https://hermes-agent.nousresearch.com/docs/developer-guide/agent-loop
• Montagem do prompt: https://hermes-agent.nousresearch.com/docs/developer-guide/prompt-assembly
• Compressão e cache: https://hermes-agent.nousresearch.com/docs/developer-guide/context-compression-and-caching
• Internals do gateway: https://hermes-agent.nousresearch.com/docs/developer-guide/gateway-internals
• Banco de sessões: https://hermes-agent.nousresearch.com/docs/developer-guide/session-storage
• Biblioteca Python: https://hermes-agent.nousresearch.com/docs/guides/python-library
• Adicionando ferramentas: https://hermes-agent.nousresearch.com/docs/developer-guide/adding-tools
• Contribuindo: https://hermes-agent.nousresearch.com/docs/developer-guide/contributing
• Leitura: "Refactoring Hermes with 1,393 agents", Teknium, setembro de 2026: https://nousresearch.com/refactoring-hermes-with-1393-agents
• Vídeo: palestra de Sam Herring (Nous) na Arize Observe 2026, sobre por que o Hermes foi reescrito em Python e suas decisões de projeto. Link em recursos/videos.md.

Objetivos

• Rodar o Hermes sem nenhuma API paga, com o Ollama já instalado na sua máquina.
• Escolher um modelo com chamada de ferramentas e contexto suficiente.
• Ajustar contexto, keep-alive, timeouts e tamanho do prompt.
• Configurar um fallback para a nuvem só quando o modelo local falhar.
• Diagnosticar os erros típicos.

1. Por que local

Custo zero por token, privacidade (nada sai da máquina) e independência de assinatura. A documentação estima que uma sessão pesada de código em API comercial custa entre 60 centavos e 80 centavos de dólar, e que diariamente isso vira 18 a 24 dólares por mês. Local custa a eletricidade.

O preço é qualidade e velocidade. Modelos locais pequenos chamam ferramentas mal, e em CPU a primeira resposta pode demorar minutos enquanto o modelo processa o prompt fixo (a fase de prefill). O módulo mostra como atenuar.

2. Hardware

Verifique sua máquina com labs/verificar-ambiente.sh, que mostra RAM, GPU e versão do Ollama.

3. Instalar e testar o Ollama

Já está instalado aqui (versão 0.31.2). Se precisar em outra máquina:

curl -fsSL https://ollama.com/install.sh | sh
ollama --version
curl http://localhost:11434/api/tags

Se o curl falhar com "connection refused", inicie: sudo systemctl start ollama ou ollama serve.

4. Escolher o modelo

O critério decisivo é suporte a chamada de ferramentas. Um modelo que não chama ferramentas só conversa; não edita arquivo nem roda comando. A tabela do guia oficial (outubro de 2026):

A FAQ oficial usa qwen3.5:27b como exemplo de modelo local. A biblioteca do Ollama muda toda semana; procure modelos marcados com "tools" e com contexto de 64 mil ou mais. Modelos abaixo de uns 30B tendem a dizer "salvei" sem chamar a ferramenta, como o módulo 8 alertou.

ollama pull gemma4:31b
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "gemma4:31b", "messages": [{"role": "user", "content": "Diga olá"}], "max_tokens": 50}'

Se o JSON voltar com a resposta, o endpoint compatível com OpenAI está funcionando.

5. O contexto: o erro mais comum

O Ollama usa 2.048 tokens de contexto por padrão. O Hermes exige 64.000. Sem ajuste, o Hermes recusa o modelo ou o agente se perde. Crie uma variante com contexto maior:

cat > ~/.hermes/cache/scratch/Modelfile <<'MF'
FROM gemma4:31b
PARAMETER num_ctx 64000
MF
ollama create gemma4-64k -f ~/.hermes/cache/scratch/Modelfile

Use gemma4-64k como nome do modelo no Hermes. Atenção à dica da FAQ: o /api/show do Ollama informa o contexto máximo do modelo, não o num_ctx que você configurou; informe ao Hermes o valor efetivo.

6. Configurar o Hermes

Pelo assistente:

hermes model
# Custom endpoint
# URL base: http://localhost:11434/v1
# Chave: ollama (ou vazio)
# Modelo: gemma4-64k
# Contexto: 64000

Ou direto no config.yaml:

model:
  default: "gemma4-64k"
  provider: "custom"
  base_url: "http://localhost:11434/v1"

Se você usar --provider ollama sem endpoint configurado, o Hermes recusa em vez de cair em uma chave de nuvem que esteja no ambiente. Nesse caso:

providers:
  ollama:
    base_url: "http://localhost:11434/v1"

Depois, hermes e teste com um pedido que use ferramenta: "liste os arquivos Python desta pasta e conte as linhas de cada um".

7. Velocidade

Manter o modelo carregado. O Ollama descarrega após 5 minutos ocioso, e recarregar antes de cada resposta custa tempo:

curl http://localhost:11434/api/generate -d '{"model": "gemma4-64k", "keep_alive": "24h"}'

Ou globalmente em /etc/systemd/system/ollama.service.d/override.conf:

[Service]
Environment="OLLAMA_KEEP_ALIVE=24h"

GPU. ollama ps mostra quantas camadas foram para a GPU. Uma placa de 12 GB com um modelo de 31B faz offload parcial e ainda acelera bastante.

Timeouts. O Hermes detecta endpoints locais e sobe o timeout de leitura de stream de 120 para 1.800 segundos. Se ainda assim estourar, no .env:

HERMES_API_TIMEOUT=1800
HERMES_STREAM_READ_TIMEOUT=1800

Prompt fixo. Em CPU, o prefill do prompt de sistema mais os esquemas de ferramentas domina a primeira resposta. Meça com hermes prompt-size, desligue toolsets com hermes tools e desinstale skills que não usa.

Compressão. Conversas longas ficam lentas; use /compress com frequência ou baixe o limiar de compressão.

8. Fallback para a nuvem

Só quando o local falha:

model:
  default: "gemma4-64k"
  provider: "custom"
  base_url: "http://localhost:11434/v1"

fallback_providers:
  - provider: openrouter
    model: anthropic/claude-sonnet-4

A documentação descreve o efeito como "90% do uso gratuito, só as tarefas difíceis pagam". Lembre que cada troca de provedor invalida o cache de prefixo.

9. Bot no Telegram com modelo local

Depois que a CLI funciona, o gateway é o mesmo do módulo 10. O modelo continua local; só a mensagem passa pelo Telegram. Mantenha o modelo carregado com keep-alive de 24 horas, senão cada mensagem espera o recarregamento.

10. Erros típicos

O Hermes tem reparo automático de chamadas de ferramenta malformadas e, se o modelo local falhar três vezes, cai para o fallback.

11. Alternativas ao Ollama

LM Studio (app gráfico com API compatível, variável LM_API_KEY), llama.cpp server, vLLM, SGLang e LocalAI funcionam pelo mesmo endpoint personalizado. No Desktop há "Settings > Providers > Local Models", que instala e gerencia um servidor llama.cpp com ajuste automático de memória e contexto. O guia "Local LLM on Mac" cobre Apple Silicon.

Leia mais

• Guia Ollama: https://hermes-agent.nousresearch.com/docs/guides/local-ollama-setup
• Modelos locais: https://hermes-agent.nousresearch.com/docs/user-guide/local-models
• LLM local no Mac: https://hermes-agent.nousresearch.com/docs/guides/local-llm-on-mac
• Provedores: https://hermes-agent.nousresearch.com/docs/integrations/providers
• Nemotron grátis via NVIDIA NIM: https://hermes-agent.nousresearch.com/docs/guides/run-nemotron-3-ultra-free
• Vídeos: Café com Dados & Gatos, "Como configurar Ollama no Hermes Agent rápido" (português), Masterclass 5 (Providers & Models) e Jack Roberts, "Hermes Agent + Ollama". Links em recursos/videos.md.
• Guia em português: Urutau Dev, "Hermes Agent com Ollama". Link em recursos/leituras.md.

Objetivos

• Ter uma rotina de operação: atualizar, diagnosticar, fazer backup, limpar.
• Controlar custo: cache de prefixo, compressão, modelo certo por tarefa, modelos auxiliares.
• Resolver os problemas mais frequentes com o método da documentação.
• Endurecer uma instalação exposta na internet.

1. Rotina de operação

Diária, em servidores com gateway:

hermes gateway status
tail -n 50 ~/.hermes/logs/gateway.log
hermes cron status

Semanal:

hermes update --check
hermes update
hermes doctor
hermes config check
hermes curator status
hermes sessions optimize      # com o gateway parado

Mensal:

hermes backup
hermes sessions prune
hermes approvals suggest      # revise e aplique o que fizer sentido

Antes de todo hermes update o Hermes tira um snapshot dos arquivos de estado em state-snapshots/. Com updates.pre_update_backup: full ele zipa o home inteiro em backups/. Em instalação git, mudanças locais são guardadas em stash antes do pull.

Os logs em ~/.hermes/logs/ têm segredos redigidos automaticamente.

2. O método de recuperação

Quando algo parece errado, nesta ordem:

1. hermes doctor
2. hermes model
3. hermes setup
4. hermes sessions list
5. hermes --continue
6. hermes gateway status

E a regra: se uma conversa simples na CLI não funciona, não mexa em gateway, cron, skills, voz ou roteamento até funcionar.

3. Tabela de sintomas

4. Custo

Onde o dinheiro vai:

• Cada turno reenvia o contexto inteiro. Conversas longas custam mais por mensagem.
• O prompt fixo (identidade, orientação, índice de skills, memória, esquemas de ferramentas) é pago em todo turno. hermes prompt-size mostra o tamanho.
• Tarefas auxiliares (compressão, visão, resumo de busca, curador, avaliação de risco no modo smart) usam modelo também.

Como reduzir:

Preserve o cache de prefixo. O provedor cobra menos pelo prefixo idêntico ao da chamada anterior. Trocar de modelo com /model, cair em fallback ou rotacionar credencial invalida o cache e o próximo turno paga tudo de novo. Em sessões longas, abrir uma sessão nova no outro modelo sai mais barato que alternar.

Comprima antes do limite. /compress quando a conversa cresce; /usage para ver onde está. A compressão automática dispara aos 50%.

Escolha o modelo por tarefa. Modelo de fronteira para arquitetura e raciocínio; modelo rápido e barato para formatação e boilerplate.

Modelos auxiliares. Aponte compressão, visão, busca de sessão, curador e outros para um modelo barato:

hermes model        # Auxiliary models > escolha a tarefa > provedor > modelo

Ou em config.yaml:

auxiliary:
  compression:
    provider: openrouter
    model: google/gemini-3-flash-preview
  curator:
    provider: openrouter
    model: google/gemini-3-flash-preview

Delegue para economizar o contexto principal. Subagentes devolvem só o resumo.

Use execute_code para lotes. Um script que renomeia cem arquivos custa menos que cem chamadas de terminal.

Desligue o que não usa. Toolsets e skills ocupam tokens em todo turno.

Fixe o modelo do cron. cron.model separado do modelo de chat evita que uma troca no chat encareça a frota de jobs.

/insights mostra padrões de uso dos últimos 30 dias.

5. Endurecendo uma instalação exposta

Para um VPS com bot de Telegram e terminal:

• Listas de permitidos por plataforma. Nunca GATEWAY_ALLOW_ALL_USERS=true.
• Backend de terminal em Docker ou SSH para outro host. Dentro de contêiner a verificação de comandos perigosos é pulada, então a imagem precisa estar fechada.
• approvals.deny com os padrões que você nunca quer ver, mesmo em YOLO.
• approvals.cron_mode: deny (padrão) mantido.
• memory.write_approval: true se várias pessoas falam com o bot.
• Segredos em gerenciador externo: o Hermes integra com 1Password, Bitwarden e comandos arbitrários via bloco secrets:, e tem um cofre de credenciais.
• Dashboard só em loopback; em bind público, autenticação é obrigatória.
• Proxy de saída (hermes egress) para o Docker não ver chaves reais.
• Um perfil por agente. Nunca dois processos no mesmo home.
• Guia oficial "Secure Hermes on a work machine" para máquinas corporativas, e "Managed Scope" para administradores fixarem valores que o usuário não pode alterar.

6. Migrar para outra máquina

hermes backup exporta tudo; hermes profile export <nome> exporta um perfil. Restaure na máquina nova depois de instalar o Hermes. A FAQ compara os dois e explica mover um único perfil. Para quem vem do OpenClaw, hermes claw migrate importa persona, memória, skills, allowlists e configurações de plataforma, com --dry-run para pré-visualizar.

7. Onde pedir ajuda

• FAQ e troubleshooting: https://hermes-agent.nousresearch.com/docs/reference/faq
• Guia de qualidade do agente ("Troubleshooting agent quality"): quando ele responde mal, não quando quebra.
• Discord da Nous Research, Issues e Discussions no GitHub (links no README do repositório).
• Comunidade brasileira: o repositório Hermes Brasil reúne guias (produção em VPS, cron, backup, perfis e Kanban, MCP) e skills em português, com grupos no Telegram e no WhatsApp. Link em recursos/leituras.md.

Leia mais

• FAQ: https://hermes-agent.nousresearch.com/docs/reference/faq
• Dicas: https://hermes-agent.nousresearch.com/docs/guides/tips
• Atualizar e desinstalar: https://hermes-agent.nousresearch.com/docs/getting-started/updating
• Segurança em máquina de trabalho: https://hermes-agent.nousresearch.com/docs/guides/secure-hermes-on-a-work-machine
• Qualidade do agente: https://hermes-agent.nousresearch.com/docs/guides/troubleshooting-agent-quality
• Cron troubleshooting: https://hermes-agent.nousresearch.com/docs/guides/cron-troubleshooting

Projeto A. Assistente pessoal sempre ligado

Módulos: 5, 6, 8, 9, 10, 15.

Monte um bot no Telegram, rodando como serviço em um perfil próprio, com personalidade em SOUL.md, memória ativa e pelo menos duas skills instaladas do Hub.

Critérios:

• hermes -p assistente gateway status mostra o serviço ativo.
• Só o seu ID (e um segundo aprovado por pareamento) consegue falar com o bot.
• O bot lembra seu nome e uma preferência em uma sessão nova, e isso está em USER.md.
• Um /new por dia é documentado como prática no seu AGENTS.md pessoal ou em um lembrete por cron.
• Um comando perigoso pedido pelo chat gera o prompt de aprovação e no o bloqueia.

Projeto B. Briefing diário com entrega e voz

Módulos: 10, 11, 9.

O bot do tutorial oficial, estendido: três temas, uma skill anexada (youtube-content ou arxiv), entrega no Telegram às 7h30 em dias úteis, mais uma versão em áudio com [[audio_as_voice]] se você tiver TTS configurado.

Critérios:

• hermes cron list mostra o job com nome, agenda e skill.
• hermes cron run <nome> entrega no chat home em menos de 5 minutos.
• O prompt é autocontido (o professor vai ler).
• O job tem modelo fixado (--pin) e esforço de raciocínio definido.
• Um hermes cron edit muda a agenda sem recriar.

Projeto C. Agente de projeto para um repositório seu

Módulos: 6, 7, 9, 11, 12.

Escolha um repositório real (por exemplo um dos projetos em ~/Projetos). Escreva um AGENTS.md com arquitetura, comandos de teste e proibições. Crie uma skill própria com o procedimento de release ou deploy desse projeto. Conecte o servidor MCP do GitHub. Use /goal com um gate de testes para resolver uma issue de verdade.

Critérios:

• Abrir o Hermes na raiz e perguntar "quais são as regras aqui?" devolve o conteúdo do AGENTS.md.
• /nome-da-skill carrega o procedimento e o agente o segue até o fim.
• /tools lista ferramentas mcp-github.
• /goal gate add "<comando de teste>" seguido de um objetivo termina com "Goal achieved".
• Uma correção foi commitada em branch separada, com mensagem gerada pelo agente e revisada por você.

Projeto D. Hermes 100% local com fallback

Módulos: 14, 15, 6.

Perfil local com Ollama, modelo de 64k de contexto que chama ferramentas, keep-alive de 24 horas, prompt enxuto (toolsets reduzidos), e fallback para um provedor de nuvem.

Critérios:

• hermes -p local responde a uma tarefa com ferramenta sem acessar a internet (verifique com o Ollama servindo e nenhuma chave de nuvem disponível, exceto a do fallback).
• hermes prompt-size abaixo do valor do perfil padrão, com registro dos dois números.
• Tempo da primeira resposta antes e depois do keep-alive registrado.
• Ao parar o Ollama no meio de uma conversa, o fallback assume e o log mostra a troca.
• Um bot de Telegram nesse perfil responde usando o modelo local.

Projeto E. Plugin e hook para a sua empresa

Módulos: 12, 13.

Escreva um plugin que expõe uma ferramenta útil para o seu contexto (por exemplo consultar uma API interna, ou um webhook do Bitrix24) e um hook de gateway que registra todo agent:end em um arquivo JSONL com plataforma, usuário e tamanho da resposta. Opcional: um comando de barra que chama a ferramenta.

Critérios:

• hermes plugins lista o plugin e ele está em plugins.enabled.
• O handler devolve JSON e trata erro como {"error": ...}.
• A ferramenta aparece em /tools e o agente a usa quando faz sentido.
• O hook grava uma linha por turno no gateway.
• Segredos vêm de .env, nunca estão no código.

Projeto F. Equipe de agentes no Kanban

Módulos: 11, 6.

Dois perfis com papéis (por exemplo pesquisador e redator). Crie três cartões no Kanban com dependências: pesquisa, redação, revisão. Deixe os trabalhadores processarem e acompanhe pelo dashboard.

Critérios:

• hermes kanban mostra os três cartões com estado final concluído.
• O cartão de redação só começou depois do de pesquisa.
• Cada trabalhador rodou com seu perfil (sessões com origem kanban em cada state.db).
• Um cartão foi criado com --goal e iterou mais de um turno.

Entrega

Para cada projeto, crie uma pasta entregas/<letra>/ com:

• RELATO.md: o que fez, o que deu errado, como resolveu, tempo gasto;
• os arquivos de configuração relevantes com segredos removidos;
• a saída dos comandos de verificação.

Peça ao professor: /professor-hermes avalie o projeto A em entregas/A.