session-migrator
Allows using OpenAI's API (or any OpenAI-compatible service) for LLM-based topic summarization of conversations during session migration, compressing a full session into structured memory markdown.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@session-migrator Migrate this session from Claude Sonnet to GPT-4o mini, compressing if needed."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
session-migrator
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).
Related MCP server: agentfit-mcp
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
└── LICENSEQuick start
1. Run the core logic first (zero dependencies)
python examples/demo.py
python tests/test_core.pyBoth 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.server3. 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_KEYThe three core MCP tools don't require it (they only do decision / truncation compression, no LLM calls).
MCP tools
Tool | Purpose |
| Query a model's context window capacity |
| List built-in models and their capacities |
| 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 firstNon-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
/modelsAPI)Headroom reversible compression (recall original text)
Vector-store retrieval injection (on-demand retrieval)
Precise token counting with tiktoken
License
MIT
Available Tools
3 toolslist_known_modelsB
列出内置映射表里已知的模型及其容量。
Inputs: no named parameters.
migrate_sessionA
把一个会话从源模型迁移到目标模型。
messages_json: JSON 数组字符串,形如 [{"role": "user", "content": "..."}, {"role": "assistant", "content": "..."}]
返回:决策(action / reason / 容量对比)+ 迁移后的消息数组 + token 前后对比。
Inputs: source_model (required), target_model (required), messages_json (required), session_id, +1 more.
model_context_windowB
查询某个模型的上下文窗口容量(token 数)。
Inputs: model (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
每个工具职责明确:一个查询具体模型容量,一个列出所有已知模型,一个执行会话迁移。三者之间没有功能重叠或模糊边界。
list_known_models和migrate_session遵循动词_名词模式,但model_context_window是名词短语,缺少动词前缀,构成轻微偏差。整体命名仍可读且可预测。
3个工具对于会话迁移这一窄领域非常合适,每个工具都服务于核心流程,没有冗余或缺失。
覆盖了迁移会话所需的全部关键操作:查看模型容量、列出已知模型、执行迁移并返回结果对比。没有明显的功能缺口。
Maintenance
Related MCP Connectors
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Multiple MCP tools, persistent graph memory, token-saving data pointers, and more.
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides context compression via the tokenslim engine, enabling MCP hosts to reduce token usage while preserving key information. Offers compress, retrieve, and stats tools for managing compressed content.Apache 2.0
- AlicenseAqualityDmaintenanceLets Claude Desktop, Cursor, Cline, Windsurf, Zed, or any other MCP client estimate token counts and fit a chat history into a model's context budget on demand.345 npm1MIT
- AlicenseNot gradedqualityBmaintenanceProvides MCP tools to profile and optimize LLM conversation context, identifying token waste and applying deterministic fixes to reduce context window usage.1,207 npm3MIT
- FlicenseAqualityDmaintenanceEnables LLM chat with routing and failover, balance checking, and model listing via MCP.3-