Projectmem

🎉 v0.3.2 foi lançada — Suporte para Windows no observador de arquivos, e um doctor que percebe quando uma correção é desfeita. Veja o que mudou →

Não deixamos a IA mais inteligente. Nós a tornamos experiente.

Memória para agentes de codificação — a camada de memória e julgamento local-first para agentes de codificação de IA. Um servidor MCP para cada projeto. Economize até 50%+ dos tokens de IA. Pare de repetir o bug de ontem.

Site • Guia • Demonstração • Changelog • Artigo

_{pjm visualize — cada caso que seu projeto resolveu, o que falhou no caminho e o que ele economizou. Gerado localmente a partir de .projectmem/events.jsonl.}

🚀 Comece aqui — cinco minutos, uma vez

Cinco minutos se você seguir este guia. Prefere que mostremos — cada comando, a saída exata que ele imprime e os dashboards no final? Siga o guia de configuração completo.

Novo no projectmem, ou atualizando de 0.1.x / 0.2.x? Desde 0.3.0, um único servidor MCP atende a todos os projetos, então esta é a última vez que você configura algo.

1. Instale ou atualize

pip install -U projectmem

2. Encontre os projetos que você já tem

pjm doctor

Ele procura onde o código mora — ~/Developer, ~/code, ~/projects, suas pastas na nuvem e cada unidade no Windows — e lista projetos com memória que ainda não estão registrados. Qualquer coisa que ele perdeu, adicione manualmente:

pjm project register "/Users/you/Developer/repos/ossdrop"

3. Registre-os

pjm doctor --fix

4. Aponte sua IA para todos eles com uma única configuração

"mcpServers": {
  "projectmem": {
    "command": "/absolute/path/to/python",
    "args": ["-m", "projectmem.mcp_server"]
  }
}

Sem --root, sem cwd — é isso que faz ele atender a tudo. Instruções por cliente (Claude Desktop, Claude Code, Cursor, Antigravity, Codex) estão em Integração MCP; pjm init imprime este bloco com o caminho do seu próprio Python preenchido. Em seguida, reinicie completamente o cliente — servidores MCP só carregam em uma inicialização a frio.

5. Verifique seu trabalho

pjm doctor

Adicione --online se você também quiser que ele avise quando houver uma versão mais nova do projectmem — o projectmem não faz chamadas de rede de outra forma, e --auto transforma isso em uma verificação diária, se você preferir.

Execute novamente após editar a configuração. Ele sinaliza qualquer cliente ainda preso a um único repositório — o motivo mais comum para um novo projeto ficar invisível para seu agente.

Tudo verde? Você terminou. Daqui em diante é um comando por repositório:

pjm init

Seu agente lê o que o projeto já aprendeu em vez de redescobrir, e registra o que encontra. Menos tokens, sem becos sem saída repetidos, memória que sobrevive à sessão.

O que é memória para agentes de codificação?

Memória para agentes de codificação é um registro persistente do que aconteceu durante a construção de um projeto — os problemas encontrados, as abordagens tentadas, as correções que funcionaram e as decisões tomadas — armazenado para que um agente de codificação de IA possa lê-lo no início de uma nova sessão. Sem ela, toda sessão começa do zero.

projectmem é uma camada de memória de agente open-source construída para essa função. Ela é local-first: a memória vive em um diretório .projectmem/ simples dentro do seu repositório, sem nuvem, sem conta e sem telemetria — a única chamada de rede que ela pode fazer é uma verificação de atualização que você ativa manualmente. Um servidor MCP nativo expõe 17 ferramentas para Claude Code, Claude Desktop, Cursor, Antigravity e Codex, para que seu agente leia a memória e registre seu trabalho por conta própria.

Diferente de ferramentas de memória baseadas em histórico de chat, o projectmem armazena eventos tipados — problemas, tentativas, correções, decisões, notas — o que possibilita a única coisa que nenhuma outra ferramenta faz: um aviso de pré-commit que dispara antes de você repetir uma abordagem que já falhou.

pip install projectmem
cd your-project && pjm init

🎬 Assista à demonstração

Tutorial completo gravado em tela — assista no YouTube

📚 Documentação

O Problema

Toda nova sessão de IA começa do zero. Claude, Cursor, Aider — todos esquecem as decisões de ontem, repetem tentativas de depuração que falharam e queimam milhões de tokens reconstruindo contexto a partir dos arquivos-fonte brutos.

O modelo não é o problema. A arquitetura é. Modelos sem estado precisam de um córtex de memória.

A Solução

projectmem é a camada de memória e julgamento local-first que fica acima das suas ferramentas de IA. Ela captura cada tentativa falha, decisão e pegadinha — e injeta essa experiência de volta nas futuras sessões de IA. O Git rastreia o que mudou. projectmem rastreia por que mudou, o que foi tentado e o que falhou.

Instalação

