Model context management
Model context management keeps long-running Strix security scans usable as model requests and stored conversations grow. It combines model-aware token budgets, safe history compaction, and warmup work so each scan can start promptly and continue without losing important state.
Context management goals
The system treats model context as a limited working area shared by instructions, tool descriptions, conversation history, and the next model response. It protects that area before a request and also recovers when a provider reports that the limit was exceeded.
The main protections are:
- Budget awareness: Use the selected model's known limits when possible. Use safe fallbacks when model metadata or token counting is not available.
- History compaction: Replace older turns with a factual checkpoint while keeping recent work in its original form.
- Request recovery: Detect real context overflows without confusing them with rate limits or other provider errors.
- Session safety: Prevent a slow history rewrite from deleting turns added by another part of the scan.
- Startup warmup: Move heavy imports and the first model connection work ahead of the scan's active work.
These protections work together. Budget checks reduce avoidable overflows, compaction preserves the state needed to continue, and warmup reduces delay without changing scan behavior.
References: strix/…/context_budget.py• L65-89 strix/…/compaction.py• L339-400 strix/…/execution.py• L643-789 strix/…/warmup.py• L1-10 strix/…/main.py• L129-254
Context budget lifecycle
Model capacity
Model capacity is the input space available to the selected model. Strix resolves it from provider metadata when possible and uses a configured fallback for an unknown model. Token counting follows the same safe approach, so an unavailable tokenizer does not make the request look smaller than it is.
The budget is not only the visible conversation. It also accounts for the agent instructions and tool descriptions that accompany the conversation, plus room for the model's response. The child page Context budgets and compaction explains these controls and their effect in more detail.
References: strix/…/context_budget.py• L16-27 strix/…/context_budget.py• L46-89 strix/…/settings.py• L85-102
Request preparation
Before a session-backed model turn, the execution loop limits retained image outputs and checks whether the session is near its usable context budget. This keeps large tool results and visual data from consuming all space needed for the next response.
If the session is within its budget, the normal model turn starts. If it is over budget, the system attempts compaction before sending the turn. A failed or impossible compaction leaves the stored session unchanged rather than replacing useful history with incomplete state.
References: strix/…/execution.py• L643-687 strix/…/sessions.py• L159-199 strix/…/compaction.py• L339-387
Overflow recovery
Providers do not all report context errors in the same form. Strix accepts typed context-overflow errors and known message forms from providers that return a general request error. It excludes rate-limit and service errors so those events do not trigger an unrelated history rewrite.
When a true overflow reaches the model-turn loop, Strix forces compaction and retries the turn. The retry has a bounded number of compaction attempts. If compaction cannot produce a safe checkpoint, the normal failure handling remains in control.
References: strix/…/compaction.py• L40-93 strix/…/execution.py• L735-789
Conversation compaction
Checkpoint history
Conversation compaction turns older history into one checkpoint that the agent treats as established context. The checkpoint preserves the security objective, findings, secrets, system details, work state, failed paths, next actions, and relevant files so the scan can continue with the information that matters.
The most recent turns remain verbatim. Later compaction updates the existing checkpoint instead of building a chain of unrelated summaries. This gives the agent one current record of older state plus the latest work.
References: strix/…/compaction.py• L96-143 strix/…/compaction.py• L224-230 strix/…/compaction.py• L278-285 strix/…/compaction.py• L368-390
Safe history boundaries
The retained recent history ends at a tool-safe boundary. A tool call and its matching tool result stay together, including when several calls run in parallel. This prevents the rebuilt session from becoming invalid input for a provider.
The compaction summary has its own context budget. Strix reserves space for the summary instructions, any prior checkpoint, the summary response, and request overhead. If the older history is still too large, it keeps the start and end and marks the omitted middle.
References: strix/…/compaction.py• L190-221 strix/…/compaction.py• L233-275 strix/…/compaction.py• L380-387
Session rewrite safety
Compaction rewrites persisted session history only after it has generated a summary. A session write lock serializes the rewrite, and an expected-size check rejects a stale rewrite when new turns arrived during summary generation. If storage fails during replacement, the original history is restored.
This makes compaction conservative: it can leave an overlong session for a later attempt, but it does not silently remove newer scan progress.
References: strix/…/sessions.py• L89-156 strix/…/compaction.py• L302-336 strix/…/compaction.py• L386-400
Model warmup
Import warmup
Import warmup starts heavy scan dependencies in a background daemon thread during CLI startup. It overlaps startup work such as argument handling, runtime checks, image setup, and interface setup. The scan does not depend on warmup completing; a normal import waits on the normal import lock when needed, and a failed warmup does not fail the run.
The warmup starts once for a process and imports the shared scan engine and external client packages. If a package import fails partway, it removes submodules left without their parent package so a later normal import starts from a clean state. Embedders can provide a narrower module set when they do not use all backends. This improves cold-start time without changing which components the scan uses.
References: strix/…/warmup.py• L1-10 strix/…/warmup.py• L23-28 strix/…/warmup.py• L34-82 strix/…/main.py• L413-452
LLM connection warmup
LLM warmup checks the configured model route before an interactive or non-interactive scan proceeds. It applies the model settings, verifies the main route, and checks a separately configured dedupe route when one exists. A connection failure becomes a model connection error before scan work begins.
Warmup also warns about unknown or non-recommended model names. These warnings help the operator correct routing or model quality issues before the scan relies on the model for security findings.
References: strix/…/main.py• L129-180 strix/…/main.py• L182-254 strix/…/main.py• L449-463
Change checklist
When these files or sections are changed, remember to consider these:
- Keep model capacity lookup, token counting, output allowance, and compaction reserves aligned. A change in one can make either the scan request or the summary request exceed the provider limit.
- Preserve the checkpoint content contract when changing the summary prompt. Findings, secrets, proof values, work state, and next actions must remain available after compaction.
- Keep tool-call pairing tied to the history split. A new history shape must not allow a result without its matching call.
- Keep overflow detection separate from rate-limit detection. Provider error changes can cause false compaction or hide a real overflow.
- Keep the session length check and restore-on-failure behavior with every persisted history rewrite.
- Keep import warmup optional and non-fatal. It must improve startup time without becoming a required dependency for scan correctness.
- Keep failed import cleanup limited to orphaned modules. Warmup must not remove modules that another thread imported successfully.
- Keep the main model and dedupe model warmup routes separate. A dedupe provider must not receive the main model route's connection settings.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Model metadata or tokenizer is unavailable | The exact model budget cannot be measured. | Use configured capacity and a conservative UTF-8 byte count. |
| Instructions, tools, history, and response space exceed the usable budget | The provider rejects the next model request. | Estimate the full request and compact before the turn. |
| A provider reports overflow as a general request error | The run may miss the chance to reduce history. | Match known overflow messages and exclude throttle-like errors. |
| Summary generation fails or has no room | Older history cannot be represented safely. | Leave the session unchanged. |
| A tool result is separated from its call | The provider may reject the compacted session. | Split only at a boundary with no open tool calls. |
| New turns arrive during summary generation | A stale summary could erase current scan state. | Lock the rewrite and compare the expected session size. |
| Heavy import warmup fails | Startup loses its speed improvement. | Log the failure and let normal imports continue. |
| A package import fails after leaving child modules cached | A later import can see an incomplete package state and fail again. | Remove cached submodules whose parent package is absent. |
| Main or dedupe model connection warmup fails | The scan does not start with an unverified model route. | Raise a model connection error before scan execution. |
Key files
| File | Why to read it |
|---|---|
| strix/…/context_budget.py | Defines the model capacity and token estimates used by context protection. |
| strix/…/compaction.py | Defines the checkpoint, safe history reduction, and overflow classification. |
| strix/…/execution.py | Shows where budget checks, compaction, and overflow retry fit in the model-turn lifecycle. |
| strix/…/sessions.py | Shows how session history rewrites avoid data loss and control image growth. |
| strix/…/settings.py | Defines the high-level controls for context capacity, reserves, summaries, and tool output. |
| strix/…/warmup.py | Defines non-blocking import warmup and cleanup of orphaned modules after failed imports. |
| strix/…/main.py | Shows model connection warmup and where startup warmup begins. |
| docs/context-budget-and-compaction.md | Explains the child topic in detail, including budget math and compaction behavior. |