Context Management
Relevant source files
The following files were used as context for generating this wiki page:
Context Management within the project refers to the systematic process of gathering, preserving, and injecting relevant information into AI agent interactions to ensure accurate execution and prevent context loss. The system utilizes a combination of specialized agents (Prometheus, Sisyphus, Atlas), background research probes, and persistent storage mechanisms like drafts and notepads to maintain a coherent "working memory" across long-running developer sessions.
The primary objective is to bridge the gap between initial user requests and executable actions by capturing requirements, architectural patterns, and research findings. This is achieved through structured phases including intent classification, parallel context gathering, and the use of persistent artifacts like .sisyphus/notepads/ and .sisyphus/drafts/.
Sources: src/agents/prometheus/identity-constraints.ts, src/agents/prometheus/interview-mode.ts, src/agents/sisyphus.ts
Architecture of Context Flow
The context management architecture is designed to handle the stateless nature of subagents by using a "Notepad" system and session persistence. The orchestrator (Atlas) manages the high-level context, while executing agents like Sisyphus use specialized tools to grep and research information.
This diagram shows the flow of context from the initial request through research and drafting phases into final plan execution.
Sources: src/agents/prometheus/interview-mode.ts:5-20, src/agents/atlas/gpt.ts:98-115
Working Memory and Persistent Artifacts
To prevent context loss during long conversations, the system implements a "Draft as Working Memory" protocol. This ensures that even if the AI's immediate context window is exceeded, the critical decisions remain accessible.
Draft Files
During the interview phase, the Prometheus agent continuously records requirements, technical decisions, and research findings into a draft file located at .sisyphus/drafts/{name}.md.
| Trigger | Action |
|---|---|
| Meaningful User Response | Update Draft with stated requirements |
| Research Result Received | Record findings from explore/librarian agents |
| Decision Confirmed | Update technical choices and rationale |
| Scope Changed | Update boundary definitions (IN/OUT) |
Sources: src/agents/prometheus/identity-constraints.ts:167-200, src/agents/prometheus/interview-mode.ts:250-265
Notepad System
The Atlas orchestrator uses a notepad system to provide cumulative intelligence for stateless subagents. Before every delegation, Atlas reads from the notepad and includes extracted "Inherited Wisdom" in the subagent's prompt.
- learnings.md: General patterns discovered during execution.
- decisions.md: Architectural or technical choices made.
- issues.md / problems.md: Blockers or bugs encountered.
Sources: src/agents/atlas/gpt.ts:140-155
Context Gathering Strategies
The system employs parallel background agents to gather context without blocking the main interaction thread.
Specialized Research Agents
- Explore Agent: Acts as a "contextual grep" for the internal codebase to find patterns, structure, and usages.
- Librarian Agent: Performs "reference grep" against external sources, including official documentation and remote repositories.
This sequence illustrates the parallel research process used to populate the initial context.
Sources: src/agents/prometheus/interview-mode.ts:55-80, src/agents/librarian.ts:20-50
Session ID Persistence
For efficient context reuse, agents utilize a session_id. Resuming a session preserves the full conversation context, which can save up to 70% of tokens on follow-up tasks by avoiding redundant file reads or exploration.
Sources: src/agents/sisyphus.ts:310-335
Context Injection in Delegation
When a task is delegated, the orchestrator must inject specific context into the subagent's prompt to ensure it operates within project constraints.
The 6-Section Prompt Protocol
Every delegation prompt must include:
- TASK: The specific atomic goal.
- EXPECTED OUTCOME: Concrete deliverables.
- REQUIRED TOOLS/SKILLS: Whitelist of capabilities.
- MUST DO: Pattern references and explicit requirements.
- MUST NOT DO: Forbidden actions.
- CONTEXT: Paths to relevant notepads and inherited wisdom.
Sources: src/agents/atlas/gpt.ts:55-90, src/agents/sisyphus.ts:348-360
Conclusion
Context Management in this project is a multi-layered system that prioritizes persistent documentation over transient chat history. By utilizing draft files, wave-based notepads, and parallel research agents, the system ensures that complex architectural decisions and codebase patterns are consistently respected across delegated subtasks, enabling autonomous deep work while maintaining technical accuracy.