How IntelligentContext Scores Message Importance in Headroom

IntelligentContext computes a composite importance score for each message using a weighted sum of six dimensions—recency, semantic similarity, TOIN importance, error indicators, forward references, and token density—to determine which messages to retain when token budgets are exceeded.

Headroom's IntelligentContext transform replaces the naive "drop-oldest-first" truncation policy with a multi-factor scoring system. According to the chopratejas/headroom source code, every message in a conversation receives a normalized score between 0 and 1 that reflects its value for the next model call. Messages scoring below the threshold are moved to the CCR (Cross-Conversation Retrieval) cache, while high-scoring messages remain in the active context window regardless of age.

The Six Dimensions of Message Importance

The scoring algorithm evaluates six distinct metrics, each weighted according to the ScoringWeights dataclass defined in docs/spec/008-capabilities.md (lines 30-38).

Recency

Recency applies an exponential decay function based on the message's position relative to the latest turn. The calculation uses exp(-λ * distance_from_end), where λ represents the recency_decay_rate (default 0.1). Newer messages receive higher scores, but the decay rate prevents recent yet irrelevant messages from dominating the context.

Semantic Similarity

Semantic similarity measures topical relevance by computing the cosine similarity between the message's embedding and the aggregated embedding of the most recent context window. The embedder used is determined by the HEADROOM_EMBEDDER_RUNTIME configuration. Messages discussing topics aligned with the current conversation receive elevated scores.

TOIN Importance

TOIN importance leverages learned retrieval statistics from the Telemetry-TOIN subsystem. It calls toin.retrieval_rate(message_signature) to determine how frequently a specific message pattern has been retrieved via ccr_retrieve in previous interactions. Patterns that the model frequently recalls are deemed more valuable, with a default weight of 0.25—the highest of any dimension.

Error Indicators

Error indicators identify messages where field_semantics.inferred_type == "error_indicator" according to TOIN telemetry. These represent previous errors or failed attempts that the model struggled with. Retaining these messages prevents the model from repeating mistakes, applying a default weight of 0.15.

Forward References

Forward references count how many subsequent messages explicitly reference a given message ID (for example, through tool arguments or quotations). Messages that serve as anchors for later reasoning receive higher scores, reflecting their structural importance to the conversation flow.

Token Density

Token density calculates the ratio of unique_tokens / total_tokens. Information-dense messages (those with high lexical diversity) are preferred over repetitive or verbose content, though this dimension carries the lowest default weight of 0.05.

How the Composite Score Is Calculated

The final importance score is computed as a weighted sum:

score = Σ (weight_i × normalized_metric_i)

The ScoringWeights configuration class normalizes all user-provided values to ensure they sum to 1.0, as documented in wiki/configuration.md (lines 26-34). During each turn, headroom/transforms/intelligent_context.py calculates each dimension for every stored message, normalizes the metrics, and applies the weights.

Messages are sorted ascending by this composite score. The lowest-scoring messages are dropped first, while the highest-scoring messages are retained—even if they are significantly older than other candidates. Dropped messages are stored in the CCR cache and recorded back to TOIN, creating a feedback loop that increases the importance scores of patterns users retrieve later (see wiki/ARCHITECTURE.md, lines 76-94).

Configuration and Customization

You can override the default weights and decay parameters through IntelligentContextConfig. The default weights are:

• Recency: 0.20
• Semantic similarity: 0.20
• TOIN importance: 0.25
• Error indicator: 0.15
• Forward reference: 0.15
• Token density: 0.05

The recency_decay_rate (default 0.1) controls how quickly recency scores degrade, as specified in wiki/configuration.md (lines 50-52). Lower values favor older messages, while higher values enforce stricter recency bias.

Code Examples

Create a custom scoring configuration with adjusted weights:

from headroom.config import IntelligentContextConfig, ScoringWeights

weights = ScoringWeights(
    recency=0.15,
    semantic_similarity=0.25,
    toin_importance=0.30,
    error_indicator=0.15,
    forward_reference=0.10,
    token_density=0.05,
)

ic_config = IntelligentContextConfig(
    enabled=True,
    use_importance_scoring=True,
    scoring_weights=weights,
    toin_integration=True,
    recency_decay_rate=0.08,          # faster decay

    output_buffer_tokens=3000,
)

from headroom.telemetry import get_toin
from headroom.transforms import IntelligentContextManager

toin = get_toin()
manager = IntelligentContextManager(config=ic_config, toin=toin)

messages = [...]                     # list of dicts {role, content, ...}

kept, dropped = manager.apply(messages)

print(f"Kept {len(kept)} messages, dropped {len(dropped)}")

# Dropped messages are automatically stored in CCR for later retrieval

For minimal configuration changes, override specific weights:

from headroom.transforms import IntelligentContextManager
from headroom.config import IntelligentContextConfig, ScoringWeights

cfg = IntelligentContextConfig(
    scoring_weights=ScoringWeights(toin_importance=0.40)  # prioritize TOIN learned importance

)

manager = IntelligentContextManager(config=cfg, toin=get_toin())

Summary

• IntelligentContext replaces FIFO truncation with importance-based scoring in chopratejas/headroom.
• The composite score combines six dimensions: recency, semantic similarity, TOIN importance, error indicators, forward references, and token density.
• TOIN importance (default weight 0.25) is the primary factor, learned from historical retrieval patterns via toin.retrieval_rate().
• Scoring weights are defined in ScoringWeights and normalized to sum to 1.0, with configuration documented in docs/spec/008-capabilities.md and wiki/configuration.md.
• The implementation resides in headroom/transforms/intelligent_context.py, integrating with TOIN telemetry and CCR caching as described in wiki/ARCHITECTURE.md.

Frequently Asked Questions

What is the exact formula for IntelligentContext importance scoring?

The formula is score = Σ (weight_i × normalized_metric_i), where each metric_i represents one of the six dimensions (recency, semantic similarity, TOIN importance, error indicators, forward references, token density). Each metric is normalized to a 0-1 scale before weighting, and the weights are defined in the ScoringWeights dataclass. The configuration class automatically normalizes user-provided weights so they sum to 1.0.

How does the TOIN telemetry system influence which messages are kept?

TOIN (Telemetry-Optimized Information Network) tracks how often specific message patterns are retrieved via ccr_retrieve. The toin.retrieval_rate(message_signature) function returns a learned statistic indicating historical importance. Messages with high retrieval rates receive higher scores, ensuring that information the model frequently references remains available even if it is not recent.

Can I customize the recency decay behavior in Headroom?

Yes. The recency_decay_rate parameter in IntelligentContextConfig controls the λ value in the exponential decay function exp(-λ * distance_from_end). The default value is 0.1, but you can increase it to favor very recent messages or decrease it to retain older messages longer. This configuration is documented in wiki/configuration.md (lines 50-52).

What happens to messages that are dropped from the context window?

Dropped messages are automatically stored in the CCR (Cross-Conversation Retrieval) cache and recorded back to TOIN. This creates a feedback loop where messages that users or the system retrieve later receive increased importance scores in future interactions. This mechanism ensures that dropped content can be recovered if needed and that the importance scoring improves over time based on actual usage patterns.

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