SuperClaude/Framework-Hooks/docs/Configuration/compression.yaml.md

Compression Configuration (compression.yaml)

Overview

The compression.yaml file defines intelligent token optimization strategies for the SuperClaude-Lite framework. This configuration implements the Token Efficiency Mode with adaptive compression levels, selective content preservation, and quality-gated optimization.

Purpose and Role

The compression configuration serves as the foundation for:

• Token Efficiency Mode: Implements intelligent token optimization with 30-50% reduction targets
• Selective Compression: Protects framework content while optimizing session data
• Quality Preservation: Maintains ≥95% information fidelity during compression
• Symbol Systems: Provides efficient communication through standardized symbols
• Abbreviation Systems: Intelligent abbreviation for technical terminology
• Adaptive Intelligence: Context-aware compression based on user expertise and task complexity

Configuration Structure

1. Compression Levels (compression_levels)

The framework implements 5 compression levels with specific targets and use cases:

Minimal Compression (0-40%)

minimal:
  symbol_systems: false
  abbreviation_systems: false
  structural_optimization: false
  quality_threshold: 0.98
  use_cases: ["user_content", "low_resource_usage", "high_quality_required"]

Purpose: Preserves maximum quality for critical content Usage: User project code, important documentation, complex technical content Quality: 98% preservation guarantee

Efficient Compression (40-70%)

efficient:
  symbol_systems: true
  abbreviation_systems: false
  structural_optimization: true
  quality_threshold: 0.95
  use_cases: ["moderate_resource_usage", "balanced_efficiency"]

Purpose: Balanced optimization for standard operations Usage: Session metadata, working artifacts, analysis results Quality: 95% preservation with symbol enhancement

Compressed Level (70-85%)

compressed:
  symbol_systems: true
  abbreviation_systems: true
  structural_optimization: true
  quality_threshold: 0.90
  use_cases: ["high_resource_usage", "user_requests_brevity"]

Purpose: Aggressive optimization for resource constraints Usage: Large-scale operations, user-requested brevity Quality: 90% preservation with full optimization suite

Critical Compression (85-95%)

critical:
  symbol_systems: true
  abbreviation_systems: true
  structural_optimization: true
  advanced_techniques: true
  quality_threshold: 0.85
  use_cases: ["resource_constraints", "emergency_compression"]

Purpose: Maximum optimization for severe constraints Usage: Resource exhaustion scenarios, emergency situations Quality: 85% preservation with advanced techniques

Emergency Compression (95%+)

emergency:
  symbol_systems: true
  abbreviation_systems: true
  structural_optimization: true
  advanced_techniques: true
  aggressive_optimization: true
  quality_threshold: 0.80
  use_cases: ["critical_resource_constraints", "emergency_situations"]

Purpose: Ultra-compression for critical resource constraints Usage: System overload, critical memory constraints Quality: 80% preservation with aggressive optimization

2. Selective Compression (selective_compression)

Framework Exclusions

framework_exclusions:
  patterns:
    - "/SuperClaude/SuperClaude/"
    - "~/.claude/"
    - ".claude/"
    - "SuperClaude/*"
    - "CLAUDE.md"
    - "FLAGS.md"
    - "PRINCIPLES.md"
    - "ORCHESTRATOR.md"
    - "MCP_*.md"
    - "MODE_*.md"
    - "SESSION_LIFECYCLE.md"
  compression_level: "preserve" # 0% compression
  reasoning: "Framework content must be preserved for proper operation"

Critical Protection: Framework components receive zero compression to ensure operational integrity.

User Content Preservation

user_content_preservation:
  patterns:
    - "project_files"
    - "user_documentation"
    - "source_code"
    - "configuration_files"
    - "custom_content"
  compression_level: "minimal" # Light compression only
  reasoning: "User content requires high fidelity preservation"

Quality Guarantee: User content maintains 98% fidelity through minimal compression only.

Session Data Optimization

session_data_optimization:
  patterns:
    - "session_metadata"
    - "checkpoint_data"
    - "cache_content"
    - "working_artifacts"
    - "analysis_results"
  compression_level: "efficient" # 40-70% compression
  reasoning: "Session data can be compressed while maintaining utility"

Balanced Approach: Session operational data compressed efficiently while preserving utility.

3. Symbol Systems (symbol_systems)

