ajbcoding/moai-alfred-session-state

Alfred Session State Management Skill (Enterprise v4.0.0)

Skill Metadata

| Field | Value | | ----- | ----- | | Skill Name | moai-alfred-session-state | | Version | 4.0.0 (Enterprise) | | Updated | 2025-11-12 | | Status | Active | | Tier | Alfred | | Supported Models | Claude Sonnet 4.5, Claude Haiku 4.5 | | Context Window | 200K tokens (Sonnet/Haiku), 500K tokens (Enterprise), 1M tokens (beta) | | Key Features | Context Awareness, Token Budget Tracking, Session Persistence, Adaptive Recovery |

---

What It Does

Provides enterprise-grade session state management for extended workflows, token budget optimization, runtime tracking, and handoff protocols to maintain context continuity across Alfred workflows and session boundaries.

Enterprise v4.0.0 Capabilities:

• ✅ Context-aware token budget management (November 2025 Claude API features)
• ✅ Session persistence with automatic history loading
• ✅ Session forking for parallel exploration
• ✅ Incremental multi-pack index optimization (Git 2.47+ integration)
• ✅ Context continuity across handoffs with state snapshots
• ✅ Progressive disclosure for memory efficiency
• ✅ Adaptive recovery checkpoints
• ✅ Multi-agent coordination protocols
• ✅ Memory file state synchronization
• ✅ Token budget awareness callbacks (Sonnet/Haiku 4.5 feature)

---

When to Use

Automatic triggers:

• Session start/end events
• Long-running task execution (>10 minutes)
• Multi-agent handoffs
• Context window approaching limits
• Model switches (Haiku ↔ Sonnet)
• Workflow phase transitions

Manual reference:

• Session state debugging and recovery
• Token budget optimization strategies
• Handoff protocol design
• Context continuity planning
• Multi-session workflow design

---

Token Budget Management (November 2025)

Context Awareness Feature

Claude Sonnet 4.5 and Haiku 4.5 feature built-in context awareness, enabling these models to:

• Track remaining context window ("token budget") throughout conversation
• Understand current position within 200K token limit (Sonnet/Haiku)
• Execute adaptive strategies based on available tokens
• Automatically manage context without manual intervention

Key Advantage: Models now self-regulate context usage in real time.

Token Budget Optimization Framework

Token Allocation Strategy (200K Sonnet context):
├── System Prompt & Instructions: ~15K tokens (7.5%)
│   ├── CLAUDE.md: ~8K
│   ├── Command definitions: ~4K
│   └── Skill metadata: ~3K
├── Active Conversation: ~80K tokens (40%)
│   ├── Recent messages: ~50K
│   ├── Context cache: ~20K
│   └── Active references: ~10K
├── Reference Context (Progressive Disclosure): ~50K (25%)
│   ├── Project structure: ~15K
│   ├── Related Skills: ~20K
│   └── Tool definitions: ~15K
└── Reserve (Emergency Recovery): ~55K tokens (27.5%)
    ├── Session state snapshot: ~10K
    ├── TAGs and cross-references: ~15K
    ├── Error recovery context: ~20K
    └── Free buffer: ~10K

Optimization Techniques (v4.0.0)

Technique 1: Progressive Summarization

Step 1: Original context (50K tokens)
Step 2: Compress to summary (15K tokens)
Step 3: Add pointers to original → 35K tokens saved
Step 4: Carry forward summary only across handoffs

Technique 2: Context Tagging with Unique Identifiers

❌ Bad (high token cost):
"The user configuration from the previous 20 messages..."

✅ Good (efficient reference):

Technique 3: Structured Context Architecture

├── Critical Context (ALWAYS keep)
│   ├── Current task objectives
│   ├── User preferences & expertise level
│   └── Active constraints
├── Supporting Context (keep if space allows)
│   ├── Related history
│   ├── Reference documentation
│   └── Tool availability
└── Temporary Context (discard when not needed)
    ├── Raw tool outputs
    ├── Intermediate calculations
    └── Debug information

Technique 4: MCP Server Context Budget

# Check MCP server context consumption
/context

# Result: Each enabled MCP server adds tool definitions
# Example: context7 MCP = ~2K tokens for tool definitions

# Optimization: Disable unused servers before critical tasks
# Typical savings: 5-10K tokens per unused MCP server

Technique 5: Task-Based Session Management

Strategy: Start new conversation for distinct tasks

Benefits:
- Fresh 200K token budget per task
- Eliminates stale context accumulation
- Enables parallel session forking
- Improves recovery speed

Implementation:
1. Complete current task in Session A
2. Save session snapshot to .moai/sessions/
3. Start Session B for new task with fresh context
4. Resume Session A later if needed via session ID

---

Session State Architecture (Enterprise v4.0.0)

State Layers

Session State Stack (Enterprise v4.0.0):
├── L1: Context-Aware Layer (Claude 4.5+ feature)
│   ├── Token budget tracking
│   ├── Context window position
│   ├── Auto-summarization triggers
│   └── Model-specific optimizations
├── L2: Active Context (current task, variables, scope)
├── L3: Session History (recent actions, decisions)
├── L4: Project State (SPEC progress, milestones)
├── L5: User Context (preferences, language, expertise)
└── L6: System State (tools, permissions, environment)