Primeira vez aqui? → O guia de configuração completo percorre todo o caminho de ponta a ponta: instalação, conexão com Claude Desktop, Claude Code, Cursor, Codex ou Antigravity, verificação com pjm doctor e leitura da sua memória pelos dashboards — com a saída real do terminal em cada etapa.

Três comandos para um projeto que lembra:

pip install projectmem
cd your-project
pjm init

É isso. pjm init instala três hooks do git (avisos de pré-commit, classificação de pós-commit, rastreamento de pós-merge), inicia automaticamente um observador de arquivos em tempo real, herda memória entre projetos se disponível e cria .projectmem/. A captura está ativa desde o primeiro minuto.

O comando canônico é projectmem. Um alias pjm é instalado para agilizar.

✨ Novo na 0.3.2 — Windows, de verdade

pjm watch --daemon travava no Windows com AttributeError: module 'os' has no attribute 'fork'. Agora ele inicia um worker destacado em vez de fazer fork, então o monitoramento em segundo plano funciona em todas as plataformas.

Corrigir isso revelou um segundo bug escondido atrás dele. A vivacidade era verificada com os.kill(pid, 0) — um idioma POSIX que não é portável, porque no Windows os.kill roteia para TerminateProcess e o sinal 0 não é uma verificação. O observador não podia ser visto ou interrompido lá, e cada pjm watch --daemon vazava outro processo. Ambos foram corrigidos.

