Session Fork & Rewind

The SessionForkManager enables session state management: create checkpoints, fork sessions into independent branches, and rewind to previous points in time. All state is backed by Cortex.

Operations

Checkpoint

Save the current session state at a point in time. Captures the event count and last event ID.

bash
mayros session checkpoint

Checkpoints serve as named save points you can reference later for forks or rewinding.

Fork

Create a new independent session branching from the current one. All events up to the fork point are copied to the new session.

bash
mayros session fork --name experiment-1

The original session continues unchanged. The forked session is a fully independent copy.

Rewind

Restore a session to a previous point in time. Events after the specified timestamp are soft-deleted (marked as "rewound" via Cortex triples, not permanently removed).

bash
mayros session rewind --to 2025-01-15T10:30:00Z

Use cases

  • Experimentation: fork a session to try an alternative approach without losing the original
  • Recovery: rewind to before a bad decision or error
  • A/B testing: fork and compare two different approaches
  • Debugging: rewind past a problematic change to isolate the issue

Session states

mermaid
stateDiagram-v2
    [*] --> Active : new session
    Active --> Active : checkpoint
    Active --> Forked : fork (original becomes "forked")
    Active --> Rewound : rewind
    Forked --> Active : new fork created

Cortex storage

{ns}:session:{key} → {ns}:session:status → "active"
{ns}:session:{key} → {ns}:session:checkpoint → { JSON checkpoint }
{ns}:session:{forkedKey} → {ns}:session:parentSession → "original-key"
{ns}:session:{forkedKey} → {ns}:session:forkedAt → "2025-01-15T10:30:00Z"

Agent tools

  • trace_session_fork — fork the current session from within a conversation
  • trace_session_rewind — rewind the session to a previous point