Session State and Continuation
Relevant source files
The following files were used as context for generating this wiki page:
Session State and Continuation management in the project ensures that long-running tasks, complex multi-step workflows, and transitions between different AI agent sessions maintain perfect context and architectural integrity. This system prevents context loss, which typically occurs due to token limit exhaustion or session degradation, by utilizing dedicated "Drafts," "Plans," and "Handoff" mechanisms.
The architecture relies on a structured hierarchy of state artifacts stored within the .sisyphus/ directory, allowing agents like Prometheus (the Planner) and Sisyphus (the Orchestrator) to hand off work seamlessly to specialized subagents or to a new session entirely. Sources: src/agents/prometheus/identity-constraints.ts, src/features/builtin-commands/templates/handoff.ts
State Management Artifacts
The system utilizes specific file-based artifacts to maintain state across agent turns and sessions.
Drafts as Working Memory
Prometheus uses draft files located at .sisyphus/drafts/{name}.md as an external "backup brain." This is mandatory during the interview phase to prevent memory loss in long conversations.
- Continuous Recording: Requirements, technical decisions, and research findings are recorded after every meaningful user response.
- Structure: Drafts include sections for confirmed requirements, technical choices with rationale, research findings from explore/librarian agents, open questions, and defined scope boundaries.
Sources: src/agents/prometheus/identity-constraints.ts:167-195, src/agents/prometheus/gpt.ts:133-149
Detailed Work Plans
The primary artifact for execution state is the Work Plan, stored at .sisyphus/plans/{plan-name}.md.
- Single Plan Mandate: Regardless of task size, all work must be consolidated into one plan to avoid context fragmentation.
- Decision Completeness: Plans must be "decision complete," meaning the executor (Atlas or Sisyphus) requires zero judgment calls to proceed.
Sources: src/agents/prometheus/identity-constraints.ts:121-137, src/agents/prometheus/gpt.ts:28-30
| Artifact Type | Path | Purpose |
|---|---|---|
| Draft | .sisyphus/drafts/*.md | Temporary memory for requirements gathering and active discussion. |
| Plan | .sisyphus/plans/*.md | The finalized, immutable (for the executor) source of truth for work. |
| Notepad | .sisyphus/notepads/{name}/*.md | Shared learnings, issues, and architectural decisions used during orchestration. |
| Sources: src/agents/prometheus/identity-constraints.ts:114-118, src/agents/atlas/gemini-prompt-sections.ts:54-58 |
Handoff and Continuation Logic
Continuation is handled through two primary mechanisms: the /handoff command and "Compaction Context Injection."
The Handoff Workflow
The /handoff template defines a multi-phase process to transition work to a new session when quality degrades or context windows fill up.
Description: The sequence of gathering programmatic state and formatting it for a new session.
Sources: src/features/builtin-commands/templates/handoff.ts:1-122
Compaction Context Prompt
When sessions undergo compaction (summarization to save tokens), a specific prompt ensures critical metadata is preserved.
- Agent Verification State: Tracks which agent is running (e.g., Momus, Oracle) and the progress of verification.
- Delegated Sessions: A list of all active background agent tasks, including their
session_id, to allow resuming instead of restarting.
Sources: src/hooks/compaction-context-injector/compaction-context-prompt.ts:1-55
Task Tracking and Verification State
Sisyphus and Atlas use a TodoWrite mechanism to track multi-step work.
Todo/Task Lifecycle
- Creation: Tasks are created via
TaskCreateortodowritebefore starting any non-trivial work. - In-Progress: Agents must update status to
in_progressbefore starting a step. - Completion: Each step is marked
completedimmediately upon verification.
Sources: src/agents/sisyphus/default.ts:25-45, src/agents/prometheus/gpt.ts:184-194
Session Continuity via session_id
For delegated work, the system enforces the reuse of session_id.
- Resume, Don't Restart: If a task fails or needs verification, the same session must be resumed using its ID to preserve the subagent's accumulated context.
- Benefits: Saves up to 70% in token costs and prevents redundant file exploration.
Sources: src/agents/sisyphus/default.ts:211-231, src/agents/atlas/gemini-prompt-sections.ts:153-157
Orchestration and Boulder State
Atlas, the Master Orchestrator, manages the high-level state of a plan (the "boulder").
Description: Atlas's loop for managing task execution and plan status updates.
Sources: src/agents/atlas/gemini-prompt-sections.ts:44-150, src/agents/atlas/gemini-prompt-sections.ts:182-192
Final Verification Wave
The session reaches "completion" only after the Final Verification Wave (tasks F1-F4). These are approval gates where multiple reviewers (e.g., Oracle, Deep Reviewer) must provide an APPROVE verdict before the work is considered complete. Sources: src/agents/atlas/gemini-prompt-sections.ts:162-178, src/agents/prometheus/gpt.ts:311-316
Summary
The Session State and Continuation system is a robust framework designed to ensure AI agents operate with long-term consistency. By externalizing state into Drafts and Plans and utilizing session_id for continuation, the project overcomes LLM context window limitations, enabling complex software engineering tasks to be performed across multiple turns and sessions with high reliability. Sources: src/agents/prometheus/identity-constraints.ts, src/agents/sisyphus/default.ts