Agent Handoff Generation
Relevant source files
The following files were used as context for generating this wiki page:
Agent Handoff Generation creates structured context bundles to transfer state between different AI agents or sessions. In the target architecture, this process replaces the transfer of raw transcripts with summarized, high-confidence artifacts. This minimizes token usage and ensures continuity in long-running tasks.
The system uses Model Context Protocol (MCP) as the interface for these transfers. It primarily relies on the generate_handoff tool to package session data, architecture decisions, and promoted memories into a format suitable for the next agent.
Sources: README.md:1-15, CLAUDE.md:37-43, README.md:86-95
Architecture and Data Flow
The handoff process extracts data from the UnifiedSessionManager and packages it through the MCPToolsHandler. The current implementation utilizes session exports and analysis to simulate handoff state, while the target architecture defines generate_handoff as a dedicated stable tool.
Handoff Components
A handoff bundle includes the following key elements derived from the UnifiedSession model:
- Problem Statement and Success Criteria: The core objectives of the active task.
- Architecture Decisions: Chosen options and their rationales to prevent redundant exploration.
- Promoted Memories: High-confidence conclusions and implementation patterns.
- Session Analysis: Metadata regarding thoughts, branches, and discovered packages.
Sources: models.py:1-20, session_manager.py:465-480, README.md:39-45
Data Flow Diagram
The following diagram illustrates how session data moves from storage to a handoff artifact.
The flow demonstrates the transition from persistent markdown files to a consumable handoff bundle for the next agent.
Sources: session_manager.py:1-40, mcp_tools.py:12-25, CLAUDE.md:65-75
Handoff Generation Process
The generation process involves filtering ephemeral "scratch reasoning" and retaining only "promoted conclusions." This ensures the next agent receives actionable intelligence rather than raw chain-of-thought data.
1. Data Selection and Filtering
The system identifies durable machine memory. Ephemeral thoughts are generally excluded unless they represent a critical branch point.
2. Summary and Compaction
The system triggers compaction when the active context reaches specific triggers (e.g., 45K tokens). The handoff generator then creates a compact recovery artifact.
3. Serialization
The MCPToolsHandler serializes the data into either Markdown or JSON. JSON is preferred for machine-to-machine transfer, while Markdown serves as the human-readable canonical truth.
Sources: CLAUDE.md:27-35, README.md:73-82, mcp_tools.py:192-205
Key Implementation Elements
The following table describes the tools and data structures involved in handoff generation.
| Component | Type | Description |
|---|---|---|
generate_handoff | MCP Tool | (Target) Primary tool for creating state transfer bundles. |
export_session | MCP Tool | (Current) Exports session state to Markdown or JSON files. |
analyze_session | MCP Tool | Provides summary statistics of the current reasoning state. |
UnifiedSession | Class | The aggregate root containing all thoughts, memories, and decisions. |
ArchitectureDecision | Class | Records chosen options and rationales for architectural continuity. |
Sources: README.md:94-96, mcp_tools.py:167-200, models.py:1-15, session_manager.py:465-475
Sequence of Handoff Generation
This sequence diagram shows the interaction between the MCP client and the server during a handoff generation request.
The diagram shows how the handler aggregates data from the manager and memory bank to produce the final export.
Sources: mcp_tools.py:167-210, session_manager.py:465-500, tests/test_integration.py:340-365
Token Management Policy
Handoff generation adheres to specific token ceilings to ensure agents stay within operational limits.
- Active Context Ceiling: Target of 64K tokens.
- Compaction Trigger: Summarization occurs at 45K tokens.
- Transfer Efficiency: The system passes handoff bundles and summaries instead of raw transcripts to preserve the token budget.
Sources: CLAUDE.md:41-43, README.md:73-82
Summary
Agent Handoff Generation is a critical mechanism for project continuity in sequential-thinking-mcp-v2. By transitioning from raw reasoning logs to structured, summarized handoff bundles, the system enables efficient state transfer between agents. This process relies on the distinction between ephemeral scratchpad data and durable promoted conclusions, ensuring that the target context is high-quality and token-efficient.
Sources: README.md:17-25, CLAUDE.md:27-35