O suporte a daemon no Windows foi contribuído por @medium-effort (#13).

pjm doctor também ganhou duas coisas. Agora ele avisa para sair do seu cliente de IA antes de editar a configuração dele — esses arquivos também guardam as preferências do próprio app, então um cliente em execução pode reescrever tudo ao sair e restaurar o --root que você acabou de remover. E ele lembra o que viu da última vez, então uma configuração que estava limpa e foi fixada novamente é apontada como uma reversão, em vez de parecer que o doctor está instável. Apenas arquivos locais; nada sai da sua máquina.

✨ Novo na 0.3.1 — saiba quando atualizar

Ambos os dashboards agora mostram qual versão gerou a página, com um link de verificar atualizações ao lado. A página não faz nenhuma requisição até você clicar — o JSON público do PyPI é buscado direto do seu navegador e nada sobre sua máquina é enviado. Na linha de comando, pjm doctor --online verifica uma vez e pjm doctor --auto lembra de verificar diariamente; ambos estão desativados a menos que você peça.

✨ Novo na 0.3.0 — um servidor, muitos projetos

Até agora, uma configuração MCP estava ligada a um repositório: onze projetos significavam onze entradas de servidor e onze reinicializações. 0.3.0 atende a todos os projetos registrados a partir de um único servidor. Cole a configuração uma vez; todo repositório que você pjm init depois fica acessível a partir dele.

pjm project list          # what this server can reach
pjm project use ossdrop   # the default when a call names no project

log_issue(summary="stars come back empty", project="ossdrop")
→ Logged issue #0019 → ossdrop: stars come back empty

Toda escrita nomeia o projeto em que caiu — em um servidor compartilhado, a falha perigosa não é "nada funciona", é uma escrita que tem sucesso contra o repositório errado. Configurações --root existentes continuam funcionando sem alterações, e um servidor fixado agora recusa escrever em qualquer outro lugar, mesmo quando solicitado.

Também na 0.3.0:

• Corrigido: o servidor MCP estava quebrado em instalações novas. mcp 2.0 renomeou FastMCP e deixou o caminho de importação antigo gerando erro — desde 2026-07-28, todo novo pip install projectmem recebia um servidor que morria na importação. Detectado e corrigido por @VIVAAN-DHAWAN.
• Segurança: XSS armazenado em pjm visualize. Resumos de eventos chegavam ao DOM sem escape, e mensagens de commit do git se tornam resumos de eventos — então um commit malicioso em um branch que você puxou poderia executar script no seu dashboard. Todos os sinks agora têm escape.
• Um dashboard reconstruído — um Memory Card compartilhável, arquivos de caso com a cadeia completa problema → tentativa → correção, um treemap de esforço, dossiês por arquivo e uma visão global que abre de onde você parou.

A migração do registro é automática: a lista de caminhos 0.2.x é convertida na primeira leitura, com um .bak mantido ao lado.

✨ Novo na 0.2.0 — a versão do workspace

0.1.6 tornou a memória de um projeto algo que você podia observar. 0.2.0 eleva isso para todo o seu workspace — e fecha a lacuna entre o que aconteceu (memória) e o que seu código é (estrutura).

• 🌐 Painel global — pjm dashboard é uma página sobre todos os projetos que você já pjm init-ou: total de problemas capturados, correções confirmadas, becos sem saída evitados, tokens economizados, uma nota por projeto e uma lista de "precisa de atenção". Clique em qualquer cartão para abrir o painel daquele repositório, gerado na hora. É uma visão global, não um armazenamento global — o .projectmem/ de cada repositório é agregado no momento da leitura e nunca sai da sua pasta. O padrão é serverless (um snapshot estático); adicione --serve para um pequeno servidor ao vivo e efêmero, onde o botão Atualizar relê seus arquivos — sem daemon em segundo plano, Ctrl+C interrompe.
• 🧬 Estrutura e relações — pjm map --build (executado automaticamente no pjm init) percorre seu código e, para Python, resolve imports em um grafo de dependências real. As visualizações Graph e Flow do Project Map agora renderizam arquivos reais e as arestas de import entre eles. O cache (structure.json) é derivado do código, ignorado pelo git e nunca commitado — o código é apenas lido.
• 🔥 Calor de falhas na estrutura (a combinação) — a única visualização que um grafo de código puro não consegue desenhar e uma ferramenta de memória pura também não: arquivos com tentativas falhas repetidas brilham em vermelho, sobrepostos diretamente ao grafo de imports real. A estrutura vem do código, o calor vem da sua memória, e eles se encontram apenas no renderizador.
• 🗂️ plan.md — um novo arquivo de intenção editável: ideias e planos, o que você pretende fazer — deliberadamente não o log de eventos. events.jsonl → summary.md registra o que aconteceu; plan.md registra o que você pretende. A IA lê no início da sessão e edita diretamente; um plano nunca vira um evento. pjm plan / pjm plan "idea" / MCP get_plan().

Tudo permanece 100% local — o painel global é um agregado em tempo de leitura, nunca um honeypot central do histórico do seu código.

Painel Global — todos os projetos pjm init-ados em uma visão: notas, problemas, economias e uma lista de "precisa de atenção", agregados no momento da leitura. Cada cartão abre o painel daquele repositório.

O conjunto de visualizações (lançado na 0.1.6)

A memória do seu projeto também é algo que você pode assistir — e compartilhar.

• 🎬 Showoff — uma aba do painel com três cenas de história animadas, todas renderizadas a partir do seu log de eventos real: Story Replay (assista o histórico do seu projeto se construir, nó por nó), Orbit (arquivos orbitam o projeto, eventos orbitam seus arquivos) e Universe (seu projeto como uma galáxia rotativa — cada estrela brilhante é um problema, tentativa, correção ou decisão real; clique em uma para ver os detalhes completos).
• ⏺ Gravador integrado — pressione REC (10–60 s) e o Showoff baixa um clipe .webm da animação, renderizado 100% localmente com um selo "feito com projectmem". Sua história de depuração, pronta para um tweet ou uma reunião diária.
• 🗺️ Flow — a visualização padrão do Project Map: um fluxograma em camadas que lê PROJECT → DIRECTORIES → FILES → WHAT HAPPENED → MEMORY. Arquivos com falhas repetidas brilham em vermelho ao longo do caminho, cada arquivo mostra seus selos de resultado, e tudo flui para o cilindro events.jsonl. As visualizações Tree e Graph estão a um clique de distância.
• 🧵 Time Spine — a visualização padrão da Timeline: um eixo em tempo real que você rola, com problemas ramificando à esquerda (problemas, tentativas falhas) e conhecimento ramificando à direita (correções, decisões, notas). Passe o mouse sobre qualquer cartão e toda a linha de problemas dele acende. A lista clássica permanece como "Details".

Showoff · Universe — cada estrela brilhante é um evento real da memória deste projeto

Project Map · Flow — o que aconteceu, arquivo por arquivo, fluindo para a memória append-only

Timeline · Time Spine — problemas à esquerda, conhecimento à direita, tempo real no meio

Por Que Você Vai Amar

• Avisos Pré-Commit — pjm precheck avisa antes de você commitar se estiver prestes a repetir uma abordagem que falhou, modificar um arquivo de alta rotatividade ou tocar em um problema não resolvido. Nenhuma outra ferramenta de IA faz isso — exige a camada de memória por baixo. O aviso agora lista os becos sem saída em si ("O que já falhou aqui: ✗ tentou CSS contain:layout"), e pjm precheck --snooze 2h silencia educadamente — o adiamento em si é registrado, então até o silêncio é auditado.
• Detecção de Memória Obsoleta (novo na 0.1.4) — outras ferramentas de memória decaem ou excluem memórias antigas silenciosamente; o projectmem nunca exclui. Cada decisão que cita um arquivo é verificada contra o histórico git desse arquivo — quando o arquivo evoluiu, a memória é sinalizada ("predata 7 commits em auth.py — confirme ou substitua") e um humano decide. Aposente-a limpo com pjm decision "new way" --supersedes <id>: o evento antigo permanece no log, marcado, para sempre.
• Briefing de Início de Sessão (novo na 0.1.4) — pjm brief responde "onde eu estava?" em uma tela: avisos ativos, memórias possivelmente obsoletas, problemas abertos, decisões recentes, pegadinhas de stack e sua pontuação de prevenção com variação semana a semana.
• Memória para agentes sem MCP (novo na 0.1.4) — pjm export --claude-md compila decisões ao vivo, pegadinhas e uma lista "NÃO tente novamente — estes já falharam" em um bloco marcado no CLAUDE.md (ou .cursorrules). Copilot, Claude simples, qualquer agente que leia o arquivo herda o julgamento do seu projeto.
• Injeção Inteligente de Contexto — pjm wrap claude (ou cursor/aider) injeta um bloco de memória com orçamento de tokens na sua IA antes da sessão abrir. Sua IA começa experiente, não em branco.
• Pontuação de ROI Comprovada — pjm score gera uma nota em letras (A+ → F) respaldada por números concretos — horas de depuração economizadas, tokens evitados, dólares protegidos. Saída JSON compatível com CI e selo shields.io para seu README.
• Memória Entre Projetos — Lições aprendidas em um repositório seguem você para sempre. Pegadinhas de bibliotecas, decisões e padrões vivem em ~/.projectmem/global/ e são herdados automaticamente em todo novo projeto que corresponda ao seu stack.
• Observador de Arquivos em Tempo Real — Daemon em segundo plano detecta edições rápidas no mesmo arquivo (sessões de depuração) entre commits. Consciente de bateria, consciente de gitignore, iniciado automaticamente por pjm init.
• Servidor MCP Nativo — Conecta-se ao Claude Desktop, Cursor, Antigravity, Codex e qualquer ferramenta compatível com MCP. 15 ferramentas nativas forçam a IA a ler contexto, verificar arquivos por falhas conhecidas, ler seu plan.md e registrar trabalho automaticamente. Verificado de ponta a ponta contra todos os quatro clientes.
• Painel Interativo (expandido na 0.1.6) — pjm visualize abre um painel local de seis abas: Overview, Story Map (mapa de calor de falhas com controles de recolher/focar), ROI Dashboard, Project Map (Flow / Tree / Graph, agora sobre sua estrutura de código real), Timeline (Time Spine / Details) e Showoff — cenas de história animadas com um gravador de vídeo integrado.
• Um servidor MCP para cada projeto (novo na 0.3.0) — configure seu cliente uma vez em vez de uma vez por repositório. Chamadas nomeiam seu projeto (project="ossdrop"), ou recorrem ao ativo; cada escrita relata em qual repositório caiu, e um servidor --root fixado se recusa a escrever fora do seu próprio. Configurações existentes de projeto único não são afetadas.
• Painel Global (novo na 0.2.0) — pjm dashboard é uma visão entre projetos sobre todos os repositórios que você já pjm init-ou: notas, problemas, economias e detalhamento por projeto. Uma visão global, nunca um armazenamento global — a memória de cada repositório é agregada no momento da leitura e nunca sai da sua pasta. Serverless por padrão; --serve para um servidor ao vivo efêmero (Ctrl+C para parar).
• Estrutura de Código + Julgamento (novo na 0.2.0) — pjm map --build lê seu código em um grafo de imports real, e o Project Map sobrepõe calor de falhas do seu log de eventos por cima: os arquivos que continuam quebrando, brilhando em vermelho sobre a estrutura que realmente os conecta. O cache de estrutura é derivado do código e ignorado pelo git — nunca commitado.
• Intenção, separada da memória (novo na 0.2.0) — plan.md guarda ideias e planos (o que você pretende fazer), mantidos deliberadamente separados do log de eventos append-only (o que aconteceu). pjm plan, ou o MCP get_plan(); a IA edita diretamente e um plano nunca vira um evento.
• 100% Local — Sem nuvem, sem telemetria, sem contas. Seu código, sua memória, sua máquina.

Como Se Compara

_{✅ sim · 🟡 parcial · ❌ não — snapshot de junho de 2026; capacidades de design, não resultados de benchmark. claude-mem executa um worker em segundo plano (porta 37777) e ativa telemetria por padrão (v13.5+); agentmemory rebaixa e poda memórias antigas via decaimento, mem0 reescreve fatos na atualização, os blocos de memória da Letta se auto-editam no lugar — o projectmem nunca exclui: sinaliza obsolescência e deixa você decidir. A Letta exige um servidor em execução (Postgres ou nuvem).}

_{† Não há banco de dados e nada que você precise manter em execução: o servidor MCP é um subprocesso stdio que seu cliente de IA inicia, e todo o resto são arquivos simples. O único servidor em qualquer lugar é o opcional pjm dashboard --serve, um visualizador local efêmero que você inicia e para com Ctrl+C — nunca um serviço em segundo plano.}

🚧 Próximos Passos

• Importe sua memória existente — pjm import (planejado para 0.3.3) migrará histórico de mem0, agentmemory, Letta e logs de sessão do Claude para o projectmem. Ele mapeia apenas para o vocabulário central de eventos — problemas, tentativas, correções, decisões, notas — para que o sinal entre e a bagunça de outra ferramenta fique de fora. Seu histórico de julgamento se move com você.

Quer uma fonte suportada? Abra um problema e conte-nos de onde você está migrando.

Como a IA Lê Sua Memória (Eficiência de Tokens)

A arquitetura é construída em torno de uma regra: a IA lê arquivos pequenos e destilados. Ferramentas os geram a partir do log bruto grande.

A IA nunca lê events.jsonl diretamente. Esse arquivo é para ferramentas (pjm score, pjm context, pjm wrap). Ferramentas destilam o log bruto em resumos compactos legíveis por IA.

Um servidor, muitos projetos

Desde 0.3.0, um único servidor MCP atende a todos os projetos que você registrou. Cole a configuração uma vez e todo repositório que você pjm init depois disso fica acessível a partir dele — sem segunda entrada, sem reinicialização.

pjm project list          # what this server can reach
pjm project use ossdrop   # the default when a call names no project
pjm project alias ossdrop od

Seu agente escolhe o projeto por chamada:

log_issue(summary="stars come back empty", project="ossdrop")
→ Logged issue #0019 → ossdrop: stars come back empty

Toda escrita diz onde ela foi parar. Esse eco é o ponto: em uma configuração de projeto único, um servidor mal configurado simplesmente falha, mas um servidor compartilhado pode ter sucesso contra o repositório errado, o que corrompe duas trilhas de auditoria de uma vez. Se o nome na resposta não for o projeto que você pretendia, pare.

Como uma chamada é roteada, da maior prioridade para a menor:

As raízes do cliente superam o projeto ativo de propósito: a raiz é onde você está agora, o projeto ativo é um modo que você definiu dias atrás. Quando eles discordam, o desatualizado é a resposta errada.

Configurações de repositório único não são afetadas — pjm init --mcp-config-single ainda imprime a configuração fixada, e uma entrada --root existente continua funcionando exatamente como antes.

Integração MCP (Recomendada)

Para: Claude Desktop, Cursor, Antigravity, Codex — e qualquer ferramenta com suporte nativo a MCP. O servidor MCP força a IA a ler a memória e registrar cada ação automaticamente.

Desde 0.3.0 você configura isso uma vez, não uma vez por repositório. O bloco abaixo não tem --root: o servidor atende a todos os projetos que você registrou, e cada chamada resolve o seu próprio. Cole e todo repositório que você pjm init a partir de então fica acessível — sem segunda entrada, sem reinicialização.

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": ["-m", "projectmem.mcp_server"]
  }
}

