session-migrator

English | 中文

Слой миграции памяти сессий между агентами: автоматически переносит или сжимает диалог в зависимости от ёмкости окна контекста целевой модели.

Какую проблему это решает

У Агента 1 идёт диалог, который нужно передать Агенту 2, но эти два агента используют разные модели с разными окнами контекста. Правила просты:

• Если весь диалог помещается в целевую модель → переносим как есть, без сжатия;

• Если не помещается → сохраняем только самый ценный контекст (в первую очередь последние сообщения).

Related MCP server: OpenAI Assistant MCP Server

Структура каталога

session-migrator/
├── session_migrator/
│   ├── context_windows.py   # model capacity mapping table (the soul)
│   ├── exporter.py          # session export/serialization + token estimation
│   ├── decision.py          # decision engine: compare capacity → direct/compress
│   ├── compressors.py       # compressor: budget truncation, keeps latest
│   ├── storage.py           # shared storage: JSON files, per-workspace isolation
│   ├── codex_adapter.py     # Codex session → Session adapter
│   ├── llm_summarizer.py    # LLM topic summarization (deepseek/OpenAI-compatible)
│   ├── server.py            # MCP server entry (exposes migration tools)
│   └── __init__.py
├── examples/
│   ├── demo.py                     # full demo, zero dependencies
│   ├── codex_to_workbuddy_demo.py  # Codex → memory (truncation)
│   └── llm_summarize_demo.py       # Codex → memory (LLM topic summarization)
├── tests/test_core.py       # core logic tests
├── pyproject.toml
├── requirements.txt
└── LICENSE

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

1. Сначала запустите базовую логику (без зависимостей)

python examples/demo.py
python tests/test_core.py

Обе версии используют только стандартную библиотеку. Установка не нужна — вы сразу увидите, как «решение + сжатие + хранение» работают от начала до конца.

2. Запуск в качестве MCP-сервера

pip install mcp
python -m session_migrator.server

3. Подключение к любому MCP-клиенту

На примере Claude Code — добавьте это в .mcp.json проекта (или в глобальную конфигурацию):

{
  "mcpServers": {
    "session-migrator": {
      "command": "python",
      "args": ["-m", "session_migrator.server"]
    }
  }
}

Cursor / Codex / WorkBuddy или любой клиент, поддерживающий MCP stdio, работает так же. После подключения агент может вызывать model_context_window, list_known_models и migrate_session.

4. Настройка LLM API (нужно только для «тематического обобщения»)

Чтобы сжать сессию Codex в структурированную память, нужна LLM, совместимая с OpenAI. deepseek / OpenAI / любой сервис, совместимый с /chat/completions, подойдёт — достаточно задать переменную окружения:

export DEEPSEEK_API_KEY="sk-xxx"          # or OPENAI_API_KEY

Три основных MCP-инструмента в этом не нуждаются (они только принимают решение / выполняют усечение, без обращений к LLM).

Инструменты MCP

Параметр messages_json у migrate_session выглядит так:

[{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]

Ключевые концепции

Модуль принятия решения decide(session, target_model)

Критерий — «может ли целевая ёмкость вместить фактическое число токенов диалога», а не просто сравнение ёмкости двух моделей. Даже если ёмкость целевой модели меньше, чем у исходной, небольшой диалог всё равно переносится как есть.

Компрессор TruncationCompressor

Реализация по умолчанию не имеет внешних зависимостей: она сохраняет целые сообщения, двигаясь от последнего к ранним, отбрасывает ранние сообщения, которые не помещаются, и вставляет в начало примечание-заглушку (число пропущенных сообщений + превью самого раннего сообщения).

Тематическое обобщение (Codex → память)

Полный конвейер для переноса сессии Codex в структурированную память (адаптер + LLM):

from session_migrator.codex_adapter import get_thread_meta, extract_rollout
from session_migrator.llm_summarizer import summarize_session

meta = get_thread_meta("your-codex-thread-id")
session = extract_rollout(meta["rollout_path"], meta["id"], meta["model"])
markdown = summarize_session(session, meta, target_chars=5000)  # needs LLM key set first

Версия с усечением без LLM: codex_adapter.to_memory_markdown(session, meta).

Таблица ёмкости моделей

В session_migrator/context_windows.py поставляется статическая таблица соответствий (OpenAI / Anthropic / Google / китайские модели). Обратите внимание: это статические запасные значения, которые могут меняться по мере обновлений у провайдеров.

Дорожная карта

• Тематическое обобщение через LLM (llm_summarizer.py, см. «Тематическое обобщение»)

• Динамическое получение ёмкости (запрос к /models API каждого провайдера)

• Обратимое сжатие при наличии запаса контекста (восстановление исходного текста)

• Интеграция с векторным хранилищем (извлечение по запросу)

• Точный подсчёт токенов с помощью tiktoken

Лицензия

MIT