kaeru dá ao Claude Code e ao Codex memória de longo prazo em forma de grafo via MCP

Quem trabalha com agentes de IA há mais de uma semana conhece essa cena. Você abre o projeto, e o agente pergunta algo que você já respondeu ontem. Meia hora depois, ele propõe consertar justamente o que você decidiu não mexer, e soa convincente porque desconhece o motivo. Quando o contexto estoura e a conversa é comprimida em um resumo, metade da discussão vira duas linhas.

A equipe da Lamantin AI propõe resolver isso com uma camada de memória separada. A ferramenta se chama kaeru, e o código-fonte está no GitHub. Abaixo, uma análise de como ela funciona e de onde estão seus pontos fracos. O autor do texto original é o desenvolvedor da própria ferramenta, então vale ler isto como uma visão de dentro.

Por que um arquivo de regras não basta

O primeiro passo é igual para todo mundo: CLAUDE.md, AGENTS.md, .cursorrules ou uma nota no Obsidian. Cerca de um mês depois, os problemas começam:

• o arquivo só é atualizado quando alguém se lembra dele, ou seja, três dias depois e com perda de detalhes;
• ele só cresce: acrescentar é fácil, riscar dá medo, e o agente confia igualmente na regra de ontem e em uma regra cancelada há um mês;
• ele tem o «o quê», mas não o «porquê»: um «não mexer no parser» sem motivo não pode ser verificado nem revogado;
• cada membro da equipe tem o seu próprio arquivo.

ADRs e gerenciadores de tarefas como o beads resolvem parte dos problemas, mas não a camada de trabalho entre os commits: hipóteses, verificações, particularidades dos ambientes de teste. Levar tudo isso para o repositório polui o histórico, e não registrar significa perder. É para essa camada que o kaeru foi feito.

Como ele funciona

O kaeru roda na sua máquina como um servidor MCP, ao qual se conectam Claude Code, Codex, Cursor e outros clientes. A memória é armazenada como um grafo: observações («os arquivos do cliente chegam em cp1251»), decisões, tarefas com prazo, hipóteses com o resultado da verificação e documentos. As conexões são tipadas: «surgiu de», «substitui», «refuta», «confirma», «bloqueia», «contradiz». O agente pode salvar a cadeia inteira, da observação à decisão, como um raciocínio.

Exemplo do artigo: o agente suspeita que a exportação noturna falha por causa do tamanho do arquivo. Ele testa com um arquivo de 2 GB e registra a hipótese já com o veredito «refutada». Se a exportação falhar de novo na semana seguinte, o próximo agente começa por outra explicação. Sem memória, o resultado negativo é o primeiro a se perder: as soluções que deram certo entram no código, e as que falharam não vão a lugar nenhum.

O que é antigo pode ser substituído de forma explícita. A chamada replace marca o registro anterior como substituído e mostra quais conclusões dependiam dele. O registro não é apagado, mantém seu histórico, e é possível abrir a versão de qualquer momento.

Há também lembretes: um registro pode ser ocultado até uma data determinada. Exemplo do autor: o certificado do ambiente de teste é renovado a cada seis dias. No quinto dia, essa informação é necessária; no primeiro, só atrapalha. O prazo do lembrete conta a partir da primeira exibição, então ele não expira depois de umas férias.

O que fazem os hooks e o que faz o servidor

O servidor cuida do armazenamento e do resumo. Quando solicitá-lo e o que fazer na compressão de contexto é decisão do cliente, por meio de hooks no Claude Code e no Codex. O autor escreveu alguns hooks para uso próprio, e eles ainda não fazem parte do kaeru. O repositório inclui o kaeru-first: antes de o agente fazer uma pergunta ao humano, o hook procura correspondências na memória e sugere ler primeiro o que foi encontrado.

Há ainda uma observação útil. Simplesmente sugeriram ao agente que lesse os raciocínios salvos, e em sete sessões ele nunca o fez. Por isso o resumo é injetado automaticamente, no início da sessão.

Limitações

• O kaeru não garante a veracidade dos registros. O agente pode anotar bobagem, assim como em um arquivo de regras. O ganho está em ver de quais observações a conclusão nasceu e em poder marcar o erro e refazer a cadeia.
• A substituição do que é antigo precisa ser chamada pelo próprio agente. Com o autor, duas regras com IDs diferentes das mesmas pessoas no GitLab conviveram por duas semanas: a nova foi registrada, mas a antiga não foi substituída.
• Coincidência de palavras não significa que o registro contenha a resposta.
• O servidor de equipe kaeru-cloud é instalado por você mesmo. Ele foi pensado para uma equipe de confiança, com um único espaço compartilhado dividido por projetos, e ainda não há isolamento entre usuários e organizações. Por padrão, os projetos são privados, e os registros são escaneados em busca de chaves e tokens antes do envio.

O que fazer com isso

Se seus agentes vivem mais do que alguns dias no mesmo projeto, vale separar o conhecimento em duas camadas. Os acordos duradouros ficam no repositório (regras, ADRs) e passam por revisão. Achados de trabalho, hipóteses descartadas e os «porquês» precisam de um armazenamento à parte, com histórico e substituição explícita do que ficou obsoleto. Mesmo sem o kaeru, vale adotar duas práticas: registrar hipóteses junto com o veredito e entregar ao agente um resumo curto de forma automática, em vez de esperar que ele o leia por conta própria.