How IntelligentContext Scoring Determines Context Fitting in Headroom

Headroom's IntelligentContext scoring assigns each context entry a weighted relevance score based on recency, semantic similarity, error indicators, and other factors to determine exactly which stored context fits within the LLM's token budget.

The chopratejas/headroom repository implements a sophisticated IntelligentContext scoring system that solves the critical problem of selecting the most relevant context for large language model (LLM) requests. When building AI agents, developers face hard token limits that prevent sending entire conversation histories or tool outputs. Headroom's scoring algorithm evaluates each stored entry across six distinct dimensions and selects only the highest-value context that fits within configurable budget constraints.

Configuration of IntelligentContext Scoring

The scoring behavior is controlled through the IntelligentContextConfig interface defined in sdk/typescript/src/types/config.ts. This configuration determines whether scoring is enabled and how each factor influences the final selection.

Key configuration fields include:

• useImportanceScoring – A boolean toggle that activates the scoring engine.
• scoringWeights – A ScoringWeights object mapping each factor to its relative importance.
• recencyDecayRate – Controls how quickly older entries lose relevance via exponential decay.
• outputBufferTokens and compressThreshold – Hard limits that cap the total context sent to the LLM.

// sdk/typescript/src/types/config.ts – scoring configuration
export interface ScoringWeights {
  recency?: number;
  semanticSimilarity?: number;
  toinImportance?: number;
  errorIndicator?: number;
  forwardReference?: number;
  tokenDensity?: number;
}

export interface IntelligentContextConfig {
  enabled?: boolean;
  useImportanceScoring?: boolean;
  scoringWeights?: ScoringWeights;
  recencyDecayRate?: number;
  outputBufferTokens?: number;
  compressThreshold?: number;
}

The Scoring Algorithm

When a request arrives, Headroom iterates over all non-expired entries stored in SharedContext. For each entry, it computes a composite score using the formula:

score = Σ weight_i × normalized_metric_i

Each metric is normalized to the range [0, 1] before the weighted sum is applied. The algorithm evaluates six specific factors:

Recency Decay

The system calculates the time elapsed since the entry's timestamp (Δt) and applies an exponential decay factor: exp(-Δt · recencyDecayRate). Entries older than the configured decay rate contribute diminishing scores, ensuring recent interactions carry higher weight.

Semantic Similarity

Headroom embeds the entry's compressed text using the same model that performs compression, then compares it to the embedding of the current user message. The cosine similarity between these vectors serves as the metric, favoring context that semantically relates to the current query.

TOIN Importance

When toinIntegration is enabled, the system inspects entries for Tool-Output-Importance-Note annotations. The confidence score extracted from these annotations directly contributes to the metric, prioritizing tool outputs explicitly marked as important by the agent framework.

Error Indicators

Entries containing patterns like "error", "exception", or stack-trace tokens receive boosted scores. The system recognizes that error-related context is historically valuable for debugging subsequent requests, even if the errors occurred earlier in the session.

Forward References

The detector scans for placeholder markers (e.g., {{ref}}) within entries. Detecting these markers raises the score, signaling that later conversation turns will explicitly reference this content, making it essential for coherence.

Token Density

The ratio originalTokens / compressedTokens rewards entries that compress efficiently while preserving information. High-density entries provide more semantic value per token consumed, optimizing the limited context window.

Context Selection and Thresholds

After computing scores for all entries, Headroom sorts them in descending order. It then greedily adds entries to the output buffer until hitting one of three limits:

1. Output Buffer Tokens – The maximum token count specified by outputBufferTokens.
2. Compression Threshold – The limit (compressThreshold) that triggers second-stage summarization if exceeded.
3. Maximum Entries – The hard limit defined by SharedContext configuration.

The selected subset is returned in compressed form by default, or in original form when get(..., {full:true}) is requested. The scores themselves guide inclusion decisions but are never transmitted to the LLM.

Implementation Example

The following example demonstrates configuring the SharedContext with custom IntelligentContext scoring weights:

import { SharedContext, IntelligentContextConfig } from "headroom-ai";

// Configure IntelligentContext with custom scoring weights
const icConfig: IntelligentContextConfig = {
  enabled: true,
  useImportanceScoring: true,
  scoringWeights: {
    recency: 0.4,
    semanticSimilarity: 0.3,
    toinImportance: 0.15,
    errorIndicator: 0.1,
    forwardReference: 0.05,
  },
  recencyDecayRate: 0.0001,
  outputBufferTokens: 1500,
};

// Initialize context with scoring enabled
const ctx = new SharedContext({ intelligentContext: icConfig });

// Store entries (tool outputs, logs, etc.)
await ctx.put("log-1", "File not found: ./src/utils.ts");
await ctx.put(
  "search-result",
  "Found 12 matching snippets – see lines 42-58 for the implementation."
);

// Retrieve the best-fitting compressed context
const compressed = ctx.get("log-1");
const selectedKeys = ctx.keys(); // Already filtered by scoring and TTL

In production agent pipelines, the middleware automatically invokes the IntelligentContext transform during the request lifecycle, applying the scoring logic without manual intervention.

Summary

• IntelligentContext scoring in Headroom uses a weighted multi-factor algorithm to rank context entries by relevance.
• Six metrics drive the score: recency (with exponential decay), semantic similarity (cosine embedding distance), TOIN importance (tool output annotations), error indicators (debugging content), forward references (placeholder detection), and token density (compression efficiency).
• Configuration occurs through IntelligentContextConfig in src/types/config.ts, allowing fine-tuning of weights and thresholds.
• Selection respects hard limits including outputBufferTokens, compressThreshold, and maxEntries, ensuring the LLM receives only the most valuable context within budget constraints.
• The implementation resides in SharedContext (src/shared-context.ts), which handles entry storage, TTL management, and the public API (put, get, keys).

Frequently Asked Questions

How does Headroom normalize the scoring metrics?

Headroom normalizes each individual metric to the range [0, 1] before applying the weighted sum. This ensures that factors with different scales—such as recency (time in seconds) versus semantic similarity (cosine distance)—contribute proportionally according to their configured weights in scoringWeights.

What happens when the token budget is exceeded during context selection?

When the cumulative token count approaches outputBufferTokens or compressThreshold, Headroom stops adding entries to the output buffer, even if lower-ranked entries remain. Entries are processed in descending score order, meaning only the highest-scoring context that fits within the budget is returned to the LLM.

Can I disable specific scoring factors if they are not relevant to my use case?

Yes. You can effectively disable any factor by setting its corresponding weight to zero in the ScoringWeights configuration. For example, setting forwardReference: 0 removes forward reference detection from the composite calculation while keeping other factors active.

Where is the actual scoring computation implemented in the codebase?

According to the Headroom architecture, the runtime scoring logic lives within the IntelligentContext transform, which processes entries from SharedContext (defined in sdk/typescript/src/shared-context.ts). The configuration types reside in sdk/typescript/src/types/config.ts, while the high-level architectural description appears in the README's IntelligentContext section.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}