agent-handoff-memory

複数のエージェントに共有のバージョン管理されたメモリと、明示的なハンドオフパケットを提供するMCPサーバーです。これにより、次のセッションは前回の続きから開始され、再導出する必要がなくなります。

エージェントはセッションの境界でコンテキストを失います。通常の対処法は、トランスクリプトをプロンプトにダンプし、次の実行がその中から適切な文を選ぶことを期待するものです。ハンドオフパケットはその逆で、何が行われたか、次に何をするか、何がまだ不明か、そしてどの正確なレコードバージョンから開始するかを示す短く構造化されたオブジェクトです。受信エージェントは同じ呼び出しでそれらのバージョンを解決し、その間に更新されたものについては警告を受け取ります。

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

これは、1つのSQLiteファイルに対して2つのプロセスで2つのエージェントを実行します。APIキー、サービス、ネイティブビルドステップは不要です。node:sqliteはランタイムの一部です。

デモの内容

スカウトエージェントが（フィクスチャの）求人ボードをクロールし、見つけた内容を書き込み、自身の評価の1つを修正して、引き継ぎます。別のエグゼキュータプロセスが、それ以外は何も知らずに作業を引き継ぎます：

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

スカウトはパケットを書いた後にlisting/553を編集しました。エグゼキュータは、新しいバージョンを背後でこっそり渡されるのではなく、固定されたバージョンが古くなっていることを通知され、再読み込みしてそのリスティングを破棄します。その後、実際に何が起こったかを報告し、その決定の背後にある事実の信頼度がそれに応じて変動します。

両方のセッションの完全な出力：docs/demo-transcript.md。

1つのスクリプトではなく2つのターミナルで見るには：

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

ツール

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

複数のクライアントを異なるAGENT_IDで同じMEMORY_DBに向けると、1つのメモリを共有します。ストアはWALモードで動作するため、それが正確に機能します。

Claude Codeの場合：

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

設計上の決定

値は不変ですが、意見はそうではありません。 既存のscope+keyに書き込むと、バージョンN+1が追加され、古いバージョンは置き換えられたとマークされます。信頼度と結果カウントは現在のバージョン上で変動します。これらは事実そのものではなく、事実に関する意見であり、すべての変動は変更前後の値とともにoutcomesテーブルに書き込まれます。したがって、historyは何が信じられていたかの履歴であり、投票変更のログではありません。

すべてのバージョンはハッシュ化され、チェーン化されています。 各行は、その本文のsha256と前のバージョンのハッシュを保持します。memory_stats { verify: true }はすべてを再計算します。データベースファイル内で直接編集された値は、破損しているものとして表示されます。テストの1つはまさにその編集を行い、それが検出されることをアサートします。

古い参照は報告され、静かに置き換えられることはありません。 パケットはバージョンを固定します。状況が変わった場合、受信エージェントは通知され、意図的に再読み取りできます。最新バージョンを静かに提供する代替案は、エージェントに、その計画が決して基づいていなかったデータに基づいて行動させることになります。

信頼度は結果に従い、0..1の範囲内に留まります。 成功は1へのギャップの一部を埋め、失敗はスケールダウンするため、繰り返される証拠は端に固定されることなく端に近づきます。乗数はsrc/models.tsの1つのテーブルにあります。

ネットワーク、デーモン、ネイティブモジュールは不要です。 ストレージはnode:sqlite、トランスポートはstdioです。全体はnodeプロセスとファイルです。

SenseLab AMFS

このプロジェクトはSenseLabのAMFS TypeScript SDKでも動作します。src/amfs/sqlite-adapter.tsは、SenseLabのAmfsAdapterコントラクトをSQLite上に実装します。彼らのAgentMemoryが推論を行い、こちらが記憶を行います。demo/amfs-bridge.tsは、ハンドオフのウォークスルーを彼らのAPIを通して再現します：

npm run demo:amfs

SDKはインメモリアダプタ（プロセス終了時に消える）とHTTPアダプタ（ホストされたエンドポイントとキーが必要）を提供します。これはそれらの間のギャップを埋め、その過程でcontentHash/integrityChainを設定し、インメモリアダプタが空のままにするcommitLog()に応答します。パリティテストは、両方のアダプタを通じて同じセッションを実行し、結果を比較します。

構築中に測定したこと（0.3.2でcommitOutcome(SUCCESS)が信頼度を下げる理由を含む）は、docs/senselab-amfs.mdにまとめられています。

テスト

npm test

ストア、ハンドオフライフサイクル、MCPサーフェス（インメモリトランスポートで接続された実際のクライアントとサーバー。ツールスキーマも実行されます）、およびAMFSアダプタに対する29のテスト。AMFSグループは、オプションのSDKがインストールされていない場合、自身をスキップします。

レイアウト

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

要件

Node 24以降。node:sqliteは安定しており、フラグは不要です。25.9で開発およびテスト済み。Node 22.5-23.xでは、同じコードが--experimental-sqliteで実行されます。npm installは（prepareを介して）プロジェクトをビルドするため、その後dist/が使用可能になります。

オプションの@senselab-ai/amfs依存関係は、SenseLabによってBSL-1.1の下で公開されています。このリポジトリの独自コードはMITです。

ライセンス

MIT - LICENSEを参照してください。