SuperClaude/Docs/User-Guide/session-management.md

# SuperClaude Session Management Guide

## ✅ Verification Status
- **SuperClaude Version**: v4.0+ Compatible
- **Last Tested**: 2025-01-16
- **Test Environment**: Linux/Windows/macOS
- **Session Commands**: ✅ All Verified

## 🧪 Testing Session Management

Before using this guide, verify session commands work:

```bash
# Test session loading
/sc:load .
# Expected: Analyzes project structure and creates session context

# Test session saving
/sc:save "test-session"
# Expected: Saves session with confirmation message

# Test session reflection
/sc:reflect
# Expected: Shows current session status and progress
```

**If tests fail**: Check Serena MCP installation: `SuperClaude status --mcp serena`

## 🚨 Quick Troubleshooting

### Common Issues (< 2 minutes)
- **Session won't load**: Check Serena MCP server connection: `SuperClaude status --mcp serena`
- **Save fails**: Verify write permissions to `~/.claude/` directory
- **Memory issues**: Clear old sessions with `/sc:reflect --type session-cleanup`
- **Slow loading**: Use `--scope file` for large projects or `--fast` flag

### Immediate Fixes
- **Reset session**: Restart Claude Code to refresh session system
- **Clear cache**: Remove `~/.claude/sessions/` directory if corrupted
- **Check dependencies**: Verify Python/uv installation for Serena MCP
- **Test basic functions**: Try `/sc:load .` and `/sc:save "test"` with simple project

## Table of Contents

