paif/SESSION_PROTOCOL.md

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

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:

paif_config:
  agent_id: "zero"
  session_protocol:
    checkpoint_on_exit: true
    restore_on_start: true
    checkpoint_interval_minutes: 30

Scripts in session:

# At session start
claude-paif restore --agent zero

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