SuperClaude/User-Guide/session-management.md

SuperClaude Session Management Guide 🧠

Introduction

SuperClaude transforms Claude Code from a stateless assistant into a persistent development partner through intelligent session management. Sessions preserve project context, accumulated insights, and development progress across interruptions, creating continuity that builds expertise over time.

Persistent Intelligence: Load project context with /sc:load, work naturally with accumulated understanding, save progress with /sc:save, and resume exactly where you left off. SuperClaude remembers your codebase structure, decisions made, patterns discovered, and project goals.

Cross-Session Learning: Each session builds on previous understanding, creating a development partner that becomes more effective with your specific project over time.

Session Fundamentals

What is a SuperClaude Session? A session is a persistent development context that includes:

• Project Understanding: Codebase structure, architecture patterns, dependencies
• Development History: Decisions made, problems solved, patterns applied
• Current State: Active tasks, progress tracking, next steps
• Learned Insights: Code conventions, team preferences, domain knowledge

Session Intelligence vs Standard Claude:

• Standard Claude: Each conversation starts fresh, no project memory
• SuperClaude Sessions: Cumulative understanding that builds over time

Session Types:

Project Sessions: Long-term development context for specific codebases

• Persistent across weeks/months of development
• Accumulates architectural understanding
• Remembers team conventions and decisions

Task Sessions: Focused context for specific features or problems

• Short to medium-term (hours to days)
• Maintains task-specific context and progress
• Integrates with project sessions for broader context

Learning Sessions: Educational context for understanding complex systems

• Preserves learning progress and insights
• Builds conceptual understanding over time
• Connects theoretical knowledge with practical application

Session Persistence Powered by Serena MCP:

• Semantic code understanding with symbol-level navigation
• Project memory that survives Claude Code restarts
• Intelligent context loading based on current work
• Cross-session insight accumulation and pattern recognition

Session Commands

/sc:load - Session Initialization

Purpose: Load project context and initialize persistent development session

Usage Patterns:

# Load existing project context
/sc:load src/

# Load with specific focus
/sc:load --focus architecture existing-project/

# Load previous session by name
/sc:load "payment-integration-session"

# Load with fresh analysis
/sc:load --refresh large-codebase/

What Happens During Load:

1. Project Structure Analysis: Serena MCP scans codebase organization
2. Context Restoration: Previous session memory and insights loaded
3. Pattern Recognition: Code conventions and architecture patterns identified
4. Dependency Mapping: Component relationships and data flow understood
5. Session Initialization: Persistent context established for continued work

Load Modes:

Smart Load (Default):

/sc:load project-directory/

• Automatically detects project type and structure
• Loads relevant previous session context
• Optimizes analysis based on project size and complexity

Focused Load:

/sc:load --focus security payment-system/
/sc:load --focus performance api-endpoints/
/sc:load --focus architecture microservices/

• Specialized analysis for specific concerns
• Activates domain experts and relevant tools
• Loads context specific to focus area

Fresh Load:

/sc:load --refresh --comprehensive legacy-system/

• Re-analyzes project from scratch
• Updates understanding with latest changes
• Comprehensive re-indexing of codebase

Example Load Experience:

/sc:load e-commerce-platform/

→ 🔍 Analyzing project structure...
→ 📂 Detected: React frontend + Node.js API + PostgreSQL
→ 🧠 Loading previous session: "checkout-optimization-work"
→ 📝 Restored context: 847 files analyzed, 23 patterns identified
→ ✅ Session ready: Continue checkout flow optimization
→ 💡 Next: Complete payment validation implementation

/sc:save - Session Persistence

Purpose: Preserve session context and development progress for future continuation

Usage Patterns:

# Save current session with automatic naming
/sc:save

# Save with descriptive name
/sc:save "authentication-module-complete"

# Save checkpoint during long work
/sc:save --checkpoint "api-endpoints-analysis-done"

# Save with summary
/sc:save --description "Completed user registration flow, ready for testing"

What Gets Saved:

• Project Understanding: Current codebase analysis and insights
• Work Progress: Completed tasks, current focus, next steps
• Decision History: Architectural choices, patterns applied, trade-offs made
• Code Context: Modified files, dependencies, integration points
• Learning Insights: Discovered patterns, conventions, best practices