Atualizando com projetos que você já tem? O registro só gravou projetos em que você executou pjm init desde que ele existiu (0.2.0), então qualquer coisa mais antiga está faltando — e o modo global roteia pelo registro. Um comando resolve isso:

pjm doctor          # what's unregistered, what's stale, what's still pinned
pjm doctor --fix    # register what it found

Ele procura nos lugares onde o código realmente mora — ~/Developer, ~/code, ~/src, ~/projects e afins, além de cada unidade fixa no Windows, onde os projetos ficam em D:\ e E:\ com tanta frequência quanto sob sua pasta pessoal. Para apontá-lo para algum lugar específico:

pjm doctor --path ~/work --path /Volumes/ssd --fix
pjm project scan D:\ E:\ --depth 3     # the same walk, without the other checks

Nada é escaneado até você executar, e nada é escrito sem --fix. Após uma atualização, a CLI menciona pjm doctor uma vez — uma instalação via wheel não pode executar código, então o primeiro comando que você digita é o único lugar para dizer isso.

Com um projeto registrado, essa é toda a configuração — há apenas um lugar para onde uma chamada pode ir. Com vários, sua IA passa project="<name>", ou você define um padrão com pjm project use <name>. pjm init imprime este bloco com seu próprio caminho do Python já preenchido.

