SuperClaude/Framework-Lite/Core/SESSION_LIFECYCLE.md

# SuperClaude Session Lifecycle Pattern

## Overview

The Session Lifecycle Pattern defines how SuperClaude manages work sessions through integration with Serena MCP, enabling continuous learning and context preservation across sessions.

## Core Concept

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  /sc:load   │────▶│    WORK     │────▶│  /sc:save   │────▶│    NEXT     │
│  (INIT)     │     │  (ACTIVE)   │     │ (CHECKPOINT)│     │  SESSION    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
       │                                                              │
       └──────────────────── Enhanced Context ───────────────────────┘
```

## Session States

### 1. INITIALIZING
- **Trigger**: `/sc:load` command execution
- **Actions**:
  - Activate project via `activate_project`
  - Load existing memories via `list_memories`
  - Check onboarding status
  - Build initial context with framework exclusion
  - Initialize session context and memory structures
- **Content Management**:
  - **Session Data**: Session metadata, checkpoints, cache content
  - **Framework Content**: All SuperClaude framework components loaded
  - **User Content**: Project files, user docs, configurations loaded
- **Duration**: <500ms target
- **Next State**: ACTIVE

### 2. ACTIVE
- **Description**: Working session with full context
- **Characteristics**:
  - Project memories loaded
  - Context available for all operations
  - Changes tracked for persistence
  - Decisions logged for replay
- **Checkpoint Triggers**:
  - Manual: User requests via `/sc:save --checkpoint`
  - Automatic: See Automatic Checkpoint Triggers section
- **Next State**: CHECKPOINTED or COMPLETED

### 3. CHECKPOINTED
- **Trigger**: `/sc:save` command or automatic trigger
- **Actions**:
  - Analyze session changes via `think_about_collected_information`
  - Persist discoveries to appropriate memories
  - Create checkpoint record with session metadata
  - Generate summary if requested
- **Storage Strategy**:
  - **Framework Content**: All framework components stored
  - **Session Metadata**: Session operational data stored
  - **User Work Products**: Full fidelity preservation
- **Memory Keys Created**:
  - `session/{timestamp}` - Session record with metadata
  - `checkpoints/{timestamp}` - Checkpoint with session data
  - `summaries/{date}` - Daily summary (optional)
- **Next State**: ACTIVE (continue) or COMPLETED

### 4. RESUMED
- **Trigger**: `/sc:load` after previous checkpoint
- **Actions**:
  - Load latest checkpoint via `read_memory`
  - Restore session context and data
  - Display resumption summary
  - Continue from last state
- **Restoration Strategy**:
  - **Framework Content**: Load framework content directly
  - **Session Context**: Restore session operational data
  - **User Context**: Load preserved user content
- **Special Features**:
  - Shows work completed in previous session
  - Highlights open tasks/questions
  - Restores decision context with full fidelity
- **Next State**: ACTIVE

### 5. COMPLETED
- **Trigger**: Session end or explicit completion
- **Actions**:
  - Final checkpoint creation
  - Session summary generation
  - Memory consolidation
  - Cleanup operations
- **Final Outputs**:
  - Session summary in memories
  - Updated project insights
  - Enhanced context for next session

## Checkpoint Mechanisms

### Manual Checkpoints
```bash
/sc:save --checkpoint                  # Basic checkpoint
/sc:save --checkpoint --summarize      # With summary
/sc:save --checkpoint --type all       # Comprehensive
```

### Automatic Checkpoint Triggers

#### 1. Task-Based Triggers
- **Condition**: Major task marked complete
- **Implementation**: Hook into TodoWrite status changes
- **Frequency**: On task completion with priority="high"
- **Memory Key**: `checkpoints/task-{task-id}-{timestamp}`

#### 2. Time-Based Triggers
- **Condition**: Every 30 minutes of active work
- **Implementation**: Session timer with activity detection
- **Frequency**: 30-minute intervals
- **Memory Key**: `checkpoints/auto-{timestamp}`

#### 3. Risk-Based Triggers
- **Condition**: Before high-risk operations
- **Examples**:
  - Major refactoring (>50 files)
  - Deletion operations
  - Architecture changes
  - Security-sensitive modifications
- **Memory Key**: `checkpoints/risk-{operation}-{timestamp}`

#### 4. Error Recovery Triggers
- **Condition**: After recovering from errors
- **Purpose**: Preserve error context and recovery steps
- **Memory Key**: `checkpoints/recovery-{timestamp}`

## Session Metadata Structure

### Core Metadata
```yaml
# Stored in: session/{timestamp}
session:
  id: "session-2025-01-31-14:30:00"
  project: "SuperClaude"
  start_time: "2025-01-31T14:30:00Z"
  end_time: "2025-01-31T16:45:00Z"
  duration_minutes: 135
  
context:
  memories_loaded:
    - project_purpose
    - tech_stack
    - code_style_conventions
  initial_context_size: 15420
  final_context_size: 23867
  context_stats:
    session_data_size: 3450      # Session metadata size
    framework_content_size: 12340 # Framework content size
    user_content_size: 16977      # User content size
    total_context_bytes: 32767
    retention_ratio: 0.92
  
