Context Truncation & Compaction
Relevant source files
The following files were used as context for generating this wiki page:
Context Truncation and Compaction refers to the systematic management of the LLM context window to maintain performance, accuracy, and continuity in long-running software engineering sessions. As sessions grow in complexity—involving multiple file edits, background research, and tool calls—the system employs specialized agents and protocols to summarize working state, track essential constraints, and enable seamless session transitions through handoff mechanisms.
This system is critical for agents like Hephaestus and Prometheus, which operate in "autonomous deep worker" or "strategic consultant" modes where the volume of gathered research and discussion can quickly overwhelm raw context limits.
Core Management Strategies
The project implements several layers of context management to ensure that "AI slop" is avoided and that the agent remains anchored to the original user request despite long-running execution loops.
Response Compaction & State Tracking
Agents are instructed to periodically summarize their internal working state. This involves tracking modified files, changes made, and completed verifications to prevent losing track of the original request across many tool calls. This is particularly relevant for the Hephaestus agent during repository-scale architecture refactoring.
Sources: src/agents/hephaestus.ts:446-451, src/agents/hephaestus.ts:543-548
Working Memory via Drafts
The Prometheus agent utilizes a mandatory "Draft as Working Memory" protocol. During the interview phase, decisions, requirements, and research findings are continuously recorded to a persistent markdown file (.sisyphus/drafts/{name}.md). This draft serves as an "external memory" that survives beyond the immediate context window, ensuring that the subsequent Plan Generation phase has access to the complete conversation history even if the raw context is truncated.
Sources: src/agents/prometheus/identity-constraints.ts:133-149, src/agents/prometheus/interview-mode.ts:252-263
Handoff Protocol
When context length leads to quality degradation or approaches window limits, the /handoff command is used to synthesize a fresh starting point. This process programmatically extracts the "Goal," "Work Completed," and "Pending Tasks" while preserving verbatim user requests and explicit constraints.
The diagram above shows the lifecycle of a handoff to manage context overflow.
Sources: src/features/builtin-commands/templates/handoff.ts:15-55
Component Roles in Context Management
| Component | Role in Management | Primary Mechanism |
|---|---|---|
| Prometheus | Strategic Continuity | Continuous Draft updates during Interview Mode to prevent loss of requirements. |
| Hephaestus | Execution Anchoring | "Todo Discipline" ensures work doesn't drift during deep autonomous cycles. |
| Handoff Template | Fresh Start Logic | Programmatic extraction of session metadata to reset the context window. |
| Sisyphus System | Orchestration | Coordinates subagents (Librarian/Explore) and provides session IDs for continuity. |
Sources: src/agents/hephaestus.ts:23-40, src/agents/prometheus/identity-constraints.ts:151-168, src/features/builtin-commands/templates/handoff.ts:70-110
Implementation Details
Session Continuity via IDs
To maximize efficiency and preserve specific context within sub-tasks, the system uses session_id passing. When an agent (like Librarian or Explore) is resumed, passing the ID preserves the full context of that sub-task's history without needing to re-send all previous data as part of the primary agent's prompt.
Sources: src/agents/hephaestus.ts:403-413, src/features/builtin-commands/templates/handoff.ts:25-30
Handoff Context Structure
The handoff summary is strictly formatted to ensure that the "next" agent has exactly what is needed to continue implementation without fluff.
HANDOFF CONTEXT
===============
USER REQUESTS (Verbatim)
GOAL (One sentence)
WORK COMPLETED (Bullet points)
PENDING TASKS (Verbatim from Todo list)
KEY FILES (Max 10 prioritized files)
EXPLICIT CONSTRAINTS (Verbatim)
Sources: src/features/builtin-commands/templates/handoff.ts:72-105
Automated Cleanup
To prevent "leakage" or unnecessary context bloat, agents are required to cancel all background tasks (background_cancel(all=true)) before delivering a final answer to the user. This ensures that the next turn starts with a clean slate regarding active background processes.
Sources: src/agents/hephaestus.ts:238-245
Conclusion
Context Truncation & Compaction in this project is not merely about deleting old text, but about intentional state preservation. By using persistent Draft files, detailed Handoff summaries, and strict Todo discipline, the project ensures that high-accuracy engineering work can continue across sessions and deep reasoning cycles without losing sight of user constraints or project patterns.