session-migrator

English | 中文

A cross-agent session memory migration layer: automatically migrate or compress a conversation based on the target model's context window capacity.

What problem does it solve

Agent 1 has a conversation in progress that needs to be handed off to Agent 2, but the two agents use different models with different context windows. The rules are simple:

• If the target model fits the whole conversation → migrate as-is, no compression;
• If it doesn't fit → keep only the most valuable context (latest messages first).

Directory structure

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

Quick start

1. Run the core logic first (zero dependencies)

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

Both use only the standard library. No installation needed — you'll immediately see "decision + compression + storage" working end to end.

2. Run as an MCP server

pip install mcp
python -m session_migrator.server

3. Connect to any MCP client

Using Claude Code as an example, add this to the project .mcp.json (or your global config):

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

Cursor / Codex / WorkBuddy or any client that supports MCP stdio works the same way. Once connected, the agent can call model_context_window, list_known_models, and migrate_session.

4. Configure the LLM API (only needed for "topic summarization")

To compress a Codex session into structured memory, you need an OpenAI-compatible LLM. deepseek / OpenAI / any service compatible with /chat/completions works — just set an env var:

export DEEPSEEK_API_KEY="sk-xxx"          # or OPENAI_API_KEY

The three core MCP tools don't require it (they only do decision / truncation compression, no LLM calls).

MCP tools

Tool	Purpose
model_context_window(model)	Query a model's context window capacity
list_known_models()	List built-in models and their capacities
migrate_session(messages_json, source_model, target_model, ...)	Run migration, returns decision + migrated messages + token before/after

migrate_session's messages_json looks like:

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

Core concepts

Decision engine decide(session, target_model)

The criterion is "can the target capacity fit the session's actual token count", not simply comparing the two models' capacities — even if the target capacity is smaller than the source model, a small session still migrates as-is.

Compressor TruncationCompressor

The default implementation has zero external dependencies: it keeps whole messages working backward from the latest, omits earlier ones that don't fit, and inserts a placeholder note at the top (omitted count + preview of the earliest message).

Topic summarization (Codex → memory)

Full pipeline for migrating a Codex session into structured memory (adapter + 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

Non-LLM truncation version: codex_adapter.to_memory_markdown(session, meta).

Model capacity table

session_migrator/context_windows.py ships a static mapping table (OpenAI / Anthropic / Google / Chinese models). Note: these are static fallback values that may change as providers update.

Roadmap

• LLM topic summarization (llm_summarizer.py, see "Topic summarization")
• Dynamic capacity fetching (call each provider's /models API)
• Headroom reversible compression (recall original text)
• Vector-store retrieval injection (on-demand retrieval)
• Precise token counting with tiktoken

License

MIT