11 · Persistence and Resume

utils/sessionStorage.ts, 176 KB. This chapter covers how conversations get written to disk, how they're resumed, and how file changes get rolled back.

11.1 The Transcript Format: JSONL

JSONL stands for JSON Lines: a text file where every line is a complete JSON object.

The reasons for choosing JSONL over one big JSON array are practical:

There's a read-size cap as protection:

export const MAX_TRANSCRIPT_READ_BYTES = 50 * 1024 * 1024   // 50 MB

11.2 The Transcript Is a Tree, Not a List

Note that every record above has two fields, uuid and parentUuid. That tells you the transcript is structurally a tree.

Why a tree?

The comment quoted in section 2.5 can now be read in full:

11.3 The Write Queue

Writes don't go straight to the file every time. In between sits a write queue, whose two properties came up in section 2.5:

• 100 ms deferred serialization — a message entering the queue isn't turned into a JSON string immediately; it waits a moment and gets processed in a batch
• Order preservation — even when callers submit fire-and-forget, the write order matches the submission order

The purpose of that 100 ms delay was covered in section 2.5: it gives “the usage fields on the model's message getting filled in” a time window. Because the API layer emits the message first and receives the usage data afterward.

There's also a flushSessionStorage() function for forcing a drain:

// QueryEngine.ts, right before yielding the final result
// Flush buffered transcript writes before yielding result.
// The desktop app kills the CLI process immediately after receiving the
// result message, so any unflushed writes would be lost.
if (persistSession) {
  if (isEnvTruthy(process.env.CLAUDE_CODE_EAGER_FLUSH) ||
      isEnvTruthy(process.env.CLAUDE_CODE_IS_COWORK)) {
    await flushSessionStorage()
  }
}

Put plainly: drain the buffered transcript writes before yielding the result message. The desktop app kills the CLI process the moment it receives the result message, so any un-drained writes would be lost.

11.4 Subagent Records: Sidechain Files

export function setAgentTranscriptSubdir(...)
export function clearAgentTranscriptSubdir(agentId: string): void
export function getAgentTranscriptPath(agentId: AgentId): string

export type AgentMetadata = { ... }
export async function writeAgentMetadata(...)
export async function readAgentMetadata(...)

A subagent's transcript is written to its own file, with a metadata record alongside (task description, status, start time, and so on). The main transcript keeps only “a subagent was spawned” and “here's what it returned.”

The benefit of this design: the main record doesn't balloon with a subagent's hundreds of messages, yet when you need to investigate, you can follow the agentId to the complete sub-record.

Remote agents have a separate set of their own:

export type RemoteAgentMetadata = { ... }
export async function writeRemoteAgentMetadata(taskId, ...)
export async function readRemoteAgentMetadata(taskId)
export async function deleteRemoteAgentMetadata(taskId)
export async function listRemoteAgentMetadata()

11.5 Resume: Three Ways

Resume takes a few optional modifiers:

• --fork-session — generate a new session ID. The original session stays untouched; it's “save as”
• --resume-session-at <message-id> — resume only up to the specified message, discarding everything after. It's “go back to a save point”

Rebuilding the chain on resume

The applyPreservedSegmentRelinks function mentioned in section 2.6 handles sessions that have been compacted:

11.6 File History: Rolling Back Files the Agent Changed

utils/fileHistory.ts. This is lightweight version control independent of git.

export type FileHistoryBackup   = { ... }    // one backup
export type FileHistorySnapshot = { ... }    // a snapshot at a point in time
export type FileHistoryState    = { ... }    // overall state
export type DiffStats = ...                  // diff statistics

export function fileHistoryEnabled(): boolean
export async function fileHistoryTrackEdit(...)       // record one edit
export async function fileHistoryMakeSnapshot(...)    // take a snapshot
export async function fileHistoryRewind(...)          // ★ rewind
export function fileHistoryCanRestore(...)            // can it be restored
export async function fileHistoryGetDiffStats(...)    // diff statistics
export async function fileHistoryHasAnyChanges(...)
export async function checkOriginFileChanged(...)     // ★ detect external modification
export function fileHistoryRestoreStateFromLog(...)   // rebuild state from the log
export async function copyFileHistoryForResume(...)   // copy history on resume

When snapshots are taken

// QueryEngine.ts
if (fileHistoryEnabled() && persistSession) {
  messagesFromUserInput
    .filter(messageSelector().selectableUserMessagesFilter)
    .forEach(message => {
      void fileHistoryMakeSnapshot(
        (updater) => { setAppState(prev => ({ ...prev, fileHistory: updater(prev.fileHistory) })) },
        message.uuid,      // ★ snapshots are anchored to the "user message's uuid"
      )
    })
}

Every user message gets a snapshot. So the user can say “go back to the state before I asked this question” — the matching command-line flag:

--rewind-files <user-message-id>
  Restore files to state at the specified user message and exit (requires --resume)
  (i.e. roll the files back to how they stood at that user message, then quit)

Detecting external modifications

checkOriginFileChanged handles this scenario: the agent read a.ts, you changed it in your editor, and now the agent wants to change the same file.

Without detection, the agent would edit based on the old content and overwrite your changes. So it detects and flags — typically by rejecting the edit and requiring the model to re-read first.

11.7 Multi-Source Settings and Migrations

Settings source priority

--setting-sources <sources>
  Comma-separated list of setting sources to load (user, project, local).

The existence of the “local” layer matters: it keeps personal, temporary settings (say, “authorize one more directory on this machine of mine”) from polluting the team-shared project settings.

Settings migrations

The migrations/ directory has 13 files. Their job: after the program is upgraded, automatically convert old-format settings files to the new format.

Any product maintained over the long term needs this — otherwise every change to the settings structure would break existing users' configs. And migrations have to be idempotent and safe to run repeatedly, because you don't know which version the user is upgrading from.

11.8 The Memory Directory

memdir/, 10 files. It manages long-term memory across sessions.

The recall mechanism was covered in section 3.9: prefetch + model judges relevance + dedup against the read-file state.

Note a trait of this design: memories are human-readable plain-text files that can be managed with git. No vector database, no embedding model.

There's also the special CLAUDE.md file, which is loaded nested by directory level: when working in ~/project/src/utils/, it loads ~/project/CLAUDE.md, ~/project/src/CLAUDE.md, and ~/project/src/utils/CLAUDE.md in turn. The closer to the current directory, the more specific the rules and the higher their priority.