work:
  tasks_completed:
    - id: "TASK-006"
      description: "Refactor /sc:load command"
      duration_minutes: 45
    - id: "TASK-007"
      description: "Implement /sc:save command"
      duration_minutes: 60
      
  files_modified:
    - path: "/SuperClaude/Commands/load.md"
      operations: ["edit"]
      changes: 6
    - path: "/SuperClaude/Commands/save.md"
      operations: ["create"]
      
  decisions_made:
    - timestamp: "2025-01-31T15:00:00Z"
      decision: "Use Serena MCP tools directly in commands"
      rationale: "Commands are orchestration instructions"
      impact: "architectural"
      
discoveries:
  patterns_found:
    - "MCP tool naming convention: direct tool names"
    - "Commands use declarative markdown format"
  insights_gained:
    - "SuperClaude as orchestration layer"
    - "Session persistence enables continuous learning"
    
checkpoints:
  - timestamp: "2025-01-31T15:30:00Z"
    type: "automatic"
    trigger: "30-minute-interval"
  - timestamp: "2025-01-31T16:00:00Z"
    type: "manual"
    trigger: "user-requested"
```

### Checkpoint Metadata
```yaml
# Stored in: checkpoints/{timestamp}
checkpoint:
  id: "checkpoint-2025-01-31-16:00:00"
  session_id: "session-2025-01-31-14:30:00"
  type: "manual|automatic|risk|recovery"
  
state:
  active_tasks:
    - id: "TASK-008"
      status: "in_progress"
      progress: "50%"
  open_questions:
    - "Should automatic checkpoints include full context?"
    - "How to handle checkpoint size limits?"
  blockers: []
  
context_snapshot:
  size_bytes: 45678
  key_memories:
    - "project_purpose"
    - "session/current"
  recent_changes:
    - "Updated /sc:load command"
    - "Created /sc:save command"
    
recovery_info:
  restore_command: "/sc:load --checkpoint checkpoint-2025-01-31-16:00:00"
  dependencies_check: "all_clear"
  estimated_restore_time_ms: 450
```

## Memory Organization

### Session Memories Hierarchy
```
memories/
├── session/
│   ├── current                    # Always points to latest session
│   ├── {timestamp}                # Individual session records
│   └── history/                   # Archived sessions (>30 days)
├── checkpoints/
│   ├── latest                     # Always points to latest checkpoint
│   ├── {timestamp}                # Individual checkpoints
│   └── task-{id}-{timestamp}      # Task-specific checkpoints
├── summaries/
│   ├── daily/{date}               # Daily work summaries
│   ├── weekly/{week}              # Weekly aggregations
│   └── insights/{topic}           # Topical insights
└── project_state/
    ├── context_enhanced           # Accumulated context
    ├── patterns_discovered        # Code patterns found
    └── decisions_log              # Architecture decisions
```

## Integration Points

### With Python Hooks (Future)
```python
# Planned hook integration points
class SessionLifecycleHooks:
    def on_session_start(self, context):
        """Called after /sc:load completes"""
        pass
        
    def on_task_complete(self, task_id, result):
        """Trigger automatic checkpoint"""
        pass
        
    def on_error_recovery(self, error, recovery_action):
        """Checkpoint after error recovery"""
        pass
        
    def on_session_end(self, summary):
        """Called during /sc:save"""
        pass
```

### With TodoWrite Integration
- Task completion triggers checkpoint evaluation
- High-priority task completion forces checkpoint
- Task state included in session metadata

### With MCP Servers
- **Serena**: Primary storage and retrieval
- **Sequential**: Session analysis and summarization
- **Morphllm**: Pattern detection in session changes

## Performance Targets

### Operation Timings
- Session initialization: <500ms
- Checkpoint creation: <1s
- Checkpoint restoration: <500ms
- Summary generation: <2s
- Memory write operations: <200ms each

### Storage Efficiency
- Session metadata: <10KB per session typical
- Checkpoint size: <50KB typical, <200KB maximum
- Summary size: <5KB per day typical
- Automatic pruning: Sessions >90 days
- **Storage Benefits**:
  - Efficient session data management
  - Fast checkpoint restoration (<500ms)
  - Optimized memory operation performance

## Error Handling

### Checkpoint Failures
- **Strategy**: Queue locally, retry on next operation
- **Fallback**: Write to local `.superclaude/recovery/` directory
- **User Notification**: Warning with manual recovery option

### Session Recovery
- **Corrupted Checkpoint**: Fall back to previous checkpoint
- **Missing Dependencies**: Load partial context with warnings
- **Serena Unavailable**: Use cached local state

### Conflict Resolution
- **Concurrent Sessions**: Last-write-wins with merge option
- **Divergent Contexts**: Present diff to user for resolution
- **Version Mismatch**: Compatibility layer for migration

## Best Practices

### For Users
1. Run `/sc:save` before major changes
2. Use `--checkpoint` flag for critical work
3. Review summaries weekly for insights
4. Clean old checkpoints periodically

### For Development
1. Include decision rationale in metadata
2. Tag checkpoints with meaningful types
3. Maintain checkpoint size limits
4. Test recovery scenarios regularly

## Future Enhancements

### Planned Features
1. **Collaborative Sessions**: Multi-user checkpoint sharing
2. **Branching Checkpoints**: Exploratory work paths
3. **Intelligent Triggers**: ML-based checkpoint timing
4. **Session Analytics**: Work pattern insights
5. **Cross-Project Learning**: Shared pattern detection

### Hook System Integration
- Automatic checkpoint on hook execution
- Session state in hook context
- Hook failure recovery checkpoints
- Performance monitoring via hooks