Atualizando da 0.2.x? Sua entrada --root existente continua funcionando exatamente como antes, e um servidor fixado agora se recusa a escrever fora do próprio repositório, mesmo se solicitado. Substitua pelo bloco acima quando quiser um servidor para tudo.

O fluxo de trabalho de 3 minutos (deixe sua IA fazer a configuração)

1. Instale + inicialize. pip install projectmem, depois cd no seu projeto e execute pjm init — ou simplesmente peça à sua IA para executar.
2. Peça à sua IA para configurar o servidor MCP do projectmem para você — ela pode editar o arquivo de configuração do cliente por conta própria. (Ela precisa de permissão para isso: use o modo Auto / aceitar edições, ou aprove a edição do arquivo quando solicitado. A configuração exata por cliente está nas seções abaixo se você preferir colar manualmente.)
3. Reinicie a ferramenta de IA para que o servidor MCP carregue, e então comece sua sessão com este prompt:

Hi — I use projectmem as this project's memory. Before anything else,
call get_instructions(), then get_summary(), then get_project_map() to
load what we already know. As we work, log issues, attempts
(failed/worked), fixes, decisions, and notes with the projectmem tools,
and call precheck_file(path) before you edit a file. Ideas and plans go
in plan.md via get_plan() — never as events.

Estritamente falando, este prompt é opcional — com o servidor MCP instalado corretamente, a IA descobre a memória por conta própria. Mas dizê-lo torna a captura visivelmente mais consistente, então recomendamos.