Save Types:

Milestone Save:

/sc:save "payment-integration-complete"

• Major feature completion or phase end
• Comprehensive context preservation
• Clear handoff point for future sessions

Checkpoint Save:

/sc:save --checkpoint "database-schema-analysis"

• Periodic progress preservation
• Intermediate work state capture
• Recovery point for complex work

Automatic Save:

# Triggered automatically during:
- Long-running tasks (every 30 minutes)
- Before risky operations
- Session interruption detection
- Context limit approaching

Save Output Example:

/sc:save "user-dashboard-feature-complete"

→ 💾 Saving session context...
→ 📊 Progress summary:
  ✅ 3 components implemented
  ✅ 12 tests passing
  ✅ API integration complete
  📝 Documentation updated
→ 🧠 Context preserved:
  - 247 files in working memory
  - 15 architectural patterns identified
  - 8 integration points mapped
→ ✅ Session saved: "user-dashboard-feature-complete"
→ 🔄 Ready for future continuation

/sc:reflect - Session Validation

Purpose: Analyze session progress, validate task completion, and assess development quality

Usage Patterns:

# General session reflection
/sc:reflect

# Specific task validation
/sc:reflect "payment-processing-implementation"

# Quality assessment
/sc:reflect --type quality-review

# Completion verification
/sc:reflect --type completion-check

Reflection Types:

Progress Analysis:

/sc:reflect --type progress

• Current task status and completion percentage
• Blockers and dependencies identified
• Next steps and priority recommendations
• Timeline and effort assessment

Quality Review:

/sc:reflect --type quality

• Code quality assessment and improvements needed
• Test coverage and validation gaps
• Security and performance considerations
• Documentation and maintainability review

Completion Verification:

/sc:reflect --type completion

• Task completion criteria assessment
• Integration and testing verification
• Deployment readiness evaluation
• Handoff preparation and next steps

Learning Assessment:

/sc:reflect --type learning

• Insights gained and patterns discovered
• Decision rationale and trade-offs made
• Knowledge gaps and learning opportunities
• Best practices and conventions established

Example Reflection Output:

/sc:reflect --type completion "user-authentication-system"

→ 🎯 Task Completion Analysis:
  ✅ JWT authentication implemented
  ✅ Password hashing and validation  
  ✅ Session management
  ⚠️  Email verification pending
  ❌ OAuth integration incomplete

→ 📊 Quality Assessment:
  ✅ Security best practices followed
  ✅ 89% test coverage achieved
  ⚠️  Performance testing needed
  ✅ Documentation complete

→ 🔄 Next Steps:
  1. Complete email verification flow
  2. Implement OAuth providers
  3. Performance optimization
  4. Production deployment preparation

→ 💡 Session Status: 75% complete, 2-3 days remaining

Session Lifecycle Management

Complete Session Workflow:

Phase 1: Session Initialization

# 1. Project Discovery and Loading
/sc:load new-project/
→ Project analysis and context establishment

# 2. Goal Setting and Planning  
/sc:brainstorm "improve user onboarding experience"
→ Requirements discovery and strategic planning

# 3. Initial Analysis
/sc:analyze --focus user-experience --think-hard
→ Comprehensive system understanding

Phase 2: Active Development

# 4. Implementation Planning
/sc:workflow "streamlined-onboarding-flow"
→ Systematic implementation strategy

# 5. Feature Development (Iterative)
/sc:implement "progressive-user-registration"
→ Coordinated development with automatic progress tracking

# 6. Regular Checkpoints
/sc:save --checkpoint "registration-flow-complete"
→ Periodic progress preservation

Phase 3: Validation and Quality

# 7. Progress Review
/sc:reflect --type progress
→ Status assessment and next steps

# 8. Quality Assurance
/sc:test --comprehensive user-onboarding/
→ Testing and validation workflows

# 9. Quality Review
/sc:reflect --type quality
→ Code review and improvement identification

Phase 4: Completion and Handoff

# 10. Completion Verification
/sc:reflect --type completion
→ Task completion criteria validation

# 11. Final Documentation
/sc:document --type user-guide onboarding-system/
→ Documentation and knowledge transfer

# 12. Session Archive
/sc:save "onboarding-improvement-complete"
→ Final context preservation and handoff preparation

