session-migrator

Inglés | 中文

Una capa de migración de memoria de sesión entre agentes: migra o comprime automáticamente una conversación según la capacidad de la ventana de contexto del modelo de destino.

¿Qué problema resuelve?

El agente 1 tiene una conversación en curso que debe entregarse al agente 2, pero los dos agentes usan modelos diferentes con ventanas de contexto distintas. Las reglas son sencillas:

• Si en el modelo de destino cabe toda la conversación → migrarla tal cual, sin compresión;

• Si no cabe → conservar solo el contexto más valioso (los mensajes más recientes primero).

Related MCP server: OpenAI Assistant MCP Server

Estructura de directorios

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

Inicio rápido

1. Ejecuta primero la lógica principal (cero dependencias)

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

Ambos usan solo la biblioteca estándar. No se necesita instalación — verás enseguida «decisión + compresión + almacenamiento» funcionando de principio a fin.

2. Ejecútalo como servidor MCP

pip install mcp
python -m session_migrator.server

3. Conéctalo a cualquier cliente MCP

Usando Claude Code como ejemplo, añade esto al .mcp.json del proyecto (o a tu configuración global):

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

Cursor / Codex / WorkBuddy o cualquier cliente que admita MCP stdio funciona de la misma manera. Una vez conectado, el agente puede llamar a model_context_window, list_known_models y migrate_session.

4. Configura la API del LLM (solo necesaria para el «resumen temático»)

Para comprimir una sesión de Codex en memoria estructurada, necesitas un LLM compatible con OpenAI. deepseek / OpenAI / cualquier servicio compatible con /chat/completions funciona — solo tienes que definir una variable de entorno:

export DEEPSEEK_API_KEY="sk-xxx"          # or OPENAI_API_KEY

Las tres herramientas MCP principales no lo requieren (solo hacen compresión por decisión / truncamiento, sin llamadas al LLM).

Herramientas MCP

El messages_json de migrate_session tiene este aspecto:

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

Conceptos principales

Motor de decisión decide(session, target_model)

El criterio es «¿puede la capacidad de destino contener el recuento real de tokens de la sesión?», no simplemente comparar las capacidades de los dos modelos — incluso si la capacidad de destino es menor que la del modelo de origen, una sesión pequeña se migra tal cual.

Compresor TruncationCompressor

La implementación por defecto tiene cero dependencias externas: conserva mensajes completos retrocediendo desde el más reciente, omite los anteriores que no caben e inserta una nota de marcador de posición al principio (cantidad omitida + vista previa del mensaje más antiguo).

Resumen temático (Codex → memoria)

Proceso completo para migrar una sesión de Codex a memoria estructurada (adaptador + 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

Versión de truncamiento sin LLM: codex_adapter.to_memory_markdown(session, meta).

Tabla de capacidades de modelos

session_migrator/context_windows.py incluye una tabla de mapeo estática (modelos de OpenAI / Anthropic / Google / chinos). Nota: estos son valores de reserva estáticos que pueden cambiar cuando los proveedores actualicen.

Hoja de ruta

• Resumen temático con LLM (llm_summarizer.py, consulta «Resumen temático»)

• Obtención dinámica de capacidades (llamar a la API /models de cada proveedor)

• Compresión reversible con margen (recuperar el texto original)

• Inyección de recuperación mediante almacén vectorial (recuperación bajo demanda)

• Recuento preciso de tokens con tiktoken

Licencia

MIT