How Headroom Context Tracker Prevents Context Amnesia in Multi-Turn Conversations

Headroom’s Context Tracker prevents context amnesia by recording every compression event in a bounded LRU cache, analyzing new queries for relevance against stored metadata, and automatically expanding previously compressed content when needed, all while maintaining strict project isolation via workspace keys.

The chopratejas/headroom repository implements a sophisticated Context Tracker as part of its CCR (Compress-Cache-Retrieve) pipeline to solve the problem of "context amnesia" in long-running LLM conversations. This component ensures that once information is compressed to save token space, it can be intelligently recalled when relevant to future queries, preventing the model from forgetting critical details across conversation turns.

Understanding Context Amnesia in the CCR Pipeline

Context amnesia occurs when an LLM loses access to previously discussed information after it has been compressed or removed from the active context window to manage token limits. In headroom/ccr/context_tracker.py, the Context Tracker counters this by maintaining a persistent registry of compressed content that survives beyond a single turn, enabling the system to retrieve "forgotten" data when needed.

Five Mechanisms That Prevent Amnesia

Recording Compression Events with track_compression

Every time content is compressed, the tracker invokes track_compression() to create a CompressedContext entry. This stores the hash of the compressed payload, turn number, original and compressed item counts, the triggering query, and a preview of sample content. According to the source code in headroom/ccr/context_tracker.py (lines 10-18), this creates an immutable audit trail of what was removed from the active context.

Memory-Bounded Storage via LRU Cache

The tracker maintains an internal _contexts dictionary that behaves as a least-recently-used (LRU) cache. With a default max_tracked_contexts of 100, the system evicts older entries when the limit is exceeded, guaranteeing predictable memory usage while preserving the most recent interactions. This prevents unbounded growth while keeping recent context alive.

Query Analysis and Relevance Scoring

When new queries arrive, the analyze_query() method extracts keywords and scores them against the sample_content of all stored CompressedContext entries. The system generates ExpansionRecommendation objects for any matches exceeding the relevance_threshold of 0.3 (default), identifying which compressed data might be relevant to the current conversation turn.

Proactive Context Expansion

If proactive_expansion is enabled in the configuration, the tracker automatically expands up to max_proactive_expansions relevant contexts per turn before the LLM generates a response. This re-introduces previously compressed data into the prompt before the model processes the query, effectively eliminating the gap where "forgotten" information would otherwise be needed.

Workspace Isolation for Security

Every CompressedContext carries a workspace_key that isolates data per project (lines 39-48 in headroom/ccr/context_tracker.py). The tracker only expands contexts sharing the same workspace as the current request, preventing cross-project leakage and ensuring that sensitive information from one project does not contaminate another.

Practical Implementation

The following example demonstrates initializing a tracker, recording a compression event, and analyzing a follow-up query:

# Initialise a tracker (uses default configuration)

from headroom.ccr.context_tracker import ContextTracker

tracker = ContextTracker()

# After a search/compression step, record what was compressed

tracker.track_compression(
    hash_key="abc123",
    turn_number=1,
    tool_name="Bash",
    original_count=120,
    compressed_count=12,
    query_context="find all python source files",
    sample_content='["src/main.py", "src/auth.py", "src/utils.py"]',
    workspace_key="my-project",
)

# Later, when the user asks a follow‑up question

recommendations = tracker.analyze_query(
    query="How does the authentication flow work?",
    current_turn=5,
)

# The tracker may suggest expanding the earlier compression:

for rec in recommendations:
    if rec.expand_full:
        # Load the full content from the compression store and add it to the prompt

        full_items = get_compression_store().load_full(rec.hash_key)
        prompt.extend(full_items)

Key Source Files and Architecture

• headroom/ccr/context_tracker.py: Implements CompressedContext, ContextTrackerConfig, and the ContextTracker class that records compressions and decides when to expand them.
• headroom/ccr/batch_store.py: Stores per-turn BatchContext objects that the tracker queries for relevance.
• headroom/cache/compression_store.py: Provides the persistence layer where the full, uncompressed data lives and can be re-loaded on demand.
• headroom/ccr/__init__.py: Exposes the CCR API, including the context-tracking entry point used by the proxy server.

Summary

• The Context Tracker records every compression via track_compression(), creating immutable metadata entries including hash keys, turn numbers, and sample content.
• An LRU cache with default limit of 100 entries ensures bounded memory usage via max_tracked_contexts.
• The analyze_query() method scores new queries against stored samples using a default relevance_threshold of 0.3.
• Proactive expansion settings allow automatic re-insertion of relevant compressed content before LLM generation when proactive_expansion is enabled.
• Workspace keys enforce project isolation, preventing cross-contamination of context between different projects.

Frequently Asked Questions

What is context amnesia in Headroom?

Context amnesia refers to the phenomenon where an LLM loses access to previously provided information after it has been compressed out of the active context window to save tokens. Headroom's Context Tracker prevents this by maintaining a registry of compressed content and automatically re-expanding it when relevant to new queries, ensuring continuity across long conversations.

How does the Context Tracker decide which compressed content to expand?

The tracker uses analyze_query() to extract keywords from incoming queries and match them against the sample_content of stored CompressedContext entries. Matches exceeding the relevance_threshold (default 0.3) generate ExpansionRecommendation objects, which trigger expansion if proactive expansion is enabled or can be used for manual retrieval.

What limits the memory usage of the Context Tracker?

The internal _contexts dictionary operates as a bounded LRU cache controlled by max_tracked_contexts, which defaults to 100 entries. When this limit is reached, the least recently used compressed context entries are evicted, ensuring predictable memory consumption regardless of conversation length.

Can compressed contexts from different projects leak into each other?

No. The workspace_key parameter in every CompressedContext ensures strict isolation. The tracker only considers contexts for expansion when they share the same workspace_key as the current request, preventing cross-project context leakage as implemented in lines 39-48 of headroom/ccr/context_tracker.py.

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