agent-handoff-memory

Ein MCP-Server, der mehreren Agenten einen gemeinsamen, versionierten Speicher bietet – und ein explizites Übergabepaket (handoff packet), damit die nächste Sitzung dort beginnt, wo die letzte aufgehört hat, anstatt sie neu abzuleiten.

Agenten verlieren ihren Kontext an der Sitzungsgrenze. Die übliche Notlösung besteht darin, ein Transkript in den Prompt zu werfen und zu hoffen, dass der nächste Durchlauf den richtigen Satz daraus auswählt. Ein Übergabepaket ist das Gegenteil: ein kurzes, strukturiertes Objekt, das sagt, was getan wurde, was als nächstes kommt, was noch unklar ist – und von welchen genauen Datensatzversionen ausgegangen werden soll – und der empfangende Agent erhält diese Versionen im selben Aufruf aufgelöst, zusammen mit einer Warnung zu solchen, die sich seitdem geändert haben.

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

Das führt zwei Agenten in zwei Prozessen gegen eine einzige SQLite-Datei aus. Keine API-Schlüssel, keine Dienste, kein nativer Build-Schritt – node:sqlite ist Teil der Laufzeitumgebung.

Was die Demo zeigt

Ein Scout-Agent durchsucht eine (Test-)Jobbörse, schreibt auf, was er gefunden hat, korrigiert eine seiner eigenen Bewertungen und übergibt. Ein separater Executor-Prozess übernimmt dann die Arbeit, ohne sonst etwas zu wissen:

--- 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%

Der Scout hat listing/553 nach dem Schreiben des Pakets bearbeitet. Der Executor erfährt, dass seine festgelegte Version veraltet ist, anstatt ihm hinter seinem Rücken die neue zu übergeben, liest erneut und verwirft das Inserat. Dann berichtet er, was tatsächlich passiert ist, und die Konfidenz der Fakten, die hinter der Entscheidung stehen, verschiebt sich entsprechend.

Vollständige Ausgabe beider Sitzungen: docs/demo-transcript.md.

Um es als zwei Terminals anstelle eines Skripts zu betrachten:

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

Werkzeuge

Verwendung mit einem MCP-Client

{
  "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"
      }
    }
  }
}

Richten Sie mehrere Clients mit unterschiedlichen AGENT_IDs auf dieselbe MEMORY_DB aus, und sie teilen sich einen Speicher. Der Speicher läuft im WAL-Modus, genau damit das funktioniert.

Für Claude Code:

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

Designentscheidungen

Werte sind unveränderlich, Meinungen nicht. Das Schreiben eines vorhandenen scope+key fügt Version N+1 an und markiert die alte als ersetzt. Konfidenz und Ergebniszahlen ändern sich auf der aktuellen Version – sie sind Meinungen über eine Tatsache, nicht die Tatsache – und jede Änderung wird in einer outcomes-Tabelle mit Vorher/Nachher-Werten festgehalten. Somit bleibt history eine Geschichte dessen, was geglaubt wurde, kein Protokoll von Stimmenänderungen.

Jede Version wird gehasht und verkettet. Jede Zeile enthält den sha256 ihres Inhalts plus den Hash der vorherigen Version. memory_stats { verify: true } berechnet alles neu; ein direkt in der Datenbankdatei bearbeiteter Wert wird als korrupt gemeldet. Einer der Tests führt genau diese Bearbeitung durch und stellt sicher, dass sie erkannt wird.

Veraltete Referenzen werden gemeldet, niemals stillschweigend ausgetauscht. Ein Paket legt Versionen fest. Wenn sich die Grundlage geändert hat, wird der empfangende Agent informiert – er kann bewusst neu lesen. Die Alternative (stilles Ausliefern der neuesten Version) führt dazu, dass ein Agent auf Daten handelt, auf die sein Plan niemals aufgebaut wurde.

Konfidenz folgt den Ergebnissen und bleibt innerhalb von 0..1. Erfolg schließt einen Teil der Lücke zu 1, Misserfolg skaliert herunter, sodass wiederholte Beweise sich den Rändern annähern, ohne dort festzustecken. Die Multiplikatoren befinden sich in einer Tabelle in src/models.ts.

Kein Netzwerk, kein Daemon, keine nativen Module. Der Speicher ist node:sqlite, das Transportprotokoll ist stdio. Das Ganze ist ein node-Prozess und eine Datei.

SenseLab AMFS

Das Projekt läuft auch mit dem TypeScript SDK von SenseLab's AMFS. src/amfs/sqlite-adapter.ts implementiert SenseLabs AmfsAdapter-Vertrag auf SQLite – deren AgentMemory übernimmt das Denken, dieses hier das Erinnern – und demo/amfs-bridge.ts erzählt die Übergabe-Walkthrough durch ihre API neu:

npm run demo:amfs

Das SDK enthält einen In-Memory-Adapter (verschwindet, wenn der Prozess endet) und einen HTTP-Adapter (benötigt einen gehosteten Endpunkt und einen Schlüssel); dieser füllt die Lücke zwischen ihnen und füllt dabei contentHash / integrityChain und beantwortet commitLog(), das der In-Memory-Adapter leer lässt. Ein Paritätstest führt dieselbe Sitzung durch beide Adapter aus und vergleicht die Ergebnisse.

Was ich während der Entwicklung gemessen habe – einschließlich, warum commitOutcome(SUCCESS) in 0.3.2 die Konfidenz senkt – ist in docs/senselab-amfs.md beschrieben.

Tests

npm test

29 Tests über den Speicher, den Übergabe-Lebenszyklus, die MCP-Oberfläche (ein echter Client und Server, verbunden durch einen In-Memory-Transport, sodass auch die Werkzeugschemas getestet werden) und den AMFS-Adapter. Die AMFS-Gruppe überspringt sich selbst, wenn das optionale SDK nicht installiert ist.

Aufbau

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

Anforderungen

Node 24 oder neuer, wo node:sqlite stabil ist und kein Flag benötigt; entwickelt und getestet auf 25.9. Auf Node 22.5-23.x läuft derselbe Code mit --experimental-sqlite. npm install erstellt das Projekt (über prepare), sodass dist/ danach bereit ist.

Die optionale Abhängigkeit @senselab-ai/amfs wird von SenseLab unter BSL-1.1 veröffentlicht; der eigene Code dieses Repos ist MIT.

Lizenz

MIT – siehe LICENSE.