session-migrator

English | 中文

Eine agentenübergreifende Sitzungsspeicher-Migrationsebene: Migriert oder komprimiert automatisch eine Konversation basierend auf der Kontextfenster-Kapazität des Zielmodells.

Welches Problem löst es?

Agent 1 führt eine Konversation, die an Agent 2 übergeben werden muss, aber die beiden Agenten verwenden unterschiedliche Modelle mit unterschiedlichen Kontextfenstern. Die Regeln sind einfach:

• Wenn das Zielmodell die gesamte Konversation aufnehmen kann → Migration ohne Komprimierung;

• Wenn es nicht passt → nur den wertvollsten Kontext behalten (neueste Nachrichten zuerst).

Related MCP server: OpenAI Assistant MCP Server

Verzeichnisstruktur

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

Schnellstart

1. Kernlogik zuerst ausführen (keine Abhängigkeiten)

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

Beide verwenden nur die Standardbibliothek. Keine Installation erforderlich – Sie sehen sofort „Entscheidung + Komprimierung + Speicherung" Ende-zu-Ende funktionieren.

2. Als MCP-Server ausführen

pip install mcp
python -m session_migrator.server

3. Mit einem beliebigen MCP-Client verbinden

Am Beispiel von Claude Code: Fügen Sie dies zur Projekt-.mcp.json (oder Ihrer globalen Konfiguration) hinzu:

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

Cursor / Codex / WorkBuddy oder jeder Client, der MCP stdio unterstützt, funktioniert auf die gleiche Weise. Sobald die Verbindung hergestellt ist, kann der Agent model_context_window, list_known_models und migrate_session aufrufen.

4. LLM-API konfigurieren (nur für „Themenzusammenfassung" erforderlich)

Um eine Codex-Sitzung in strukturierten Speicher zu komprimieren, benötigen Sie ein OpenAI-kompatibles LLM. deepseek / OpenAI / jeder Dienst, der mit /chat/completions kompatibel ist, funktioniert – setzen Sie einfach eine Umgebungsvariable:

export DEEPSEEK_API_KEY="sk-xxx"          # or OPENAI_API_KEY

Die drei Kern-MCP-Tools benötigen dies nicht (sie führen nur Entscheidungs-/Kürzungskomprimierung durch, keine LLM-Aufrufe).

MCP-Tools

Das messages_json von migrate_session sieht so aus:

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

Kernkonzepte

Entscheidungs-Engine decide(session, target_model)

Das Kriterium ist „kann die Zielkapazität die tatsächliche Token-Anzahl der Sitzung aufnehmen", nicht einfach der Vergleich der Kapazitäten der beiden Modelle – selbst wenn die Zielkapazität kleiner ist als das Quellmodell, wird eine kleine Sitzung trotzdem unverändert migriert.

Kompressor TruncationCompressor

Die Standardimplementierung hat keine externen Abhängigkeiten: Sie behält ganze Nachrichten, die von der neuesten rückwärts arbeiten, lässt frühere, die nicht passen, weg und fügt oben einen Platzhalterhinweis ein (Anzahl der weggelassenen + Vorschau der ältesten Nachricht).

Themenzusammenfassung (Codex → Speicher)

Vollständige Pipeline zum Migrieren einer Codex-Sitzung in strukturierten Speicher (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

Nicht-LLM-Kürzungsversion: codex_adapter.to_memory_markdown(session, meta).

Modellkapazitätstabelle

session_migrator/context_windows.py enthält eine statische Zuordnungstabelle (OpenAI / Anthropic / Google / chinesische Modelle). Hinweis: Dies sind statische Fallback-Werte, die sich ändern können, wenn Anbieter aktualisieren.

Roadmap

• LLM-Themenzusammenfassung (llm_summarizer.py, siehe „Themenzusammenfassung")

• Dynamische Kapazitätsabfrage (Aufruf der /models-API jedes Anbieters)

• Umkehrbare Komprimierung mit Headroom (ursprünglichen Text abrufen)

• Vektor-Speicher-Retrieval-Injektion (On-Demand-Retrieval)

• Präzise Token-Zählung mit tiktoken

Lizenz

MIT