Resumen Técnico: projectmem

Planteamiento del Problema

Los asistentes de codificación con IA, aunque potentes dentro de una única sesión, sufren un fallo arquitectónico crítico: son apátridas (stateless) entre sesiones. Cuando una ventana de conversación se cierra, el agente pierde el estado duradero específico del proyecto. En consecuencia, las sesiones subsiguientes suelen requerir que el agente vuelva a leer archivos fuente, vuelva a preguntar cuestiones ya respondidas anteriormente y, de la forma más rentable, vuelva a intentar correcciones que ya han fallado.

Esto se identifica no como un problema de calidad del modelo, sino como un problema de arquitectura. La reconstrucción del contexto mediante la relectura de un proyecto consume un estimado de 5,000 a 20,000 tokens por sesión. Además, las soluciones de memoria existentes suelen depender de bases de datos vectoriales o de la extracción de hechos mediante un LLM en el bucle (LLM-in-the-loop), lo que introduce no determinismo, costos de lectura recurrentes y una falta de privacidad de tipo local-first. Crucialmente, los sistemas actuales actúan principalmente como "Memoria-como-Herramienta" pasiva (responder consultas) en lugar de "Memoria-como-Gobernanza" activa (intervenir antes de una acción para prevenir fallos conocidos).

Metodología y Diseño del Sistema

El artículo presenta projectmem, una capa de memoria y juicio de código abierto y local-first para agentes de codificación con IA. El sistema se basa en cuatro principios de diseño fundamentales:

1. Inmutabilidad: La memoria es un registro de eventos de solo adición (append-only), nunca se edita en su lugar, creando un rastro de auditoría reproducible.
2. Legibilidad Humana: El registro es texto plano (JSON Lines + Markdown), lo que lo hace rastreable mediante grep, comparable mediante diff y controlable mediante versiones a través de Git.
3. Localidad: Todo el estado reside en el repositorio y en la máquina local, sin dependencia de red ni telemetría.
4. Determinismo: Los resúmenes y las puertas de juicio son proyecciones puras del registro, no salidas generadas por un LLM.

Componentes Principales

• Substrato Basado en Eventos: El desarrollo se registra como eventos tipados: issue (problema), attempt (intento, con resultados: funcionó/falló/parcial), fix (corrección), decision (decisión) y note (nota). Estos se añaden a events.jsonl.
• Proyección Determinista: Un archivo de resumen (summary.md) se regenera determinísticamente a partir del registro de eventos. Esto asegura que el agente lea un estado derivado y consistente que no puede desviarse de la historia subyacente.
• Capa de Juicio (Memoria-como-Gobernanza): El sistema introduce una puerta de pre-acción determinista. Antes de que un agente toque un archivo, la función precheck_file(path) consulta el registro de eventos en busca de intentos fallidos, problemas abiertos o alta rotación asociados con esa ruta. Devuelve una advertencia (ej. "intentaste esto hace 2 días—falló") sin realizar una llamada al LLM.
• Memoria Trans-Proyecto: Las lecciones aprendidas en un proyecto (ej. peculiaridades específicas de una librería) se filtran y se promueven a un almacén global de ámbito de máquina (~/.projectmem/global). Estas se presentan automáticamente en otros proyectos que utilizan el mismo stack, indexadas por manifiestos de librerías (ej. package.json, pyproject.toml).
• Integración MCP: El sistema funciona como un servidor MCP (Model Context Protocol) nativo, exponiendo 14 herramientas tipadas (9 de lectura, 5 de escritura) a cualquier cliente compatible con MCP (ej. Cursor, Claude). También incluye un puente de Markdown para herramientas que no sean MCP.
• Seguridad: La redacción de secretos está activada por defecto, eliminando tokens y claves del texto de los eventos antes de escribirlos en el registro.

Contribuciones Clave

El artículo describe cuatro contribuciones principales:

1. Substrato de Memoria Basado en Eventos: Un registro de texto plano y de solo adición de eventos tipados que reemplaza las bases de datos vectoriales, permitiendo la proyección determinista de resúmenes compactos y legibles para la IA.
2. Capa de Juicio: Una puerta de pre-acción determinista derivada de la historia que advierte a los agentes antes de repetir correcciones fallidas o editar archivos frágiles, operacionalizando el concepto de "Memoria-como-Gobernanza".
3. Sistema Local-First y Agnóstico a Herramientas: Un servidor MCP nativo y un puente de Markdown universal que se ejecuta totalmente offline con redacción de secretos activada por defecto.
4. Implementación y Evaluación: Un paquete de Python de tres dependencias (14 herramientas MCP, 19 comandos CLI, 37 pruebas automatizadas) evaluado mediante un autoestudio de dos meses.

Resultados y Evaluación

Los autores evaluaron projectmem mediante un análisis de costo de tokens y un autoestudio en 10 proyectos reales (ML, aplicaciones web, código de investigación) durante dos meses (30 de marzo – 29 de mayo de 2026).

• Reducción del Costo de Tokens: En modo MCP, el agente carga aproximadamente 800–1,500 tokens por sesión vía get_summary(), comparado con un estimado de 5,000–20,000 tokens requeridos para reconstruir el contexto sin una capa de memoria. Esto representa una reducción estimada de más del 50% en el uso de tokens por sesión.
• Datos del Autoestudio: El sistema acumuló 207 eventos reales en 10 proyectos. La composición de los eventos estuvo dominada por notas y decisiones duraderas (61%), seguidas de correcciones (25%), intentos (5%), problemas (5%) y decisiones (4%).
• Acumulación de Memoria: A diferencia de los agentes sin estado que se reinician a cero en cada sesión, la memoria de projectmem se acumula de forma monótona, preservando las ternas de "problema/intento/corrección" y las decisiones arquitectónicas que los agentes sin estado descartan.
• Compatibilidad: Se verificó que el sistema sirve la misma memoria a cuatro clientes diferentes compatibles con MCP sin modificaciones.
• Auditabilidad: El registro inmutable sirve como un rastro de procedencia, registrando qué se cambió, qué se intentó y por qué, utilizando herramientas estándar de control de versiones.

Significancia y Reivindicaciones

El artículo posiciona a projectmem como un substrato práctico para el desarrollo de software asistido por IA y auditable. Su significancia radica en el cambio de paradigma de "Memoria-como-Herramienta" (recuperación pasiva) a "Memoria-como-Gobernanza" (intervención activa).

Los autores afirman que, al mantener la memoria inmutable, legible por humanos, offline y agnóstica a las herramientas, projectmem aborda la "amnesia" de los agentes de IA que conduce a fallos repetidos. Proporciona un mecanismo determinista para detener a un agente de repetir un error conocido antes de que ocurra la acción, en lugar de aprender de él después de los hechos. El sistema está diseñado explícitamente para ser complementario, y no un reemplazo, de la memoria basada en embeddings donde el objetivo es la recuperación semántica amplia; projectmem prioriza el determinismo, la legibilidad y el costo de modelo cero en tiempo de lectura.

El artículo mantiene la modestia respecto a sus afirmaciones, señalando que los ahorros de tokens son estimaciones de uso en lugar de resultados de benchmarks controlados, y que la puerta de juicio es de carácter consultivo por diseño para evitar falsos positivos en cambios nuevos que sean superficialmente similares pero válidos. El trabajo se presenta como una contribución de infraestructura de código abierto al campo de la ingeniería de software agéntica.