agent-handoff-memory

MCP-сервер, который предоставляет нескольким агентам одну общую версионированную память — и явный пакет передачи (handoff packet), чтобы следующий сеанс начинался с того места, где закончился предыдущий, а не пересоздавал всё заново.

Агенты теряют свой контекст на границе сеанса. Обычное решение — сбросить стенограмму в промпт и надеяться, что следующий запуск выберет из неё нужное предложение. Пакет передачи — это противоположность: короткий структурированный объект, который сообщает, что было сделано, что нужно сделать дальше, что остаётся неясным и с каких именно версий записей начинать — и принимающий агент получает эти версии разрешёнными в том же вызове, с предупреждением о тех, которые с тех пор изменились.

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

Проект также работает на TypeScript SDK SenseLab AMFS. src/amfs/sqlite-adapter.ts реализует контракт AmfsAdapter SenseLab на SQLite — их AgentMemory занимается рассуждениями, этот — запоминанием — а demo/amfs-bridge.ts пересказывает пошаговое руководство по передаче через их API:

npm run demo:amfs

SDK поставляется с адаптером в памяти (исчезает при завершении процесса) и HTTP-адаптером (требует хостируемой конечной точки и ключа); этот заполняет пробел между ними, а заодно заполняет contentHash / integrityChain и отвечает на commitLog(), который адаптер в памяти оставляет пустым. Тест на паритетность запускает один и тот же сеанс через оба адаптера и сравнивает результаты.

То, что я измерил во время его создания — включая то, почему commitOutcome(SUCCESS) снижает уверенность в версии 0.3.2 — описано в docs/senselab-amfs.md.

Тесты

npm test

29 тестов, охватывающих хранилище, жизненный цикл передачи, поверхность MCP (реальный клиент и сервер, соединённые транспортом в памяти, так что схемы инструментов также проверяются) и адаптер AMFS. Группа 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.