Home › Entities › Session Persistence

Session Persistence

The append-only JSONL transcript system that enables --resume in claude-code. Every session writes to an audit log; sessions can be restored from these transcripts.

Architecture

Session transcripts are stored as append-only JSONL files. Each line is a complete JSON object representing a message, tool call, tool result, or system event.

Asymmetric Persistence

queryengine-ts uses an asymmetric write strategy:

Message Type Write Mode Rationale
User messages await (blocking I/O) Essential for --resume — must know what user asked
Assistant messages Fire-and-forget (no await) Can be reconstructed from context if lost

The asymmetry matters for latency: assistant response saving never blocks the loop, keeping interactive turn-around fast.

Context Collapse Snapshots

The compaction-pipeline's Context Collapse tier (Tier 4) creates read-time projections over REPL history. These snapshots enable selective recovery of previously loaded files after compaction, without re-reading them from disk.

preservedSegment boundaries allow the system to restore file references and skill state after compression.

Tombstone Garbage Collection

Tombstones — markers for invalidated entries (from streaming-tool-executor orphaned calls) — accumulate over long sessions. A garbage collection mechanism runs at the 50MB threshold, cleaning up tombstoned entries that are no longer needed for conversation coherence.

The --resume Workflow

When --resume is invoked: 1. The JSONL transcript is read and user messages are reconstructed 2. The conversation state is rebuilt from the transcript 3. Context is re-injected, but the cache prefix differs from the live session

This reconstruction creates the cache-economics "resume tax" — a triple cache-prefix discrepancy causing 10-20x cost on resumed sessions.

Sources