Session Recovery & Persistence
Relevant source files
The following files were used as context for generating this wiki page:
Session Recovery and Persistence in Oh-My-OpenCode is a critical architectural pattern designed to ensure that AI agents maintain state, context, and progress across long-running tasks, multi-turn dialogues, and potential system interruptions. The system utilizes a combination of "Drafts" for working memory during planning, "Work Plans" for execution anchoring, and "Notepads" for cumulative intelligence during delegation.
The primary goal of this system is to prevent context loss in complex workflows and enable "Sisyphus" and other agents to resume work seamlessly. It transforms the stateless nature of LLMs into a stateful execution environment by persisting intermediate decisions and findings to the filesystem within the .sisyphus/ directory.
Sources: src/agents/prometheus/identity-constraints.ts:167-185, src/agents/sisyphus.ts:54-65, src/agents/atlas/default.ts:133-145
Architectural Components
The persistence layer is divided into three distinct stages of the task lifecycle: Interview, Planning, and Execution.
1. Drafts as Working Memory
During the initial requirement gathering phase (Interview Mode), the Prometheus agent is mandated to continuously record user decisions, research findings, and technical choices into a draft file. This serves as an "external memory" beyond the context window.
- Path:
.sisyphus/drafts/{name}.md - Update Trigger: After every meaningful user response or agent research result.
Sources: src/agents/prometheus/identity-constraints.ts:167-185
2. Work Plans as Execution Anchors
Once requirements are cleared, a formal Work Plan is generated. This file acts as the definitive source of truth for the execution phase. It contains the dependency matrix, parallel execution waves, and granular TODOs with specific acceptance criteria.
- Path:
.sisyphus/plans/{plan-name}.md - Mandate: All tasks for a request must exist in a single atomic work plan to avoid lost context between sessions.
Sources: src/agents/prometheus/identity-constraints.ts:135-150, src/agents/prometheus/plan-generation.ts:80-85
3. Notepads for Cumulative Intelligence
During the orchestration phase, Atlas uses a "Notepad" system to provide state for stateless subagents. Before every delegation, Atlas reads these notepads to extract "Inherited Wisdom" (conventions, decisions, and issues) and passes them into the subagent's prompt.
- Directory:
.sisyphus/notepads/{plan-name}/ - Files:
learnings.md,decisions.md,issues.md,problems.md
Sources: src/agents/atlas/default.ts:133-145, src/agents/atlas/gpt.ts:149-160
Session Recovery Workflow
The system recovers state by utilizing session_id tracking and filesystem lookups. If a task fails or the session is interrupted, agents are instructed to resume using the previous session's context rather than starting fresh.
The diagram shows the lifecycle of a session from initial draft persistence to the recursive delegation and notepad update loop.
Sources: src/agents/prometheus/plan-generation.ts:1-50, src/agents/atlas/default.ts:169-180, src/agents/sisyphus.ts:250-265
Task Management & Continuity
Persistence is enforced through a strict "Todo/Task Discipline." Agents must register their intended actions using TodoWrite or TaskCreate before performing any work. This allows the system to track progress in real-time.
Persistence State Table
| File Type | Location | Purpose | Persistence Strategy |
|---|---|---|---|
| Draft | .sisyphus/drafts/*.md | Records interview decisions | Continuous Append/Edit |
| Plan | .sisyphus/plans/*.md | The "Source of Truth" for TODOs | Single Atomic Write |
| Notepad | .sisyphus/notepads/{id}/*.md | Cross-task learning | Append Only |
| Task State | Internal Hook/System | Tracks in_progress vs completed | Real-time Hook Tracking |
Sources: src/agents/prometheus/identity-constraints.ts:153-165, src/agents/prometheus/plan-generation.ts:20-40, src/agents/atlas/gpt.ts:182-192
Session Continuation Protocol
Agents use a specific protocol to ensure multi-turn tasks do not lose information. This is particularly critical for the delegate_task tool, which returns a session_id that must be reused for retries or follow-ups.
This sequence illustrates how session_id is used to preserve the subagent's memory during a failure-recovery cycle.
Sources: src/agents/sisyphus.ts:315-330, src/agents/atlas/default.ts:169-190
Implementation Constraints
- Single Atomic Write: During plan generation, agents must prepare the entire content in memory and write once. Using the
Writetool on an existing file overwrites it, which can lead to content loss if not managed carefully. - Hook-Based Tracking: Every task or todo creation is tracked by system hooks (
[SYSTEM REMINDER - TASK CONTINUATION]), ensuring that even if the process crashes, the "Boulder" (the task) remains visible to the system. - Clean-up Requirement: Upon completion of the entire work cycle, agents are mandated to run
background_cancel(all=true)and guide the user to delete the draft file once the plan is fully executed.
Sources: src/agents/prometheus/identity-constraints.ts:153-165, src/agents/sisyphus.ts:60-65, src/agents/prometheus/plan-generation.ts:40-45
Summary
The Session Recovery & Persistence system in Oh-My-OpenCode provides a robust framework for managing long-term agent state. By forcing agents to externalize their "thinking" into drafts, plans, and notepads, the project ensures that complex software engineering tasks—which often span hours or days—can be managed with high reliability and zero context drift. This structural discipline is what allows the "Sisyphus" agent to maintain its identity as a senior engineer who "works, delegates, verifies, and ships."
Sources: src/agents/sisyphus.ts:45-55, src/agents/prometheus/identity-constraints.ts:180-185