Session State Transitions:

Active Session States:

• Discovery: Requirements exploration and goal setting
• Analysis: System understanding and strategy development
• Implementation: Active development and feature creation
• Validation: Testing, review, and quality assurance
• Completion: Final verification and handoff preparation

Session Continuity Patterns:

• Daily Sessions: Load → Work → Checkpoint → Save
• Weekly Sprints: Load → Sprint planning → Daily work → Sprint review → Save
• Feature Cycles: Load → Analysis → Implementation → Testing → Completion → Save

Memory and Context

Serena MCP-Powered Memory System:

Project Memory Components:

• Structural Memory: Codebase organization, file relationships, dependencies
• Semantic Memory: Code meaning, business logic, domain concepts
• Historical Memory: Development decisions, evolution patterns, change history
• Contextual Memory: Working sessions, current focus, progress state

Memory Operations:

Memory Accumulation:

# As you work, memory automatically builds:
/sc:analyze user-service/
→ Records: Service patterns, data flows, API contracts

/sc:implement "user-preferences"  
→ Records: Implementation patterns, coding conventions, integration points

/sc:troubleshoot "performance-issue"
→ Records: Problem patterns, solution strategies, optimization techniques

Memory Recall:

# Previous insights automatically inform current work:
/sc:implement "user-notifications"
→ Recalls: User service patterns, preference storage, communication flows
→ Applies: Established conventions, tested patterns, integration strategies

Memory Types:

Architectural Memory:

{
  "patterns": ["MVC", "Repository Pattern", "Dependency Injection"],
  "conventions": ["camelCase variables", "async/await preferred"],
  "decisions": ["PostgreSQL for persistence", "JWT for authentication"],
  "integrations": ["Stripe API", "SendGrid", "Redis cache"]
}

Development Memory:

{
  "workflows": ["TDD approach", "Feature branch strategy"],
  "quality_gates": ["ESLint rules", "Test coverage >80%"],
  "preferences": ["Functional components", "Hooks over classes"],
  "tooling": ["Jest testing", "Prettier formatting"]
}

Context Preservation:

{
  "current_task": "implement-user-dashboard",
  "progress": "components-complete-api-pending",
  "next_steps": ["API integration", "state management", "testing"],
  "blockers": ["API rate limiting", "design system tokens"]
}

Memory Intelligence:

Smart Context Loading:

• Loads relevant memory based on current work
• Prioritizes recent and frequently accessed patterns
• Connects related concepts and components

Pattern Recognition:

• Identifies recurring code patterns and conventions
• Suggests consistent approaches based on project history
• Detects deviations from established patterns

Predictive Context:

• Anticipates needed information based on current task
• Pre-loads related components and dependencies
• Suggests next steps based on similar previous work

Session Workflows

Common Session Patterns:

Daily Development Session

# Morning: Resume previous work
/sc:load project/
→ Context restoration and progress review

# Planning: Review and plan day's work
/sc:reflect --type progress
→ Status assessment and priority setting

# Work: Active development with periodic saves
/sc:implement "current-feature"
/sc:save --checkpoint "feature-milestone"

# Evening: End-of-day preservation
/sc:reflect --type completion
/sc:save "end-of-day-progress"

Feature Development Cycle

# Discovery Phase
/sc:load project/
/sc:brainstorm "new-feature-requirements"
/sc:save --checkpoint "requirements-complete"

# Planning Phase  
/sc:workflow "feature-implementation-plan"
/sc:design "feature-architecture"
/sc:save --checkpoint "planning-complete"

# Implementation Phase
/sc:implement "feature-core-functionality"
/sc:save --checkpoint "core-complete"

/sc:implement "feature-integration"
/sc:save --checkpoint "integration-complete"

# Validation Phase
/sc:test --comprehensive feature/
/sc:reflect --type quality
/sc:save "feature-complete"

Bug Investigation Session

# Load with focus on problem area
/sc:load --focus debugging problematic-module/

# Systematic investigation
/sc:troubleshoot "specific-bug-description"
/sc:analyze --focus root-cause affected-components/

# Solution implementation
/sc:implement "bug-fix-solution"
/sc:test --focus regression bug-area/

