CP Memory

CP Memory

Memória local-first e governável para agentes de codificação de IA.
Lembre-se das regras do projeto entre sessões, recupere apenas o que importa e corrija memórias ruins sem ocultar o histórico.

简体中文 | English

---

Por que CP Memory

Para verificações reproduzíveis de pacote, protocolo e recuperação, consulte evidências de verificação e limites.

• Local-first: a memória permanece em ~/.cp-memory/memory.db por padrão.
• Governável: inspecione, revise, corrija, escope ou aposente memórias em vez de sobrescrevê-las silenciosamente.
• Pronto para MCP, aprimorado com Codex: o servidor MCP stdio é a base portátil; o plugin Codex adiciona Skills e Hooks de ciclo de vida.

Início Rápido — MCP Portátil

Com Python 3.10+ e uv instalados, qualquer cliente MCP stdio pode iniciar o CP Memory com:

uvx cp-memory-mcp

O pacote público passou por um handshake MCP com cache limpo, incluindo todas as 40 ferramentas e um fluxo de escrita/busca/correção. Consulte configuração de cliente MCP para exemplos com Codex, Claude Code, Cursor, VS Code e Gemini CLI.

Para a integração aprimorada com Codex, incluindo Hooks de ciclo de vida e Skills, instale o plugin:

codex plugin marketplace add CJhuochai/cp-memory
codex plugin add cp-memory@cp-memory

Reinicie o Codex após a instalação e aprove os Hooks de ciclo de vida se for solicitado.

Veja o Resultado em 30 Segundos

1. Diga ao Codex uma regra do projeto, como: "Releases devem começar em uma branch, executar testes e ser mesclados por meio de um PR."
2. Em uma sessão posterior, o CP Memory restaura a regra relevante do armazenamento primário local para que o Codex possa continuar seguindo-a.
3. Se a regra estiver errada, preserve o histórico de correção e marque o registro antigo como errado, desatualizado ou escopado, em vez de sobrescrevê-lo silenciosamente.

O CP Memory é um plugin de memória local-first para Codex. Ele armazena fatos, preferências, trabalho em andamento, episódios, decisões e checkpoints de conversa em um banco de dados SQLite local e, em seguida, restaura o contexto relevante por meio de ferramentas MCP e hooks de ciclo de vida.

O objetivo não é lembrar o máximo possível. O objetivo é uma memória que permaneça confiável após uso prolongado: explicável, revisável, corrigível e governável.

Capacidades Atuais

• Restauração de contexto: restaura memórias locais primárias relevantes na inicialização e em prompts elegíveis.
• Extração automática: cria conservadoramente candidatos a memória pessoal de longo prazo a partir de declarações explícitas.
• Escopo do projeto: prioriza memórias do projeto atual com escopos repo:, project: e workspace:.
• Governança revisável: suporta caixa de entrada de revisão, resumos de revisão, sugestões de conflito, estados de correção e lembretes de inicialização.
• Manutenção segura: a manutenção semanal executa verificações de saúde, preflight de governança e limpeza de expiração de baixo risco apenas.

Exemplo em 30 Segundos

Você diz ao Codex:

Remember this: releases for this project must start on a branch, run tests, and merge through a PR.

Em uma sessão posterior, você pergunta:

What are the release rules for this plugin?

O CP Memory restaura a memória relevante do armazenamento primário local primeiro, e o Codex segue essa regra. Se a memória estiver errada, você pode marcá-la como errada, desatualizada ou escrever uma versão corrigida.

Veja mais exemplos anonimizados em docs/examples.md.

Para um GIF, vídeo curto ou post de lançamento, use o script de demonstração de 30 segundos sanitizado.

Instalação

Para qualquer cliente MCP stdio, use o pacote público verificado:

uvx cp-memory-mcp

Comandos específicos de cliente e arquivos JSON estão em docs/mcp-clients.md.

Para Windows, o caminho recomendado é a instalação via GitHub Marketplace:

codex plugin marketplace add CJhuochai/cp-memory
codex plugin add cp-memory@cp-memory

Reinicie o Codex após a instalação. Se o Codex pedir para você confiar nos hooks, aprove os hooks de ciclo de vida do CP Memory na visualização de hooks.

Para macOS/Linux, use o instalador de origem. Ele cria um runtime Python privado para o plugin e instala a dependência MCP:

git clone https://github.com/CJhuochai/cp-memory.git
cd cp-memory
sh ./install.sh

Reinicie o Codex quando terminar. Não trate a instalação via GitHub Marketplace no macOS/Linux como um caminho igualmente verificado: o Marketplace não executa install.sh, portanto não cria esse runtime privado.

Suporte de Plataforma

Plataforma	Instalação recomendada	Cobertura verificada
Windows	GitHub Marketplace; install.ps1 para desenvolvimento local	Testes de unidade, validação de instalação isolada e CI do GitHub Actions aprovados
macOS	Instalador de origem: sh ./install.sh	CI do GitHub Actions no macOS aprovou testes de unidade e validação isolada de instalação/inicialização MCP
Linux	Instalador de origem: sh ./install.sh	CI do GitHub Actions no Ubuntu aprovou testes de unidade e validação isolada de instalação/inicialização MCP

Testes manuais de fumaça da injeção real de Hooks no desktop Codex em macOS/Linux ainda estão pendentes de acesso a dispositivos físicos. Esta versão é aceita por meio de CI em três plataformas; a limitação não afeta o instalador e as verificações de inicialização MCP já cobertas, mas não substitui a aceitação manual completa no desktop.

Segurança

• Não envie seu memory.db real, logs, resumos privados ou arquivos de ambiente.
• A extração automática é intencionalmente conservadora. As memórias geradas podem ser revisadas, corrigidas, marcadas como desatualizadas ou erradas.
• Quando memórias precisam de revisão, a versão atual injeta um lembrete no contexto do assistente. Não é um popup voltado ao usuário nem um painel de revisão visível, e não exclui memórias automaticamente nem resolve conflitos automaticamente.
• A manutenção semanal executa verificações de saúde, preflight de governança e limpeza de expiração de baixo risco apenas; memórias pessoais de longo prazo, tarefas e decisões são protegidas por padrão.
• Exemplos e capturas de tela usam conteúdo sanitizado, então você não precisa expor seu banco de memória real.

Comparação

Se você já viu outros projetos de memória, comece por docs/comparison.md. A principal diferença do CP Memory é a integração com o ciclo de vida do Codex mais a governança de memória, não apenas armazenamento e busca.

Roadmap

Consulte docs/roadmap.md para direções futuras. O roadmap prioriza comportamento local-first, explicabilidade, corrigibilidade e segurança de privacidade.

Consulte CHANGELOG.md para o histórico de versões.

Desenvolvimento Local

Usuários de Windows normalmente não precisam executar install.ps1. Ele é principalmente para desenvolvimento local, atualização do cache do marketplace pessoal e migração de wiring antigo de hooks globais de versões anteriores.

Para desenvolvimento local em macOS/Linux, execute:

sh ./install.sh
sh ./scripts/test-install.sh

Python 3 com python3 no PATH é necessário. O instalador cria um ambiente virtual privado no diretório do plugin e instala as dependências de runtime; este é o caminho de instalação atualmente verificado para macOS/Linux.

Execute a suíte de testes:

python -m unittest discover -s tests -p test_cp_memory.py

Valide o instalador em um perfil temporário isolado sem tocar na sua configuração real do Codex:

powershell -ExecutionPolicy Bypass -File .\scripts\test-install.ps1

Licença

MIT