Disciplina de Memória do Agente

Visão Geral

Conectar uma ferramenta de memória não faz um agente usá-la: as ferramentas são registradas, a sessão é executada e nada é recuperado ou salvo. Esta habilidade fornece a parte que falta, estabelecendo regras para quando ler a memória e quando gravá-la.

O problema que ela resolve é específico. Um agente com memória disponível ainda repete perguntas já respondidas, reverte hábitos corrigidos e perde decisões entre sessões, porque nada lhe diz quando a recuperação e o salvamento são devidos. As regras abaixo tornam ambos os momentos explícitos.

Quando Usar Esta Habilidade

• Use quando uma ferramenta de memória ou servidor de memória MCP estiver conectado, mas o agente não o estiver usando consistentemente.
• Use quando o usuário reclamar que o assistente perde preferências, convenções ou decisões passadas entre sessões.
• Use ao configurar memória persistente para um projeto e o agente precisar de regras permanentes para lê-la e gravá-la.
• Use quando o usuário disser "lembre-se disso", "o que decidimos", "recupere" ou "salve isso para a próxima vez".

Como Funciona

Antes de Começar: Qualquer Backend de Memória

O agente precisa de uma ferramenta de memória que possa chamar. Qualquer backend funciona, e as regras são idênticas para cada um:

• Arquivos. Uma pasta memory/ de notas Markdown, um fato por arquivo. Sem dependências, totalmente pesquisável, versionável em git.
• Um servidor de memória MCP local. Mantém tudo na máquina local; existem várias opções de código aberto.
• Um serviço de memória hospedado via MCP. Adiciona portabilidade entre ferramentas e máquinas ao custo de os dados ficarem em outro lugar.

A autenticação é o que o backend escolhido exigir: nenhuma para uma pasta local, a própria configuração do servidor para um servidor MCP local, uma chave de API ou login OAuth para um serviço hospedado. Esta habilidade nunca lida com credenciais por si só e nunca as grava na memória.

Passo 1: Recuperar Antes de Agir

Leia a memória antes de fazer qualquer uma destas ações, não depois:

• iniciar o trabalho em um projeto já abordado anteriormente
• escolher uma biblioteca, padrão ou ferramenta
• escrever testes, commits ou documentação, onde convenções se aplicam
• responder "como costumamos fazer X aqui"
• qualquer coisa que o usuário formule como "de novo", "como da última vez" ou "como combinamos"

Pule a recuperação para perguntas factuais pontuais, aritmética ou qualquer coisa totalmente especificada na mensagem atual. A recuperação custa uma chamada de ferramenta e contexto; gastá-la em uma pergunta autocontida é desperdício.

Pesquise com as palavras que o usuário realmente usou, mais o nome do projeto ou repositório. Se a primeira pesquisa não retornar nada útil, tente uma consulta mais ampla, depois pare e prossiga sem memória em vez de entrar em loop.

Passo 2: Salvar Após Decidir

Grave na memória quando uma destas situações acabou de ocorrer:

• uma decisão foi tomada e ainda será relevante na próxima semana ("usamos pnpm", "o módulo de faturamento permanece intocado")
• o usuário corrigiu o agente, que é o sinal mais forte que existe
• uma abordagem falhou, e o motivo pelo qual falhou
• uma preferência foi declarada que se aplica além desta tarefa
• um fato sobre o ambiente foi descoberto da maneira mais difícil (uma porta, um sinalizador, um serviço que deve estar em execução)

Não salve: o conteúdo de arquivos que podem ser lidos novamente, reafirmações da tarefa atual, estado transitório, qualquer coisa que o usuário marcou como temporária e qualquer coisa que contenha segredos, tokens ou dados pessoais.

Uma memória, um fato. Um parágrafo contendo quatro decisões não pode ser substituído de forma limpa quando uma delas muda.

Passo 3: Escreva de Forma Que Sobreviva

Uma memória que é inútil em três semanas foi escrita incorretamente. Dê a cada entrada, no texto se o backend não tiver campos para isso:

• o que foi decidido ou observado, em uma frase
• por quê, brevemente, porque a razão sobrevive à decisão
• quando se tornou verdade e quando deixou de ser verdade, se for o caso
• de onde veio: um arquivo, um commit, uma conversa, uma execução de teste

Prefira as palavras do próprio usuário a um resumo. O resumo se desvia.

Passo 4: Feche o Passado em Vez de Sobrescrevê-lo

Quando algo muda, a memória antiga não está errada. Ela está fechada.

Se o projeto mudou de Redux para Zustand, "usamos Redux" foi verdade de janeiro a junho. Excluí-la destrói a explicação para cada componente escrito nessa janela. Marque-a como substituída, mantenha sua janela de validade e escreva a nova ao lado.

Este é o hábito mais destrutivo na memória do agente e permanece invisível até que alguém faça uma pergunta sobre código antigo.

Passo 5: Mantenha as Contradições Visíveis

…