🏛️ Os 5 Pilares na Prática

No início de cada sessão, o conteúdo de USER.md e MEMORY.md é lido e injetado no system prompt como um bloco fixo. Modificações durante a sessão usam a tool memory.

Entender que é frozen explica por que o agente "esquece" alterações feitas no meio da sessão até a próxima. Você decide o que merece persistir.

Os arquivos ficam em ~/.hermes/memories/. Snapshot frozen = lido uma vez por sessão. A tool memory é o mecanismo oficial pra alterar entre sessões.

Arquivo com o seu perfil: nome, papel, preferências, estilo de comunicação, idiomas, contextos relevantes. Limite rígido de 1.375 caracteres (~500 tokens).

É o que faz o agente parar de te tratar como estranho a cada sessão. Sem USER.md útil, você repete contexto sempre.

Foco em fatos estáveis (não em status atual). Bom: "Falo PT-BR, prefiro respostas curtas, programo em Python." Ruim: "Estou trabalhando no projeto X agora."

Notas pessoais do agente sobre o ambiente: paths importantes, fatos aprendidos, decisões fechadas, atalhos. Limite rígido de 2.200 caracteres (~800 tokens).

É a memória "de trabalho" do agente. Sem ela, ele redescobre o ambiente toda vez (onde fica o repo X, qual o stack Y, como você prefere commits).

Limite apertado obriga a consolidar. Quando enche, o próprio agente reescreve entradas mais antigas pra abrir espaço. Foco em conhecimento durável, não em tarefas.

A ferramenta memory tem três operações: add (adicionar entrada), replace (substituir), remove (apagar). O agente usa sozinho quando você pede "salva isso".

Saber que existe te dá o vocabulário pra pedir certo: "salva na memória X", "remove a entrada Y do MEMORY.md", "atualiza o que sabe sobre meu setup".

Quando o arquivo enche, o agente consolida automaticamente — junta entradas redundantes pra liberar espaço. Você pode auditar manualmente abrindo os MD.

Cada sessão é gravada em SQLite (~/.hermes/state.db) com índice full-text (FTS5). A tool session_search permite achar conversas antigas por palavra-chave.

É a "memória longa". Quando algo não cabe em MEMORY.md mas você sabe que falou disso, peça pro agente buscar no histórico de sessões.

Memória ≠ histórico. MEMORY.md é o que está sempre carregado; SQLite é o arquivo morto pesquisável sob demanda. Backup do state.db = backup da história toda.

Memória NÃO é cofre de senhas. NÃO é to-do list. NÃO é status atual. Salvar tipo errado polui o snapshot e desperdiça os 1.375/2.200 chars de orçamento.

Memória mal usada vira ruído que prejudica o raciocínio. Secret salvo lá pode vazar em logs ou prompts de modelos remotos.

Secrets vão em ~/.hermes/.env. Tarefas temporárias ficam na conversa. Status atual é volátil. Memória = conhecimento durável que vai te servir em sessões futuras.

Skill é um arquivo SKILL.md com YAML front matter no topo e instruções abaixo. Diz ao agente "quando usar isto", "como executar passo-a-passo", "armadilhas", "como verificar".

Skill transforma "instrução repetida toda sessão" em "procedimento documentado uma vez". Cada tarefa que você fez 3 vezes vira candidata a skill.

Skill ≠ código. É linguagem natural estruturada. O modelo lê e segue. Padrão aberto: agentskills.io/specification.

Cabeçalho YAML com campos: name, description, version, platforms (opcional), e metadata.hermes com tags, category, fallback_for_toolsets, requires_toolsets, config.

É o que aparece no skills_list(). Description ruim = skill nunca chamada. Tags e category ajudam a filtrar e ativar condicionalmente.

platforms restringe a OS (macos, linux). fallback_for_toolsets ativa quando outro toolset falha. requires_toolsets ativa só quando tem o toolset disponível. config gera prompts no setup.

Quatro seções: When to Use (gatilhos), Procedure (passos), Pitfalls (armadilhas conhecidas), Verification (como saber que deu certo).

É o esqueleto que o modelo espera. Skill sem "When to Use" é chamada errada. Sem "Verification" é dada como sucesso quando falhou.

Procedure deve ser numerado e direto. Pitfalls vem da experiência: o que já quebrou antes e como contornou. Verification é teste curto de saída esperada.

Padrão de carregamento em 3 níveis: L0 skills_list() (~3k tokens, só nome+descrição+categoria), L1 skill_view(name) (corpo completo), L2 skill_view(name, path) (referência específica).