Session Creation & Persistence

Agent SDK Session Management (November 2025 API):

{
  "session_id": "sess_uuid_v4",
  "model": "claude-sonnet-4-5-20250929",
  "created_at": "2025-11-12T10:30:00Z",
  "context_window": {
    "total": 200000,
    "used": 85000,
    "available": 115000,
    "position_percent": 42.5
  },
  "persistence": {
    "auto_load_history": true,
    "context_preservation": "critical_only",
    "cache_enabled": true
  },
  "forking": {
    "enabled": true,
    "fork_session_id": "sess_fork_uuid",
    "checkpoint_timestamp": "2025-11-12T10:30:00Z"
  }
}

Session Resumption Pattern

# Capture session ID from initial response
session_id = extract_session_id(response)

# Save for later use
save_session_checkpoint({
    'session_id': session_id,
    'timestamp': now(),
    'model': 'claude-sonnet-4-5',
    'context_state': current_context_snapshot()
})

# Later: Resume conversation
response = claude.messages.create(
    model="claude-sonnet-4-5-20250929",
    resume=session_id,  # Continue from checkpoint
    messages=[new_message]
)

# Or: Fork session for parallel exploration
response = claude.messages.create(
    model="claude-sonnet-4-5-20250929",
    fork_session=session_id,  # Branch from checkpoint
    messages=[alternative_message]
)

---

Runtime State Tracking

Task State Machine (Enterprise v4.0.0)

Workflow State Transitions:

pending → in_progress → blocked (waiting) → completed/failed
             ↓                                    ↓
         [monitor token budget]          [save checkpoint]
         [track elapsed time]            [update history]
         [check for recovery]            [archive state]

Task Lifecycle States:

• pending - Queued but not started
• in_progress - Currently executing (monitor tokens)
• blocked - Waiting for dependencies or input
• token_warning - Approaching context limit (v4.0.0)
• context_switch - Model change or session fork
• completed - Finished successfully
• failed - Error occurred, initiating recovery
• recovered - Resumed from checkpoint

Token Budget Callbacks (Haiku/Sonnet 4.5 Feature)

def token_budget_callback(context):
    """
    Called automatically when token budget changes.
    Model provides real-time context awareness.
    """
    
    remaining_tokens = context.available_tokens
    used_percent = context.token_usage_percent
    
    if used_percent > 85:
        # Activate emergency summarization
        compress_context_window()
        archive_old_context()
        
    elif used_percent > 75:
        # Start progressive disclosure
        defer_non_critical_context()
        
    elif used_percent > 60:
        # Monitor for safety
        track_context_growth()

---

Session Handoff Protocols

Inter-Agent Handoff Package (Enterprise v4.0.0)

{
  "handoff_id": "uuid-v4",
  "timestamp": "2025-11-12T10:30:00Z",
  "from_agent": "spec-builder",
  "to_agent": "tdd-implementer",
  "session_context": {
    "session_id": "sess_uuid",
    "model": "claude-sonnet-4-5-20250929",
    "context_position": 42.5,
    "available_tokens": 115000,
    "user_language": "ko",
    "expertise_level": "intermediate",
    "current_project": "MoAI-ADK"
  },
  "task_context": {
    "spec_id": "SPEC-001",
    "current_phase": "implementation",
    "completed_steps": ["spec_complete", "architecture_defined"],
    "next_step": "write_tests",
    "constraints": ["must_use_pytest", "coverage_85"]
  },
  "context_snapshot": {
    "critical_context": "...compressed...",
    "session_checkpoints": [...],
    "active_todos": [...],
    "token_budget_strategy": "progressive_summarization"
  },
  "recovery_info": {
    "last_checkpoint": "2025-11-12T10:25:00Z",
    "recovery_tokens_reserved": 55000,
    "session_fork_available": true
  }
}

Handoff Validation (Enterprise v4.0.0)

def validate_handoff(handoff_package):
    """Enterprise validation with token budget check"""
    
    required_fields = [
        'handoff_id', 'from_agent', 'to_agent',
        'session_context', 'task_context', 'context_snapshot'
    ]
    
    for field in required_fields:
        if field not in handoff_package:
            raise HandoffError(f"Missing required field: {field}")
    
    # NEW v4.0.0: Validate token budget
    context = handoff_package['session_context']
    available = context['available_tokens']
    if available < 30000:  # Minimum safe buffer
        trigger_context_compression()
    
    # Validate agent compatibility
    if not can_agents_cooperate(
        handoff_package['from_agent'],
        handoff_package['to_agent']
    ):
        raise AgentCompatibilityError("Agents cannot cooperate")
    
    return True

---

Session Recovery (Enterprise v4.0.0)

Recovery Checkpoints

Checkpoint Triggers:

• Task phase boundaries (before RED, GREEN, REFACTOR)
• Agent handoffs
• User interruptions
• Token budget thresholds
• Error conditions
• Session timeouts

Checkpoint Structure:

{
  "checkpoint_id": "ckpt_uuid",
  "timestamp": "2025-11-12T10:30:00Z",
  "phase": "GREEN",
  "token_usage": {
    "used": 85000,
    "available": 115000
  },
  "context_snapshot": "...compressed snapshot...",
  "session_id": "sess_uuid",
  "recovery_tokens_reserved": 55000
}

Recovery Process (Enterprise v4.0.0)

1. State Restoration - Reload last valid checkpoint
2. Context Validation - Verify token budget sufficient
3. Session Resumption - Use Agent SDK resume feature
4. Progress Assessment - Determine what was completed
5. Continuation Planning - Decide next steps with updated token budget
6. User Notification - Inform user of recovery status

---

Memory State Synchronization

Memory Files (v4.0.0)

Files:

• .moai/sessions/session-state.json - Current session metadata
• .moai/sessions/context-cache.json - Cached context for performance
• .moai/sessions/checkpoints/ - Saved recovery checkpoints
• .moai/sessions/token-usage.log - Token budget history
• active-tasks.md - TodoWrite task tracking

Synchronization Protocol:

def sync_memory_files(session_state):
    """Ensure memory files reflect current session state"""
    
    # Update session metadata with token info
    update_session_metadata({
        'session_id': session_state.id,
        'token_usage': session_state.token_budget,
        'context_position': session_state.context_position,
        'last_sync': timestamp()
    })
    
    # Sync TodoWrite tasks
    sync_todowrite_tasks(session_state.active_tasks)
    
    # Update context cache (compressed)
    update_context_cache(compress_context(session_state.context))
    
    # Log token usage for analytics
    log_token_usage({
        'timestamp': timestamp(),
        'used': session_state.tokens_used,
        'available': session_state.tokens_available,
        'percent': session_state.usage_percent
    })
    
    # Archive old checkpoints (>7 days)
    archive_old_checkpoints()

---

Best Practices (Enterprise v4.0.0)

Context Management

✅ DO:

• Use context-aware token budget tracking (Sonnet/Haiku 4.5 feature)
• Create checkpoints before major operations
• Apply progressive summarization for long workflows
• Enable session persistence for recovery
• Monitor token usage and plan accordingly
• Use session forking for parallel exploration

❌ DON'T:

• Accumulate unlimited context history
• Ignore token budget warnings
• Skip state validation on recovery
• Lose session IDs without saving
• Mix multiple sessions without clear boundaries
• Assume session continuity without checkpoint

Token Budget Optimization

✅ DO:

• Start new session per distinct task (fresh 200K tokens)
• Use /context to identify expensive MCP servers
• Compress context before handoffs
• Keep reserve buffer (25-30% of tokens)
• Monitor usage percent, not absolute tokens
• Enable auto-summarization at 75% threshold

❌ DON'T:

• Let single conversation exceed 150K tokens
• Keep all MCP servers enabled if not needed
• Reuse sessions across fundamentally different tasks
• Ignore available_tokens feedback
• Store uncompressed context in memory files

---

Configuration

Location: .moai/config/config.json

{
  "session": {
    "persistence_enabled": true,
    "auto_checkpoint": true,
    "checkpoint_interval_minutes": 10,
    "recovery_strategy": "progressive_summarization",
    "context_budget": {
      "warning_threshold_percent": 75,
      "emergency_threshold_percent": 85,
      "reserve_tokens": 55000
    },
    "forking_enabled": true,
    "max_parallel_sessions": 3
  }
}

---

Debugging & Troubleshooting

Inspection Tools

# View current session state
/alfred:debug --show-session-state

# Check context window position
/alfred:debug --show-token-budget

# View all checkpoints
/alfred:debug --list-checkpoints

# Validate memory synchronization
/alfred:debug --check-memory-sync

# Show token usage history
/alfred:debug --show-token-usage-log

Common Issues

| Issue | Symptoms | Solution | |-------|----------|----------| | Lost session | Cannot resume conversation | Check .moai/sessions/ for session IDs | | Token budget exceeded | Model stops responding | Use /context to identify heavy consumers, create new session | | Handoff failed | Agent has wrong context | Verify handoff package completeness before transfer | | Recovery stuck | Cannot continue after interruption | Restore from earlier checkpoint or start new session | | Memory drift | Inconsistent information | Run sync_memory_files() or check cache integrity |

---

Version History

| Version | Date | Key Changes | |---------|------|-------------| | 4.0.0 | 2025-11-12 | Enterprise context awareness, token budget tracking, Session SDK integration, Git 2.47+ support | | 1.1.0 | 2025-11-05 | Session state management foundation | | 1.0.0 | 2025-10-01 | Initial release |

---

Related Skills

• moai-alfred-context-budget - Token optimization deep dive
• moai-alfred-agent-guide - Multi-agent coordination
• moai-foundation-trust - State validation principles
• moai-foundation-git - Git session state tracking

---

Learn more in reference.md for detailed implementation guides, recovery procedures, advanced coordination patterns, and November 2025 API examples.

Skill Status: Production Ready | Last Updated: 2025-11-12 | Model Support: Sonnet 4.5, Haiku 4.5 | Enterprise v4.0.0