Sessions

✓ Fresh · 2026-02-24

Pi stores all session history as JSONL files with a tree structure. Every entry has an id and parentId, enabling full branching, forking, and time-travel through your conversation history.

Session Storage

Sessions are saved as .jsonl files, where each line is a JSON object representing one message or event:

{"id": "abc123", "parentId": "xyz789", "role": "user", "content": "..."}
{"id": "def456", "parentId": "abc123", "role": "assistant", "content": "..."}

The parentId field creates a tree structure — multiple entries can share the same parent, representing branches.

Session Lifecycle

Branching with /tree

The /tree command opens an interactive navigator for your session history:

Navigation

• Type to search/filter entries
• Left/Right arrows to page through history
• Enter to select a point and continue from there
• Press l to label/bookmark an entry

Filter Modes (Ctrl+O)

Cycle through filter modes to narrow what you see:

Mode	Shows
default	User messages and key assistant responses
no-tools	Everything except tool calls/results
user-only	Only user messages
labeled-only	Only bookmarked/labeled entries
all	Every entry including tool calls

Branching

When you select a previous point in /tree and continue typing, Pi creates a branch. Both the original path and the new branch remain in the same JSONL file. You can switch between branches at any time.

Forking with /fork

While /tree branching keeps everything in one file, /fork creates an entirely new session file from the current branch point:

Session A (original)
  ├── Messages 1-50
  └── Branch at message 30
        └── Messages 31-45

/fork at message 30 creates:
Session B (new file)
  └── Copy of messages 1-30
      └── Continue fresh from here

Use /fork when a branch has diverged significantly and deserves its own session.

Compaction

Long sessions exhaust the context window. Compaction summarizes older messages while preserving recent ones.

Automatic Compaction

Enabled by default. Triggers when:

• Context window overflows
• Token count approaches the model's limit

Pi automatically summarizes older conversation turns, keeping the most recent messages intact.

Manual Compaction

/compact                           # default compaction
/compact Keep all code changes     # custom instructions for what to preserve

What Happens During Compaction

1. Older messages are summarized into a compact representation
2. Recent messages remain untouched
3. The full original history stays in the JSONL file
4. Use /tree to revisit anything that was compacted

Session Commands Summary

Command	Action
/session	Show current session path, token count, cost
/name <name>	Set a display name
/tree	Navigate and branch history
/fork	Create new session file from current branch
/compact [prompt]	Manually compact context
/resume	Browse and select past sessions
/new	Start fresh session

CLI Session Flags

Flag	Action
pi	New session
pi -c	Continue most recent
pi -r	Browse past sessions
pi --session <path|id>	Resume specific session
pi --no-session	Ephemeral (not saved)