# Validation and documentation
/sc:reflect --type completion
/sc:document --type bug-report "issue-resolution"
/sc:save "bug-fix-complete"

Learning and Exploration Session

# Focused learning context
/sc:load --focus architecture new-codebase/

# Systematic exploration
/sc:analyze --introspect --think-hard codebase-structure/
/sc:explain "complex-architectural-patterns"

# Knowledge consolidation
/sc:reflect --type learning
/sc:document --type architecture-notes findings/
/sc:save "architecture-understanding-session"

Code Review Session

# Load changes context
/sc:load --focus quality pending-changes/

# Comprehensive review
/sc:analyze --focus quality --think-hard changes/
/sc:test --focus regression change-areas/

# Quality assessment
/sc:reflect --type quality
/sc:document --type review-notes quality-assessment/
/sc:save "code-review-complete"

Session Optimization Patterns:

Short Sessions (1-2 hours):

• Quick load with specific focus
• Targeted work on single component
• Checkpoint saves for continuity

Medium Sessions (Half-day):

• Comprehensive load and planning
• Multi-component development
• Regular checkpoints and quality reviews

Long Sessions (Full-day):

• Full context loading and analysis
• Complex feature development cycles
• Multiple validation and reflection points

Multi-Session Projects

Long-Term Project Management:

Project Session Architecture

# Master Project Session
/sc:load enterprise-platform/
→ Maintains overall project context and architecture understanding

# Feature Branch Sessions  
/sc:load --branch feature/user-management user-service/
/sc:load --branch feature/payment-integration payment-service/
→ Focused context for specific feature development

# Integration Sessions
/sc:load --integration-focus platform-services/
→ Cross-service integration and system-level concerns

Session Hierarchy Management

Project Level (Months):

• Overall architecture and system understanding
• Cross-cutting concerns and integration patterns
• Long-term technical decisions and evolution

Epic Level (Weeks):

• Feature set implementation and integration
• Domain-specific patterns and conventions
• Epic-level progress and quality tracking

Story Level (Days):

• Individual feature implementation
• Component-level development and testing
• Story completion and handoff

Session Coordination Patterns:

Team Coordination:

# Shared Project Context
/sc:load --shared team-project/
→ Common understanding accessible to all team members

# Individual Developer Sessions
/sc:load --developer alice team-project/user-auth/
/sc:load --developer bob team-project/payment-system/
→ Personal development context within shared project

# Integration Sessions
/sc:load --integration team-project/
→ Cross-developer integration and system-level work

Cross-Session Continuity:

Session Handoff:

# End of developer session
/sc:save --handoff "alice-user-auth-complete" --next-developer bob

# New developer pickup
/sc:load --handoff "alice-user-auth-complete"
→ Complete context transfer with work continuation

Progress Synchronization:

# Daily standup preparation
/sc:reflect --type team-progress
→ Team-level progress summary and coordination

# Sprint planning context
/sc:load --sprint-context team-project/
→ Sprint-level understanding and planning context

Long-Term Memory Evolution:

Memory Consolidation:

• Weekly: Consolidate daily insights into persistent patterns
• Monthly: Archive completed features, preserve key learnings
• Quarterly: Architectural review and pattern evolution

Memory Inheritance:

• New features inherit patterns from completed work
• Team members inherit shared conventions and decisions
• Project evolution builds on accumulated architectural understanding

Session Troubleshooting

Common Session Issues:

Session Context Lost

Problem: /sc:load doesn't restore expected context

# Symptoms
/sc:load project/
→ "No previous session found" or minimal context restored

Solutions:

# 1. Check available sessions
/sc:load --list-sessions

# 2. Load by specific session name
/sc:load "session-name"

# 3. Fresh analysis if needed
/sc:load --refresh --comprehensive project/

# 4. Check Serena MCP status
SuperClaude status --mcp serena

Memory Fragmentation

Problem: Session memory becomes inconsistent or incomplete

# Symptoms
- Conflicting pattern suggestions
- Missing context for recent work
- Inconsistent architectural understanding

Solutions:

# 1. Memory consolidation
/sc:reflect --type memory-health
/sc:save --consolidate "clean-session-state"

# 2. Selective memory refresh
/sc:load --refresh-memory specific-area/