Permite ter centenas de skills sem estourar contexto. O agente só carrega corpo completo quando decide usar.

Description curta e poderosa importa MUITO — é o que entra no L0. Referências grandes ficam em references/ e são puxadas só no L2.

Skill mora em ~/.hermes/skills/category/skill-name/. Dentro: SKILL.md (obrigatório), references/, templates/, scripts/, assets/.

Permite skill rica sem inflar SKILL.md principal. Scripts ficam separados para execução, templates pra outputs, references pra docs longas.

Categoria do diretório é tipicamente igual ao metadata.hermes.category. Versionamento da skill toda via git fica trivial — é só Markdown e arquivos auxiliares.

Hub público em agentskills.io. Cinco fontes de instalação: official (bundled), skills-sh (hub), GitHub (user/repo/path), URL direta, well-known (auto-discovery via /.well-known/agent-skills).

Você não precisa criar tudo do zero. Vê demo no X → cola link da skill → o agente instala e usa.

Auto-discovery em /.well-known/agent-skills permite que sites publiquem skills oficiais — basta apontar o agente pro domínio.

SOUL.md é o primeiro bloco do system prompt — antes de memória, antes de skills. É a base da identidade que o modelo lê pra qualquer interação.

Posição importa. Coisa no slot #1 tem mais peso na decisão do modelo. Tom errado lá ecoa em tudo. Tom certo lá molda toda a conversa.

Sempre carregado (não condicional). É a única peça desse trio (SOUL/USER/MEMORY) que NÃO tem limite rígido documentado, mas mantenha conciso pra economizar tokens.

Arquivo único em ~/.hermes/SOUL.md. Escopo global (vale pra qualquer projeto). Markdown puro — não tem YAML front matter como SKILL.md.

Está no home do Hermes, não dentro de projeto. Por isso não muda quando você troca de pasta — a identidade do agente é constante.

Pra ter identidades diferentes (marketing alegre, financeiro sério), você usa perfis Hermes diferentes — cada perfil com seu próprio diretório ~/.hermes-marketing/, ~/.hermes-financeiro/.

Bom SOUL.md cobre: tom (formal, descontraído, direto), personalidade (quem é o agente), princípios (o que sempre/nunca faz), regras de comunicação (idioma, comprimento, emojis).

É a diferença entre "ChatGPT padrão" e "agente que parece COM você". Quanto mais específico, mais característico fica.

Evite contradições internas. "Seja sucinto" + "explique cada decisão em detalhe" briga. Soul deve ser coerente como personagem.

Em setups com múltiplos perfis, soul é o que dá personalidade distinta a cada um. Marketing pode ser leve e usar emojis. Financeiro deve ser sóbrio e direto.

Sem soul próprio, todos os perfis soam igual e perdem o sentido de existir separados. Cada um carrega sua voz.

Soul define voz; skills definem capacidades; memory carrega fatos. Os três se combinam pra dar caráter ao perfil.

"Atualize seu soul para ser X" → o próprio agente edita SOUL.md. Funciona surpreendentemente bem porque ele entende o efeito de cada linha.

Você não precisa virar designer de prompts. Descreve o ajuste em linguagem natural ("seja mais direto", "menos emojis", "use exemplos práticos") e o agente formaliza.

Sempre revise o diff antes de aceitar. Soul é arquivo crítico — uma reescrita ruim degrada o agente todo.

Diferença fundamental: SOUL.md = quem o agente é (identidade dele). USER.md = quem você é (perfil seu). Confundir os dois é erro comum.

Misturar gera coisas estranhas. Colocar "sou Nei, programador" em SOUL.md faz o agente achar que ELE é Nei. Colocar "seja sucinto" em USER.md desperdiça espaço.

Teste mental: "Se eu trocasse o usuário, isto continuaria valendo?" Se sim → SOUL. Se não → USER.

Cron = job agendado. A cada disparo o gateway scheduler abre uma sessão fresh de AIAgent — sem histórico de conversa anterior, mas com SOUL.md, USER.md e MEMORY.md carregados.

É o que faz o agente ser realmente útil 24/7. Você dorme, ele trabalha. Acorda com resumo no Telegram.

Sessão fresh = prompt deve ser auto-contido. "Continua o que estava fazendo" não funciona — não há contexto. Bom: "Audite PRs abertos no repo X e poste resumo no Telegram."

Comandos no chat criam crons sem CLI: /cron add 30m "...", /cron add "every 2h" "...", /cron add "every 1h" "..." --skill blogwatcher.

É o jeito mais rápido de criar cron — direto do Telegram. Não precisa SSH no servidor.