Core Logic and Flow Symbols

core_logic_flow:
  enabled: true
  mappings:
    "leads to": "→"
    "implies": "→"
    "transforms to": "⇒"
    "rollback": "←"
    "bidirectional": "⇄"
    "and": "&"
    "separator": "|"
    "sequence": "»"
    "therefore": "∴"
    "because": "∵"
    "equivalent": "≡"
    "approximately": "≈"
    "not equal": "≠"

Purpose: Express logical relationships and flow with mathematical precision Token Savings: 50-70% reduction in logical expression length

Status and Progress Symbols

status_progress:
  enabled: true
  mappings:
    "completed": "✅"
    "failed": "❌"
    "warning": "⚠️"
    "information": "ℹ️"
    "in progress": "🔄"
    "waiting": "⏳"
    "critical": "🚨"
    "target": "🎯"
    "metrics": "📊"
    "insight": "💡"

Purpose: Visual status communication with immediate recognition User Experience: Enhanced readability through universal symbols

Technical Domain Symbols

technical_domains:
  enabled: true
  mappings:
    "performance": "⚡"
    "analysis": "🔍"
    "configuration": "🔧"
    "security": "🛡️"
    "deployment": "📦"
    "design": "🎨"
    "network": "🌐"
    "mobile": "📱"
    "architecture": "🏗️"
    "components": "🧩"

Purpose: Domain-specific communication with contextual relevance Persona Integration: Symbols adapt to active persona domains

4. Abbreviation Systems (abbreviation_systems)

System and Architecture

system_architecture:
  enabled: true
  mappings:
    "configuration": "cfg"
    "implementation": "impl"
    "architecture": "arch"
    "performance": "perf"
    "operations": "ops"
    "environment": "env"

Technical Focus: Core system terminology with consistent abbreviations

Development Process

development_process:
  enabled: true
  mappings:
    "requirements": "req"
    "dependencies": "deps"
    "validation": "val"
    "testing": "test"
    "documentation": "docs"
    "standards": "std"

Workflow Integration: Development lifecycle terminology optimization

Quality Analysis

quality_analysis:
  enabled: true
  mappings:
    "quality": "qual"
    "security": "sec"
    "error": "err"
    "recovery": "rec"
    "severity": "sev"
    "optimization": "opt"

Quality Focus: Quality assurance and analysis terminology

5. Structural Optimization (structural_optimization)

Whitespace Optimization

whitespace_optimization:
  enabled: true
  remove_redundant_spaces: true
  normalize_line_breaks: true
  preserve_code_formatting: true

Code Safety: Preserves code formatting while optimizing prose content

Phrase Simplification

phrase_simplification:
  enabled: true
  common_phrase_replacements:
    "in order to": "to"
    "it is important to note that": "note:"
    "please be aware that": "note:"
    "for the purpose of": "for"
    "with regard to": "regarding"

Natural Language: Simplifies verbose phrasing while maintaining meaning

Redundancy Removal

redundancy_removal:
  enabled: true
  remove_articles: ["the", "a", "an"] # Only in high compression levels
  remove_filler_words: ["very", "really", "quite", "rather"]
  combine_repeated_concepts: true

Intelligent Reduction: Context-aware redundancy elimination

6. Quality Preservation (quality_preservation)

Minimum Thresholds

minimum_thresholds:
  information_preservation: 0.95
  semantic_accuracy: 0.95
  technical_correctness: 0.98
  user_content_fidelity: 0.99

Quality Gates: Enforces minimum quality standards across all compression levels

Validation Criteria

validation_criteria:
  key_concept_retention: true
  technical_term_preservation: true
  code_example_accuracy: true
  reference_link_preservation: true

Content Integrity: Ensures critical content elements remain intact

Quality Monitoring

quality_monitoring:
  real_time_validation: true
  effectiveness_tracking: true
  user_feedback_integration: true
  adaptive_threshold_adjustment: true

Continuous Improvement: Real-time quality assessment and adaptation

7. Adaptive Compression (adaptive_compression)

Context Awareness

context_awareness:
  user_expertise_factor: true
  project_complexity_factor: true
  domain_specific_optimization: true

Personalization: Compression adapts to user expertise and project context

Learning Integration

learning_integration:
  effectiveness_feedback: true
  user_preference_learning: true
  pattern_optimization: true

