> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qredence.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Sessions

> How Fleet Prime Agent keeps state between turns: persistent IPython kernels, transcripts on disk, branching, and compaction.

A session is one continuous conversation with the agent. Everything the agent does — chat turns, tool calls, subagent runs — is recorded to a single transcript, and the Python kernel that backs the session survives from turn to turn.

## Anatomy

Each session has:

* **A transcript on disk** at `~/.prime/agent/sessions/`. Entries are `message`, `custom_message`, `compaction`, `branch_summary`, or `git_state`.
* **A persistent IPython kernel** provisioned on first use. Variables, imports, open files, and background tasks live for the lifetime of the session.
* **A header** (`SessionHeader`) with metadata: provider, model, thinking level, extensions loaded.
* **A version** (`CURRENT_SESSION_VERSION = 3`) so the runtime can migrate older transcripts.

## Resume and fork

Any session can be resumed from where it stopped:

```bash theme={null}
prime-agent --resume <session-id>
```

Any session can be forked from a specific point:

```bash theme={null}
prime-agent --fork <session-id>
```

Forking creates a new session that shares history up to the branch point and diverges after. Fork points are tracked with `parentSession` and `rlmDepth` so the runtime knows how deep the tree is.

## Branching

The agent creates branches on its own when it needs to try a different approach. Each branch has its own summary (`createBranchSummaryMessage`) so long transcripts stay readable and the model can jump between them without re-reading everything.

## Compaction

Long sessions get compacted automatically when they approach the model's context window. `prepareBranchEntries` and `compact` produce a shorter transcript that keeps the important entries and drops noise. Every compaction is recorded as its own transcript entry so you can see what was dropped.

Key limits:

* `SESSION_STREAMING_LOAD_THRESHOLD_BYTES` — 128 MB. Above this the transcript is streamed instead of loaded.
* `SESSION_ASYNC_PARSE_YIELD_BYTES` — 4 MB. The parser yields every 4 MB to keep the event loop responsive.
* `SESSION_LIST_SEARCH_TEXT_MAX_CHARS` — 64 KB per entry when searching session lists.
* `SESSION_LIST_PARSE_MAX_LINE_CHARS` — 1 MB max line length in a transcript.

See [Sessions and branching](/fleet-prime-agent/guides/sessions-and-branching) for the day-to-day commands.