Toda sessão nova com um assistente de IA começa com o mesmo ritual: explicar de novo o projeto, as decisões já tomadas, as preferências já combinadas. No post sobre agentes fora do laboratório listei o contexto que evapora como um dos quatro furos clássicos. Entre uma sessão e outra, o furo vira regra: evapora tudo. A solução que uso todos os dias neste blog não é plataforma nova nem banco vetorial: é um arquivo Markdown versionado no git.

O recomeço custa mais do que parece

O custo visível é o tempo de reexplicar. O custo invisível é pior: lição paga uma vez volta a ser cobrada. Um exemplo real daqui: “imagem antiga depois de publicar quase sempre é cache do navegador, não defeito”. Essa lição custou uma caçada a um bug que não existia. Sem memória, cada sessão nova teria repetido a caçada — com memória, virou uma linha que o assistente lê antes de começar, e o falso defeito morreu ali.

O mesmo vale para decisões. Uma escolha discutida e fechada num dia reaparece como pergunta aberta na semana seguinte, porque quem perguntou esqueceu que já tinha resposta. Decisão rediscutida sem necessidade não é só desperdício: é risco de decidir diferente sem perceber.

Um arquivo Markdown, versionado junto do projeto

A implementação cabe numa frase: um arquivo MEMORIA-PROJETO.md na raiz do repositório, que o assistente lê por inteiro no início de cada sessão e devolve atualizado no fim. Aqui ele está na sétima versão, com data e histórico de cada consolidação no rodapé.

O arquivo guarda quatro tipos de conteúdo, todos curtos e diretos:

  • Preferências — como o dono do projeto gosta que o trabalho seja feito;
  • Lições — o bug resolvido e a causa, a abordagem que falhou, a correção que veio de fora;
  • Convenções — os fluxos e padrões que se repetem;
  • Decisões com motivo — o que foi escolhido e por quê, para não rediscutir do zero.

Versionar junto do projeto muda a natureza da memória. Cada atualização vira um diff revisável, como qualquer mudança de código. A memória deixa de ser uma caixa-preta da ferramenta e passa a ser um artefato do projeto, que qualquer pessoa (ou qualquer assistente) consegue abrir, auditar e corrigir.

O teste dos sete dias decide o que entra

A regra de corte é uma pergunta: esta informação ainda estará válida daqui a uma semana? Se não, ela não pertence à memória. Progresso de tarefa, pendência, próximo passo — tudo isso envelhece em dias e vive em outro arquivo, um controle de estado próprio, atualizado a cada avanço.

A separação parece burocracia e é o contrário: é o que mantém o arquivo vivo. Misturar os dois soterra as lições permanentes debaixo de status que apodrece. O arquivo de memória que vira depósito de tudo deixa de ser lido — e memória que não é lida não é memória.

Fato declarativo, nunca ordem para o futuro

A forma de escrever cada item importa mais do que parece. Registrar “o dono prefere respostas curtas” funciona; registrar “responda sempre curto” quebra. A diferença: a ordem imperativa é reexecutada em toda sessão futura sem o contexto em que fez sentido, inclusive nos dias em que a resposta precisava ser longa.

Fato declarativo é contexto; ordem gravada é comando cego. E disso sai a regra de conflito: quando a instrução de agora contradiz o que está gravado, vale a instrução de agora — e o conflito se declara em voz alta, nunca se resolve em silêncio. Memória orienta; quem manda é o presente.

O que nunca entra no arquivo

Segredo não entra. Senha, token, chave de API: num arquivo versionado, segredo gravado é segredo vazado. O que se registra é a convenção em volta dele — “as chaves vivem em variáveis de ambiente” — nunca o valor.

E nada entra sozinho. O assistente propõe o que registrar; quem aprova é o dono, e o diff da atualização mostra exatamente o que mudou. É o mesmo princípio do gate humano que protege o que este blog publica: o agente dispõe a proposta na mesa, a decisão continua sendo de quem responde por ela.

Onde o arquivo não chega

Os limites são reais e vale declará-los. O método exige disciplina de consolidação: sem o ritual de atualizar no fim da sessão, o arquivo congela e mente. Ele cresce, e precisa de poda periódica para continuar legível. E ele é contexto de um projeto — não substitui busca semântica em base de conhecimento grande, nem resolve memória compartilhada de uma equipe inteira.

As plataformas de IA tendem a oferecer memória automática própria, e ela ajuda. O arquivo manual mantém duas vantagens que nenhuma delas entrega: é inspecionável (dá para ler exatamente o que a ferramenta “sabe” e corrigir o que estiver errado) e é portável (a memória pertence ao projeto, não ao fornecedor — trocar de ferramenta não apaga o que se aprendeu).

Para começar hoje

  1. Crie um MEMORIA-PROJETO.md na raiz do projeto com três seções: preferências, lições aprendidas, convenções.
  2. Combine o ritual com o assistente: ler o arquivo no início da sessão e confirmar em uma linha.
  3. Durante o trabalho, anote o que passar no teste dos sete dias — e só isso.
  4. No fim da sessão, consolide: mesclar com o que existe (nunca duplicar), datar e incrementar a versão.
  5. Progresso de tarefa vai para um arquivo de estado separado; segredo não vai para nenhum dos dois.

Um modelo maior não resolve o esquecimento entre sessões; um arquivo simples resolve. Memória de projeto não é apenas contexto reaproveitado — é a diferença entre um assistente que trabalha no seu projeto e um que recomeça nele toda manhã.

Fontes

  • Peça baseada em experiência própria: a prática descrita está em uso neste blog, com o arquivo de memória do projeto na sétima versão na data de publicação (verificado em 2026-07-27). Nenhum número ou alegação de terceiros foi citado.