codex-lcm

Gestión local y sin pérdidas del contexto para OpenAI Codex CLI.

codex-lcm captura los eventos de conversación de Codex en SQLite, compacta el contexto más antiguo en una jerarquía de resúmenes sin eliminar los mensajes fuente, restaura el contexto relevante al iniciar una sesión y expone la recuperación léxica a través de un servidor MCP local.

Significado de "sin pérdidas": el contenido fuente se conserva después de la redacción de secretos configurada. Las vistas previas de herramientas buscables están limitadas, mientras que la entrada y salida completas de herramientas redactadas permanecen disponibles mediante expansión paginada.

Estado y plataforma

codex-lcm es software beta para macOS. Depende de los hooks de Codex y de flock de POSIX; Windows y Linux no son compatibles ni se reivindican actualmente.

Related MCP server: ClaudeX

Características

• Captura en vivo: las indicaciones del usuario, las respuestas del asistente y la actividad de las herramientas se capturan a través de los hooks de Codex.

• Almacenamiento local duradero: SQLite en modo WAL almacena mensajes sin procesar, partes de mensajes estructuradas, resúmenes e índices FTS5.

• Compactación jerárquica: los mensajes más antiguos se convierten en resúmenes hoja; las ejecuciones de resúmenes elegibles pueden condensarse en nodos DAG más profundos. Las filas fuente nunca se eliminan automáticamente.

• Restauración de contexto: los resúmenes activos y los mensajes no resumidos más recientes se inyectan al inicio de la sesión dentro de un límite de tamaño estricto.

• Recuperación local: seis herramientas MCP stdio proporcionan búsqueda léxica, consulta de sesiones recientes, inspección de metadatos y expansión de fuente paginada.

• Hooks con apertura ante fallos: los fallos de captura o compactación no bloquean un turno de Codex.

• Controles de seguridad: redacción de secretos, bloqueos de compactación por sesión, escrituras atómicas de mensajes/FTS, reservas de llamadas al proveedor, comprobaciones de progreso y permisos de archivo privados por defecto.

Instalar desde un checkout del repositorio

python3 -m venv ~/.codex-lcm/venv
~/.codex-lcm/venv/bin/python -m pip install .
~/.codex-lcm/venv/bin/codex-lcm install
~/.codex-lcm/venv/bin/codex-lcm doctor

Reinicia Codex después de la instalación. Usa /hooks en Codex para inspeccionar y confiar en los hooks instalados.

El instalador fusiona las entradas de codex-lcm en ~/.codex/hooks.json y ~/.codex/config.toml. Crea copias de seguridad con marca de tiempo antes de modificar los archivos existentes. Ejecutar el instalador de nuevo es idempotente.

Un checkout de la fuente también incluye scripts/install.sh, que realiza la misma instalación y verificación aisladas.

Resumen LLM opcional

En Python 3.11+, el paquete principal no tiene dependencias de terceros en tiempo de ejecución. Python 3.10 instala el backport de compatibilidad tomli para un manejo seguro de la configuración TOML. Sin un cliente LLM, la compactación utiliza truncamiento determinista de cabeza/cola.

Para habilitar el resumen compatible con OpenAI, instala el extra opcional y configura las credenciales:

~/.codex-lcm/venv/bin/python -m pip install ".[llm]"
export CODEX_LCM_API_KEY="..."

OPENAI_API_KEY también se reconoce. Usa CODEX_LCM_BASE_URL o OPENAI_BASE_URL para un endpoint compatible con OpenAI. Los ajustes del proveedor CODEX_LCM_* se tratan como un par y tienen prioridad como par, por lo que una clave global nunca se envía a un endpoint con ámbito. Cuando se establece CODEX_LCM_BASE_URL, configura también CODEX_LCM_API_KEY.

CLI

codex-lcm install                       Wire hooks and the MCP server into Codex
codex-lcm uninstall                     Remove codex-lcm wiring and keep stored data
codex-lcm status                        Show database statistics
codex-lcm doctor                        Verify package, database, hooks, and MCP wiring
codex-lcm compact --session <id>        Compact one session synchronously
codex-lcm compact --all                 Compact every recorded session synchronously

Desinstalar no elimina ~/.codex-lcm/ ni su base de datos.

Herramientas MCP

La recuperación es léxica, no semántica: no hay incrustaciones ni afirmaciones de similitud vectorial en esta versión.

Configuración

La configuración se lee de las variables de entorno.

El directorio de datos por defecto tiene modo 0700; la base de datos, los archivos laterales WAL, los archivos de bloqueo y el registro de compactación tienen modo 0600 en sistemas POSIX.

Límites de datos y seguridad

• La redacción ocurre antes de la persistencia para claves API conocidas, tokens, cabeceras de autorización, asignaciones de contraseñas/secretos, JWT y claves privadas PEM.

• Las URL de repositorios Git con credenciales se almacenan sin información de usuario, parámetros de consulta ni fragmentos.

• La redacción es defensa en profundidad, no una garantía de que se reconozca cada posible formato de secreto.

• Las cargas útiles de herramientas redactadas completas pueden contener aún datos privados de conversación o proyecto. Protege la cuenta local y las copias de seguridad de la base de datos en consecuencia.

• No se envían datos a un proveedor LLM a menos que el cliente opcional esté instalado y se configuren credenciales del proveedor o una URL base.

• La retención y eliminación automáticas están intencionalmente ausentes. La aplicación no descarta silenciosamente el historial fuente.

Desarrollo

Usa un entorno local al proyecto; las pruebas nunca necesitan el perfil o la base de datos de Codex en vivo.

python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/python -m pytest -q
.venv/bin/python tests/smoke_test.py
.venv/bin/python tests/reliability_test.py
.venv/bin/python tests/package_test.py
.venv/bin/ruff check .
.venv/bin/bandit -q -r codex_lcm

La compilación de prueba del paquete se instala en un directorio de inicio y un entorno virtual desechables. Los scripts de humo y fiabilidad también usan bases de datos temporales.

Consulta DESIGN.md para el modelo de almacenamiento, invariantes, flujo de hooks y comportamiento ante fallos.

Licencia

MIT