Ebb — граф знаний, ориентированный на агентов

Долговременная память для ИИ-агентов, построенная как граф. Релевантность — это взвешенная по недавности сила связей: повторное использование знаний сохраняет их живыми, неиспользуемые знания затухают и архивируются, и ничего не удаляется, пока человек не даст добро. Работает во встроенном режиме (без инфраструктуры) или на Neo4j (продакшн).

Два механизма, на которых он построен — релевантность, взвешенная по связям, и временное затухание — являются нативными графовыми операциями, и оба имеют глубокую предысторию (PageRank/центральность; базовая активация ACT-R и распространение активации из когнитивной науки; кривые забывания при интервальном повторении). Это небольшая, честная реализация этой линии, нацеленная именно на память агентов.

Почему это устроено так

1. Движок и интерфейс разделены. Хранилище графа находится за небольшим интерфейсом (GraphStore). Агенты и логика оценки никогда не касаются конкретной базы данных, поэтому вы можете запустить тот же самый граф на встроенном движке сегодня и переключиться на Neo4j позже с помощью одной переменной окружения.

2. Релевантность взвешивается по недавности, а не по сырому количеству связей. «Больше связей = более релевантно» вознаграждает старые, часто упоминаемые данные вечно — это та самая проблема устаревших данных, которую система призвана устранить. Здесь вклад каждого ребра в релевантность умножается на коэффициент временного затухания, привязанный к моменту последнего подкрепления связи. Ребро, подкреплённое вчера, учитывается почти полностью; то, к которому обращались шесть месяцев назад, почти не учитывается. Повторное использование связи (recall/reinforce) сбрасывает её часы — так что релевантность отслеживает то, что действительно живо, а устаревшие знания тонут сами собой.

Доказательство из демонстрационного графа (python -m ebb.demo):

node                             raw#   activation
decision:outcome-pricing            3        6.116   <- fresh, few links, ranks #1
decision:seat-pricing              11        3.077   <- MOST links, ranks #3
...
note:analysis-* (x10)               1        0.051   <- decayed -> archived (tier 4)

Устаревшее решение о цене за место имеет самое высокое сырое количество связей в графе и всё равно занимает третье место, уступая свежему решению с втрое меньшим числом связей. Сырое количество проиграло; недавность победила.

Related MCP server: Memory Engine MCP

Что внутри

• Графовая модель — каждая заметка, решение, встреча, человек, клиент, факт — это узел; каждая ссылка — это ребро с временной меткой, типом и весом.

• Движок оценки (scoring.py) — активация с учётом недавности, экспоненциальное затухание (настраиваемый период полураспада), один шаг распространения активации (переносимая замена PageRank) и назначение уровней. Чистые функции, полностью покрыты юнит-тестами.

• Четыре уровня архивации — 1 горячий (по умолчанию для recall) · 2 тёплый (более глубокий recall) · 3 холодный (архивирован, только по запросу) · 4 замороженный (ожидает подтверждения человеком перед удалением). Закреплённые узлы никогда не архивируются автоматически.

• MCP-сервер (mcp_server.py) — интерфейс агента: remember, recall, connect, reinforce, forget, neighbors, pin, maintain, review_queue, stats.

• Два бэкенда — KuzuStore (встроенный, по умолчанию) и Neo4jStore (продакшн), одинаковый интерфейс, одинаковые формы Cypher.

Быстрый старт (встроенный — без инфраструктуры)

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python -m ebb.demo      # narrated end-to-end walkthrough
pytest -q                 # 11 tests, all green

Никакого Docker, сервера и портов. Kùzu — это встраиваемая графовая база данных, поэтому Ebb — это просто папка (./ebb_db).

Подключение к MCP-клиенту (например, Claude Desktop)

1. Скопируйте блок ebb из claude_desktop_config.example.json в конфигурацию MCP вашего клиента, исправив абсолютные пути.

2. Перезапустите клиент. Инструменты ebb появятся в меню инструментов.

3. Теперь агент может remember (запоминать) информацию между сессиями, recall (вызывать) релевантное и reinforce (подкреплять) то, что продолжает использовать — затухание и архивация обрабатываются автоматически.

Продакшн-режим (Neo4j)

docker compose up -d      # Neo4j + Graph Data Science + APOC
EBB_BACKEND=neo4j NEO4J_PASSWORD=brainbrain python -m ebb.demo

Тот же код, то же поведение. На Neo4j вы дополнительно получаете библиотеку GDS, так что проход распространения активации в scoring.py может перерасти в настоящий PageRank / центральность / обнаружение сообществ, когда потребует масштаб. (Cypher-запросы бэкенда Neo4j повторяют полностью протестированный бэкенд Kùzu; запустите pytest на живом экземпляре, прежде чем доверять ему в проде.)

Модель вкратце

Активация узла = Σ (edge.weight × decay(age_since_last_reinforced)) + read-recency-bonus, плюс один затухающий шаг того же от его соседей. Затухание — это период полураспада (по умолчанию 30 дней, настраивается). Уровни определяются по активации, нормализованной относительно самого активного незакреплённого узла. recall смешивает эту активацию с текстовым совпадением запроса и возвращает почему каждый результат всплыл. Всё настраивается в одном месте — ebb/scoring.py::Config.

Написание адаптера приёма данных

Ebb не зависит от источника: всё, что вызывает remember/connect, может его питать. Источник (папка заметок, вики, трекер задач) становится графом путём сопоставления документов с узлами, ссылок/упоминаний с рёбрами, а временной метки редактирования с часами недавности. Держите адаптеры и их данные вне репозитория.

Структура

src/ebb/
  model.py        # Node, Edge, tiers
  scoring.py      # decay, activation, spreading, tiering  <- the core
  store.py        # GraphStore interface
  kuzu_store.py   # embedded backend (default)
  neo4j_store.py  # production backend
  engine.py       # Brain: remember/recall/connect/reinforce/maintain/...
  mcp_server.py   # agent-facing MCP tools
  seed.py         # fictional demo graph
  demo.py         # narrated walkthrough
tests/            # 11 tests: scoring + end-to-end
docker-compose.yml

Лицензия

MIT — см. LICENSE.