Skip to main content
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:
Any session can be forked from a specific point:
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 for the day-to-day commands.
Last modified on August 17, 2026