Qual Arquivo Faz o Quê

"Falei uma coisa para o agente e ele esqueceu." "Qual arquivo é o cérebro dele?" "Editei o SOUL.md — por que ele não sabe meu nome?" Todas essas perguntas caem no mesmo ponto: o Hermes Agent é moldado por vários arquivos markdown, e cada um tem uma função diferente. Esta página mapeia todos num lugar só. Para se aprofundar em qualquer um, siga os links para Memória Persistente, Personalidade e SOUL.md e Arquivos de Contexto.

A tabela principal

Arquivo	O que guarda	Quem escreve	Quando o agente vê	Onde fica
SOUL.md	A identidade principal do agente — personalidade, tom, estilo de comunicação, o que evitar no jeito de falar	Você. O Hermes cria um arquivo inicial sozinho se não existir; arquivos existentes nunca são sobrescritos	Na primeira posição do prompt de sistema, no início da sessão	~/.hermes/SOUL.md (ou $HERMES_HOME/SOUL.md, com um diretório próprio) — nunca no diretório de trabalho
USER.md	Perfil do usuário — seu nome, seu papel, suas preferências, seu jeito de se comunicar, o que você espera	O agente, pela ferramenta memory (dá para exigir aprovação com write_approval, ou editar entradas com hermes journey edit)	Entra no prompt de sistema como retrato congelado, no início da sessão	~/.hermes/memories/
MEMORY.md	Anotações do agente — fatos do ambiente, convenções do projeto, manias das ferramentas, o que aprendeu	O agente, pela ferramenta memory (mesmas opções de aprovação e edição do USER.md)	Entra no prompt de sistema como retrato congelado, no início da sessão	~/.hermes/memories/
AGENTS.md	Instruções do projeto, convenções, arquitetura — comandos, portas, caminhos, fluxos daquele repositório	Você, ou quem escreveu o projeto	Carregado no prompt de sistema na inicialização, a partir do seu diretório de trabalho; cópias aninhadas vão sendo descobertas conforme o agente navega pelos subdiretórios	Diretório de trabalho do projeto e subdiretórios
.hermes.md / HERMES.md	Instruções do projeto, como o AGENTS.md, mas específicas do Hermes e com prioridade maior	Você	Carregado no prompt de sistema na inicialização (a primeira correspondência vence o AGENTS.md)	Seu projeto — a busca sobe até a raiz do git

Um arquivo de contexto de projeto por sessão

Só um tipo de contexto de projeto é carregado por sessão, e a primeira correspondência vence: .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules. O SOUL.md é sempre carregado à parte, como identidade do agente — ele não entra nessa disputa. Veja Arquivos de Contexto para a lista completa, incluindo compatibilidade com CLAUDE.md e .cursorrules.

Um resumo útil:

• SOUL.md é quem o agente é — se deve acompanhar você em todo lugar, é aqui.
• USER.md é quem você é — o agente mantém isso por você.
• MEMORY.md é o que o agente aprendeu — ele também mantém sozinho.
• AGENTS.md (ou .hermes.md) é o que o projeto precisa — se pertence a um projeto, é aqui.

"Por que ele esqueceu o que eu acabei de falar?"

A memória (MEMORY.md e USER.md) entra no prompt de sistema como retrato congelado, capturado uma vez no início da sessão. Quando o agente salva algo no meio do caminho, a mudança vai para o disco na hora, mas só aparece no prompt de sistema na sessão seguinte. Isso é de propósito: preserva o cache de prefixo do modelo, o que rende desempenho. E as respostas da ferramenta sempre mostram o estado real, então nada se perde — comece uma sessão nova e a memória atualizada está lá. Detalhes em como a memória aparece no prompt de sistema.

Confusões comuns

"Coloquei fatos sobre mim no SOUL.md, mas o USER.md continuou vazio"

SOUL.md e USER.md são sistemas separados, que nunca se alimentam. O SOUL.md é um arquivo de personalidade que você edita direto — ele molda tom e identidade, e o conteúdo entra literal na primeira posição do prompt. O USER.md faz parte da memória persistente e é escrito pelo agente, pela ferramenta memory. Se você quer fatos sobre si mesmo no USER.md, diga ao agente ("lembre que eu prefiro respostas curtas") e ele salva — editar o SOUL.md não popula a memória, e entradas de memória não mudam a persona. Use o SOUL.md para voz e personalidade duradouras; deixe preferências e fatos de perfil para a memória. Veja o que deve ir no SOUL.md e os dois alvos da memória.

"Falei meu nome no meio da sessão e ele agiu como se nunca tivesse ouvido"

Se o agente salvou seu nome na memória, a gravação funcionou — confira nas respostas da ferramenta memory ou com hermes journey list. O que você está vendo é a regra do retrato congelado, acima: o prompt de sistema não se atualiza no meio da sessão, então o bloco de memória injetado ainda mostra o estado do começo. O agente continua conseguindo usar o que você disse dentro da conversa atual (está no contexto), e a entrada salva vai estar no prompt de sistema da próxima sessão em diante. O mesmo vale para edições que você faz no SOUL.md ou no AGENTS.md com uma sessão aberta: o contexto é montado no início, então reinicie a sessão para pegar as mudanças.

Guia rápido de decisão

• Quer mudar como o agente fala? Edite o ~/.hermes/SOUL.md — Personalidade e SOUL.md.
• Quer que o agente lembre de um fato? Só falar — ele salva sozinho. Memória Persistente.
• Quer definir regras do projeto? Coloque um AGENTS.md (ou .hermes.md) no projeto — Arquivos de Contexto.
• Precisa de uma mudança temporária de personalidade? Use /personality — é uma camada de sessão, sem editar arquivo nenhum.

Documentação relacionada

• Memória Persistente — MEMORY.md, USER.md, a ferramenta memory, limites de capacidade, write_approval
• Personalidade e SOUL.md — o que escrever no SOUL.md, presets de /personality, a pilha do prompt
• Arquivos de Contexto — AGENTS.md, .hermes.md, descoberta progressiva, varredura de segurança