Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoAnálise · No radarHabr AI→ original

Anthropic mostra como dar a um agente de IA memória sobre o projeto sem inflar o contexto

Um agente de IA sem memória começa o projeto do zero todos os dias, como um desenvolvedor com amnésia. Lamis Mukta, da Anthropic, mostrou o caminho percorrido pelo Claude Code: de um único arquivo CLAUDE.md com regras a um diretório de notas em markdown com índice. O agente lê apenas o sumário e abre as notas de que precisa, de modo que o contexto — tudo o que o modelo enxerga em uma chamada — não incha. A memória merece confiança com ressalvas: cada entrada precisa de fonte, escopo e status.

Processado por IA de Habr AI; editado por Hamidun News
Anthropic mostra como dar a um agente de IA memória sobre o projeto sem inflar o contexto
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Dado-chave #1O CLAUDE.md é carregado inteiro no contexto, então um arquivo inchado consome a atenção do agente
Skill é uma pasta com um SKILL.mdo agente vê só a descrição e carrega o texto completo conforme a tarefa
Dado-chave #3Uma nota como "teste quebrado" é inútil; é preciso registrar condições, ambiente e data da verificação

Imagine que um desenvolvedor excelente entrou para a equipe. No primeiro dia, ele entendeu o projeto, encontrou o serviço certo, descobriu por que os testes falhavam e fechou uma pilha de tickets. No segundo dia, descobre-se que ele tem amnésia: estuda de novo o mesmo repositório e tropeça nos mesmos erros de ontem.

É mais ou menos assim que um agente de IA funciona por padrão. O conhecimento geral está embutido nos pesos do modelo, mas a estrutura do seu projeto, as regras adotadas pela equipe e os motivos pelos quais você rejeitou a mesma solução três vezes ele não conhece de fábrica. A experiência não se acumula sozinha entre as execuções.

Lamis Mukta, da Anthropic, contou como o Claude Code lida com isso: o agente guarda a memória do projeto em arquivos e carrega no contexto, ou seja, nos dados que o modelo enxerga em uma chamada específica, só o que é necessário. A palestra dela foi analisada na décima parte da série "Me leve para dentro do harness", no Habr.

De um único arquivo a um diretório de notas

Primeiro, o autor recomenda distinguir quatro coisas. A janela de contexto é o que o modelo vê agora. A transcrição é o registro das mensagens e ações da sessão. O estado de execução guarda em que etapa o agente está e o que foi confirmado. A memória é o conjunto de informações selecionadas para tarefas futuras. Ela não substitui o log nem o estado atual do sistema.

No Claude Code, a memória evoluiu por etapas, embora o autor ressalte que isso não é uma escada obrigatória. A opção mais simples é o arquivo CLAUDE.md, com o comando para rodar os testes, a localização dos serviços e os acordos da equipe. Ele é fácil de revisar a olho e de manter no git. Mas o arquivo é carregado inteiro no contexto de cada sessão. Se você escrever ali tudo o que lhe vier à cabeça, o resultado será uma instrução "do tamanho de um quebra-gelo atômico", e até a correção de um erro de digitação vai gastar a atenção do agente com texto desnecessário.

O passo seguinte é a ferramenta de memória. O modelo tem as funções memory_read, memory_write e memory_edit e decide sozinho quando chamá-las. Onde tudo fica armazenado depende da implementação: uma pasta com markdown, um banco de dados ou outra coisa. Por isso é possível limitar o que o agente lê e escreve e verificar as entradas antes de salvá-las. A edição é pontual, então as informações vizinhas não se perdem.

Depois vêm as skills. A memória guarda fatos ("os testes rodam com o comando X"), enquanto a skill guarda uma sequência de ações ("como publicar uma release"). Fisicamente, é uma pasta com um arquivo SKILL.

md, ao lado do qual podem ficar modelos, exemplos e scripts. O agente vê o tempo todo apenas a lista de descrições e carrega a instrução completa quando a tarefa corresponde a ela. Por isso dá para manter dezenas de skills sem grande custo de contexto.

Um script, onde a precisão é necessária, é mais confiável do que um pedido em texto: ele se comporta da mesma forma todas as vezes. Mas ele roda na sua máquina, com as suas permissões, então skills de terceiros devem ser lidas como código de terceiros.

Como funcionam a escrita e a leitura

O esquema apresentado na palestra é este. Durante o trabalho, o agente decide o que vale a pena salvar: um acordo da equipe, uma preferência do usuário, a causa encontrada para um bug. Ele cria ou atualiza um arquivo markdown.

