Post-Session Context Health Check

Analyze context health after each session to detect degradation patterns, measure optimization effectiveness, and recommend improvements for future sessions.

---

Purpose

The post-session context health hook automatically analyzes context usage after session completion to:

1. Detect Degradation Patterns - Identify lost-in-middle, confusion, distraction symptoms
2. Measure Optimization Effectiveness - Track compaction, masking, caching performance
3. Generate Health Reports - Provide actionable insights for context improvement
4. Trigger Alerts - Warn when context health falls below thresholds
5. Build Historical Trends - Track context health across sessions

Priority: P1 - Important for long-running agent systems Impact: Prevents context-related performance degradation over time

---

Trigger

Event: Session completion (post-session hook)

• Session export via /cxs
• Manual session end
• Context compaction trigger
• Session timeout

Blocking: No - runs asynchronously after session Timeout: 60 seconds

---

Context Health Metrics

Degradation Indicators

Indicator	Description	Threshold
Lost-in-Middle	Important middle content ignored	>15% ignored
Poisoning	Bad context corrupting outputs	Any detected
Distraction	Irrelevant content affecting focus	>20% context
Confusion	Contradictory information present	Any detected
Clash	Semantic conflicts between elements	Any detected

Optimization Metrics

Metric	Target	Warning
Context Utilization	<80%	>85%
Compaction Savings	50-70%	<40%
Masking Savings	60-80%	<50%
KV-Cache Hit Rate	>70%	<60%
Quality Preservation	>95%	<90%

---

Health Check Process

1. Context Usage Analysis

def analyze_context_usage(session_data: dict) -> dict:
    """Analyze how context was used during session."""
    return {
        "total_tokens": count_tokens(session_data),
        "utilization_peaks": find_peaks(session_data),
        "component_breakdown": {
            "system_prompt": count_system_tokens(session_data),
            "tool_definitions": count_tool_tokens(session_data),
            "tool_outputs": count_observation_tokens(session_data),
            "message_history": count_history_tokens(session_data),
            "retrieved_docs": count_doc_tokens(session_data)
        },
        "optimization_applied": detect_optimizations(session_data)
    }

2. Degradation Detection

def detect_degradation(session_data: dict) -> list:
    """Detect context degradation patterns."""
    patterns = []

    # Lost-in-middle: Check if middle content was referenced
    middle_usage = analyze_middle_content_usage(session_data)
    if middle_usage.ignored_ratio > 0.15:
        patterns.append({
            "type": "lost_in_middle",
            "severity": "warning",
            "ignored_ratio": middle_usage.ignored_ratio,
            "recommendation": "Move critical content to beginning/end"
        })

    # Confusion: Check for contradictory outputs
    contradictions = find_contradictions(session_data)
    if contradictions:
        patterns.append({
            "type": "confusion",
            "severity": "error",
            "contradictions": contradictions,
            "recommendation": "Remove conflicting context elements"
        })

    # Distraction: Check for irrelevant context impact
    relevance_score = calculate_relevance(session_data)
    if relevance_score < 0.8:
        patterns.append({
            "type": "distraction",
            "severity": "warning",
            "relevance_score": relevance_score,
            "recommendation": "Filter irrelevant context before injection"
        })

    return patterns

3. Optimization Effectiveness

def measure_optimization(session_data: dict) -> dict:
    """Measure effectiveness of applied optimizations."""
    return {
        "compaction": {
            "applied": check_compaction_applied(session_data),
            "savings_percent": calculate_compaction_savings(session_data),
            "quality_impact": measure_quality_after_compaction(session_data)
        },
        "masking": {
            "observations_masked": count_masked_observations(session_data),
            "tokens_saved": calculate_masking_savings(session_data),
            "retrieval_success": check_mask_retrievals(session_data)
        },
        "cache": {
            "hit_rate": calculate_cache_hit_rate(session_data),
            "stability_score": measure_cache_stability(session_data)
        }
    }

---

Health Report Format

{
  "session_id": "session-2025-12-27-1430",
  "timestamp": "2025-12-27T14:35:00Z",
  "health_score": 85,
  "status": "healthy",

  "usage": {
    "peak_utilization": 78,
    "average_utilization": 65,
    "total_tokens": 45000,
    "components": {
      "system_prompt": 2000,
      "tool_definitions": 1500,
      "tool_outputs": 25000,
      "message_history": 12000,
      "retrieved_docs": 4500
    }
  },

  "degradation_patterns": [],

  "optimizations": {
    "compaction": {"applied": true, "savings": "62%", "quality": "97%"},
    "masking": {"count": 8, "savings": "18000 tokens"},
    "cache": {"hit_rate": "75%"}
  },

  "recommendations": [
    "Consider masking tool outputs after 3 turns",
    "Move frequently-referenced instructions to beginning"
  ]
}

---

Alert Thresholds

Condition	Level	Action
Health score < 60	Critical	Immediate notification
Degradation detected	Warning	Log and track
Utilization > 90%	Warning	Trigger optimization
Quality drop > 10%	Error	Review optimizations

---

Integration

Trigger Points

hooks:
  post_session:
    - name: context-health-check
      script: hooks/post-session-context-health.py
      async: true
      timeout: 60
      on_failure: log_and_continue

Output Storage

Health reports are stored in:

• context-storage/health-reports/{session_id}.json - Individual reports
• context-storage/health-trends.json - Aggregated trends
• context-storage/health-alerts.log - Alert history

---

Related Components

Skills

• context-optimization - Optimization techniques
• context-degradation - Degradation patterns
• context-compression - Compression strategies

Agents

• context-health-analyst - Analyze context health

Workflows

• context-optimization.workflow.yaml - Optimization workflow

Commands

• /context-health - Manual health check

---

Implementation Notes

1. Async Execution - Runs asynchronously to not block session completion
2. Trend Analysis - Builds historical data for pattern detection
3. Configurable Thresholds - Adjust sensitivity per project needs
4. Privacy-Safe - Only stores metrics, not actual content
5. Graceful Degradation - Continues on partial data