agent-context-substrate

El sustrato es el activo; el modelo es un cliente intercambiable.

git clone https://github.com/thomaskawas/agent-context-substrate.git
cd agent-context-substrate
make setup && make demo

Requisitos: Python 3.12+, Docker, make. make setup crea un venv e instala las dependencias, alrededor de 1.4 GB ya que la demo se ejecuta en CPU y omite las wheels de CUDA; permite unos minutos en una conexión lenta. La base de datos se vincula a 127.0.0.1:5432, así que detén cualquier cosa que ya esté usando ese puerto.

Por qué existe esto

Construyo proyectos de larga duración con agentes de IA, y restablecer el contexto al inicio de cada sesión era el impuesto que pagaba con más frecuencia. Subir los mismos archivos, reexplicar las mismas decisiones, ver cómo la parte útil de la ventana se llenaba con material que el modelo ya había visto dos veces. Un mejor modelo saldría y nada de eso se trasladaba. El problema nunca fue que faltara el contexto. Era que el contexto no era direccionable: no había forma de hacer una pregunta y obtener solo lo que la responde, así que envías todo y esperas. La solución fue dejar de tratar el contexto como algo que llevas a una sesión y empezar a tratarlo como algo que consultas.

Una implementación de referencia de un sustrato de memoria independiente del modelo para agentes de IA: la memoria del proyecto vive fuera del modelo en un almacén consultable y versionado, expuesto a través de una puerta de enlace MCP. Cambia el modelo; conserva todo. Claude hoy, Gemini o GPT mañana, la misma memoria de proyecto debajo. En lugar de pegar el historial en cada sesión, la recuperación selecciona el pequeño conjunto de registros que la tarea actual realmente necesita.

Este repositorio es una implementación de referencia de sala limpia de ese patrón, escrita desde cero contra un corpus sintético para que cada número en esta página se reproduzca desde un clon limpio con las dependencias fijadas. Es el patrón, no el sistema que ejecuto en mi propio trabajo.

No se requieren claves API: make demo se ejecuta completamente en componentes locales. Los modelos locales fijados (nombre y revisión) son el perfil de adaptador predeterminado, local (make warmup, ejecutado automáticamente por make demo, precarga ~180 MB una vez); el perfil hermético de cero descargas deterministic respalda las pruebas y la puerta de CI siempre activa.

Related MCP server: AI Memory MCP Server

Estructura

src/acs/adapters/base.py es la tesis en código: cuatro pequeñas interfaces detrás de las cuales se asienta cada capacidad externa. src/acs/store/ trata la memoria como un sistema de registro (versionado, auditable, genuinamente eliminable). src/acs/retrieval/ es el pipeline como etapas pequeñas y separadamente probables. eval/ es la puerta: los cambios se envían si igualan o superan baseline.lock.json, o no se envían.

La justificación del diseño vive en docs/adr/: nueve registros de decisión. La mayoría son de media página; tres son más largos, donde el argumento necesitaba espacio.

También en docs/: architecture.md para saber por qué existe cada capa, threat-model.md para los límites adversariales y dónde vive cada defensa, principles.md para las reglas de las que se derivan el resto, y build-your-own.md para la secuencia de construcción que siguió este repositorio.

Qué demuestra

• Ingesta escribe ambas representaciones en una sola pasada: embeddings para similitud, un grafo de entidad/relación para la estructura. Cada documento se incrusta; un documento que no declara ninguna relación no contribuye con aristas.

• Recuperación es un pipeline de cuatro etapas: búsqueda híbrida vectorial + texto completo con una mezcla ajustable, fusión multi-consulta (RRF), reordenamiento con cross-encoder, y una partición anclada en entidades donde el grafo reordena la lista reordenada para que un reordenador temático deje de confundir un componente con su hermano de nombre similar. Los perfiles de recuperación por consumidor son datos, no código.

• Gobernanza: los cambios de recuperación se envían igualando o superando una línea base de evaluación bloqueada. La memoria está versionada con SCD2 y lecturas de viaje en el tiempo, la purga elimina genuinamente (vectores incluidos), y el registro de auditoría rechaza la mutación a nivel de base de datos.

• Acceso: una puerta de enlace MCP sirve el sustrato a cualquier cliente MCP, con alcance por llamante. Un bucle de investigación en cuarentena llena los vacíos con escritura de vuelta obligatoria con citas.

• Portabilidad: cada proveedor se asienta detrás de un adaptador; el incrustador está fijado a propósito.

El id de linaje y las marcas de tiempo provienen ambos de make history: sin argumentos, lista las memorias actuales con sus ids; con LINEAGE=<id> recorre la cadena de versiones de una memoria e imprime la ventana de validez de cada versión. Esas ventanas son marcas de tiempo ISO para que un TS= que pegues de vuelta resuelva a la versión que realmente leíste, en lugar de una un segundo antes o después. Los ids se generan por clon, así que los tuyos no coincidirán con los que se muestran aquí.

make purge elimina genuinamente (objetivos del conjunto dorado incluidos, cuando pertenecen al sujeto purgado), por lo que un benchmark contra un corpus purgado se niega a ejecutarse como incompleto en lugar de informar silenciosamente un recall más bajo. make demo restablece a un corpus limpio.

Cada número de benchmark en esta página proviene de una ablación sobre un corpus sintético sembrado (corpus/generate.py), reproducible desde un clon limpio y controlado en CI (el perfil determinista en cada push, el perfil local en la etiqueta bench-local) contra una línea base bloqueada que también bloquea el digest del corpus. Lee los deltas, no los absolutos: recall@5 / mrr@5 en un corpus sintético demuestran lo que cada etapa contribuye, nunca la calidad del mundo real. Para ver dónde una etapa gana su delta, ejecuta .venv/bin/python eval/run_benchmark.py --by-family.

La ablación, perfil local

Cada etapa aporta algo diferente, lo cual es el argumento para un pipeline en lugar de un solo mejor recuperador. tests/test_readme_table.py falla si esta tabla y eval/baseline.lock.json alguna vez discrepan, por lo que la tabla no puede desviarse de los números que la puerta impone. La puerta es un piso, así que un cambio que mejora una métrica la pasa y los números aquí permanecen hasta que la línea base se vuelva a bloquear a propósito con make lock-baseline, lo que luego hace fallar esta tabla hasta que se actualice para coincidir. Perfil local, 120 consultas doradas, k=5, fusión de etapa 1 rank, digest del corpus ad7bf7ca. Reproduce con make demo.

Lo que estos números respaldan y no respaldan, incluido por qué la comparación del carril del modelo es un límite en lugar de una curva, se expone en docs/limitations.md.