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%)
```yaml
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%)
```yaml
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%)
```yaml
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%)
```yaml
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%+)
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
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
```yaml
learning_integration:
  effectiveness_feedback: true
  user_preference_learning: true
  pattern_optimization: true
```

**Machine Learning**: Continuous improvement through usage patterns

#### Dynamic Adjustment
```yaml
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
```yaml
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
```yaml
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
```yaml
learning_engine:
  effectiveness_tracking: true
  pattern_learning: true
  adaptation_feedback: true
```

**Continuous Learning**: Improves compression effectiveness through usage analysis

## Cache Configuration

### Compression Results Caching
```yaml
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
```yaml
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