• Repita para cada projeto: pjm init + o mesmo prompt inicial.
• Voltando depois de fechar a janela? Abra com um lembrete de uma linha — "Lembrete: usamos projectmem como memória aqui." — e toda a configuração continua de onde você parou.

Prefere configurar manualmente? A configuração exata e verificada para cada cliente segue abaixo.

Claude Desktop

Mais fácil — abra a configuração pela interface:

• macOS: menu Claude → Settings… → aba Developer → Servidores MCP locais → Editar Configuração.
• Windows / Linux: mesmo caminho esperado (Settings → Developer → Edit Config) — abra uma issue se sua plataforma for diferente e atualizaremos isto.

Se preferir o caminho bruto do arquivo: ~/Library/Application Support/Claude/claude_desktop_config.json no macOS, %APPDATA%\Claude\claude_desktop_config.json no Windows, ~/.config/Claude/claude_desktop_config.json no Linux (ou $XDG_CONFIG_HOME/Claude/ se você o moveu). pjm init imprime o caminho certo para a máquina em que você o executa.

Cole este bloco:

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": ["-m", "projectmem.mcp_server"]
  }
}

Duas coisas para saber sobre este bloco:

• Use o caminho absoluto para python (ex.: /opt/anaconda3/bin/python, ou execute which python para encontrar o seu). Os subprocessos do Claude Desktop não herdam seu PATH do shell, então "python" puro frequentemente falha.
• Você não precisa mais do campo cwd, e nunca pôde confiar nele. A versão atual do Claude Desktop (com o sistema de workspace Epitaxy / Cowork) ignora silenciosamente cwd — o servidor acaba rodando com cwd=/ e não consegue encontrar .projectmem/. É por isso que versões mais antigas precisavam de --root. O registro substitui isso: o servidor encontra projetos pelo nome, não por onde ele está rodando.

"mcpServers": {
  "projectmem": {
    "command": "/opt/anaconda3/bin/python",
    "args": [
      "-m", "projectmem.mcp_server",
      "--root", "/absolute/path/to/your/project"
    ]
  }
}

Então saia completamente do Claude Desktop (Cmd+Q no Mac) e reabra — servidores MCP só inicializam em inicialização a frio.

Cursor

Duas maneiras de registrar o servidor MCP — escolha a que se encaixa no seu fluxo:

1. Global (recomendado): menu Cursor → Settings… → barra lateral esquerda Ferramentas e MCPs → Servidores MCP instalados → Adicionar MCP personalizado. Cole o JSON abaixo.
2. Por projeto: coloque o JSON em <project-root>/.cursor/mcp.json — só ativo quando aquele projeto está aberto.

{
  "mcpServers": {
    "projectmem": {
      "command": "/opt/anaconda3/bin/python",
      "args": ["-m", "projectmem.mcp_server"]
    }
  }
}

Duas coisas para saber sobre este bloco (mesmas pegadinhas do Claude Desktop):

• Use o caminho absoluto para python (execute which python para encontrar o seu). Os subprocessos do Cursor não herdam de forma confiável seu PATH do shell.
• Não se preocupe com o campo cwd. O Cursor — como o Claude Desktop — o ignora silenciosamente: o servidor acaba rodando com cwd=~. Desde 0.3.0 isso não importa mais, porque os projetos são encontrados pelo nome no registro, e não por onde o servidor roda.

Registrado globalmente, uma entrada cobre todos os projetos. .cursor/mcp.json por projeto ainda funciona se você preferir que o servidor exista apenas quando aquele repositório estiver aberto — adicione "--root", "/absolute/path/to/your/project" a args lá para fixá-lo.

Então saia completamente do Cursor (Cmd+Q no Mac) e reabra. O projectmem também descobre automaticamente .projectmem/ subindo a partir do CWD (como o git faz para .git/), e honra PROJECTMEM_ROOT e um argumento de CLI --root <path>.

Antigravity

O Antigravity (IDE de IA do Google) fala MCP padrão.

Mais fácil — abra a configuração pela interface:

1. Abra a janela Agente (o painel de chat à direita).
2. Clique no botão ⋯ Opções Adicionais no cabeçalho do painel.
3. Escolha Servidores MCP → Gerenciar Servidores MCP → Adicionar novo (ou Editar Configuração).

O arquivo bruto está em ~/.gemini/antigravity/mcp_config.json se você preferir editá-lo diretamente.

