Agent Memory Bridge

Chino simplificado

Una capa de memoria nativa de MCP para agentes de codificación que convierte sesiones reales en memoria de ingeniería reutilizable.

Creado primero para Codex.

Agent Memory Bridge captura lo que el historial de chat suele perder:

• decisiones duraderas

• correcciones conocidas

• traspasos entre sesiones

• problemas comunes reutilizables

• conocimiento del dominio compacto

La idea central es simple: mantener la capa de memoria pequeña, confiable y auditable. Deja que la orquestación de nivel superior se asiente encima.

La parte interesante no es solo la persistencia. Es el modelado automático de la memoria:

• las sesiones se convierten en learn (aprendizaje) reutilizable

• los fallos repetidos se convierten en gotcha (problemas comunes)

• los grupos de lecciones se convierten en domain-note (notas de dominio) compactas

Por qué existe esto

La mayoría de los sistemas de memoria de agentes derivan en uno de estos tres patrones:

• memoria atrapada dentro de una aplicación o un modelo

• infraestructura alojada más pesada antes de que se prueben los conceptos básicos de recuperación

• volcado de transcripciones en lugar de conocimiento operativo reutilizable

Agent Memory Bridge toma un camino más estrecho:

• nativo de MCP desde el primer día

• tiempo de ejecución local primero

• SQLite + FTS5 en lugar de infraestructura más pesada

• promoción automática de rastros de sesión a memoria reutilizable

No es solo almacenamiento. Es una tubería de modelado de memoria:

session -> summary -> learn -> gotcha -> domain-note

Posicionamiento

Agent Memory Bridge es intencionalmente estrecho.

Si deseas una plataforma de memoria más amplia con SDK, paneles, conectores y soporte para aplicaciones de múltiples superficies, proyectos como OpenMemory o Mem0 se ajustan más a esa forma.

Este proyecto es diferente a propósito:

1. Está construido para flujos de trabajo de agentes de codificación, no para almacenamiento genérico de notas.

2. Mantiene la superficie de MCP intencionalmente pequeña: store y recall.

3. Promueve la salida de sesión sin procesar a memoria compacta legible por máquina en lugar de tratar los resúmenes como el artefacto final.

4. Es local primero y auditable por defecto.

Para una nota de posicionamiento más larga, consulta docs/COMPARISON.md.

Cómo funciona

El tiempo de ejecución tiene cuatro piezas principales:

1. Servidor MCP

   • expone store y recall

2. observador (watcher)

   • observa los archivos de despliegue de Codex

   • escribe session-seen, checkpoint y closeout

3. reflejo (reflex)

   • promueve resúmenes a learn, gotcha y signal

4. consolidación

   • sintetiza registros recurrentes de learn y gotcha en notas de dominio

Esto mantiene el sistema comprensible:

• las sesiones sin procesar no son memoria final

• los resúmenes no son memoria final

• la memoria duradera es primero para la máquina

• la síntesis ocurre después de la promoción

Inicio rápido

Requisitos:

• Python 3.11+

• Codex con MCP habilitado

• SQLite con soporte FTS5

1. Instalar

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]

2. Crear configuración del puente

Copia config.example.toml a:

$CODEX_HOME/mem-bridge/config.toml

Configuración recomendada:

• mantén la base de datos SQLite activa localmente en cada máquina

• mantén el perfil compartido o las bóvedas de origen en NAS o almacenamiento compartido si es necesario

• muévete a un backend alojado más tarde si deseas escrituras en vivo verdaderas entre múltiples máquinas

3. Registrar el servidor MCP en Codex

Añade esto a $CODEX_HOME/config.toml:

[mcp_servers.agentMemoryBridge]
command = "D:\\path\\to\\agent-memory-bridge\\.venv\\Scripts\\python.exe"
args = ["-m", "agent_mem_bridge"]
cwd = "D:\\path\\to\\agent-memory-bridge"

[mcp_servers.agentMemoryBridge.env]
CODEX_HOME = "%USERPROFILE%\\.codex"
AGENT_MEMORY_BRIDGE_HOME = "%USERPROFILE%\\.codex\\mem-bridge"
AGENT_MEMORY_BRIDGE_CONFIG = "%USERPROFILE%\\.codex\\mem-bridge\\config.toml"

4. Iniciar el servicio

Inicia el servidor MCP:

.\.venv\Scripts\python.exe -m agent_mem_bridge

Ejecuta el servicio de puente en segundo plano:

.\.venv\Scripts\python.exe .\scripts\run_mem_bridge_service.py

Ejecuta solo un ciclo:

