MÓDULO 3.1

🧠 Memory: USER.md + MEMORY.md

Os dois arquivos que o agente injeta no system prompt como snapshot frozen no início de cada sessão. Limites rígidos, gerenciados via tool, complementados por SQLite + FTS5.

6
Tópicos
30
Minutos
Médio
Nível
Prática
Tipo
1

🧊 Memória persistente como snapshot frozen

No início de cada sessão, o Hermes lê o conteúdo de ~/.hermes/memories/USER.md e ~/.hermes/memories/MEMORY.md e injeta tudo no system prompt como um bloco fixo. Esse bloco não muda mais durante a sessão — é um snapshot frozen.

📐Os dois arquivos por dentro

  • USER.md — perfil seu, ~500 tokens, limite 1.375 chars
  • MEMORY.md — notas do agente, ~800 tokens, limite 2.200 chars
  • Local: ~/.hermes/memories/
  • Carregamento: uma vez por sessão (frozen)
  • Atualização entre sessões: via tool memory ou edição direta

⚠️Implicação prática

Se o agente atualizar memória durante a sessão atual, o snapshot já injetado não muda nessa sessão. Quem usa essa nova entrada é a próxima sessão. Por isso "salva isso na memória" só impacta as próximas conversas.

2

👤 USER.md — quem é VOCÊ

USER.md é o perfil do usuário: nome, papel, preferências, estilo de comunicação, idiomas, contextos relevantes. Tem limite rígido de 1.375 caracteres (~500 tokens). Excedeu, o agente para de aceitar novas entradas até abrir espaço.

✅ O que faz sentido aqui

  • •Nome, papel/profissão, fuso horário, idioma preferido
  • •Estilo: respostas curtas vs detalhadas, formal vs informal
  • •Preferências técnicas estáveis (linguagens, stack, sistemas operacionais usados)
  • •Regras pessoais não-negociáveis ("não me chame por apelido", "evite emojis em mensagens financeiras")

❌ O que NÃO entra em USER.md

  • •Status atual ("estou trabalhando no projeto X agora") — é volátil
  • •To-do list e tarefas em andamento — uso outro lugar (issues, planner)
  • •Senhas, tokens, API keys — vão em ~/.hermes/.env
  • •Identidade do agente — isso é SOUL.md
3

📓 MEMORY.md — notas pessoais do agente

MEMORY.md é a memória "de trabalho" do agente. Notas sobre ambiente, decisões fechadas, paths, atalhos, fatos aprendidos. Limite rígido de 2.200 caracteres (~800 tokens). Quando enche, o próprio agente consolida entradas redundantes.

🧱 Bons exemplos de entrada

  • •"Repo principal do usuário fica em ~/projetos/site/, deploy via Hostinger."
  • •"Usuário prefere commits no formato tipo: descrição curta, sem prefixos extras."
  • •"Banco Postgres do projeto X fica acessível via db.local.example porta 5432."
  • •"Cron de backup roda às 3h, não interferir nesse horário."

💡Limite apertado é feature

2.200 chars força você a guardar só o que realmente importa. Ferramenta perfeita pra evitar "memória bagunçada que não ajuda em nada". Se você sente falta de mais espaço, provavelmente está colocando coisa errada lá (status, tarefa, histórico).

4

🔧 Tool memory: add, replace, remove

O agente gerencia a própria memória via tool memory. Três operações disponíveis. Você não edita os arquivos manualmente o tempo todo — pede em linguagem natural e o modelo dispara a operação certa.

add

Adiciona nova entrada. Frase: "Salva na memória que prefiro Postgres pra projetos novos."

replace

Substitui entrada existente. Frase: "Atualiza a entrada sobre meu fuso, agora estou em Lisboa."

remove

Apaga entrada obsoleta. Frase: "Remove o que sabe sobre o projeto X, descontinuei."

🤖Auto-consolidação quando enche

Quando MEMORY.md ou USER.md atinge o limite, o agente faz pass de consolidação: junta entradas redundantes, reescreve mais conciso, descarta o que ficou obsoleto. Você pode forçar manualmente: "Faz uma limpeza no MEMORY.md, junta o que for redundante."

5

🔍 session_search: SQLite + FTS5

Toda conversa passa por SQLite com índice full-text (FTS5) em ~/.hermes/state.db. A tool session_search permite buscar conversas antigas por palavra-chave — é a "memória longa" complementar.

📚 Quando usar cada um

  • MEMORY.md: fato durável e relevante pra MUITAS sessões. Sempre carregado.
  • USER.md: seu perfil. Sempre carregado.
  • SQLite + FTS5: conversa específica que pode ou não voltar a ser útil. Pesquisado sob demanda.

💡Frase pronta

"Busca no histórico de sessões qualquer conversa onde falamos sobre <tópico> e me resume os pontos principais." O agente roda session_search e te traz o material consolidado sem inflar memória.

💾Backup importa

Backup do state.db = backup da história inteira do agente. Inclua esse arquivo na rotina de backup do VPS. Perdeu, perdeu o passado.

6

🚫 O que NUNCA salvar na memória

Memória mal usada não é só desperdício — vira ruído ativo que prejudica o raciocínio do agente em toda sessão. E pior: secret salvo lá pode vazar em logs ou em chamadas pra modelos remotos.

🚨 Lista do "não"

  • ✗Secrets, tokens, API keys, senhas — vão em ~/.hermes/.env, nunca em arquivos de memória
  • ✗Tarefa temporária — issue tracker, planner ou conversa atual
  • ✗Status atual ("estou em férias") — vai estar errado em duas semanas
  • ✗Histórico de conversa — já está no SQLite, não duplique
  • ✗Procedimentos longos — vire skill (Markdown completo cabe lá)
  • ✗Personalidade do agente — vai em SOUL.md

🎯Teste do "vai me servir em 6 meses?"

Antes de salvar, pergunte: "isso vai me ser útil em 6 meses, em qualquer sessão, independente da tarefa?" Se sim → memória. Se não → outro lugar.

🎯Resumo do módulo

✓
Memória é snapshot frozen no system prompt — lida uma vez por sessão a partir de ~/.hermes/memories/.
✓
USER.md = perfil seu (1.375 chars / ~500 tokens) — fatos estáveis sobre você.
✓
MEMORY.md = notas do agente (2.200 chars / ~800 tokens) — ambiente, decisões, atalhos.
✓
Tool memory tem add, replace, remove — auto-gerenciada, consolida quando enche.
✓
session_search é a memória longa — SQLite + FTS5 em ~/.hermes/state.db.
✓
Nunca salvar secrets, tarefas temporárias ou status — esses têm outros lugares próprios.

Próximo módulo:

3.2 - 🛠️ Skills: SKILL.md + Progressive Disclosure

← Voltar para Trilha Próximo Módulo →