🧬 As 3 camadas de aprendizado
O agente acumula contexto útil em três camadas com naturezas diferentes. Saber qual camada usar pra cada tipo de aprendizado é o que evita memória inflada com coisas que deveriam ser skill, e skills criadas pra coisas que são só fato.
💾 Memória (MEMORY.md / USER.md)
Natureza: fatos. Carregamento: sempre, snapshot frozen no system prompt.
Bom pra: ambiente, decisões fechadas, preferências estáveis.
🛠️ Skills (SKILL.md)
Natureza: procedimentos. Carregamento: Progressive Disclosure 3 níveis.
Bom pra: tarefas reproduzíveis, fluxos com passos claros, capacidade compartilhável.
📚 Histórico (SQLite + FTS5)
Natureza: conversas. Carregamento: sob demanda via session_search.
Bom pra: contexto pontual que pode voltar a ser útil. Não vale a pena promover a memória.
🧭Diagnóstico rápido
- • Fato pontual ("uso PostgreSQL no projeto X") → memória
- • Procedimento repetível ("como faço deploy do X") → skill
- • Conversa específica ("aquela vez que discutimos a arquitetura Y") → fica no histórico
♻️ Ciclo: tarefa → execução → correção → persistência
O loop completo de auto-aperfeiçoamento tem cinco passos. Sem o passo de persistência, você corrige os mesmos erros sempre. Sem o passo de uso futuro, a persistência é desperdício.
🔁 Os passos
💬Frases de gatilho
Sem frases assim, o aprendizado some no fim da sessão:
- • "Salva isso na memória — sempre uso PostgreSQL nos projetos novos."
- • "Vira skill: deploy do projeto X com esses 5 passos."
- • "Atualiza seu soul pra ser mais direto, sem frases de transição."
- • "Lembra disso pra próxima: minha branch padrão é
main, nãomaster."
⚠️Sem frase = sem persistência
O agente não decide sozinho que algo virou aprendizado. Você precisa explicitar. "Anotei mentalmente" não conta — só o que foi pra arquivo persiste.
2️⃣ Regra dos 2 erros
Heurística simples e poderosa: 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.
1ª vez
Corrija e siga. Pode ter sido contexto específico.
2ª vez
Atualize a camada certa. É padrão, não acidente.
3ª vez
Você falhou em atualizar. Pare e atualize agora.
🎯Por que 2 e não 3
3 já desperdiçou tempo demais. 1 ainda é cedo pra generalizar. 2 é o limiar pragmático: você comprovou padrão sem ainda ter perdido muito tempo. Esse é um número arbitrário, mas funciona como regra mental simples.
🪄 Repetir instrução = candidato a skill
Toda vez que você se pega digitando "primeiro faz X, depois Y, cuidado com Z" pela terceira 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. Inclua When to Use, Procedure passo-a-passo, Pitfalls que já encontramos e Verification pra confirmar que deu certo. Categoria: devops."
O agente formaliza com YAML front matter e estrutura canônica. Você só revisa.
🔍Sinais de "isto deveria ser skill"
- •Você tem um documento separado com o passo-a-passo (Notion, Google Doc) que precisa abrir antes de pedir
- •O agente erra os mesmos passos em sessões diferentes
- •Você precisa explicar o procedimento pra outra pessoa do time
- •O fluxo tem mais de 3 passos sequenciais
- •Tem armadilhas conhecidas que precisariam de aviso explícito
🎚️ Tom errado = soul; fato repetido = memória; processo errado = skill
Diagnóstico rápido pra escolher onde corrigir. Roteamento errado piora o problema (soul mais grosso não conserta falta de fato; memória mais cheia não conserta tom).
🗺️ Tabela de roteamento
| Tipo de erro | Camada | Frase de exemplo |
|---|---|---|
| Tom/voz | SOUL.md | "Está formal demais. Atualize seu soul." |
| Fato sobre você | USER.md | "Salva no USER que eu sou esquerdo." |
| Fato do ambiente | MEMORY.md | "Salva na memória: backup roda às 3h." |
| Procedimento | SKILL.md | "Vira skill: deploy do projeto X." |
| Contexto pontual | Histórico | "Quando precisar, busca no histórico." |
⚠️Roteamento errado degrada
- ✗Procedimento de 8 passos virando entrada de MEMORY.md → estoura os 2.200 chars rapidamente
- ✗Regras de tom indo pra USER.md → sumindo no slot errado, sem força
- ✗Fato do ambiente virando skill → skill com 1 frase no procedure, sem ter quando usar
🩺 Manutenção periódica
Sem revisão periódica, esses arquivos viram lixo acumulado. Entradas antigas brigam com novas. O agente perde clareza. Auditoria mensal de 10 minutos vale mais que reescrever tudo do zero a cada 6 meses.
📅 Frase de revisão
"Mostre o conteúdo atual de SOUL.md, USER.md, MEMORY.md e a lista de skills. Aponte: o que está obsoleto, o que está contraditório, o que está redundante. Proponha consolidação."
Cadência sugerida
- • Memória: revisão mensal
- • Skills: revisão a cada 2-3 meses
- • Soul: revisão a cada 1-2 meses ou quando tom incomoda
Versione no GitHub
Comite ~/.hermes/SOUL.md, memories/ e skills/ num repo privado. Você ganha histórico de evolução do agente, fica fácil reverter, dá pra clonar pra novo VPS sem refazer tudo.
📌Loop completo, em uma frase
Use o agente. Corrija o que sair errado. Mande persistir na camada certa. Reveja periodicamente. Versione tudo. Em poucos meses, o agente já é seu — não um chatbot genérico.
🎯Resumo do módulo
Próxima trilha:
Trilha 4 - 🛡️ Segurança e Configuração