CP Memory

CP Memory

Memoria local-primero y gobernable para agentes de codificación de IA.
Recuerda reglas de proyecto entre sesiones, recupera solo lo que importa y corrige memoria incorrecta sin ocultar el historial.

简体中文 | English

---

Por qué CP Memory

Para comprobaciones reproducibles de paquetes, protocolos y recuperación, consulta evidencia de verificación y límites.

• Local-primero: la memoria permanece en ~/.cp-memory/memory.db por defecto.
• Gobernable: inspecciona, revisa, corrige, delimita o retira memoria en lugar de sobrescribirla silenciosamente.
• Listo para MCP, mejorado con Codex: el servidor MCP stdio es la base portable; el plugin de Codex añade Skills y Hooks de ciclo de vida.

Inicio rápido — MCP portable

Con Python 3.10+ y uv instalado, cualquier cliente MCP stdio puede iniciar CP Memory con:

uvx cp-memory-mcp

El paquete público pasó un handshake MCP con caché limpia con las 40 herramientas y un flujo de escritura/búsqueda/corrección. Consulta configuración de clientes MCP para ejemplos con Codex, Claude Code, Cursor, VS Code y Gemini CLI.

Para la integración mejorada con Codex con Hooks de ciclo de vida y Skills, instala el plugin:

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

Reinicia Codex después de la instalación y aprueba los Hooks de ciclo de vida si se te solicita.

Ve el resultado en 30 segundos

1. Dile a Codex una regla de proyecto, como: "Los lanzamientos deben comenzar en una rama, ejecutar pruebas y fusionarse mediante un PR."
2. En una sesión posterior, CP Memory restaura la regla relevante desde el almacén primario local para que Codex pueda seguir cumpliéndola.
3. Si la regla es incorrecta, conserva el historial de corrección y marca el registro antiguo como incorrecto, desactualizado o delimitado en lugar de sobrescribirlo silenciosamente.

CP Memory es un plugin de memoria local-primero para Codex. Almacena hechos, preferencias, trabajo en curso, episodios, decisiones y puntos de control de conversación en una base de datos SQLite local, y luego restaura el contexto relevante mediante herramientas MCP y hooks de ciclo de vida.

El objetivo no es recordar tanto como sea posible. El objetivo es una memoria que siga siendo confiable tras un uso prolongado: explicable, revisable, corregible y gobernable.

Capacidades actuales

• Restauración de contexto: restaura memoria local-primero relevante al inicio y en indicaciones elegibles.
• Extracción automática: crea de forma conservadora candidatos de memoria personal a largo plazo a partir de declaraciones explícitas.
• Alcance de proyecto: prioriza memorias del proyecto actual con alcances repo:, project: y workspace:.
• Gobernanza revisable: admite bandeja de revisión, resúmenes de revisión, sugerencias de conflictos, estados de corrección y recordatorios de inicio.
• Mantenimiento seguro: el mantenimiento semanal ejecuta solo comprobaciones de salud, preflight de gobernanza y limpieza de expiración de bajo riesgo.

Ejemplo en 30 segundos

Le dices a Codex:

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

En una sesión posterior, preguntas:

What are the release rules for this plugin?

CP Memory restaura la memoria relevante desde el almacén primario local primero, y Codex sigue esa regla. Si la memoria es incorrecta, puedes marcarla como incorrecta, desactualizada o escribir una versión corregida.

Consulta más ejemplos anonimizados en docs/examples.md.

Para un GIF, video corto o publicación de lanzamiento, usa el guion de demostración de 30 segundos sanitizado.

Instalación

Para cualquier cliente MCP stdio, usa el paquete público verificado:

uvx cp-memory-mcp

Los comandos específicos de cliente y archivos JSON están en docs/mcp-clients.md.

Para Windows, la ruta recomendada es la instalación desde GitHub Marketplace:

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

Reinicia Codex después de la instalación. Si Codex te pide confiar en los hooks, aprueba los hooks de ciclo de vida de CP Memory en la vista de hooks.

Para macOS/Linux, usa el instalador de fuente. Crea un runtime privado de Python para el plugin e instala la dependencia MCP:

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

Reinicia Codex cuando termine. No trates la instalación desde GitHub Marketplace en macOS/Linux como una ruta igualmente verificada: Marketplace no ejecuta install.sh, por lo que no crea ese runtime privado.

Soporte de plataformas

Plataforma	Instalación recomendada	Cobertura verificada
Windows	GitHub Marketplace; install.ps1 para desarrollo local	Pruebas unitarias, validación de instalación aislada y CI de GitHub Actions aprobados
macOS	Instalador de fuente: sh ./install.sh	CI de macOS en GitHub Actions aprobó pruebas unitarias y validación de instalación/inicio MCP aislados
Linux	Instalador de fuente: sh ./install.sh	CI de Ubuntu en GitHub Actions aprobó pruebas unitarias y validación de instalación/inicio MCP aislados

Las pruebas manuales de inyección real de Hooks en el escritorio de Codex en macOS/Linux aún están pendientes de acceso a dispositivos físicos. Esta versión se acepta mediante CI en tres plataformas; el límite no afecta las comprobaciones de instalador e inicio MCP ya cubiertas, pero no sustituye la aceptación manual completa en escritorio.

Seguridad

• No confirmes tu memory.db real, registros, resúmenes privados o archivos de entorno.
• La extracción automática es intencionalmente conservadora. Las memorias generadas pueden revisarse, corregirse, marcarse como desactualizadas o incorrectas.
• Cuando las memorias necesitan revisión, la versión actual inyecta un recordatorio en el contexto del asistente. No es una ventana emergente para el usuario ni un panel de revisión visible, y no elimina memoria automáticamente ni resuelve conflictos automáticamente.
• El mantenimiento semanal ejecuta solo comprobaciones de salud, preflight de gobernanza y limpieza de expiración de bajo riesgo; las memorias personales a largo plazo, tareas y decisiones están protegidas por defecto.
• Los ejemplos y capturas de pantalla usan contenido sanitizado, por lo que no necesitas exponer tu base de datos de memoria real.

Comparación

Si has visto otros proyectos de memoria, comienza con docs/comparison.md. La principal diferencia de CP Memory es la integración con el ciclo de vida de Codex más la gobernanza de memoria, no solo almacenamiento y búsqueda.

Hoja de ruta

Consulta docs/roadmap.md para direcciones futuras. La hoja de ruta prioriza el comportamiento local-primero, la explicabilidad, la corregibilidad y la seguridad de privacidad.

Consulta CHANGELOG.md para el historial de versiones.

Desarrollo local

Los usuarios de Windows normalmente no necesitan ejecutar install.ps1. Es principalmente para desarrollo local, actualizar la caché del marketplace personal y migrar la conexión de hooks globales antiguos de versiones anteriores.

Para desarrollo local en macOS/Linux, ejecuta:

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

Se requiere Python 3 con python3 en PATH. El instalador crea un entorno virtual privado en el directorio del plugin e instala las dependencias de runtime; esta es la ruta de instalación actualmente verificada para macOS/Linux.

Ejecuta la suite de pruebas:

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

Valida el instalador en un perfil temporal aislado sin tocar tu configuración real de Codex:

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

Licencia

MIT