Context and Budget Management
Relevant source files
The following files were used as context for generating this wiki page:
The Context and Budget Management system is a core infrastructure component designed to monitor token consumption, manage AI context windows, and prioritize information relevance within the swarm. Its primary purpose is to ensure that agents—specifically the Architect orchestrator—operate within reasonable cost limits and technical constraints of the LLM context window while maintaining access to task-critical data.
This system combines real-time token estimation with a tiered triage strategy, allowing the swarm to discard low-value historical data while preserving critical verdicts and requirements. It provides a structured reporting mechanism that alerts users and the Architect when the context size approaches critical thresholds, suggesting interventions like session handoffs to reset context.
Context Budget Monitoring
The core monitoring logic resides in the ContextBudgetService. It tracks tokens across multiple components injected into the system prompt.
Token Estimation and Tracking
Tokens are estimated using a character-based approximation: Math.ceil(text.length / 3.5). This provides a consistent, albeit conservative, measure of context size without requiring expensive external tokenizer calls.
Sources: src/services/context-budget-service.ts:75-80
The service monitors several context components:
- System Prompt: The base instructions for the agent.
- Plan Cursor: The current phase and upcoming tasks extracted from
plan.md. - Knowledge Entries: Relevant lessons retrieved from the knowledge system.
- Run Memory: Past task outcomes and attempt history.
- Handoff Content: Narrative state transitions between sessions.
- Context Documentation: Critical decisions and identified patterns.
Sources: src/services/context-budget-service.ts:168-201
Budget Thresholds and Status
The system uses a configurable threshold model to determine the health of the current session context:
| Status | Threshold | Recommendation |
|---|---|---|
| OK | < 70% | Normal operation. |
| Warning | 70% - 89% | Wrap up current phase and run /swarm handoff. |
| Critical | ≥ 90% | Immediate handoff required to avoid cost escalation. |
Sources: src/services/context-budget-service.ts:54-65, src/services/context-budget-service.ts:213-228
Warning Suppression Modes
To avoid chat noise, the service supports three warning modes:
- once: The warning fires only the first time a threshold is crossed.
- every: The warning fires on every turn once the threshold is exceeded.
- interval: The warning fires every N turns (default 20).
Sources: src/services/context-budget-service.ts:60-64, src/services/context-budget-service.ts:340-355
Context Triage and Prioritization
When context limits are reached, the Architect agent applies a "Context Triage" protocol to decide what information to retain.
The diagram shows the prioritization levels used by the Architect to manage prompt size.
Sources: src/agents/architect.ts:104-124
Relevance Scoring for Knowledge
Context is not just about size but about relevance. The system uses a composite scoring algorithm to determine which knowledge entries should be injected into the context window.
Scoring Weights
Relevance is calculated using three primary axes:
- Category Match (40%): Does the entry category (e.g., testing, security) match the current phase?
- Confidence (35%): The calibrated reliability of the information.
- Keywords/Tags (25%): Overlap between entry tags and the current tech stack.
Sources: tests/unit/knowledge/relevance-scoring-task3-4.test.ts:75-120
Tiebreaking and Clamping
- Recency: If two entries have a relevance score within 0.001 of each other, the more recent entry is prioritized.
- Clamping: Final scores are always clamped between 0.0 and 1.0.
- Tier Boost: Global "Hive" knowledge entries receive a 0.05 boost to encourage the use of established standards.
Sources: tests/unit/knowledge/relevance-scoring-task3-4.test.ts:290-310, tests/unit/knowledge/relevance-scoring-task3-4.test.ts:390-410
Implementation Wiring
The context budget check is integrated into the System Enhancer hook. This hook executes as the final step of prompt assembly before the prompt is sent to the LLM.
The sequence shows the context budget check running as the final safety gate during prompt generation.
Sources: tests/unit/hooks/system-enhancer-context-budget-wiring.test.ts:60-90, src/services/context-budget-service.ts:317-335
Security and Reliability
The system includes several adversarial protections:
- Path Traversal Protection: Validation ensures budget state cannot be written outside the
.swarm/directory. - Malformed JSON Handling: If
budget-state.jsonis corrupted or truncated, the service reverts to default safe states. - Extreme Values: Logic handles negative budget tokens, zero-turn counts, or multi-megabyte system prompts without crashing.
Sources: tests/unit/services/adversarial-security.test.ts:40-80, tests/unit/services/adversarial-security.test.ts:250-300
Knowledge Consolidation
To prevent context bloat over long sessions, the Curator (a specialized mode of the Explorer agent) consolidates session history into digests.
- CURATOR_INIT: Consolidates prior session knowledge into a briefing, identifying contradictions between known facts and the current project state.
- CURATOR_PHASE: Consolidates a completed phase into a digest, identifying candidate lessons for permanent storage and summarizing key decisions.
Sources: src/agents/explorer.ts:233-280
Summary
The Context and Budget Management system provides the "financial" and "cognitive" guardrails for the OpenCode Swarm. By estimating token costs per turn and enforcing strict triage rules, it prevents technical debt in the form of context degradation. The combination of the ContextBudgetService for tracking and the Architect's Triage rules for prioritization ensures that the swarm remains cost-effective and functionally accurate throughout the project lifecycle.