No início da sessão, lê um índice curto, com uma linha por nota. Quando a tarefa corresponde a uma descrição, abre o arquivo certo. Se o índice não bastar, busca pelo conteúdo com ferramentas comuns, como o grep, e por isso nomes claros de arquivos e pastas são importantes.

Convém separar as pastas: regras da organização, notas do projeto, preferências do usuário, conclusões temporárias. Caso contrário, o agente aplicará o acordo de uma equipe a outro projeto só porque as duas notas apareceram na busca pela palavra deploy.

Uma boa entrada contém identificador, escopo, tipo, status, fonte e data de atualização. Uma nota como "a tabela quebra" é inútil: uma semana depois, ninguém vai entender qual tabela e se o problema foi corrigido. Já a entrada "na importação de DOCX com célula vazia, foi reproduzida uma divergência; antes de concluir, verificar o código atual" dá uma direção e deixa claros os limites do conhecimento.

A data, por si só, não indica que a informação ficou obsoleta: o comando para rodar um teste vale por anos, enquanto a versão de um serviço em produção muda em minutos. Por isso, tipos diferentes de entrada exigem regras de verificação diferentes. Do contrário, o agente anunciará alegremente que tudo foi implantado porque, seis meses atrás, alguém deixou uma nota dizendo isso.

Ler aos poucos e verificar mesmo assim

Suponha que se acumularam mil notas. Enviar todas em cada requisição é tecnicamente possível, mas você paga pelo processamento de texto excedente, e fica mais difícil para o modelo encontrar o que importa em meio aos fatos vizinhos. Por isso a memória é lida em etapas: escopo da tarefa, índice, busca por palavras-chave e, se necessário, por significado, e só então os trechos relevantes. A busca semântica ajuda quando o usuário e o autor da nota chamam a mesma coisa de nomes diferentes. A busca exata é melhor para nomes de arquivos, códigos de erro e identificadores. Nenhuma das duas garante que a entrada encontrada esteja correta.

Um exemplo da palestra: o usuário pede para corrigir a importação de uma tabela. O agente encontra uma nota sobre a localização do manipulador de DOCX e sobre um defeito antigo com célula vazia, e então abre o código atual e os testes. Se a nota descreve uma branch antiga, isso não é motivo para declarar a causa antiga como a origem de um novo erro. A memória encurta a busca, mas não dispensa a verificação.

Outra ideia da palestra é o dreaming: um processo em segundo plano que revisa as sessões anteriores e organiza o conhecimento acumulado.

A conclusão prática para quem constrói agentes: comece com um CLAUDE.md curto, leve os procedimentos para skills e mantenha os fatos sobre o projeto em notas com índice, fonte e status. E trate sempre a entrada como uma dica, não como a verdade.

História

Perguntas frequentes sobre a notícia

O que se sabe sobre De um único arquivo a um diretório de notas?

Primeiro, o autor recomenda distinguir quatro coisas. A janela de contexto é o que o modelo vê agora. A transcrição é o registro das mensagens e ações da sessão. O estado de execução guarda em que etapa o agente está e o que foi confirmado. A memória é o conjunto de informações selecionadas para tarefas futuras. Ela não substitui o log nem o estado atual do sistema. No Claude Code, a memória evoluiu por etapas, embora o autor ressalte que isso não é uma escada obrigatória.

Como funcionam a escrita e a leitura?

O esquema apresentado na palestra é este. Durante o trabalho, o agente decide o que vale a pena salvar: um acordo da equipe, uma preferência do usuário, a causa encontrada para um bug. Ele cria ou atualiza um arquivo markdown. No início da sessão, lê um índice curto, com uma linha por nota. Quando a tarefa corresponde a uma descrição, abre o arquivo certo. Se o índice não bastar, busca pelo conteúdo com ferramentas comuns, como o grep, e por isso nomes claros de arquivos e pastas são importantes.

O que se sabe sobre Ler aos poucos e verificar mesmo assim?

Suponha que se acumularam mil notas. Enviar todas em cada requisição é tecnicamente possível, mas você paga pelo processamento de texto excedente, e fica mais difícil para o modelo encontrar o que importa em meio aos fatos vizinhos. Por isso a memória é lida em etapas: escopo da tarefa, índice, busca por palavras-chave e, se necessário, por significado, e só então os trechos relevantes. A busca semântica ajuda quando o usuário e o autor da nota chamam a mesma coisa de nomes diferentes.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
O que você acha?
Carregando comentários…