agent-handoff-memory

Un servidor MCP que proporciona a varios agentes una memoria compartida y versionada, y un paquete de traspaso explícito, para que la siguiente sesión comience donde terminó la anterior en lugar de deducirlo de nuevo.

Los agentes pierden su contexto en el límite de la sesión. El parche habitual es volcar una transcripción en el prompt y esperar que la siguiente ejecución elija la frase correcta. Un paquete de traspaso es lo opuesto: un objeto corto y estructurado que indica qué se hizo, qué sigue, qué sigue sin aclarar y desde qué versiones de registros exactas comenzar, y el agente receptor obtiene esas versiones resueltas en la misma llamada, con una advertencia sobre aquellas que hayan cambiado desde entonces.

git clone https://github.com/JusticeUA/agent-handoff-memory.git
cd agent-handoff-memory && npm install
npm run demo

Esto ejecuta dos agentes en dos procesos contra un único archivo SQLite. Sin claves de API, sin servicios, sin paso de compilación nativa: node:sqlite es parte del entorno de ejecución.

Qué muestra la demo

Un agente explorador rastrea un tablón de empleo (simulado), escribe lo que encontró, corrige una de sus propias evaluaciones y realiza el traspaso. Un proceso ejecutor separado retoma el trabajo sin saber nada más:

--- 1. pick up whatever is waiting --------------------------------
  . packet h_1f4089bf from scout-agent: Two listings worth an application, one source caveat
  . next: Draft an application for listing/482 (supplier catalogue scrape, $900)
  . next: Draft an application for listing/553 (price monitor, $600)
  . open: Is the 60s backoff enough, or does the board keep a longer penalty window?
  . 4 pinned record versions arrived with the packet
  . stale: listing/553/assessment was pinned at v1, now at v2

--- 3. re-read anything the warning touched -----------------------
  . listing/553 v2 now says "maybe" (budget edited down to $400 and 17 more applicants arrived)
  . dropping listing/553 - acting on the pinned v1 would be wrong

--- 5. report what actually happened ------------------------------
  . success on listing/482/assessment: confidence 80% -> 84%
  . failure on source/boards-example/rate-limit: confidence 60% -> 39%

El explorador editó listing/553 después de escribir el paquete. Al ejecutor se le indica que su versión anclada está obsoleta, en lugar de recibir la nueva a escondidas, vuelve a leer y descarta el anuncio. Luego informa lo que realmente sucedió, y la confianza de los hechos detrás de la decisión se ajusta en consecuencia.

Salida completa de ambas sesiones: docs/demo-transcript.md.

Para verlo como dos terminales en lugar de un solo script:

# terminal 1
MEMORY_DB=shared.db node dist/demo/scout.js
# terminal 2
MEMORY_DB=shared.db node dist/demo/executor.js

Herramientas

Úsalo desde un cliente MCP

{
  "mcpServers": {
    "handoff-memory": {
      "command": "node",
      "args": ["/absolute/path/to/agent-handoff-memory/dist/src/server.js"],
      "env": {
        "MEMORY_DB": "/absolute/path/to/shared-memory.db",
        "AGENT_ID": "researcher"
      }
    }
  }
}

Apunta varios clientes a la misma MEMORY_DB con diferentes AGENT_ID y compartirán una única memoria. El almacén se ejecuta en modo WAL precisamente para que esto funcione.

Para Claude Code:

claude mcp add handoff-memory -e MEMORY_DB=$PWD/shared.db -e AGENT_ID=researcher \
  -- node $PWD/dist/src/server.js

Decisiones de diseño

Los valores son inmutables, las opiniones no. Escribir un scope+key existente añade la versión N+1 y marca la anterior como reemplazada. La confianza y los conteos de resultados sí se mueven en la versión actual (son opiniones sobre un hecho, no el hecho), y cada movimiento se escribe en una tabla outcomes con valores antes/después. Así, history sigue siendo un historial de lo que se creyó, no un registro de cambios de voto.

Cada versión se hashea y se encadena. Cada fila lleva el sha256 de su cuerpo más el hash de la versión anterior. memory_stats { verify: true } recalcula todo; un valor editado directamente en el archivo de base de datos se muestra como corrupto. Una de las pruebas hace exactamente esa edición y verifica que se detecta.

Las referencias obsoletas se reportan, nunca se intercambian silenciosamente. Un paquete ancla versiones. Si el terreno cambió, se informa al agente receptor, que puede releer deliberadamente. La alternativa (servir silenciosamente la versión más nueva) hace que un agente actúe sobre datos sobre los que nunca se construyó su plan.

La confianza sigue a los resultados y se mantiene dentro de 0..1. El éxito cierra parte de la brecha hacia 1, el fracaso escala hacia abajo, por lo que la evidencia repetida se acerca a los bordes sin fijarse allí. Los multiplicadores residen en una tabla en src/models.ts.

Sin red, sin demonio, sin módulos nativos. El almacenamiento es node:sqlite, el transporte es stdio. Todo es un proceso node y un archivo.

SenseLab AMFS

El proyecto también se ejecuta en el SDK TypeScript de SenseLab AMFS. src/amfs/sqlite-adapter.ts implementa el contrato AmfsAdapter de SenseLab sobre SQLite (su AgentMemory hace el razonamiento, esto hace el recuerdo), y demo/amfs-bridge.ts vuelve a contar el tutorial de traspaso a través de su API:

npm run demo:amfs

El SDK incluye un adaptador en memoria (desaparece al salir del proceso) y un adaptador HTTP (necesita un endpoint alojado y una clave); este llena el vacío entre ellos y, de paso, rellena contentHash/integrityChain y responde a commitLog(), que el adaptador en memoria deja vacío. Una prueba de paridad ejecuta la misma sesión a través de ambos adaptadores y compara los resultados.

Lo que medí mientras lo construía, incluido por qué commitOutcome(SUCCESS) reduce la confianza en la versión 0.3.2, está documentado en docs/senselab-amfs.md.

Pruebas

npm test

29 pruebas sobre el almacén, el ciclo de vida del traspaso, la superficie MCP (un cliente y servidor reales unidos por un transporte en memoria, para que también se ejerciten los esquemas de las herramientas) y el adaptador AMFS. El grupo AMFS se salta a sí mismo cuando el SDK opcional no está instalado.

Estructura

src/models.ts              types and the outcome table
src/store.ts               versioned SQLite store: memory, handoffs, outcomes
src/server.ts              the MCP server and its seven tools
src/amfs/types.ts          structural mirror of the AMFS SDK shapes
src/amfs/sqlite-adapter.ts durable adapter for SenseLab's AMFS SDK
demo/scout.ts              session 1: crawl, write, correct, hand over
demo/executor.ts           session 2: resume, act, report outcomes, hand back
demo/amfs-bridge.ts        the same story through @senselab-ai/amfs

Requisitos

Node 24 o superior, donde node:sqlite es estable y no necesita bandera; desarrollado y probado en la versión 25.9. En Node 22.5-23.x, el mismo código se ejecuta con --experimental-sqlite. npm install compila el proyecto (a través de prepare), por lo que dist/ está listo después.

La dependencia opcional @senselab-ai/amfs es publicada por SenseLab bajo BSL-1.1; el código de este repositorio es MIT.

Licencia

MIT - consulte LICENSE.