Agent Memory Bridge

Упрощенный китайский

Уровень памяти для агентов кодинга на базе MCP, который превращает реальные сессии в повторно используемую инженерную память.

Создано в первую очередь для Codex.

Agent Memory Bridge фиксирует то, что обычно теряется в истории чата:

• долгосрочные решения

• известные исправления

• передачу контекста между сессиями

• повторно используемые «подводные камни»

• компактные предметные знания

Основная идея проста: сделать уровень памяти небольшим, надежным и доступным для проверки. Пусть оркестрация более высокого уровня находится поверх него.

Самое интересное — это не просто сохранение данных. Это автоматическое формирование памяти:

• сессии становятся повторно используемыми learn (обучением)

• повторяющиеся ошибки становятся gotcha («подводными камнями»)

• кластеры уроков становятся компактными domain-note (предметными заметками)

Почему это существует

Большинство систем памяти агентов скатываются к одному из трех шаблонов:

• память заперта внутри одного приложения или одной модели

• тяжелая хостинговая инфраструктура до того, как доказана базовая эффективность извлечения

• свалка транскриптов вместо повторно используемых операционных знаний

Agent Memory Bridge выбирает более узкий путь:

• MCP-native с первого дня

• локально-ориентированная среда выполнения

• SQLite + FTS5 вместо тяжелой инфраструктуры

• автоматическое продвижение данных из сессий в повторно используемую память

Это не просто хранилище. Это конвейер формирования памяти:

session -> summary -> learn -> gotcha -> domain-note

Позиционирование

Agent Memory Bridge намеренно узкоспециализирован.

Если вам нужна более широкая платформа памяти с SDK, дашбордами, коннекторами и поддержкой приложений на нескольких поверхностях, такие проекты, как OpenMemory или Mem0, ближе к этой форме.

Этот проект намеренно отличается:

1. Он создан для рабочих процессов агентов кодинга, а не для хранения общих заметок.

2. Он намеренно сохраняет поверхность MCP небольшой: store и recall.

3. Он преобразует необработанные результаты сессий в компактную машиночитаемую память, вместо того чтобы рассматривать сводки как конечный артефакт.

4. Он по умолчанию ориентирован на локальное использование и доступен для проверки.

Более подробную информацию о позиционировании см. в docs/COMPARISON.md.

Как это работает

Среда выполнения состоит из четырех основных частей:

1. MCP-сервер

   • предоставляет store и recall

2. наблюдатель (watcher)

   • отслеживает файлы развертывания Codex

   • записывает session-seen, checkpoint и closeout

3. рефлекс (reflex)

   • продвигает сводки в learn, gotcha и signal

4. консолидация

   • синтезирует повторяющиеся записи learn и gotcha в предметные заметки

Это делает систему понятной:

• необработанные сессии не являются конечной памятью

• сводки не являются конечной памятью

• долгосрочная память ориентирована на машину

• синтез происходит после продвижения

Быстрый старт

Требования:

• Python 3.11+

• Codex с включенным MCP

• SQLite с поддержкой FTS5

1. Установка

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .[dev]

2. Создание конфигурации моста

Скопируйте config.example.toml в:

$CODEX_HOME/mem-bridge/config.toml

Рекомендуемая настройка:

• храните активную базу данных SQLite локально на каждой машине

• храните общие профили или хранилища исходного кода на NAS или общем сетевом диске, если это необходимо

• переходите на хостинговый бэкенд позже, если вам нужна настоящая живая запись с нескольких машин

3. Регистрация MCP-сервера в Codex

Добавьте это в $CODEX_HOME/config.toml:

[mcp_servers.agentMemoryBridge]
command = "D:\\path\\to\\agent-memory-bridge\\.venv\\Scripts\\python.exe"
args = ["-m", "agent_mem_bridge"]
cwd = "D:\\path\\to\\agent-memory-bridge"

[mcp_servers.agentMemoryBridge.env]
CODEX_HOME = "%USERPROFILE%\\.codex"
AGENT_MEMORY_BRIDGE_HOME = "%USERPROFILE%\\.codex\\mem-bridge"
AGENT_MEMORY_BRIDGE_CONFIG = "%USERPROFILE%\\.codex\\mem-bridge\\config.toml"

4. Запуск службы

Запустите MCP-сервер:

.\.venv\Scripts\python.exe -m agent_mem_bridge

Запустите фоновую службу моста:

.\.venv\Scripts\python.exe .\scripts\run_mem_bridge_service.py

Запустите только один цикл:

