$ pi –recall

TL;DR. 会话是 ~/.pi/agent/sessions/ 下的 append-only JSONL 文件，按工作目录归类，并组织成树 —— 每条 entry 都有 id 与 parentId。斜杠命令（/resume、/tree、/fork、/clone、/compact、/export、/share）与 CLI 参数（-c、-r、--session、--fork、--no-session）是浏览它们的两种入口。压缩与分支摘要遵循 provider 重试策略；落盘后的会话足够朴素，可直接 grep 与 jq。

每一个交互式 Pi 会话都会在后台自动落盘。你不必记得手动保存，离开几天再回来也能看到完整的会话原文。本文覆盖会话的存储位置、TUI 内的导航方式、分叉机制，以及压缩如何让长会话恢复起来依然便宜。内容对照官方 Sessions 文档与仓库中的 packages/coding-agent/docs/sessions.md。

会话存在哪里

会话写入 ~/.pi/agent/sessions/，按工作目录归类。每个会话是一个 JSONL 文件，路径里编码了所属项目。文件是 append-only：你打字、agent 回答、工具运行，文件就一条一条往下追加。

可以用环境变量 PI_SESSIONS_DIR 覆盖位置，也可以在一次性任务里用 pi --no-session 完全跳过持久化。

会话文件的内部结构

会话不是扁平的对话列表，而是一棵树：每条 entry 都有一个 id 和一个 parentId，你当前看到的位置就是这棵树的活跃叶子节点。entry 可以是：

用户 prompt 与助手回复。
模型切换与思考级别切换。
通过 Shift+L 给某条 entry 设置的标签。
压缩与分支摘要。
扩展发出的 entry。

树状结构正是分支廉价的原因。当你让 Pi 换个思路尝试时，原来的轨迹并不会被删 —— 你只是从选中的那条 entry 长出一个新分支，原分支原样保留。

日常会用的斜杠命令

交互式 TUI 通过一小撮斜杠命令暴露会话模型：

/resume —— 浏览并选择过往会话。
/new —— 开启一个全新的会话。
/name <name> —— 给当前会话设一个易读的显示名。
/session —— 显示当前会话的元数据。
/tree —— 浏览当前会话的树状结构。
/fork —— 从某条过往用户消息创建新会话文件。
/clone —— 把当前活跃分支复制到一个新会话文件。
/compact [prompt] —— 压缩较早的内容（见下文）。
/export [file] —— 把会话导出为自包含 HTML 文件。
/share —— 上传到 GitHub 私有 gist。

详细列表见 Slash commands 与 Sessions。

命令行下的会话操作

如果你想从 shell 或脚本而非交互式 TUI 驱动 Pi，同样的能力通过参数暴露：

# 续接当前项目最近的会话
pi -c

# 浏览并选择过往会话
pi -r

# 启动一个不落盘的临时会话
pi --no-session

# 启动时给会话命名
pi --name "refactor auth middleware"

# 通过文件路径或部分 ID 恢复指定会话
pi --session 2026-08-07-1530-refactor

# 把指定会话分叉成新会话
pi --fork 2026-08-07-1530-refactor

会话 ID 前缀匹配故意做得宽松：你只需要打出足够区分的时间戳前缀即可。

分叉与分支的区别

三个看起来相近的词，实际含义不同：

/tree 留在同一个会话文件里。你在原地探索替代路径，磁盘上不会复制，TUI 仍能浏览完整树。
/fork 创建一个新会话文件。你选一条过往用户消息作为分叉点，新会话从那里以全新线性历史开始。
/clone 从当前活跃分支创建一个新会话文件，适合把打磨好的轨迹交接给别人，又不必附带你试过的所有死胡同。

当 /tree 离开某条分支时，Pi 可以为被弃用的分支生成摘要并附加到新位置。你可以选择不摘要、用默认 prompt 摘要，或用自定义聚焦 prompt 摘要。这正是让长时间探索会话保持廉价的关键。

压缩长会话

当会话长度超出模型上下文窗口 —— 或者仅仅超过你愿意每次都为整个前缀付费的临界点 —— /compact [prompt] 会把较早的 entry 压缩成单条浓缩内容，让模型在之后看到的就是这份摘要。可选的 prompt 参数让你引导摘要的侧重点（“聚焦失败的测试”、“保留 API 契约”）。

从 v0.81.1 起，压缩与分支摘要遵循已配置的 provider 重试策略，并把重试生命周期事件投递给交互式、JSON、RPC 与 SDK 消费者。临时的 provider 故障不再会让摘要丢失。

跨会话检索

会话就是磁盘上的纯 JSONL，所以常见 Unix 工具直接能用。几个值得记的模式：

# 找出曾操作某条路径的会话
grep -l "src/auth/middleware.ts" ~/.pi/agent/sessions/**/*.jsonl

# 抽出会话里所有的用户消息
jq 'select(.type == "user") | .content' ~/.pi/agent/sessions/2026-08-07-1530-refactor.jsonl

在 TUI 内，/tree 的过滤模式（Ctrl+O 切换）可以隐藏工具 entry、只显示用户消息、只显示打了标签的 entry，或显示全部 —— 在需要找回指向某个改动的 prompt 时很有用。

分享与导出

/export 把会话写成自包含 HTML 文件，颜色、工具调用格式、diff 高亮都和 TUI 一致。这是把会话贴到 issue 或 PR 描述里最快的方式。

/share 把会话作为私有 GitHub gist 上传，并把链接复制到剪贴板。上传前会对凭证进行清理，但广泛分享前仍应人工复核一遍渲染后的 gist。

对更系统的发布需求，本网站资源地图上的 pi-share-hf 覆盖了清理、审阅、上传到 Hugging Face 数据集这条链路。

会话与历史记录