Aceita expressões naturais ("every 2h", "every 1d at 09:00") e durações ("30m", "1h", "2d"). Múltiplas skills com --skill A --skill B.

Mesma capacidade via terminal: hermes cron create "every 1d at 09:00" "Audit PRs" --workdir /path/projeto. Ideal pra scripts de setup e infra-as-code.

CLI permite versionar crons no repositório (script setup-crons.sh que recria tudo). Reproduzível.

Outras subcomandos úteis: hermes cron list, hermes cron remove <id>. Definição persiste em ~/.hermes/cron/jobs.json.

Define o diretório de trabalho da sessão fresh. O scheduler faz cd pra lá antes de rodar e detecta os arquivos de contexto do projeto: .hermes.md, AGENTS.md ou CLAUDE.md.

Cron pra um projeto específico precisa do contexto desse projeto. Sem --workdir, ele roda em ~ e não acha nada.

Ordem de prioridade do contexto de projeto: .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules. Apenas UM tipo é carregado por sessão.

Modo que pula o LLM completamente. O cron roda só um script .sh/.bash/.py. Saída vazia = silêncio. Saída não-zero = alerta entregue.

Watchdogs (memória, disco, heartbeat) não precisam de IA. Usar LLM aí é desperdício de token. NOAGENT mantém custo zero.

Padrão: stdout vazio = tick silencioso, stderr ou exit não-zero = alerta. Scripts .sh rodam sob bash, outros sob Python interpreter.

--deliver <plataforma> escolhe o destino: telegram, discord, all, origin. --skill <name> injeta uma skill no início da sessão fresh.

Sem --deliver, a saída vai pro canal padrão. Com --skill, você garante que o procedimento certo está disponível mesmo numa sessão fresh.

File lock ~/.hermes/cron/.tick.lock previne double-run quando o tick demora. Você pode passar múltiplas --skill pra combinar habilidades.

Memória (MEMORY.md/USER.md) = fatos. Skills (SKILL.md) = procedimentos. Histórico (SQLite FTS5) = conversa. As três funcionam juntas pra acumular contexto útil.

Saber qual camada usar para qual tipo de aprendizado evita inflar memória com coisas que deveriam virar skill, ou virar skill coisa que é só fato isolado.

Fato pontual → memória. Procedimento repetível → skill. Conversa específica → fica no histórico (busca via session_search).

Você pede tarefa → ele executa → você corrige se errado → o aprendizado é persistido em memória ou skill → próxima sessão usa isso.

É a regra do jogo. Sem o passo 4 (persistência), você vai corrigir os mesmos erros sempre. Tudo o que evolui o agente passa por esse ciclo.

Frases de gatilho: "salva isso na memória", "vira skill", "atualiza seu soul", "lembra disso pra próxima". Sem elas, o aprendizado some no fim da sessão.

Heurística simples: errou uma vez, é descuido. Errou duas vezes na mesma coisa, é padrão — atualize o pilar correspondente.

Sem critério você ou inflama memória pra qualquer detalhe ou ignora o que precisaria ser corrigido. O 2 é um bom limiar pragmático.

Erro de fato → memória. Erro de processo → skill. Erro de tom → soul. A camada certa depende do tipo de erro.

Toda vez que você se pega digitando "primeiro faz X, depois Y, cuidado com Z" pela 3ª vez, é a deixa: vire skill.

Identificar o gatilho cedo economiza horas. A skill paga investimento em poucas execuções.

Frase pronta: "Transforma esse procedimento numa skill chamada X, com when-to-use, procedure, pitfalls e verification." O agente formaliza.

Diagnóstico simples: "ele falou de um jeito que não gostei" → soul. "ele esqueceu fato sobre meu setup" → memória. "ele errou o passo a passo" → skill.

Roteamento claro evita gastar tempo editando a coisa errada. Soul mais grosso não conserta falta de fato; memória mais cheia não conserta tom.

A tabela mental: tipo do erro → camada correspondente. Aplicar errado degrada tudo (memória virando soul fica longa demais e desperdiça os 2.200 chars).

A cada poucas semanas, peça: "Mostre o conteúdo atual de SOUL.md, USER.md, MEMORY.md e a lista de skills. O que está obsoleto, contraditório ou redundante?"

Sem revisão, esses arquivos viram lixo acumulado. Entradas antigas brigam com novas. O agente perde clareza.

Auditoria mensal de 10 minutos vale mais que reescrever do zero. Comite os arquivos no GitHub — assim você tem histórico de evolução do agente.