Time Travel, Replay & Forking

Time Travel, Replay & Forking

Kazma records full conversation state snapshots at every iteration, allowing users and developers to inspect past execution states, rewind threads, or branch conversations without destroying history.

---

1. Snapshot Recording (snapshots.db)

State snapshots are captured by SnapshotRecorder (kazma_core/time_travel.py) during supervisor execution.

Snapshot Properties

• Persistence: Saved in SQLite WAL database at kazma-data/snapshots.db.
• Retention: LRU-capped per thread (default 50 snapshots per thread, configurable via time_travel.max_snapshots).
• Data Captured: Full SupervisorState (messages, iteration, model, tool results, active workspace).

---

2. Interactive Time-Travel Commands

Kazma provides two primary operations for navigating past conversation states:

Command	Action	Behavior
/replay <iteration>	In-Place Rewind	Restores state at <iteration> on the same thread ID. Modifies live thread state via graph.aupdate_state().
/fork <iteration>	Branch Thread	Restores state at <iteration> under a new thread ID (gw-{platform}-{sender}-{uuid}). Original thread remains unchanged.

---

3. Web UI & SSE Stream Integration

• Replay API Router: Mounted at /api/replay/* (kazma_ui/replay_routes.py).
• SSE Snapshot Events: Terminal graph turns emit a snapshot SSE frame carrying snapshot_id and snapshot_iteration, enabling the UI sidebar to display instant point-in-time rewind buttons.