Resumo Técnico: projectmem

Declaração do Problema

Assistentes de codificação por IA, embora poderosos dentro de uma única sessão, sofrem de uma falha arquitetural crítica: eles são sem estado (stateless) entre sessões. Quando uma janela de conversa é fechada, o agente perde o estado durável específico do projeto. Consequentemente, sessões subsequentes frequentemente exigem que o agente releia arquivos de origem, refaça perguntas já respondidas anteriormente e, de forma mais custo-efetiva, tente novamente correções que já falharam.

Isso é identificado não como um problema de qualidade do modelo, mas como um problema de arquitetura. Reconstruir o contexto através da releitura de um projeto consome um estimado de 5.000 a 20.000 tokens por sessão. Além disso, as soluções de memória existentes frequentemente dependem de bancos de dados vetoriais ou extração de fatos com o LLM no loop (LLM-in-the-loop), introduzindo não-determinismo, custos recorrentes de leitura e uma falta de privacidade local-primeiro (local-first). Crucialmente, os sistemas atuais atuam primariamente como "Memória-como-Ferramenta" passiva (respondendo consultas) em vez de "Memória-como-Governança" ativa (intervindo antes de uma ação para evitar falhas conhecidas).

Metodologia e Design do Sistema

O artigo apresenta o projectmem, uma camada de memória e julgamento local-primeiro e de código aberto para agentes de codificação de IA. O sistema é construído sobre quatro princípios fundamentais de design:

1. Imutabilidade: A memória é um log de eventos de adição exclusiva (append-only), nunca editada no lugar, criando uma trilha de auditoria reproduzível.
2. Legibilidade Humana: O log é texto puro (JSON Lines + Markdown), tornando-o pesquisável via grep, comparável via diff e controlável via versão através de Git.
3. Localidade: Todo o estado reside no repositório e na máquina local, sem dependência de rede ou telemetria.
4. Determinismo: Sumários e portões de julgamento são projeções puras do log, não saídas geradas por LLM.

Componentes Principais

• Substrato Baseado em Eventos: O desenvolvimento é registrado como eventos tipados: issue (problema), attempt (tentativa — com resultados: funcionou/falhou/parcial), fix (correção), decision (decisão) e note (nota). Estes são anexados ao events.jsonl.
• Projeção Determinística: Um arquivo de sumário (summary.md) é regenerado deterministicamente a partir do log de eventos. Isso garante que o agente leia um estado derivado consistente que não pode divergir do histórico subjacente.
• Camada de Julgamento (Memória-como-Governança): O sistema introduz um portão de pré-ação determinístico. Antes de um agente tocar em um arquivo, a função precheck_file(path) consulta o log de eventos em busca de tentativas falhas, problemas abertos ou alta rotatividade associada àquele caminho. Ela retorna um aviso (ex: "você tentou isso há 2 dias — falhou") sem fazer uma chamada de LLM.
• Memória Entre Projetos: Lições aprendidas em um projeto (ex: peculiaridades específicas de uma biblioteca) são filtradas e promovidas para um armazenamento global de máquina única (~/.projectmem/global). Elas são automaticamente apresentadas em outros projetos que utilizam a mesma pilha, indexadas por manifestos de biblioteca (ex: package.json, pyproject.toml).
• Integração MCP: O sistema roda como um servidor nativo do Protocolo de Contexto de Modelo (MCP), expondo 14 ferramentas tipadas (9 de leitura, 5 de escrita) para qualquer cliente compatível com MCP (ex: Cursor, Claude). Também inclui uma ponte de Markdown para ferramentas não-MCP.
• Segurança: A redação de segredos está ativada por padrão, limpando tokens e chaves do texto dos eventos antes de serem escritos no log.

Principais Contribções

O artigo descreve quatro contribuições principais:

1. Substrato de Memória Baseado em Eventos: Um log de texto puro e de adição exclusiva de eventos tipados que substitui bancos de dados vetoriais, permitindo a projeção determinística de sumários compactos e legíveis para IA.
2. Camada de Julgamento: Um portão de pré-ação determinístico derivado do histórico que avisa os agentes antes de repetirem correções falhas ou editarem arquivos frágeis, operacionalizando o conceito de "Memória-como-Governança".
3. Sistema Local-Primeiro e Agnóstico a Ferramentas: Um servidor MCP nativo e uma ponte de Markdown universal que roda totalmente offline com redação de segredos ativada por padrão.
4. Implementação e Avaliação: Um pacote Python de três dependências (14 ferramentas MCP, 19 comandos CLI, 37 testes automatizados) avaliado através de um autoestudo de dois meses.

Resultados e Avaliação

Os autores avaliaram o projectmem através de análise de custo de tokens e um autoestudo em 10 projetos do mundo real (ML, aplicações web, código de pesquisa) durante dois meses (30 de março – 29 de maio de 2026).

• Redução de Custo de Tokens: Em modo MCP, o agente carrega aproximadamente 800–1.500 tokens por sessão via get_summary(), comparado a um estimado de 5.000–20.000 tokens necessários para reconstruir o contexto sem uma camada de memória. Isso representa uma redução estimada de mais de 50% no uso de tokens por sessão.
• Dados do Autoestudo: O sistema acumulou 207 eventos reais em 10 projetos. A composição dos eventos foi dominada por notas e decisões duráveis (61%), seguidas por correções (25%), tentativas (5%), problemas (5%) e decisões (4%).
• Acúmulo de Memória: Ao contrário de agentes sem estado que resetam para zero a cada sessão, a memória do projectmem se acumula monotonicamente, preservando os triplos "problema/tentativa/correção" e as decisões arquiteturais que agentes sem estado descartam.
• Compatibilidade: O sistema foi verificado para servir a mesma memória para quatro clientes diferentes compatíveis com MCP sem modificação.
• Auditabilidade: O log imutável serve como uma trilha de proveniência, registrando o que foi alterado, o que foi tentado e o porquê, utilizando ferramentas padrão de controle de versão.

Significância e Alegações

O artigo posiciona o projectmem como um substrato prático para o desenvolvimento de software assistido por IA e auditável. Sua significância reside na mudança do paradigma de "Memória-como-Ferramenta" (recuperação passiva) para "Memória-como-Governança" (intervenção ativa).

Os autores alegam que, ao manter a memória imutável, legível por humanos, offline e agnóstica a ferramentas, o projectmem aborda a "amnésia" dos agentes de IA que leva a falhas repetitivas. Ele fornece um mecanismo determinístico para impedir que um agente repita um erro conhecido antes que a ação ocorra, em vez de aprender com ele depois do fato. O sistema é explicitamente projetado para ser complementar, e não um substituto, para a memória baseada em embeddings onde o objetivo é a recuperação semântica ampla; o projectmem prioriza o determinismo, a legibilidade e o custo zero de modelo em tempo de leitura.

O artigo permanece modesto quanto às suas alegações, observando que as economias de tokens são estimativas de uso e não resultados de benchmarks controlados, e que o portão de julgamento é de natureza consultiva por design para evitar falsos positivos em mudanças novas, mas superficialmente semelhantes e válidas. O trabalho é apresentado como uma contribuição de infraestrutura de código aberto para o campo da engenharia de software agêntica.