piagent_
中文
← ~/guides

Sessions and History

Last updated: Aug 7, 2026

$ pi –recall

TL;DR. Sessions are append-only JSONL files under ~/.pi/agent/sessions/, organized by working directory and structured as a tree where every entry has an id and a parentId. Slash commands (/resume, /tree, /fork, /clone, /compact, /export, /share) and CLI flags (-c, -r, --session, --fork, --no-session) are the two ways to navigate them. Compaction and branch summaries honor the retry policy; on-disk sessions are plain enough to grep and jq.

Every interactive Pi session auto-saves to disk in the background. You never need to remember to save, and you can leave a session, walk away, and come back days later to find the exact transcript you left. This guide covers how sessions are stored, how you navigate them inside the TUI, how forking works, and how compaction keeps long sessions cheap to resume. It follows the official Sessions documentation and the underlying packages/coding-agent/docs/sessions.md.

Where sessions live

Sessions are written to ~/.pi/agent/sessions/, organized by working directory. Each session is a single JSONL file whose path encodes the project it belongs to. Files are append-only: as you type, the agent answers, tools run, and the file grows one entry at a time.

You can override the location with the PI_SESSIONS_DIR environment variable, and you can opt out of persistence entirely with pi --no-session for one-off runs where you do not want anything written to disk.

Inside a session file

A session is not a flat list of messages. It is a tree: every entry has an id and a parentId, and the position you are looking at is the active leaf of that tree. Entries can be:

  • User prompts and assistant replies.
  • Model changes and thinking-level changes.
  • Labels you set with Shift+L.
  • Compactions and branch summaries.
  • Extension-emitted entries.

The tree shape is what makes branching cheap. When you ask Pi to try a different approach, you are not deleting the old one — you are growing a new branch from whichever entry you selected, and the original branch is preserved.

Slash commands you will use daily

The interactive TUI exposes the session model through a small set of slash commands:

  • /resume — browse and select from past sessions.
  • /new — start a fresh session.
  • /name <name> — set a human-readable display name for the current session.
  • /session — show metadata about the current session.
  • /tree — navigate the current session’s tree.
  • /fork — create a new session file from a previous user message.
  • /clone — duplicate the current active branch into a new session file.
  • /compact [prompt] — summarize older context (see below).
  • /export [file] — export the session to a self-contained HTML file.
  • /share — upload the session as a private GitHub gist.

These are documented in Slash commands and Sessions.

CLI flags for headless and script use

If you want to drive Pi from a shell or script rather than the interactive TUI, the same operations are exposed as flags:

# Continue the most recent session in the current project
pi -c

# Browse and select from past sessions
pi -r

# Start an ephemeral session that is not saved
pi --no-session

# Name the session at startup
pi --name "refactor auth middleware"

# Resume a specific session by file path or partial ID
pi --session 2026-08-07-1530-refactor

# Fork a specific session into a new one
pi --fork 2026-08-07-1530-refactor

The session ID prefix match is intentionally loose: you only need to type enough of the timestamp-prefixed filename to disambiguate it from siblings.

Forking versus branching

Three different verbs sound similar but mean different things:

  • /tree stays inside the same session file. You are exploring alternative paths in place; nothing is duplicated on disk, and the full tree remains visible in the TUI.
  • /fork creates a new session file. You pick a previous user message as the fork point, and the new session starts from there with a fresh linear history.
  • /clone creates a new session file from the current active branch, useful for handing off a polished trajectory to someone else without giving them the dead ends you tried along the way.

When /tree moves away from a branch, Pi can summarize the abandoned branch and attach the summary at the new position. You get to choose between no summary, the default prompt, or a custom focus prompt. This is what makes long-running exploration sessions cheap to keep.

Compacting long sessions

Once a session grows past the model’s context window — or simply past the point where you want to pay for the full prefix on every turn — /compact [prompt] summarizes the older entries into a single condensed entry that the model sees going forward. Optional prompt guidance lets you steer the summary (“focus on the test failures”, “preserve the API contract”).

As of v0.81.1, compaction and branch-summary operations honor the configured provider retry policy and emit retry lifecycle events to interactive, JSON, RPC, and SDK consumers, so transient provider failures no longer drop your summary.

Searching across sessions

Sessions are plain JSONL on disk, so the usual Unix tools work. A few patterns worth knowing:

# Find sessions that touched a particular file path
grep -l "src/auth/middleware.ts" ~/.pi/agent/sessions/**/*.jsonl

# Extract all user messages from a session
jq 'select(.type == "user") | .content' ~/.pi/agent/sessions/2026-08-07-1530-refactor.jsonl

For inside-the-TUI search, /tree’s filter modes (Ctrl+O to cycle) let you hide tool entries, show only user messages, only labeled entries, or everything — useful when you need to find the prompt that led to a specific change.

Sharing and exporting

/export writes the session to a self-contained HTML file with the same colors, tool-call formatting, and diff highlighting as the live TUI. It is the fastest way to attach a session to a bug report or PR description.

/share uploads the session as a private GitHub gist and copies the URL to the clipboard. The session content is sanitized for credentials before upload, but you should still review the rendered gist before sharing it widely.

For larger-scale publishing, the pi-share-hf tool on this site’s resource map covers redacting, reviewing, and uploading sessions as a Hugging Face dataset.

Further reading