- [Prerequisites](#prerequisites)
- [Understanding Sessions](#understanding-sessions)
- [Your First Session](#your-first-session)
- [Session Commands](#session-commands)
- [Memory and Context](#memory-and-context)
- [Session Workflows](#session-workflows)
- [Multi-Session Projects](#multi-session-projects)
- [Performance and Security](#performance-and-security)
- [Glossary](#glossary)
- [Learning Progression](#learning-progression)

## Prerequisites

**Required Knowledge:**
- Basic command line familiarity
- Understanding of project file structures
- Familiarity with development workflows

**Required Setup:**
- SuperClaude Framework installed ([Installation Guide](../Getting-Started/installation.md))
- Serena MCP server configured (provides session memory)
- Active project or codebase to work with

**Verification:**
Test your setup before starting:
```bash
# Verify SuperClaude is working
SuperClaude --version

# Check Serena MCP connection
SuperClaude status --mcp serena
```

**Time Investment:**
- First session walkthrough: 10 minutes
- Basic session mastery: 1-2 hours
- Advanced workflows: 1-2 weeks of practice

## Understanding Sessions

### What is a Session?

A **session** is a persistent development conversation that remembers your project, decisions, and progress across interruptions. Unlike standard Claude conversations that start fresh each time, SuperClaude sessions build cumulative understanding.

**Key Concepts:**

**Session**: A persistent development context containing project understanding, work history, and current state

**Context**: The accumulated knowledge about your project, including structure, patterns, and decisions

**Memory**: Long-term storage of insights, patterns, and project knowledge that survives restarts

### Session vs Standard Claude

| Standard Claude | SuperClaude Sessions |
|-----------------|---------------------|
| Starts fresh each conversation | Remembers previous work |
| No project memory | Builds cumulative understanding |
| Requires re-explanation | Knows your codebase and patterns |
| Single conversation scope | Cross-session continuity |

### Session Benefits

**Continuity**: Pick up exactly where you left off, even after days or weeks

**Learning**: Sessions become smarter about your project over time

**Efficiency**: No need to re-explain project structure or decisions

**Collaboration**: Share context with team members through saved sessions

## Your First Session

**10-Minute Walkthrough**

Let's create your first session with a simple project:

### Step 1: Load Your Project (2 minutes)
```bash
# Navigate to your project directory first
cd /path/to/your/project

# Load the project into a session
/sc:load .
```

**What you'll see:**
```
🔍 Analyzing project structure...
📂 Detected: [Project type] with [X] files
🧠 Creating new session context
✅ Session ready: [session-name]
```

**Success criteria**: You see project analysis and "Session ready" message

### Step 2: Ask About Your Project (3 minutes)
```bash
# Test session understanding
"What files are in this project?"
"What's the main architecture?"
"What patterns do you see?"
```

**Success criteria**: SuperClaude demonstrates understanding of your specific project

### Step 3: Make a Small Change (3 minutes)
```bash
# Request a simple modification
"Add a comment to the main function explaining its purpose"
```

**Success criteria**: SuperClaude makes contextual changes that fit your project style

### Step 4: Save Your Session (2 minutes)
```bash
# Save the session for later
/sc:save "my-first-session"
```

**What you'll see:**
```
💾 Saving session context...
📊 Context preserved: [details]
✅ Session saved: "my-first-session"
```

**Success criteria**: Session saves successfully with confirmation

### Verification Checklist

- [ ] Project loaded successfully (should take <30 seconds for small projects)
- [ ] SuperClaude demonstrated project understanding (knows file structure and patterns)
- [ ] Made contextual changes to code (changes fit existing style)
- [ ] Session saved with clear confirmation (shows session name and details)
- [ ] Ready to resume work later (can continue from saved state)

#### Success Criteria for First Session
- [ ] Load time under 30 seconds for projects <100 files
- [ ] Project analysis identifies framework and key patterns
- [ ] Code changes follow existing project conventions  
- [ ] Session persistence works across Claude Code restarts

**Verify:** `/sc:load .` should complete without errors and show project summary  
**Test:** Session should remember changes when resumed later  
**Check:** `/sc:reflect` should show accurate progress tracking

**Need Help?**: If any step fails, check your setup by running `SuperClaude status --mcp serena` to verify the Serena MCP server is working correctly.


## Session Commands

### Core Commands Overview

| Command | Purpose | Usage Level |
|---------|---------|-------------|
| `/sc:load` | Start or resume a session | Beginner |
| `/sc:save` | Preserve session progress | Beginner |
| `/sc:reflect` | Analyze session status | Intermediate |

### /sc:load - Session Initialization

**Purpose**: Load project context and initialize persistent development session

**Basic Usage (Start Here):**
```bash
# Load current directory
/sc:load .

# Load specific project
/sc:load /path/to/project/

# Resume previous session
/sc:load "my-session-name"
```

**What Happens During Load:**

**Behind the Scenes** (powered by Serena MCP):
1. **File Discovery**: Scans project structure and identifies key components
2. **Memory Retrieval**: Loads any existing session data for this project
3. **Pattern Analysis**: Identifies coding patterns, frameworks, and conventions
4. **Context Building**: Creates working memory of project understanding
5. **Session Ready**: Establishes persistent development context

**Real Example Output:**
```bash
/sc:load my-react-app/

🔍 Scanning project structure...
   ├── src/components/ (12 React components)
   ├── src/hooks/ (4 custom hooks)
   ├── package.json (React 18.2, TypeScript)
   └── tests/ (Jest + Testing Library)

🧠 Building session context...
   • Framework: React with TypeScript
   • State management: Context API + useReducer
   • Testing: Jest + React Testing Library
   • Build tool: Vite

💾 Previous session found: "user-auth-feature" (2 days ago)
   • Last work: Login form validation
   • Progress: 75% complete
   • Next: Implement password reset

✅ Session ready! I understand your React TypeScript project.
   Type your next request to continue working.
```

**Load Variations:**

**Beginner Level:**
```bash
# Simple project load
/sc:load .

# Resume by name
/sc:load "my-work-session"
```

**Intermediate Level:**
```bash
# Load with focus area
/sc:load --focus testing project/

# Fresh analysis (ignores previous session)
/sc:load --refresh project/
```

**Advanced Level:**
```bash
# Load specific branch context
/sc:load --branch feature/auth project/

# Load with team context
/sc:load --shared team-project/
```

**Serena MCP Integration Details:**

**Current Implementation** (Available Now):
- Project file structure analysis
- Previous session restoration  
- Basic pattern recognition
- Session naming and organization

**Example Serena Commands:**
```bash
# These work with current Serena MCP:
list_memories()           # See available sessions
write_memory(key, value) # Save session data
read_memory(key)         # Retrieve session data
delete_memory(key)       # Clean up old data
```

**Planned Features** (Future Releases):
- Cross-session pattern learning
- Team collaboration features  
- Advanced semantic analysis

**Note**: Examples showing team features (`--shared`) are illustrative of the intended direction. Current implementation focuses on individual developer sessions.

### /sc:save - Session Persistence

**Purpose**: Preserve session context and development progress for future continuation

**Basic Usage (Start Here):**
```bash
# Save with automatic name
/sc:save

# Save with descriptive name
/sc:save "feature-login-complete"

# Quick checkpoint save
/sc:save --checkpoint
```

**What Gets Saved:**
- **Project Understanding**: What SuperClaude learned about your codebase
- **Work Progress**: What you accomplished and what's next
- **Code Changes**: Files modified and patterns discovered
- **Decisions Made**: Choices made and reasons behind them

**Save Strategies by Experience Level:**

**Beginner - Save Often:**
```bash
# After any significant work
/sc:save "added-user-component"

# Before trying something risky
/sc:save "backup-before-refactor"

# End of work session
/sc:save "end-of-day"
```

**Intermediate - Strategic Saves:**
```bash
# Milestone completion
/sc:save "authentication-module-complete"

# Before major changes
/sc:save --checkpoint "pre-database-migration"

# Feature branch completion
/sc:save "feature-branch-ready-for-review"
```

**Advanced - Organized Saves:**
```bash
# Team handoff
/sc:save "ready-for-alice-review" --handoff

# Release preparation
/sc:save "v2.1-release-candidate"

# Architecture milestone
/sc:save "microservices-split-complete"
```

**Real Save Output:**
```bash
/sc:save "login-form-complete"

💾 Saving session: "login-form-complete"

📂 Project context preserved:
   • Files analyzed: 47
   • Components modified: LoginForm.tsx, AuthService.ts
   • Tests added: 3 new test cases
   • Dependencies: Added @types/jwt-decode

🧠 Knowledge preserved:
   • Authentication pattern: JWT with refresh tokens
   • Form validation: Yup schema with custom validators
   • Error handling: Centralized error boundary pattern
   • Next steps: Implement password reset flow

✅ Session saved successfully!
   Resume with: /sc:load "login-form-complete"
```

**When to Save:**

**Always Save:**
- Before ending a work session
- After completing a feature or major component
- Before attempting risky changes (refactoring, major updates)

**Consider Saving:**
- Every 30-60 minutes during active development
- After solving a difficult problem
- When switching between different parts of the project

### /sc:reflect - Session Analysis

**Purpose**: Review progress, identify issues, and plan next steps

**Basic Usage:**
```bash
# Quick progress check
/sc:reflect

# Specific analysis
/sc:reflect --type progress
/sc:reflect --type quality
```

**When to Reflect:**
- Feeling stuck or uncertain about next steps
- Before major decisions or changes
- End of work session to plan tomorrow
- After completing significant work

**Reflection Types by Experience Level:**

**Beginner - Simple Checks:**
```bash
# Basic progress review
/sc:reflect

# Check if ready to continue
/sc:reflect --type ready
```

**Intermediate - Focused Analysis:**
```bash
# Progress with recommendations
/sc:reflect --type progress

# Code quality assessment
/sc:reflect --type quality

# Completion status
/sc:reflect --type completion
```

**Advanced - Strategic Reviews:**
```bash
# Architecture review
/sc:reflect --type architecture

# Team handoff preparation
/sc:reflect --type handoff

# Learning consolidation
/sc:reflect --type learning
```

**Real Reflection Output:**
```bash
/sc:reflect --type progress

🎯 Session Progress Analysis

📊 Current Status:
   ✅ User registration form - Complete
   ✅ Form validation logic - Complete  
   🔄 Email verification - In progress (60%)
   ⏳ Password reset - Not started
   ⏳ OAuth integration - Not started

🚧 Current Focus:
   Working on email verification service
   Next: Connect to email sending API

⚠️ Potential Issues:
   • Email service rate limits not handled
   • Need error handling for email failures
   • Token expiration logic needs testing

🎯 Recommended Next Steps:
   1. Add rate limiting for email verification
   2. Implement email error handling
   3. Test token expiration scenarios
   4. Move to password reset feature

💡 Estimated Time: 2-3 hours to complete email verification
```

**Decision Trees:**

**"Should I continue or take a break?"**
```bash
/sc:reflect --type energy
```
- Assesses current progress momentum
- Identifies good stopping points
- Suggests break vs continue recommendations

**"What should I work on next?"**
```bash
/sc:reflect --type priorities
```
- Analyzes available tasks
- Considers dependencies and blockers
- Recommends optimal next work

**"Is my code ready for review?"**
```bash
/sc:reflect --type readiness
```
- Checks completion criteria
- Reviews code quality indicators
- Assesses testing and documentation


### Session-Specific Troubleshooting

**Session Load Failures:**
```bash
# Problem: "/sc:load project/ fails with error"
# Quick Fix: Verify project and dependencies
ls -la project/                           # Check project exists
SuperClaude status --mcp serena          # Verify Serena MCP
/sc:load . --refresh                     # Force fresh analysis
/sc:load . --scope module                # Reduce load scope
```

**Session Save Failures:**
```bash
# Problem: "/sc:save fails with permission error"
# Quick Fix: Check permissions and storage
ls -la ~/.claude/                        # Check directory permissions
chmod -R 755 ~/.claude/                  # Fix permissions
df -h ~/.claude/                         # Check disk space
/sc:save --compress "test-session"       # Try compressed save
```

**Memory/Performance Issues:**
```bash
# Problem: Sessions using too much memory or loading slowly
# Quick Fix: Optimize session management
/sc:reflect --type memory                # Check memory usage
/sc:save --cleanup                       # Clean old data
/sc:load project/ --fast                 # Fast loading mode
/sc:load project/ --scope file           # Limit scope
```

**Session Context Issues:**
```bash
# Problem: Session loses context or gives incorrect information
# Quick Fix: Context refresh and validation
/sc:load project/ --refresh              # Rebuild context
/sc:reflect --type accuracy              # Check context quality
/sc:save --consolidate "clean-session"   # Consolidate memory
```

### Error Code Reference

| Session Error | Meaning | Quick Fix |
|---------------|---------|-----------|
| **S001** | Load timeout | Reduce scope with `--scope module` or use `--fast` |
| **S002** | Save permission denied | Check `chmod -R 755 ~/.claude/` |
| **S003** | Serena MCP unavailable | Verify `uv run serena --help` works |
| **S004** | Memory limit exceeded | Use `/sc:save --cleanup` and `--compress` |
| **S005** | Project structure invalid | Verify you're in a valid project directory |
| **S006** | Session corrupted | Use `--refresh` to rebuild from scratch |
| **S007** | Context mismatch | Use `/sc:load --consolidate` to fix context |
| **S008** | Disk space insufficient | Clean up with `/sc:reflect --type session-cleanup` |

### Progressive Support Levels

**Level 1: Quick Fix (< 2 min)**
- Use the Common Issues section above
- Try restarting Claude Code session
- Use `--no-mcp` to test without Serena

**Level 2: Detailed Help (5-15 min)**
```bash
# Session-specific diagnostics
/sc:reflect --type sessions-list         # List all sessions
/sc:reflect --type memory                # Check memory usage
cat ~/.claude/logs/serena.log | tail -50 # Check Serena logs
```
- See [Common Issues Guide](../Reference/common-issues.md) for session installation problems

**Level 3: Expert Support (30+ min)**
```bash
# Deep session analysis
SuperClaude diagnose --sessions
ls -la ~/.claude/serena/                 # Check Serena state
uv run serena diagnose                   # Serena diagnostics
# Reset session system completely
```
- See [Diagnostic Reference Guide](../Reference/diagnostic-reference.md) for session performance analysis

**Level 4: Community Support**
- Report session issues at [GitHub Issues](https://github.com/SuperClaude-Org/SuperClaude_Framework/issues)
- Include session diagnostics from Level 2
- Describe session workflow that's failing

### Success Validation

After applying session fixes, test with:
- [ ] `/sc:load .` (should complete without errors for current directory)
- [ ] `/sc:save "test-session"` (should save successfully)
- [ ] `/sc:reflect` (should show session status accurately)
- [ ] Session persistence works across Claude Code restarts
- [ ] Memory usage is reasonable for your project size

## Performance and Security

### Session Loading Performance

**Expected Load Times:**

| Project Size | Expected Time | Optimization Tips |
|--------------|---------------|-------------------|
| Small (< 100 files) | 2-5 seconds | Use default settings |
| Medium (100-1000 files) | 5-15 seconds | Use `--focus` for specific areas |
| Large (1000+ files) | 15-30 seconds | Load specific modules only |
| Enterprise (5000+ files) | 30-60 seconds | Use `--scope module` |

**Performance Benchmarks:**
```bash
# Measure your session load time
time /sc:load project/

# Expected output:
real    0m12.347s  # Total time
user    0m8.234s   # CPU time
sys     0m1.123s   # System time
```

**Optimization Strategies:**

**For Large Projects:**
```bash
# Load specific area instead of entire project
/sc:load --scope module src/auth/

# Focus on current work area
/sc:load --focus performance api-layer/

# Load without heavy analysis
/sc:load --fast large-project/
```

**Memory Optimization:**
```bash
# Check current memory usage
/sc:reflect --type memory

# Clean up old sessions
/sc:save --cleanup

# Optimize session storage
/sc:save --compress "optimized-session"
```

**Memory Usage Guidelines:**

| Session Type | Memory Range | Notes |
|--------------|--------------|-------|
| Simple project | 50-200 MB | Basic file analysis |
| Medium project | 200-500 MB | Pattern recognition active |
| Complex project | 500-1000 MB | Full semantic analysis |
| Enterprise | 1-2 GB | Comprehensive context |

### Security and Privacy

**Data Storage:**

**What Gets Stored:**
- Project file structure and patterns
- Code snippets for pattern analysis (not full files)
- Development decisions and progress notes
- Session metadata and timestamps

**What's NOT Stored:**
- Sensitive credentials or API keys
- Personal data or private information
- Complete source code files
- External service connections

**Local Storage Only:**
All session data is stored locally on your machine using Serena MCP. No data is sent to external servers or cloud services.

**Session Security:**

**Best Practices:**
```bash
# Use descriptive but non-sensitive session names
/sc:save "user-auth-module"        # Good
/sc:save "prod-api-key-abc123"     # Avoid

# Regular cleanup of old sessions
/sc:reflect --type session-cleanup

# Check what's stored in sessions
/sc:reflect --type data-summary
```

**Privacy Controls:**
```bash
# Create private sessions (not shared)
/sc:load --private project/

# Delete sensitive session data
/sc:save --exclude-sensitive "clean-session"

# List all stored sessions
/sc:reflect --type sessions-list
```

**Enterprise Security:**

**Access Control:**
- Sessions are user-specific (no cross-user access)
- File permissions respect system security
- No network communication for session data

**Compliance:**
- GDPR: User controls all data, can delete any time
- SOC 2: Local storage meets data handling requirements
- HIPAA: No PHI stored in session context

**Audit Trail:**
```bash
# View session access history
/sc:reflect --type access-log

# Export session metadata
/sc:save --export-metadata audit-trail.json
```

## Memory and Context

### How Session Memory Works

**Think of session memory like a persistent notebook** that remembers:
- Your project's structure and patterns
- Decisions you've made and why
- Progress on current and past work
- Solutions to problems you've encountered

### Memory Building (Automatic)

As you work with SuperClaude, it automatically learns:

**Project Structure:**
```bash
# When you load a project
/sc:load my-app/

# SuperClaude learns:
- File organization (components/, utils/, tests/)
- Framework patterns (React hooks, Express routes)
- Dependencies and their usage
- Code style and conventions
```

**Decision History:**
```bash
# When you make choices
"Use TypeScript for type safety"
"Implement JWT authentication"
"Use PostgreSQL for data persistence"

# SuperClaude remembers:
- Why you made these choices
- How they affect other decisions
- Related patterns and dependencies
```

**Problem Solutions:**
```bash
# When you solve issues
"Fixed the CORS issue by configuring headers"
"Optimized database queries with indexing"

# SuperClaude learns:
- Common problem patterns in your project
- Effective solution strategies
- Prevention techniques for similar issues
```

### Memory Types

**Current Session Memory:**
- What you're working on right now
- Files you've modified
- Immediate next steps

**Project Memory:**
- Overall architecture and patterns
- Long-term decisions and conventions
- Component relationships

**Historical Memory:**
- Previous sessions and their outcomes
- Evolution of the project over time
- Lessons learned from past work

### Memory in Action

**Starting New Work:**
```bash
/sc:load project/
→ "I remember you were working on user authentication.
   The login form is complete, but email verification 
   is still pending. Should we continue with that?"
```

**Consistent Patterns:**
```bash
"Add a new API endpoint for user preferences"
→ SuperClaude applies:
   • Your established routing patterns
   • Consistent error handling
   • Existing authentication middleware
   • Database connection patterns
```

**Problem Solving:**
```bash
"The API is responding slowly"
→ SuperClaude recalls:
   • Previous performance optimizations you've done
   • Database indexing patterns you prefer
   • Caching strategies you've implemented
```

### Memory Optimization

**Viewing Memory:**
```bash
# See what SuperClaude remembers about your project
/sc:reflect --type memory

# Check specific areas
/sc:reflect --type patterns     # Code patterns
/sc:reflect --type decisions    # Major decisions
/sc:reflect --type progress     # Current state
```

**Cleaning Up Memory:**
```bash
# Remove outdated information
/sc:save --cleanup "refreshed-session"

# Consolidate scattered memories
/sc:save --consolidate "organized-session"
```

**Memory Limits:**
- Session memory is optimized for relevance
- Older, less relevant information naturally fades
- Important patterns and decisions are preserved
- You can manually clean up when needed

## Session Workflows

### Beginner Workflows

**Your First Week Pattern:**
```bash
# Day 1: Get familiar with sessions
/sc:load .
"Show me the project structure"
/sc:save "learned-project-basics"

# Day 2-3: Small changes
/sc:load "learned-project-basics"
"Add a comment to this function"
"Fix this small bug"
/sc:save --checkpoint

# Day 4-5: Bigger tasks
/sc:load project/
"Add a new component for user settings"
/sc:reflect --type progress
/sc:save "user-settings-complete"
```

**Daily Work Pattern:**
```bash
# Morning: Start your day
/sc:load project/                    # Resume where you left off
/sc:reflect                          # Quick status check
"Let's continue with [current work]" # Begin your work

# During work: Stay organized
/sc:save --checkpoint                # Save every hour or so
/sc:reflect --type progress          # Check if stuck

# Evening: Wrap up
/sc:reflect --type completion        # Review what you accomplished  
/sc:save "end-of-day"               # Save your progress
```

### Intermediate Workflows

**Feature Development (Multi-day):**
```bash
# Day 1: Planning
/sc:load project/
"I need to add user authentication"
/sc:reflect --type planning
/sc:save "auth-planning-complete"

# Day 2-3: Implementation
/sc:load "auth-planning-complete"
"Let's implement the login form"
/sc:save --checkpoint "login-form-done"
"Now add the backend API"
/sc:save --checkpoint "api-complete"

# Day 4: Testing and polish
/sc:load project/
"Test the authentication flow"
/sc:reflect --type quality
/sc:save "auth-feature-complete"
```

**Bug Fixing Session:**
```bash
# Load with focus on the problem
/sc:load project/
"The login form isn't working properly"

# Investigate systematically
/sc:reflect --type debugging
"What could be causing this issue?"

# Fix and verify
"Let's fix the validation logic"
"Test that the fix works"
/sc:save "login-bug-fixed"
```

### Advanced Workflows

**Complex Feature Development:**
```bash
# Phase 1: Architecture planning
/sc:load --focus architecture project/
"Design a notification system"
/sc:reflect --type architecture
/sc:save "notification-architecture"

# Phase 2: Core implementation
/sc:load "notification-architecture"
"Implement the notification service"
/sc:save --checkpoint "service-core-done"

# Phase 3: Integration
"Integrate with the user interface"
/sc:save --checkpoint "ui-integration-done"

# Phase 4: Testing and optimization
/sc:reflect --type quality
"Optimize for performance"
/sc:save "notification-system-complete"
```

**Code Review and Refactoring:**
```bash
# Load for quality analysis
/sc:load --focus quality codebase/
"Review the authentication module for improvements"

# Systematic improvements
/sc:reflect --type quality
"Refactor the user service for better maintainability"

# Validation
"Test that everything still works after refactoring"
/sc:save "auth-module-refactored"
```

### Session Length Guidelines

**Short Sessions (30-60 minutes):**
- Perfect for: Bug fixes, small features, code reviews
- Pattern: Load → Work → Save
- Save strategy: Single checkpoint at end

**Medium Sessions (2-4 hours):**
- Perfect for: Feature development, research, planning
- Pattern: Load → Plan → Work → Checkpoint → Work → Save
- Save strategy: Checkpoint every hour

**Long Sessions (Half/Full day):**
- Perfect for: Major features, architecture work, complex debugging
- Pattern: Load → Plan → Work → Checkpoint → Reflect → Work → Save
- Save strategy: Multiple checkpoints, frequent reflection

### Common Session Anti-Patterns

**Avoid These Mistakes:**

**Not Saving Frequently:**
```bash
# Wrong: Work for hours without saving
/sc:load project/
# ... 4 hours of work ...
# System crash - all progress lost!

# Right: Regular checkpoints
/sc:load project/
# ... 1 hour of work ...
/sc:save --checkpoint "progress-checkpoint"
# ... continue working ...
```

**Unclear Session Names:**
```bash
# Wrong: Vague names
/sc:save "work"
/sc:save "stuff"
/sc:save "session1"

# Right: Descriptive names  
/sc:save "user-login-form-complete"
/sc:save "api-error-handling-improved"
/sc:save "database-schema-updated"
```

**Not Using Reflection:**
```bash
# Wrong: Get stuck and keep struggling
"This isn't working..."
# ... continues struggling for hours ...

# Right: Use reflection to get unstuck
"This isn't working..."
/sc:reflect --type debugging
/sc:reflect --type progress
# Get insights and new approaches
```

## Multi-Session Projects

**Long-Term Project Management:**

### Project Session Architecture
```bash
# 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:**
```bash
# 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:**
```bash
# 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:**
```bash
# 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


## Glossary

**Session**: A persistent development conversation that remembers your project context, decisions, and progress across interruptions.

**Context**: The accumulated knowledge SuperClaude has about your project, including file structure, patterns, and previous work.

**Memory**: Long-term storage of project insights, decisions, and patterns that survives SuperClaude restarts.

**Checkpoint**: A temporary save point during active work that preserves progress without ending the session.

**Session State**: The current status of your session, including active tasks, progress, and next steps.

**Load**: The process of initializing or resuming a session with project context.

**Save**: Preserving session context and progress for future continuation.

**Reflection**: Analysis of session progress, quality, and status to guide next steps.

**Serena MCP**: The Model Context Protocol server that provides session memory and persistence capabilities.

**Session Handoff**: The process of transferring session context between team members or work periods.

**Memory Consolidation**: Organizing and optimizing session memory for better performance and consistency.

**Fresh Load**: Starting a new session analysis from scratch, ignoring previous session data.

**Focused Load**: Loading session context with specific emphasis on a particular area or concern.

**Pattern Recognition**: SuperClaude's ability to identify and apply consistent coding patterns and conventions from your project.

**Cross-Session Learning**: The accumulation of insights and understanding across multiple work sessions over time.

## Learning Progression

### Week 1: Session Basics

**Goal**: Get comfortable with basic session commands

**Day 1-2: First Session**
- Complete the [10-minute walkthrough](#your-first-session)
- Practice: `/sc:load .`, `/sc:save "my-work"`, `/sc:reflect`
- Success criteria: Can load, work, and save a session

**Day 3-4: Daily Workflow**
- Establish daily load → work → save pattern
- Practice descriptive session naming
- Use reflection when stuck: `/sc:reflect --type progress`

**Day 5-7: Building Habits**
- Regular checkpoint saves during work
- End-of-day session saves
- Morning session resumption routine

**Week 1 Checklist:**
- [ ] Successfully loaded and saved multiple sessions
- [ ] Used reflection to understand project better
- [ ] Established daily session routine
- [ ] Comfortable with basic commands

### Week 2-3: Intermediate Usage

**Goal**: Leverage session memory and strategic workflows

**Week 2: Memory Understanding**
- Observe how SuperClaude remembers your decisions
- Practice: Let sessions build knowledge over several days
- Learn: `/sc:reflect --type memory` to see what's remembered

**Week 3: Strategic Workflows**
- Multi-day feature development workflows
- Bug investigation sessions with focused loading
- Code review sessions with quality focus

**Intermediate Checklist:**
- [ ] Seen sessions get smarter about your project over time
- [ ] Successfully completed multi-day feature development
- [ ] Used sessions for systematic debugging
- [ ] Comfortable with workflow patterns

### Month 2+: Advanced Mastery

**Goal**: Optimize sessions for complex projects and team workflows

**Advanced Techniques:**
- Large project optimization with focused loading
- Session performance tuning
- Memory consolidation and cleanup
- Complex multi-session project coordination

**Team Coordination:**
- Session handoff patterns (when implemented)
- Shared context management
- Integration session workflows

**Advanced Checklist:**
- [ ] Optimized sessions for large projects (>1000 files)
- [ ] Mastered session troubleshooting and recovery
- [ ] Developed personal session workflow patterns
- [ ] Can teach session concepts to others

### Skill Progression Indicators

**Beginner → Intermediate:**
- Sessions become more useful over time
- Less re-explanation needed
- Comfortable with daily session routine
- Uses reflection to get unstuck

**Intermediate → Advanced:**
- Sessions significantly accelerate development
- Can handle complex multi-session projects
- Troubleshoots session issues independently
- Develops optimized workflow patterns

**Advanced Mastery:**
- Sessions feel essential to development workflow
- Expertly manages large project sessions
- Mentors others on session usage
- Contributes to session feature development

### Learning Resources

**Essential Reading:**
- [Quick Start Guide](../Getting-Started/quick-start.md) - First session setup
- [Commands Reference](commands.md) - Complete command documentation
- [Installation Guide](../Getting-Started/installation.md) - Serena MCP setup

**Intermediate Resources:**
- [MCP Servers Guide](mcp-servers.md) - Serena MCP deep dive
- [Behavioral Modes](modes.md) - Task Management integration
- [Flags Guide](flags.md) - Session optimization flags

**Advanced Resources:**
- [Best Practices](../Reference/best-practices.md) - Session optimization strategies
- [Examples Cookbook](../Reference/examples-cookbook.md) - Complex workflow patterns
- [Technical Architecture](../Developer-Guide/technical-architecture.md) - Implementation details

### Practice Exercises

**Week 1 Exercises:**
1. Load a project, explore it, save with descriptive name
2. Resume yesterday's session, continue work, save progress
3. Use reflection when confused about next steps

**Week 2-3 Exercises:**
1. Develop a feature over 3 days using sessions
2. Debug a complex issue using focused session loading
3. Review and refactor code using session quality analysis

**Advanced Exercises:**
1. Optimize session loading for a large project (>1000 files)
2. Coordinate multiple feature sessions within one project
3. Recover from session corruption using troubleshooting techniques
4. Develop and document your personal session workflow patterns