$env:AGENT_MEMORY_BRIDGE_RUN_ONCE = "1"
.\.venv\Scripts\python.exe .\scripts\run_mem_bridge_service.py

Instalación de inicio opcional:

.\scripts\install_startup_watcher.ps1

Opcional: construir una imagen Docker local

docker build -t agent-memory-bridge:local .
docker --context desktop-linux run --rm -i agent-memory-bridge:local

El punto de entrada del contenedor inicia el servidor MCP stdio con python -m agent_mem_bridge.

API central

La superficie de MCP es intencionalmente pequeña:

• store

• recall

Campos comunes de store:

• namespace

• content

• kind

• tags

• session_id

• actor

• title

• correlation_id

• source_app

Campos comunes de recall:

• namespace

• query

• kind

• tags_any

• session_id

• actor

• correlation_id

• since

• limit

Espacios de nombres típicos

• project:<workspace>

• global

• domain:<name>

• espacios de nombres de perfil importados cuando un equipo los desea

El marco es agnóstico al perfil. Se puede superponer un perfil de operador específico, pero el puente en sí no está vinculado a una persona o un protocolo.

Uso diario

La estratificación prevista es:

• perfil de operador a nivel de sistema

• sustrato de memoria a nivel de sistema: agentMemoryBridge

• anulaciones locales del proyecto: AGENTS.md

El protocolo de inicio está documentado en docs/STARTUP-PROTOCOL.md.

En resumen:

1. recuperar memoria operativa global

2. recuperar memoria de especialización relevante

3. si existe un espacio de trabajo, recuperar project:<workspace>

4. para trabajos tipo incidencia, verificar la memoria local y los problemas comunes antes de la búsqueda externa

5. inspeccionar el código en vivo antes de confiar en los detalles de implementación recuperados

Comandos útiles

Ejecutar pruebas:

.\.venv\Scripts\python.exe -m pytest

Ejecutar la prueba de humo stdio:

.\.venv\Scripts\python.exe .\scripts\verify_stdio.py

Ejecutar el benchmark:

.\.venv\Scripts\python.exe .\scripts\run_benchmark.py

Ejecutar la verificación de salud del puente:

.\.venv\Scripts\python.exe .\scripts\run_healthcheck.py --report-path .\examples\healthcheck-report.json

Forzar un punto de control desde el último despliegue:

.\.venv\Scripts\python.exe .\scripts\sync_now.py

Estructura del proyecto

El repositorio es intencionalmente pequeño:

src/agent_mem_bridge/   canonical implementation
scripts/                operational entrypoints
tests/                  verification
docs/                   design and roadmap
examples/               sanitized demo artifacts

Los archivos que más importan:

• src/agent_mem_bridge/server.py

• src/agent_mem_bridge/storage.py

• src/agent_mem_bridge/watcher.py

• src/agent_mem_bridge/reflex.py

• src/agent_mem_bridge/consolidation.py

• src/agent_mem_bridge/service.py

Decisiones de diseño

Superficie MCP pequeña

El puente expone solo store y recall. Esto mantiene el contrato estable y fácil de integrar.

Tiempo de ejecución local primero

La base de datos en vivo permanece local por defecto porque SQLite en almacenamiento de red compartido es una trampa de confiabilidad.

Memoria primero para la máquina

Los agentes son los lectores principales, por lo que la memoria favorece:

• campos compactos

• etiquetas estables

• bajo costo de tokens

sobre la prosa pulida.

Promoción estratificada

El sistema intenta moverse hacia arriba:

• summary

• learn

• gotcha

• domain-note

en lugar de tratar los resúmenes sin procesar como el artefacto final.

Estado

La base actual está funcionando:

• la carga automática de MCP funciona en Codex

• la sincronización de proyectos y sesiones funciona

• los flujos de trabajo de recuperación primero funcionan

• la promoción de reflejo funciona

• la consolidación de dominio de primera pasada funciona

Verificación de realidad y hoja de ruta:

• docs/PRODUCTION-STATUS.md

• docs/ROADMAP.md

Importaciones de perfil

El marco puede alojar perfiles de operador importados, pero el marco en sí permanece agnóstico al perfil.

Documentación

• README.zh-CN.md

• CONTRIBUTING.md

• AGENTS.md

• docs/COMPARISON.md

• docs/STARTUP-PROTOCOL.md

• docs/MEMORY-TAXONOMY.md

• docs/PROMOTION-RULES.md

• docs/MODEL-ROUTING.md

• docs/ROADMAP.md

Licencia

MIT. Ver LICENSE.