Pattern Matrix/White Paper/P1

Problem

Production agents routinely draw on source code, conversation history, tool output, and enterprise knowledge. The combined material can exceed the model's effective window. Truncating by filename or chronology may preserve stale material while dropping decisive evidence, leaving the agent to reason from an incomplete record.

Context triage turns this into an engineering process: it divides all candidate information into four levels, P0/P1/P2/P3, and loads from high to low until the token budget runs out. It governs window allocation for a single request, with the goal of guaranteeing that the most critical information is not drowned out.

Classification: Perception × Route

• Vertical axis · Perception: Triage selects the evidence available to the current request before reasoning begins. It does not change output format or persist information across sessions.
• Horizontal axis · Route: Each candidate is routed to one of four treatments: load, summarize, defer behind a handle, or drop. Priority, task relevance, identity, and safety constraints determine the route.

Solution and mechanics

A single triage layers the candidate information by priority, then uses the token budget to allocate a quota to each layer:

Priority can come from human rules or an algorithm. Claude Code's CLAUDE.md hierarchy is an example of human triage: a team can place safety rules at P0 and preferences at P2. Aider's RepoMap is algorithmic triage: it extracts symbols with tree-sitter and scores them through a code graph. Error stacks need cross-tier protection because repair and regression checks depend on that feedback. Each triage decision should also produce a trace so operators can distinguish information that was never discovered from information that was found but deferred or dropped.

Applicability

• Multi-tenant SaaS customer-service agent: One agent serves multiple tenants whose knowledge bases cannot fit in one window. tenant_id must be a hard P0 constraint, with the remaining knowledge triaged across the four levels.
• Code agent facing an unfamiliar codebase: When each request uses a different repository, symbol extraction and repository graphs can rank relevant files without requiring project-specific instructions in advance.
• Engineering agent serving the same team long term: The team can use CLAUDE.md to state safety rules, project constraints, and loading priorities, then let an algorithm handle dynamic triage.
• Long-running agent connected to a file system or knowledge base: Explicit triage is needed whenever candidate material may exceed the effective window.

Known failure modes

• Priority misjudgment: If a critical file is marked P3, the agent must retrieve it midway through reasoning, adding tool calls and increasing the risk of cascading errors. When uncertain, raise its priority temporarily and use re-read traces to tune the rule.
• Over-aggressive triage: A tight budget may defer files required by several later steps. Repeated retrieval then consumes the tokens and latency the policy was meant to save. Track re-reads and promote repeatedly requested evidence.
• Vague P3 handle naming: A name like doc://manual-page leaves the agent unsure whether to fetch it. Handles should carry a clear “what is this” signal, for example scope + topic + time.
• Cross-tenant data leakage: A P3 handle fetching the wrong tenant's data into the context is a data-breach incident. A resource with a tenant prefix must be force-validated against the P0 tenant_id at load time.
• Trace sampled away: Low-rate random sampling can miss a boundary problem concentrated in a small set of tenants. Triage decisions involving tenant isolation or safety should be retained as structured records.

Verification and metrics

• re-read ratio: The share of deferred material that the agent later requests during reasoning. A sustained increase against the local baseline suggests over-aggressive triage or unclear handle descriptions.
• Long-tail distribution of dropped_count: Means hide requests in which most candidate material is discarded. Inspect the tail alongside task type and failure traces.
• p3_hit_rate: The share of P3 handles later retrieved. Persistently low use suggests an overly broad handle pool; persistently high use suggests frequent material was misclassified. Calibrate thresholds on local workloads.

Reference implementation

Sort candidates by priority (P0 > P1 > P2 > P3), with protected evidence first:
                for each candidate:
                    P3                     → add a retrievable handle; do not preload
                    within remaining budget → add to context and count tokens
                    over budget             → defer or drop according to policy
                return selected, handles, and one TriageDecision
            TriageDecision records timestamp, budget, selected, deferred, dropped, and tokens_used
            

Production implementations should use the real model tokenizer, extend error detection for the business domain, and emit TriageDecision records to an observability system. Review dropped_count and retrieval traces at a cadence set by task risk and operating policy.

Illustrative scenario

Consider a loan-review agent receiving current financial statements, a collateral valuation, historical registration material, and correspondence. If the system truncates by filename, it may drop the current valuation while keeping stale registration documents. Four-level triage protects current financials, collateral evidence, and anomaly or missing-data markers; older material is downgraded by recency, with traceable handles for anything not loaded. The first question is whether the input set is complete enough for a decision, before evaluating the model's reasoning.

Related patterns

• Semantic Compaction (P2): Triage decides what enters the current context; compaction reduces material already admitted while preserving required evidence.
• Progressive Discovery (P3): Triage may defer a source behind a handle. Progressive Discovery follows that handle when later evidence makes the source relevant.
• Layered Retention (M1): Triage manages one request's context allocation. Memory manages information retained across tasks and sessions. Both should preserve version and provenance in their handles.

Design conclusion

Context Triage allocates limited context capacity to evidence required by the current goal. Evaluate it through missed required evidence, irrelevant-context ratio, retrieval latency, and downstream task quality.

Edit source · Published source · Review process