agent-handoff-memory

여러 에이전트가 하나의 공유된 버전 관리 메모리와 명시적인 핸드오프 패킷을 사용할 수 있게 해주는 MCP 서버입니다. 이를 통해 다음 세션이 마지막 세션이 중단된 지점부터 시작되며, 다시 유도할 필요가 없습니다.

에이전트는 세션 경계에서 컨텍스트를 잃습니다. 일반적인 해결 방법은 대화 내용을 프롬프트에 덤프하고 다음 실행이 그중에서 올바른 문장을 선택하기를 바라는 것입니다. 핸드오프 패킷은 그 반대입니다. 즉, 무엇이 완료되었는지, 다음에 무엇을 해야 하는지, 아직 불명확한 점은 무엇인지, 그리고 어떤 정확한 레코드 버전부터 시작해야 하는지를 알려주는 짧고 구조화된 객체입니다. 수신 에이전트는 동일한 호출에서 해당 버전을 해결하여 받으며, 그 사이에 변경된 사항이 있으면 경고를 받습니다.

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

이는 두 개의 프로세스에서 두 에이전트가 하나의 SQLite 파일을 대상으로 실행됩니다. API 키, 서비스, 네이티브 빌드 단계가 필요 없습니다. node:sqlite는 런타임의 일부입니다.

데모에서 보여주는 것

정찰 에이전트가 (픽스처) 구인 게시판을 크롤링하고, 찾은 내용을 기록하며, 자신의 평가 중 하나를 수정한 후 인계합니다. 그런 다음 별도의 실행기 프로세스가 다른 정보 없이 작업을 이어받습니다:

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

하나의 스크립트 대신 두 개의 터미널로 보려면:

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

여러 클라이언트를 동일한 MEMORY_DB에 서로 다른 AGENT_ID로 연결하면 하나의 메모리를 공유합니다. 저장소는 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 }는 전체를 다시 계산합니다. 데이터베이스 파일에서 직접 편집된 값은 손상된 것으로 표시됩니다. 테스트 중 하나가 정확히 그 편집을 수행하고 잡히는지 확인합니다.

오래된 참조는 보고되며, 조용히 교체되지 않습니다. 패킷은 버전을 고정합니다. 상황이 변경되면 수신 에이전트에게 알려지며, 의도적으로 다시 읽을 수 있습니다. 대안(조용히 최신 버전 제공)은 에이전트가 계획이 기반하지 않은 데이터에 대해 행동하게 만듭니다.

신뢰도는 결과를 따르며 0..1 내에 유지됩니다. 성공은 1에 대한 간격의 일부를 닫고, 실패는 축소하므로 반복된 증거는 가장자리에 고정되지 않고 접근합니다. 승수는 src/models.ts의 한 테이블에 있습니다.

네트워크, 데몬, 네이티브 모듈이 필요 없습니다. 저장소는 node:sqlite, 전송은 stdio입니다. 전체는 node 프로세스와 파일입니다.

SenseLab AMFS

이 프로젝트는 SenseLab의 AMFS TypeScript SDK에서도 실행됩니다. src/amfs/sqlite-adapter.ts는 SQLite에서 SenseLab의 AmfsAdapter 계약을 구현합니다. SenseLab의 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 참조.