$env:AGENT_MEMORY_BRIDGE_RUN_ONCE = "1"
.\.venv\Scripts\python.exe .\scripts\run_mem_bridge_service.py

Опциональная установка при запуске:

.\scripts\install_startup_watcher.ps1

Опционально: сборка локального Docker-образа

docker build -t agent-memory-bridge:local .
docker --context desktop-linux run --rm -i agent-memory-bridge:local

Точка входа контейнера запускает stdio MCP-сервер с помощью python -m agent_mem_bridge.

Основной API

Поверхность MCP намеренно мала:

• store

• recall

Общие поля store:

• namespace

• content

• kind

• tags

• session_id

• actor

• title

• correlation_id

• source_app

Общие поля recall:

• namespace

• query

• kind

• tags_any

• session_id

• actor

• correlation_id

• since

• limit

Типичные пространства имен (Namespaces)

• project:<workspace>

• global

• domain:<name>

• импортированные пространства имен профилей, когда они нужны команде

Фреймворк не зависит от профиля. Конкретный профиль оператора может быть наложен сверху, но сам мост не привязан к одной личности или одному протоколу.

Повседневное использование

Предполагаемая многослойность:

• профиль оператора системного уровня

• субстрат памяти системного уровня: agentMemoryBridge

• локальные переопределения проекта: AGENTS.md

Протокол запуска задокументирован в docs/STARTUP-PROTOCOL.md.

Вкратце:

1. вспомнить глобальную рабочую память

2. вспомнить соответствующую специализированную память

3. если рабочая область существует, вспомнить project:<workspace>

4. для задач, похожих на тикеты, проверить локальную память и «подводные камни» перед внешним поиском

5. проверить живой код, прежде чем доверять извлеченным деталям реализации

Полезные команды

Запуск тестов:

.\.venv\Scripts\python.exe -m pytest

Запуск smoke-теста stdio:

.\.venv\Scripts\python.exe .\scripts\verify_stdio.py

Запуск бенчмарка:

.\.venv\Scripts\python.exe .\scripts\run_benchmark.py

Запуск проверки работоспособности моста:

.\.venv\Scripts\python.exe .\scripts\run_healthcheck.py --report-path .\examples\healthcheck-report.json

Принудительная контрольная точка из последнего развертывания:

.\.venv\Scripts\python.exe .\scripts\sync_now.py

Структура проекта

Репозиторий намеренно мал:

src/agent_mem_bridge/   canonical implementation
scripts/                operational entrypoints
tests/                  verification
docs/                   design and roadmap
examples/               sanitized demo artifacts

Файлы, которые имеют наибольшее значение:

• src/agent_mem_bridge/server.py

• src/agent_mem_bridge/storage.py

• src/agent_mem_bridge/watcher.py

• src/agent_mem_bridge/reflex.py

• src/agent_mem_bridge/consolidation.py

• src/agent_mem_bridge/service.py

Дизайнерские решения

Малая поверхность MCP

Мост предоставляет только store и recall. Это делает контракт стабильным и простым для интеграции.

Локально-ориентированная среда выполнения

Активная БД по умолчанию остается локальной, потому что SQLite на общем сетевом хранилище — это ловушка для надежности.

Память, ориентированная на машину

Агенты являются основными читателями, поэтому память отдает предпочтение:

• компактным полям

• стабильным тегам

• низкой стоимости токенов

вместо отполированной прозы.

Многоуровневое продвижение

Система пытается двигаться вверх:

• summary

• learn

• gotcha

• domain-note

вместо того, чтобы рассматривать необработанные сводки как конечный артефакт.

Статус

Текущая основа работает:

• автозагрузка MCP работает в Codex

• синхронизация проекта и сессии работает

• рабочие процессы с приоритетом извлечения (recall-first) работают

• продвижение рефлексов работает

• консолидация предметных областей первого прохода работает

Проверка реальности и дорожная карта:

• docs/PRODUCTION-STATUS.md

• docs/ROADMAP.md

Импорт профилей

Фреймворк может размещать импортированные профили операторов, но сам фреймворк остается агностичным к профилям.

Документация

• README.zh-CN.md

• CONTRIBUTING.md

• AGENTS.md

• docs/COMPARISON.md

• docs/STARTUP-PROTOCOL.md

• docs/MEMORY-TAXONOMY.md

• docs/PROMOTION-RULES.md

• docs/MODEL-ROUTING.md

• docs/ROADMAP.md

Лицензия

MIT. См. LICENSE.