Machine Learning: Continuous improvement through usage patterns

Dynamic Adjustment

dynamic_adjustment:
  resource_pressure_response: true
  quality_threshold_adaptation: true
  performance_optimization: true

Real-Time Adaptation: Adjusts compression based on system state

Performance Targets

Processing Performance

performance_targets:
  processing_time_ms: 150
  compression_ratio_target: 0.50 # 50% compression
  quality_preservation_target: 0.95
  token_efficiency_gain: 0.40 # 40% token reduction

Optimization Goals: Balances speed, compression, and quality

Compression Level Performance

Each compression level has specific performance characteristics:

• Minimal: 1.0x processing time, 98% quality
• Efficient: 1.2x processing time, 95% quality
• Compressed: 1.5x processing time, 90% quality
• Critical: 1.8x processing time, 85% quality
• Emergency: 2.0x processing time, 80% quality

Integration Points

MCP Server Integration

integration:
  mcp_servers:
    morphllm: "coordinate_compression_with_editing"
    serena: "memory_compression_strategies"
  
  modes:
    token_efficiency: "primary_compression_mode"
    task_management: "session_data_compression"

System Coordination: Integrates with MCP servers for coordinated optimization

Learning Engine Integration

learning_engine:
  effectiveness_tracking: true
  pattern_learning: true
  adaptation_feedback: true

Continuous Learning: Improves compression effectiveness through usage analysis

Cache Configuration

Compression Results Caching

caching:
  compression_results:
    enabled: true
    cache_duration_minutes: 30
    max_cache_size_mb: 50
    invalidation_strategy: "content_change_detection"

Performance Optimization: Caches compression results for repeated content

Pattern Recognition Caching

pattern_recognition:
  enabled: true
  adaptive_pattern_learning: true
  user_specific_patterns: true

Intelligent Caching: Learns and caches user-specific compression patterns

Best Practices

1. Content Classification

Always classify content before compression:

• Framework content → Zero compression
• User project content → Minimal compression
• Session data → Efficient compression
• Temporary data → Compressed/Critical levels

2. Quality Monitoring

Monitor compression effectiveness:

• Track quality preservation metrics
• Monitor user satisfaction with compressed content
• Adjust thresholds based on effectiveness feedback

3. Context-Aware Application

Adapt compression to context:

• User expertise level (beginner → minimal, expert → compressed)
• Project complexity (simple → efficient, complex → minimal)
• Resource pressure (low → minimal, high → critical)

4. Performance Optimization

Balance compression with performance:

• Use caching for repeated content
• Monitor processing time vs. quality trade-offs
• Adjust compression levels based on system resources

5. Learning Integration

Enable continuous improvement:

• Track compression effectiveness
• Learn user preferences for compression levels
• Adapt symbol and abbreviation usage based on domain

Troubleshooting

Common Issues

Quality Degradation

• Symptom: Users report information loss or confusion
• Solution: Reduce compression level, adjust quality thresholds
• Prevention: Enable real-time quality monitoring

Performance Issues

• Symptom: Compression takes too long (>150ms target)
• Solution: Enable caching, reduce compression complexity
• Monitoring: Track processing time per compression level

Symbol/Abbreviation Confusion

• Symptom: Users don't understand compressed content
• Solution: Adjust to user expertise level, provide symbol legend
• Adaptation: Learn user preference patterns

Cache Issues

• Symptom: Stale compression results, cache bloat
• Solution: Adjust cache invalidation strategy, reduce cache size
• Maintenance: Enable automatic cache cleanup

Configuration Validation

The framework validates compression configuration:

• Range Validation: Quality thresholds between 0.0-1.0
• Performance Validation: Processing time targets achievable
• Pattern Validation: Symbol and abbreviation mappings are valid
• Integration Validation: MCP server and mode coordination settings

Related Documentation

• Token Efficiency Mode: See MODE_Token_Efficiency.md for behavioral patterns
• Pre-Compact Hook: Review hook implementation for compression execution
• MCP Integration: Reference Morphllm documentation for editing coordination
• Quality Gates: See validation documentation for quality preservation

Version History

• v1.0.0: Initial compression configuration with 5-level strategy
• Selective compression with framework protection
• Symbol and abbreviation systems implementation
• Adaptive compression with learning integration
• Quality preservation with real-time monitoring