Introducing a new way to review your PRs.

Read the announcement

usestrix / strix

Open-source AI penetration testing tool to find and fix your app’s vulnerabilities.

View on GitHub

26 documents · Updated Nov 20, 2026

docs / model-context-management

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

TriggerConsequenceGuard
Model metadata or tokenizer is unavailableThe 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 budgetThe provider rejects the next model request.Estimate the full request and compact before the turn.
A provider reports overflow as a general request errorThe run may miss the chance to reduce history.Match known overflow messages and exclude throttle-like errors.
Summary generation fails or has no roomOlder history cannot be represented safely.Leave the session unchanged.
A tool result is separated from its callThe provider may reject the compacted session.Split only at a boundary with no open tool calls.
New turns arrive during summary generationA stale summary could erase current scan state.Lock the rewrite and compare the expected session size.
Heavy import warmup failsStartup loses its speed improvement.Log the failure and let normal imports continue.
A package import fails after leaving child modules cachedA 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 failsThe scan does not start with an unverified model route.Raise a model connection error before scan execution.

Key files

FileWhy to read it
strix/…/context_budget.pyDefines the model capacity and token estimates used by context protection.
strix/…/compaction.pyDefines the checkpoint, safe history reduction, and overflow classification.
strix/…/execution.pyShows where budget checks, compaction, and overflow retry fit in the model-turn lifecycle.
strix/…/sessions.pyShows how session history rewrites avoid data loss and control image growth.
strix/…/settings.pyDefines the high-level controls for context capacity, reserves, summaries, and tool output.
strix/…/warmup.pyDefines non-blocking import warmup and cleanup of orphaned modules after failed imports.
strix/…/main.pyShows model connection warmup and where startup warmup begins.
docs/context-budget-and-compaction.mdExplains the child topic in detail, including budget math and compaction behavior.