Como construí o projectmem — um servidor MCP que dá memória persistente ao Claude, Cursor e Codex

Há alguns meses, meu agente de codificação AI sugeriu essa correção com confiança:

.header-preview {
    contain: layout;
}

Eu havia tentado exatamente isso na sexta-feira anterior. Não funcionou. O agente não tinha memória da falha — conversa diferente, contexto novo, mesmo beco sem saída.

Isso acontece toda segunda-feira. Através de Claude, Cursor, Codex, Antigravity — os agentes são sem estado entre as sessões. Cada nova conversa paga de 5.000 a 20.000 tokens para reconstruir o contexto que existia ontem. O modelo não está quebrado; a arquitetura está.

Então eu construí projectmem. Este post explica o que ele realmente faz — cinco recursos incríveis, um painel D3 de quatro visualizações, a arquitetura e o bug do hook conda/venv que quase lançou a versão v0.1.3 quebrada. É open source, MIT, roda 100% local, é enviado como um único pip install.

O que é o projectmem, em 60 segundos

Um pequeno pacote Python que faz três coisas:

1. Captura eventos de desenvolvimento — bugs, tentativas de correção, correções, decisões, armadilhas — em JSONL de texto simples dentro do seu repositório (.projectmem/events.jsonl). Você o comita. Você pode git diff isso.

2. Expõe 14 ferramentas MCP para que qualquer cliente AI compatível com MCP (Claude Desktop, Claude Code, Cursor, Antigravity, Codex) leia e escreva essa memória diretamente. Um bloco de configuração por cliente, funciona em todos eles.

3. Executa hooks do git que avisam você no momento do commit antes de repetir uma abordagem falha registrada.
   

pip install projectmem
pjm init

Essa é a instalação. pjm init escreve o diretório de memória, cria um arquivo de ponte CLAUDE.md, instala os hooks do git, pré-popula PROJECT_MAP.md a partir dos seus manifests de stack e imprime um bloco de configuração de cliente MCP pronto para colar. Sem nuvem, sem daemon, sem telemetria.

Os cinco recursos incríveis

1. Avisos pré-commit (o diferencial)

O hook pré-commit do git verifica seu arquivo em estágio contra a memória. Se houver uma abordagem falha registrada nesse arquivo, ele avisa você antes que o commit seja realizado.

projectmem: Verificação Pré-Commit
────────────────────────────────────────────────────────────

  styles.css
    AVISO  1 tentativa falha neste arquivo
           Última falha: tentou contain: layout — a pré-visualização ainda salta
             (há 3 dias)

────────────────────────────────────────────────────────────
1 aviso(s). Revise antes de commitar.

A maioria das ferramentas de "memória AI" são motores de recuperação — elas armazenam conversas e as apresentam quando solicitadas. O projectmem é uma camada de julgamento — captura eventos com resultados explícitos (funcionou / falhou / parcial) e usa o contexto do git para interromper você antes de desperdiçar outra tarde. O hook pré-commit é a chave.

2. Memória entre projetos

Lições em um repositório automaticamente aparecem em outros na mesma stack. Armadilhas de biblioteca, decisões de framework, padrões que você só teve que aprender uma vez.

~/.projectmem/global/
├── library_gotchas.jsonl
├── patterns.jsonl
└── .promotable.json    ← cache auto-curado

Quando você pjm init um novo projeto, o projectmem detecta sua stack a partir de pyproject.toml / package.json / Cargo.toml / go.mod e injeta armadilhas relevantes entre projetos em AI_INSTRUCTIONS.md. Filtragem consciente da stack, para que uma menção de vite em um projeto não polua as armadilhas do Next.js em seus repositórios Next.js reais.

100% local — ~/.projectmem/global/ permanece na sua máquina. Sem sincronização em nuvem, sem conta, sem telemetria. Uma armadilha de gin que você registra em proj-go aparece em seu próximo repositório Go. Uma armadilha de vite em proj-react aparece em seu próximo repositório React.

3. ROI comprovável (pjm score)

Uma nota de A+ → F respaldada por números concretos. A primeira ferramenta de memória AI com métricas que um CTO pode verificar.

$ pjm score

Pontuação de Prevenção do projectmem: A- (87/100)
  Abordagens falhas registradas: 8
  Decisões documentadas: 14
  Correções com contexto: 12
  Horas de depuração economizadas: ~12h
  Tokens economizados: 47.500
  USD estimados economizados: $4.75

Saída como terminal, JSON para CI (pjm score --format json), ou um badge shields.io para seu README. Permite que você coloque um número no valor que a camada de memória está realmente produzindo — em vez de uma afirmação de marketing.

4. Injeção de contexto inteligente (pjm wrap)

Lança seu agente AI com um bloco de contexto orçado em tokens já carregado — para que o agente comece com sua memória de projeto herdada, em vez de em branco.

$ pjm wrap claude --tokens 2000
# lança Claude com um bloco de contexto de 2000 tokens de:
# - seu resumo de projeto
# - decisões recentes
# - armadilhas relevantes entre projetos
# - quaisquer abordagens falhas em arquivos que você provavelmente tocará

Funciona com Claude Code, Cursor (escreve em .cursorrules), Aider e colagem de área de transferência para todo o resto. A sessão AI começa experiente, não do zero.

5. Monitor de arquivos em tempo real (pjm watch)

Inicia automaticamente em pjm init em terminais interativos. Detecta edições rápidas no mesmo arquivo (sessões de depuração) e registra eventos de churn automaticamente. Consciente da bateria, consciente do gitignore. Captura o que a AI silenciosamente perde — a iteração entre commits onde a maior parte da depuração real acontece.

$ pjm watch --status
monitor do projectmem: ativo (PID 47891)
  Monitorando: /Users/me/repos/seu-projeto
  Eventos capturados hoje: 12 churn, 3 commit
  Bateria: energia AC (velocidade total)

A visualização: quatro painéis D3 a partir de um comando

Esta é a parte que eu acho que a maioria dos projetos ignora e não deveria.

$ pjm visualize
# abre localhost:8765 no seu navegador

Você obtém um painel interativo D3 com quatro visualizações, todas auto-geradas a partir da sua memória — zero tokens AI extras.

Mapa da História

A narrativa completa do seu projeto — cada decisão, marco e falha visualizados como um gráfico interativo direcionado por força. Arquivos falhados brilham em vermelho no mapa de calor. Arraste os nós. Aproxime-se de áreas problemáticas. Sua AI lê isso para entender não apenas o que seu projeto é, mas como chegou aqui.

Painel de ROI

Visualização ao vivo de quanto proj