Cole este bloco:

{
  "mcpServers": {
    "projectmem": {
      "command": "python",
      "args": ["-m", "projectmem.mcp_server"]
    }
  }
}

O Antigravity honra o campo cwd, então adicionar "cwd": "/absolute/path/to/your/project" funciona — mas isso amarra o servidor àquele repositório. Deixe-o de fora e a mesma entrada atende a todos os projetos registrados.

Então saia completamente do Antigravity (Cmd+Q no Mac) e reabra — servidores MCP só inicializam em inicialização a frio. Todas as 17 ferramentas do projectmem se registram de forma idêntica ao Claude Desktop / Cursor.

Codex

O Codex armazena a configuração MCP como TOML (não JSON) em ~/.codex/config.toml. Há um formulário de interface em Settings → MCP Servers → Add MCP Server, mas durante a verificação entre clientes, o botão Salvar do formulário não persistia de forma confiável — o caminho de edição de arquivo é mais rápido e confiável.

Mais fácil — edite ~/.codex/config.toml diretamente:

Anexe este bloco (preserva qualquer configuração existente):

[mcp_servers.projectmem]
command = "/opt/anaconda3/bin/python"
args = ["-m", "projectmem.mcp_server"]
cwd = "/absolute/path/to/your/project"

Três coisas para saber sobre este bloco:

• Use o caminho absoluto para python (execute which python para encontrar o seu). Os subprocessos do Codex não herdam de forma confiável seu PATH do shell.
• Você não precisa mais de --root ou cwd. Versões anteriores passavam --root como defesa em profundidade (o campo cwd parece funcionar no Codex, ao contrário do Claude Desktop e do Cursor). Desde 0.3.0 o registro torna ambos desnecessários — adicione "--root", "/absolute/path/to/your/project" a args apenas se quiser este servidor bloqueado a um único repositório.
• Defina seu esforço de raciocínio para medium ou superior. Com raciocínio baixo, o Codex pula get_instructions do trio de início de sessão, o que pode fazer a IA perder as regras do fluxo de trabalho do Modo de Configuração. Médio+ honra o trio completo automaticamente.

Valide o TOML:

python -c "import tomllib; tomllib.load(open('/Users/<you>/.codex/config.toml','rb')); print('OK')"

Deve imprimir OK. Se não, o parser informa a linha problemática.

Então saia completamente do Codex (Cmd+Q no Mac) e reabra. A mesma regra de inicialização a frio de todos os outros clientes MCP. Os servidores MCP do Codex são iniciados preguiçosamente na primeira chamada de ferramenta em uma sessão de chat — se você não vir o processo em ps aux logo após reabrir, envie qualquer mensagem para um chat do Codex e verifique novamente.

Nota sobre esforço de raciocínio: O seletor de modo do Codex está na parte inferior da entrada de chat. Defina-o para medium (não low) para o comportamento completo do trio de início de sessão. Uma vez definido, ele persiste por sessão.

Prompts de permissão no primeiro uso

No primeiro uso em qualquer cliente compatível com MCP (Claude Desktop, Cursor, Antigravity, Codex), sua IA pedirá permissão antes de cada chamada de ferramenta do projectmem. Isso é comportamento de segurança esperado — clientes MCP exigem consentimento explícito para cada nova ferramenta. Aprove cada ferramenta uma vez e o prompt não reaparecerá naquela sessão.

Outras Ferramentas MCP

Qualquer cliente compatível com MCP funciona — aponte sua ferramenta para python -m projectmem.mcp_server e defina cwd para a raiz do seu projeto ou confie na descoberta automática por subida de diretório pai.

Ferramentas MCP Expostas

Todas as 17 ferramentas que sua IA pode chamar. Cada ferramenta de repositório aceita um argumento opcional project — veja Um servidor, muitos projetos:

Lado de leitura (10 ferramentas):

Lado de escrita (5 ferramentas):

Referência da CLI

Memória principal

Camada de inteligência

Projetos (MCP global)

Visualização e utilitários

Use --at "file.py:42" com qualquer comando de log para anexar metadados precisos de localização.

plan.md — intenção, mantida separada da memória

pjm init cria a estrutura de um .projectmem/plan.md: suas ideias e planos — o que você pretende fazer, em Markdown simples (Ideias · Planos ativos · Próximos · Algum dia · Enviados). É o único arquivo que deliberadamente não é o log de eventos:

• events.jsonl → summary.md registra o que aconteceu (somente anexação, nunca reescrito).
• plan.md registra o que você pretende — e você (ou a IA) edita diretamente, como PROJECT_MAP.md.

Sua IA lê no início da sessão via get_plan() e atualiza no local: adicionando ideias, marcando itens como concluídos, movendo trabalho finalizado para Enviados. Um plano nunca é registrado como evento, então a intenção permanece fora da trilha de auditoria da sua memória. pjm plan exibe; pjm plan "auto-batch the exporter" adiciona uma ideia. É commitado (não ignorado pelo git) para que a intenção seja compartilhada com sua equipe.

