A memória dos meus agentes, na prática: um sistema de registros para quem quer lida com muitas decisões simultâneas
Cinco camadas de registro com dono, formato e ciclo de vida próprios; os crons que transformam PRs e reuniões em decisões rastreáveis; e a ordem de leitura que devolve a fonte certa para cada pergunta
Em março escrevi aqui que a memória dos seus agentes está quebrada. O argumento era que jogar o histórico inteiro no contexto funciona no protótipo e desmorona em produção, e que a saída passava por separar camadas de memória com papéis distintos. Era arquitetura no papel.
Nos meses seguintes eu coloquei essa arquitetura para rodar na minha própria operação. Hoje cinco agentes trabalham para mim em máquinas diferentes: um numa instância EC2, um numa KVM, um no meu Mac, um agente de coding e um consolidador que roda diariamente. Todos escrevem e leem de um mesmo substrato. A rodada de consolidação de ontem processou 64 registros brutos vindos desses agentes e promoveu 15 arquivos ao acervo curado; a de anteontem, num dia atípico, processou cerca de 230. O sistema está vivo, tem cicatrizes, e é exatamente por isso que vale especificar.
Este ensaio é essa especificação. A tese central cabe numa frase: pare de procurar uma memória única de IA e construa um sistema de registros com fronteiras claras. A qualidade vem menos do modelo e mais de saber o que pode ser promovido, quem cura, qual é a fonte de verdade e como cada automação prova o que afirma.
Organizei a especificação em dez seções: o princípio, as quatro camadas de registro, os crons de captura que alimentam tudo, os consumidores desse contexto e as proteções de confiabilidade. A intenção é que você consiga implementar o equivalente com o agente que já usa, seja ele um assistente de código, um orquestrador próprio ou um framework de mercado.
01. O princípio: fronteiras antes de modelo
O erro mais comum que vejo em projetos de memória de agente é misturar quatro coisas que pedem tratamentos opostos: a sessão bruta, a memória semântica do agente, o conhecimento compartilhado entre agentes e o relatório executivo para humanos. Quando tudo vira “memória”, o log polui o raciocínio, a opinião de um agente contamina os demais e ninguém sabe mais o que é verdade consolidada.
O desenho que uso separa as camadas num fluxo de refino:
Cada camada tem dono, formato, ciclo de vida e critério de escrita próprios. Evidência bruta é imutável e barata; memória de sessão é volumosa e pesquisável; conhecimento curado é escasso e caro, porque passou por um funil com critério. A regra que sustenta o resto do artigo: descer de camada é automático, subir de camada exige promoção explícita. Nada “vira verdade” por acidente.
02. Session memories: o ledger do que aconteceu
A primeira camada é o ledger da sessão: conversa, ações, comandos relevantes, decisões, mudanças de contexto e resultados, gravados em append-only. Esse registro serve para auditoria e para recuperar detalhe exato (”o que foi dito na terça sobre o contrato X?”). Ele responde o que aconteceu; a verdade atual sobre um assunto mora em outra camada.
A implementação mínima é um armazenamento pesquisável por sessão, data, agente e tópico, com eventos neste formato:
{
"session_id": "uuid",
"agent_id": "daisy",
"timestamp": "ISO-8601",
"kind": "message|tool_result|decision|observation",
"text": "...",
"source": "webchat"
}Dois cuidados aprendidos em produção. Primeiro, o ledger jamais entra inteiro no contexto de cada turno; ele existe para busca sob demanda, senão você recria o modelo ingênuo que critiquei em março. Segundo, vale manter um staging de momentos relevantes por sessão: um lugar onde o agente marca uma decisão como candidata antes de promovê-la a memória durável. Esse degrau intermediário evita tanto a perda do momento quanto a promoção precipitada.
03. Mem0: a memória semântica privada de cada agente
A segunda camada, no meu caso implementada com Mem0, guarda outra coisa: um índice semântico de fatos duráveis que ajudam aquele agente a trabalhar melhor daqui a dias ou semanas. Entra aqui apenas o que passa em três filtros ao mesmo tempo: muda estado, direção ou comportamento; segue válido (ninguém reverteu); e continuará relevante depois que a sessão acabar.
Exemplos que passam no filtro: uma decisão de arquitetura, uma preferência operacional minha, o contrato de um projeto, uma lição técnica reutilizável, o estado relevante de uma integração. Exemplos que ficam de fora: polling, saída crua de comando, “verifiquei e estava tudo verde”, conversa casual, progresso temporário. A diferença entre as duas listas é o que separa memória de ruído.
Cada memória carrega metadados mínimos:
{
"agent_id": "daisy",
"user_id": "daisy",
"type": "decision|learning|correction|conclusion",
"topic": "culkin-redshift",
"durable": true,
"reversible": false,
"source": "session:<id>",
"promoted_to_shared_knowledge": false
}Um detalhe de desenho que considero inegociável: cada agente tem o seu índice privado, com a sua credencial, escrevendo sob a sua identidade. A experiência bruta de um agente é hipótese, e hipótese de um não pode virar verdade automática para todos. Já vivi o incidente que justifica a regra: um agente reportou um suposto bug de duplicação num fornecedor, e a investigação mostrou que o instrumento de medição dele é que estava errado. Se aquela “descoberta” tivesse se propagado como fato compartilhado, três agentes estariam operando sobre um erro.
04. gui-brain: o conhecimento curado que todos compartilham
A terceira camada é a que dá nome ao meu sistema: o gui-brain, um repositório Git de Markdown com frontmatter que funciona como fonte canônica sobre mim, meus projetos, decisões, preferências, pessoas e conceitos recorrentes. A distinção decisiva em relação à camada anterior: o Mem0 responde “o que este agente aprendeu?”; o repositório curado responde “qual é a verdade consolidada que todos os agentes devem usar?”.
A mecânica que faz isso funcionar é a separação entre inbox e acervo. Agente nenhum escreve direto na área curada. Cada um despeja observações numa caixa de entrada própria, por data:
gui-brain/
_inbox/openclaw/2026-07-21/ <- área RAW, escrita livre por agente
_inbox/hermes/...
identity/ <- curado, gate humano
projects/ decisions/
people/ knowledge/ work/O fluxo de promoção: o agente detecta decisão, aprendizado ou mudança material; faz pull defensivo; cria a nota na inbox com proveniência, confiança, links e data; e commita. Uma vez por dia, um curador (no meu caso, um agente consolidador com playbook versionado) lê tudo que apareceu nas inboxes, deduplica observações que múltiplos agentes registraram, funde o que é a mesma coisa preservando as duas origens, e move o que tem sinal para a pasta curada apropriada. O que foi processado vai para um arquivo morto por agente, e nada é deletado.
Cada nota carrega um frontmatter que força o agente a se comprometer com o que está afirmando:
---
type: decision
title: "Contrato de dados do projeto X"
source_agent: openclaw
source_origin: "PR #123 + validação em produção"
created: 2026-07-21
confidence: high # eu vi isso acontecer?
signal: high # isso importa?
status: raw
links: [projects/active/projeto-x.md]
---Dois campos merecem comentário. confidence e signal são ortogonais: um mede se a observação é sólida, o outro mede se ela importa. A matriz entre os dois decide o destino; sinal alto com confiança baixa, por exemplo, vira proposta para eu validar em vez de ser promovida direto. E o acervo separa updated (qualquer edição) de last_observed (a última vez que a realidade confirmou aquela informação), o que permite detectar conhecimento parado: arquivo formalmente recente cuja informação ninguém reconfirma há noventa dias é candidato a revisão.
Duas regras fecham a camada. Identidade (traços de personalidade, valores, forma de decidir) tem gate humano: o consolidador sintetiza propostas e elas ficam com review_decision: pending até eu aprovar ou rejeitar; agente nenhum escreve ali sozinho. E o consolidador também tece: injeta links bidirecionais entre arquivos relacionados e mede a razão de links novos por arquivo novo. Quando essa razão cai abaixo de um limiar, o grafo está virando um catálogo de arquivos órfãos, e isso dispara alerta. Inbox é proposta e evidência; área curada é verdade compartilhada. Essa fronteira é o coração do desenho.
05. Registros operacionais: a camada que evita contaminação
Existe uma quarta camada, auxiliar, que serve justamente para as outras não serem contaminadas por operação: um diário bruto por dia (memory/YYYY-MM-DD.md), um arquivo de obrigações futuras com prazo, verificação e rollback (FOLLOWUPS.md), os arquivos de estado dos crons (deduplicação, SHA já revisado, última notificação) e um MEMORY.md enxuto com pendências de alta visibilidade e ponteiros.
O propósito dessa camada é ser fila e estado, com ciclo de vida curto. Sem ela, o conhecimento estratégico vira lista de tarefas e a memória semântica vira log operacional, que são os dois modos clássicos de degradação.
06. Captura de decisões em PRs: review com estado e as CTO notes
Até aqui, camadas. Agora, os crons que as alimentam. O primeiro é o de captura de decisões em pull requests, que na minha operação culmina num produto executivo diário que chamo de CTO notes.
Começa pelo cron de review. Ele roda a cada 30 minutos e tem estado, o que o distingue de “pedir para uma IA opinar”:
GitHub/GitLab
→ descobre PR/MR aberto ou head alterado
→ deduplica por repo + número + SHA
→ busca body, diff, commits, checks e comentários
→ revisa contra rubrica versionada
→ publica review no SHA exato
→ grava estado e evidência
→ notifica somente quando houver mudança relevanteA rubrica é versionada e a regra de aprovação é dura: qualquer finding bloqueia. A parte que mais importa para quem for implementar é o papel do SHA. Uma review vale apenas para o head revisado; commit novo invalida o parecer anterior; e o estado do cron é chaveado por repo, número e head SHA. Sem isso, o sistema afirma coisas sobre um código que já mudou.
Sobre esse review roda o cron diário de CTO notes, à meia-noite: percorre os repositórios, coleta PRs, commits, diffs e discussões do intervalo do dia, salva a evidência bruta, sintetiza as decisões com fallback entre modelos e faz upsert idempotente da seção do dia num documento executivo. O sintetizador precisa distinguir código, discussão, decisão explícita, risco e ruído de merge; transformar todo comentário em “decisão” automaticamente produziria um documento executivo cheio de decisões que ninguém tomou. Na outra ponta, o consolidador diário lê esse documento, espelha o verbatim no acervo e destila apenas as decisões de alto sinal para a pasta de decisões curadas, com link de volta para a evidência.
07. Meeting intelligence: da fala ao objeto acionável
O segundo cron de captura trata reuniões, quatro vezes ao dia. O desenho parte de uma recusa: a saída que interessa é um conjunto de objetos acionáveis, e resumo bonito é subproduto.
gravação / notas de reunião
→ transcrição ou documento
→ extração estruturada de decisões, riscos, compromissos e owners
→ evidência bruta versionada
→ ações: issue, follow-up, estratégia ou CTO notesCada objeto extraído sai neste formato:
{
"decision": "...",
"owner": "...",
"deadline": "...",
"evidence": "meeting_id + trecho",
"destination": "issue|followup|strategy|cto_notes"
}
A regra inviolável é o campo evidence: toda ação criada carrega o link para a reunião e o trecho de origem. É isso que impede a alucinação de decisão, o modo de falha mais caro desse tipo de automação. Uma “decisão” sem trecho de origem simplesmente não nasce.
08. Estratégia é consolidada, e nunca inferida de atividade
Sobre as notas executivas vive um segundo produto: o documento de estratégia (tese, prioridades, trade-offs, posicionamento) e um terceiro sobre pessoas e organização. Aqui vale uma correção que fiz ao meu próprio desenho. Cheguei a considerar um cron diário de estratégia e recuei: estratégia muda em ritmo semanal, na melhor das hipóteses.
O desenho que recomendo é um job semanal de consolidação estratégica que lê as CTO notes, as decisões curadas, as extrações de reunião e as métricas, e reescreve um documento vivo. Na minha operação, esse documento é alimentado por meeting intelligence e por input manual meu, e o consolidador o reescreve a cada ciclo em vez de empilhar apêndices. A restrição que protege a camada: o job nunca inventa estratégia a partir de atividade técnica. Volume de commits é sinal de movimento; direção é decisão humana registrada. Confundir os dois produz documentos que parecem estratégicos e apenas descrevem inércia.
09. Recuperação de contexto: a fonte certa para a pergunta certa
Todo o investimento em escrita se paga na leitura. No início de uma sessão, meus agentes seguem uma ordem de carregamento que começa leve e aprofunda sob demanda: primeiro identidade e o índice do conhecimento curado; depois o contexto do projeto em questão; depois busca semântica na memória privada; o ledger de sessão apenas se for preciso reconstituir detalhe; e as notas executivas quando a tarefa tem implicação de gestão.
A tabela mental que governa a leitura: verdade sobre pessoa, projeto ou decisão mora no acervo curado; experiência recente do próprio agente mora no Mem0; detalhe exato de conversa mora no ledger; estado operacional mora nos follow-ups e arquivos de estado; visão executiva mora nas CTO notes e na estratégia. Quando um agente responde errado, a causa mais frequente na minha experiência é consulta à camada errada, e o sintoma clássico é usar log de sessão para responder pergunta de estado atual.
Há um sinal de saúde que monitoro com atenção: o journal diário do consolidador registra quais arquivos curados foram efetivamente usados como fonte no dia. Se esse campo fica vazio por uma semana, o sistema está escrevendo sem ler. Chamo isso de write-only drift, e considero o sintoma número um de fracasso em gestão de conhecimento, humana ou de agente.
10. Confiabilidade: o que mantém o sistema honesto
As cadências que uso hoje: writer de memória a cada 2 horas; sincronização do repositório a cada 6; curadoria consolidada uma vez ao dia; review de PR/MR a cada 30 minutos; meeting intelligence quatro vezes ao dia; CTO notes diário; auditoria de qualidade de memória diária; backup em Git diário. Os números importam menos que a existência de cadência explícita por camada; ajuste ao seu volume.
As proteções, essas sim, considero não negociáveis. Idempotência por ID de origem, SHA ou hash de conteúdo, para que rodar duas vezes produza o mesmo resultado. Proveniência obrigatória em toda síntese. Evidência bruta separada da conclusão. Timestamps com timezone explícito. Health check por cron, com alerta para falha repetida; um cron parado em silêncio é indistinguível de “nenhuma novidade”, e essa ambiguidade já me custou 19 dias lendo uma fonte congelada achando que a fonte estava quieta. Fallback de modelo com a proveniência do modelo real registrada, porque provider pode responder com outro modelo por baixo do rótulo; e nenhum caminho de fallback em que a automação responde sem fonte. Git em tudo que é curado, pela auditabilidade e pelo rollback. E permissões mínimas por fonte: o agente que lê calendário raramente precisa escrever no repositório de conhecimento.
Cicatriz recente que ilustra a categoria: dois crons meus de monitoramento ficaram um dia inteiro fora do ar porque fixavam um único provedor de LLM, e a conta desse provedor ficou sem saldo. A correção virou regra escrita no acervo: automação operacional herda a cadeia central de failover, e fixar modelo exige justificativa explícita. É o sistema de registros documentando a própria operação, que é exatamente o comportamento que você quer ver emergir.
O que levar para o seu dia a dia
Quatro lições transferíveis.
Primeira: defina as fronteiras antes de escolher ferramenta. Um arquivo de texto com fronteiras claras supera um vector database usado como balde único; a decisão cara é o que pode ser promovido, quem cura e qual é a fonte de verdade por tipo de pergunta.
Segunda: exija proveniência de toda síntese. Decisão sem link para a origem é opinião com verniz de registro, e automação que afirma precisa provar, seja pelo SHA revisado, seja pelo trecho da reunião.
Terceira: coloque um humano no gate das camadas sensíveis. No meu sistema, identidade e estratégia só mudam com veredito meu; o resto flui sozinho, e é essa assimetria que permite automatizar sem perder o controle.
Quarta: trate o substrato curado como ativo. Escrevi em junho sobre dados proprietários como vantagem competitiva no nível das empresas; o acervo curado que seus agentes leem é a versão operacional disso, e ele se valoriza com o tempo pelas mesmas razões: acumulação, path dependence e a impossibilidade de comprar o atraso depois.
Quem quiser ver o mecanismo de melhoria contínua por trás disso, escrevi sobre ele em aplicações que aprendem com uso real.
Se for começar amanhã, comece pequeno: um repositório Git, uma inbox por agente, um frontmatter mínimo com proveniência e confiança, e um cron diário de curadoria com regras escritas. O resto do sistema cresce por demanda, camada a camada, e cada camada nova nasce quando a anterior começa a ser mal utilizada para um papel que exige outra.
Fecho com a pergunta que uso para auditar o meu próprio sistema. Quando o seu agente afirmar amanhã que uma decisão foi tomada, você vai conseguir apontar onde ela está escrita, quem a promoveu e qual evidência a sustenta?