# 3. Clean session restart
/sc:save --archive "old-session"
/sc:load --fresh project/

Session Performance Issues

Problem: Slow session loading or excessive memory usage

# Symptoms
- Long load times (>30 seconds)
- Memory warnings during operation
- Reduced response quality

Solutions:

# 1. Optimize session scope
/sc:load --scope module target-area/

# 2. Use focused loading
/sc:load --focus performance specific-concern/

# 3. Memory cleanup
/sc:save --cleanup "optimized-session"

# 4. Check system resources
SuperClaude diagnose --memory

Integration Conflicts

Problem: Multi-session project coordination issues

# Symptoms
- Conflicting architectural decisions
- Integration pattern mismatches
- Cross-team context confusion

Solutions:

# 1. Sync with master session
/sc:load --sync-master project/

# 2. Resolve conflicts explicitly
/sc:reflect --type integration-conflicts
/sc:resolve-conflicts --strategy team-lead-wins

# 3. Re-establish shared context
/sc:load --shared-refresh team-project/

Session Recovery Procedures:

Emergency Session Recovery

# 1. Check session backups
/sc:load --list-backups

# 2. Restore from backup
/sc:load --restore-backup "backup-timestamp"

# 3. Partial recovery if needed
/sc:load --partial-restore specific-components/

# 4. Rebuild from artifacts
/sc:load --rebuild-from git-history project/

Session Health Monitoring

# Regular health checks
/sc:reflect --type session-health
→ Memory consistency, context completeness, performance metrics

# Memory optimization
/sc:save --optimize "clean-session"
→ Consolidate insights, remove redundant context

# Performance tuning
/sc:load --performance-mode project/
→ Optimized loading for resource-constrained environments

Best Practices for Session Reliability:

1. Regular Saves: Save at natural breakpoints and end of work
2. Descriptive Names: Use clear, descriptive session names
3. Health Monitoring: Regular reflection and health checks
4. Backup Strategy: Multiple checkpoint saves during long work
5. Scope Management: Load only necessary context for current work
6. Memory Hygiene: Periodic consolidation and cleanup

Related Guides

Learning Progression:

🌱 Essential (Week 1)

• Quick Start Guide - First session experience
• Commands Reference - Session commands (/sc:load, /sc:save, /sc:reflect)
• Installation Guide - Serena MCP setup for sessions

🌿 Intermediate (Week 2-3)

• MCP Servers Guide - Serena MCP for persistent memory
• Behavioral Modes - Task Management mode for session coordination
• Agents Guide - Agent persistence across sessions

🌲 Advanced (Month 2+)

• Best Practices - Session optimization strategies
• Examples Cookbook - Multi-session project patterns
• Flags Guide - Session control flags and optimization

🔧 Expert

• Technical Architecture - Session implementation details
• Contributing Code - Extending session capabilities

Session-Specific Learning:

🎯 Session Command Mastery:

• Load Patterns: /sc:load variations for different contexts
• Save Strategies: Checkpoint vs milestone vs completion saves
• Reflection Types: Progress, quality, completion, learning assessments

🧠 Memory Management:

• Context Building: How memory accumulates and evolves
• Pattern Recognition: Understanding session intelligence
• Memory Optimization: Efficient context management

👥 Team Coordination:

• Shared Sessions: Multi-developer session coordination
• Handoff Patterns: Session transfer and continuity
• Integration Sessions: Cross-team collaboration

🔄 Project Lifecycle:

• Daily Workflows: Effective day-to-day session patterns
• Feature Cycles: Multi-session feature development
• Long-term Projects: Enterprise-scale session management

💡 Session Mastery Tips:

• Start Small: Begin with simple load-work-save patterns
• Build Habits: Regular reflection and checkpoint saves
• Learn Memory: Understand how context builds over time
• Optimize Gradually: Advanced patterns as projects grow
• Monitor Health: Regular session health and performance checks

Common Session Workflows:

• New Project: Load → Analyze → Plan → Save
• Daily Work: Load → Progress check → Work → Checkpoint → Save
• Feature Development: Load → Brainstorm → Implement → Test → Reflect → Save
• Bug Investigation: Load focused → Troubleshoot → Fix → Validate → Save
• Code Review: Load changes → Analyze quality → Review → Document → Save