Exemplo: Avisos de Pré-Commit em Ação

$ git commit -m "switch auth to JWT"

projectmem: Pre-Commit Check
─────────────────────────────────────────────
  src/auth/middleware.py
    WARN  What already failed here (2 attempts):
           ✗ tried switching to JWT middleware (2d ago)
           ✗ patched session timeout to 60min (5d ago)
    WARN  HIGH CHURN: 5 changes in last 30 days
    WARN  1 possibly-stale memory cites this file
           decision [evt_9db5a3f8…] "auth uses session
           cookies, 30min timeout" — predates 7 commits
           Confirm it still holds, or retire it:
           pjm decision "..." --supersedes <id>
─────────────────────────────────────────────
3 warning(s). Review before committing.

~30 min re-debugging just saved.

Precisa de silêncio para um sprint de refatoração? pjm precheck --snooze 2h — os avisos pausam, a pausa em si é registrada, e cada commit mostra uma linha apagada para que o silêncio nunca seja confundido com uma verificação limpa.

Privacidade e Segurança

Por padrão, projectmem commita os arquivos destilados (summary.md, PROJECT_MAP.md, AI_INSTRUCTIONS.md, issues/) e ignora no git o log bruto + arquivos de execução (events.jsonl, watch.pid, watch.log). Isso significa que a IA do seu colega herda automaticamente o conhecimento da sua equipe — basta git clone e a IA já sabe o que sua equipe aprendeu.

Quer privacidade total? Adicione uma única linha .projectmem/ ao seu .gitignore. Nada sai da sua máquina.

Política de segurança completa e modelo de ameaças: SECURITY.md · Guia de Privacidade e Segurança

Princípios de Design

• Local-first — Sem chamadas de rede, sem nuvem, sem telemetria. Seus dados nunca saem da sua máquina.
• Escopo por projeto — A memória vive no repositório. Quando o código se move, a memória se move.
• Independente de ferramenta de IA — Funciona nativamente via MCP, ou universalmente via instruções em Markdown. Qualquer ferramenta de IA, qualquer fluxo de trabalho.

Construído Com

projectmem se apoia nos ombros destes excelentes projetos de código aberto:

• Typer — o framework de CLI que torna pjm ergonômico
• Model Context Protocol — a especificação aberta da Anthropic que permite agentes de IA conversarem com ferramentas locais
• watchdog — monitoramento de eventos de sistema de arquivos multiplataforma (o coração de pjm watch)
• D3.js — as visualizações interativas em pjm visualize

Pesquisa e Citação

projectmem é descrito em um artigo de pesquisa legível por pares:

PROJECTMEM: A Local-First, Event-Sourced Memory and Judgment Layer for AI Coding Agents Ripon Chandra Malo, Tong Qiu — Universidade de Utah arXiv:2606.12329 · cs.SE (cross-list cs.AI)

O artigo introduz o enquadramento Memory-as-Governance — memória que não apenas responde ao agente, mas age na sua próxima ação — e relata o design, o portão de julgamento determinístico de pré-commit, uma comparação de capacidades contra 12 sistemas de memória contemporâneos, e um estudo de dogfooding de dois meses com 207 eventos em 10 projetos reais.

Se projectmem for útil na sua pesquisa ou escrita, por favor cite:

@misc{malo2026projectmem,
  title         = {PROJECTMEM: A Local-First, Event-Sourced Memory and
                   Judgment Layer for AI Coding Agents},
  author        = {Malo, Ripon Chandra and Qiu, Tong},
  year          = {2026},
  eprint        = {2606.12329},
  archivePrefix = {arXiv},
  primaryClass  = {cs.SE},
  url           = {https://arxiv.org/abs/2606.12329}
}

Licença

MIT — gratuito para uso pessoal, comercial e empresarial para sempre.

Ajude-nos a Alcançar Mais Desenvolvedores

Não precisamos de dinheiro. Precisamos de você.

projectmem é construído por um desenvolvedor para a comunidade de código aberto. Cada estrela, cada compartilhamento e cada contribuição ajuda o projeto a sobreviver e crescer.

• Dê uma estrela no repositório — leva um clique, ajuda muito na descoberta
• Compartilhe no X / LinkedIn — diga a outros devs que eles não precisam continuar pagando IA para reaprender seu código
• Abra uma issue — bug, pedido de funcionalidade, ou apenas feedback
• Contribua com código — PRs são bem-vindos, veja o guia de contribuição
• Usando projectmem no trabalho ou em um produto comercial? Entre em contato com support@projectmem.dev para sabermos quem está enviando conosco. É gratuito — apenas adoramos saber disso.

Estrelas e compartilhamentos importam mais que dinheiro — mas se você realmente quiser: patrocine no GitHub →