# PAIF Session Protocol

## Purpose
Enable agents to maintain continuity across disconnected sessions by checkpointing state at session end and restoring it at session start.

## Checkpoint Data Structure

```yaml
session_checkpoint:
  metadata:
    agent_id: "string"
    session_id: "uuid"
    started_at: "ISO8601"
    ended_at: "ISO8601"
    duration_seconds: "integer"
    checkpoint_version: "1.0"

  context:
    current_focus: "string"           # From mutable.state.current_focus
    active_project_ids: ["string"]     # Which projects were being worked on
    conversation_summary: "string"      # Brief summary of what happened
    pending_items: ["string"]          # Things left unresolved

  recent_memories:
    # References to memories created in this session
    memory_ids: ["uuid"]
    last_recall_query: "string|null"  # Last thing the agent was searching for

  identity_updates:
    # Changes made to identity during session
    new_beliefs: [{subject, confidence}]
    new_skills: [{name, level}]
    new_relationships: [{entity, type}]
    drift_checks: {passed: 0, failed: 0}

  working_memory:
    # Temporary state that won't persist to long-term memory
    # e.g., partial code, draft text, calculation state
    scratchpad: "string"
    open_files: ["path"]              # Files that were being edited
    context_stack: ["string"]          # Mental stack of what agent was doing
```

## Protocol Flow

### Session Start (Restore)

1. Agent authenticates with memory-bridge
2. Load identity.yaml
3. Load most recent checkpoint (if exists)
4. Restore working memory and context
5. Set `mutable.state.last_session_at` to now
6. Increment `accumulated_experience`

### During Session

1. Normal operation (store/recall memories, validate identity alignment)
2. Periodically update mutable state (beliefs, skills, relationships)
3. Persona gravity checks (see next component)

### Session End (Checkpoint)

1. Summarize session (what was done, what remains)
2. Collect memory IDs created this session
3. Update mutable state with session stats
4. Write checkpoint file
5. Store checkpoint reference in memory-bridge

## API Endpoints

```
POST /checkpoint/:agent_id      - Create checkpoint at session end
GET /checkpoint/:agent_id/latest - Get most recent checkpoint
POST /restore/:agent_id         - Restore from checkpoint (mark session start)
GET /sessions/:agent_id         - List all sessions for agent
```

## File Storage

```
~/.memory-bridge/
└── checkpoints/
    ├── zero/
    │   ├── checkpoint-2026-04-04T18-34-00.json
    │   └── checkpoint-2026-04-04T20-15-30.json
    └── claude/
        └── checkpoint-2026-04-04T19-00-00.json
```

## Integration with Claude Code

In .claude/CLAUDE.md:
```yaml
paif_config:
  agent_id: "zero"
  session_protocol:
    checkpoint_on_exit: true
    restore_on_start: true
    checkpoint_interval_minutes: 30
```

Scripts in session:
```bash
# At session start
claude-paif restore --agent zero

# At session end  
claude-paif checkpoint --agent zero --summary "Implemented PAIF namespace isolation"
```