# session-manager

> Manages session lifecycle including context restoration, checkpoint creation, and learning capture

- Author: z
- Repository: tktk4751/superspec
- Version: 20260127050940
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/tktk4751/superspec
- Web: https://mule.run/skillshub/@@tktk4751/superspec~session-manager:20260127050940

---

---
name: session-manager
description: Manages session lifecycle including context restoration, checkpoint creation, and learning capture
version: 2.0.0
schema: ../schemas/session-protocol.yaml
implementation: src/superspec/core/session.py
memory-validator: ../skills/memory-validator/SKILL.md
requirements:
  - REQ-MCP-006
test_requirements:
  - TR-MCP-005
  - TR-MCP-006
  - TR-MCP-007
  - TR-MCP-008
  - TR-MCP-009
---

# Session Manager Skill

## Purpose

Provide unified session lifecycle management for all SuperSpec commands (REQ-MCP-006). This skill handles context restoration, checkpoint creation, and learning capture using the memory namespace system.

## Key Features

- **Automatic Context Restoration**: Restore previous session state on command start
- **30-Minute Checkpoints**: Automatic progress preservation every 30 minutes
- **Learning Capture**: Persist patterns, solutions, and insights across sessions
- **Serena Integration**: Cross-machine memory persistence via Serena MCP
- **Local Fallback**: File-based storage when Serena is unavailable

## When to Use

- At command start (onCommandStart event)
- During execution at checkpoint triggers (onCheckpoint event)
- When learnings are identified (onLearning event)
- At command end (onCommandEnd event)

## Python Implementation

```python
from superspec.core.session import (
    SessionManager,
    SessionState,
    Checkpoint,
    Learning,
    LearningType,
)
from datetime import datetime

# Initialize session manager
manager = SessionManager()

# Start session (with auto-restore)
state = manager.start_session(command="impl", restore=True)

# Check if checkpoint is needed (30-minute interval)
if manager.should_create_checkpoint():
    checkpoint = Checkpoint(
        id=f"cp-{datetime.now().strftime('%Y%m%d-%H%M%S')}",
        timestamp=datetime.now(),
        phase="Phase 1: Foundation",
        progress={"tasks_completed": 5, "tasks_total": 10},
        context={"current_task": "T006"},
    )
    manager.create_checkpoint(checkpoint)

# Capture a learning
learning = Learning(
    type=LearningType.SOLUTION,
    key="learning/solutions/jwt-expiry-fix",
    content="Fixed by increasing token expiry to 7 days",
    timestamp=datetime.now(),
)
manager.capture_learning(learning)

# End session
manager.end_session()
```

## Hook Scripts

### Session Start Hook

```bash
python superspec/hooks/scripts/session_start.py --command impl --change-id CHANGE_ID
```

### Session End Hook

```bash
python superspec/hooks/scripts/session_end.py --command impl --success --phase "Phase 1"
```

### Checkpoint Save Hook

```bash
python superspec/hooks/scripts/checkpoint_save.py --phase "Phase 1" --progress '{"completed": 5}'
```

## Input/Output Format

### Start Session

```yaml
Input:
  command: "impl"
  restore: true
  change_id: "2026-01-25-superspec-mega-upgrade"

Output:
  session_id: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  is_fresh_session: false
  restored_state:
    phase: "Phase 1"
    progress: {"tasks_completed": 5}
```

### Create Checkpoint

```yaml
Input:
  phase: "Phase 1: Foundation"
  progress:
    tasks_completed: 5
    tasks_total: 10
  context:
    current_task: "T006"

Output:
  checkpoint_id: "cp-20260125-120000"
  timestamp: "2026-01-25T12:00:00Z"
```

### Capture Learning

```yaml
Input:
  type: "solution"
  key: "learning/solutions/jwt-expiry-fix"
  content: "Fixed by increasing token expiry to 7 days"

Output:
  success: true
  learning_key: "learning/solutions/jwt-expiry-fix"
```

## Memory Keys Used

| Key Pattern | Namespace | Purpose |
|-------------|-----------|---------|
| `session/context` | session | Complete PM Agent state |
| `session/checkpoint` | session | Current checkpoint data |
| `session/last` | session | Previous session summary |
| `learning/patterns/{name}` | learning | Reusable success patterns |
| `learning/solutions/{name}` | learning | Error resolution records |
| `learning/anti-patterns/{name}` | learning | Approaches to avoid |
| `learning/insights/{name}` | learning | General observations |

## 30-Minute Checkpoint Interval

The session manager automatically tracks when checkpoints should be created:

```python
# Check if 30+ minutes since last checkpoint
if manager.should_create_checkpoint():
    # Time for a checkpoint!
    manager.create_checkpoint(...)
```

This ensures progress is preserved even during long sessions.

## Learning Types

| Type | Description | Memory Prefix |
|------|-------------|---------------|
| `pattern` | Reusable successful approach | `learning/patterns/` |
| `solution` | Error resolution | `learning/solutions/` |
| `anti-pattern` | Approach to avoid | `learning/anti-patterns/` |
| `insight` | General observation | `learning/insights/` |

## Error Handling

| Error | Recovery |
|-------|----------|
| Checkpoint read failure | Start fresh session, log warning |
| Checkpoint write failure | Retry once, then log error and continue |
| Learning capture failure | Queue for retry, continue execution |
| Invalid memory key | Log error with suggestion, continue |
| Serena unavailable | Fall back to local file storage |

## Session Report

After restore, a report is displayed to the user:

```
Session restored:
Phase: Phase 1: Foundation
Progress: 5/10 (50%)
Learnings captured: 3
```

## Related

- Schema: `superspec/schemas/session-protocol.yaml`
- Implementation: `src/superspec/core/session.py`
- Memory Validator: `superspec/skills/memory-validator/SKILL.md`
- Hook Scripts:
  - `superspec/hooks/scripts/session_start.py`
  - `superspec/hooks/scripts/session_end.py`
  - `superspec/hooks/scripts/checkpoint_save.py`
- Requirements: REQ-MCP-006
- Test Requirements: TR-MCP-005, TR-MCP-006, TR-MCP-007, TR-MCP-008, TR-MCP-009