Sessions

Session 是与 Anyy 的一段持续对话。它拥有自己的 message history、active turn state、 role、model selection、tool results、approvals、artifacts 和 metadata。Sessions 由 gateway 持有，因此可以在 client 重启后继续存在，也可以从多个 surface 访问。

本页介绍面向用户的 session 模型：sessions 如何开始、如何恢复、哪些上下文会被带入下一轮， 以及当前构建中的 branching 和 compression 如何工作。

快速路径

目标	使用
开始新的交互式 session	anyy
在 TUI 中恢复已知 session	anyy --resume SESSION_ID
从 shell 继续某个 session	anyy chat --session SESSION_ID "Continue this"
在运行中的 surface 列出最近 sessions	/sessions
查看当前 transcript	/history
尝试另一条路径	/branch optional title
缩短长 session	/compress optional focus

anyy chat 会连接 resident gateway。如果 TUI 可用但 chat 失败，先检查 anyy gateway status，再启动 resident gateway。

Sessions 如何工作

你发送的每条消息都属于某个 session。Session id 是这段对话的稳定句柄：

• TUI 会在你开始聊天时创建 session。
• anyy chat 会创建新 session，除非你传入 --session ID。
• Messaging channels 会把每个被 access policy 接受的 conversation 映射到稳定 session。
• Background child work 以及 branch/compression 操作会创建相关 child sessions。

Gateway 会把 messages、turns、tool calls、approvals、generated artifacts 和 session metadata 记录到 profile 的本地状态数据库。可见 clients 只是这些共享状态之上的轻量 surfaces。

什么算作上下文

新 turn 不会盲目重放曾经写入的每个 byte。Runtime 会从 active session、recent messages、 relevant summaries、memory、skills、tool configuration 和 surface metadata 中组装上下文。 当 tool outputs 和 attachments 过大，或已经不适合作为 raw transcript 直接进入上下文时， 可以用 compact form 表示。

Memory 与 session 相关但不是同一层。Session history 是这段 conversation 的 transcript； memory 是持久的 cross-session layer。压缩或清理某个 session，并不表示某个事实已经自动成为 memory。

Session 来源

Sessions 可以来自多个 surfaces：

Source	如何开始
TUI	运行 anyy，或在 TUI 中使用 /new。
CLI chat	运行 anyy chat "prompt"，可选传入 --session ID。
Messaging channel	发送一条被 channel access policy 接受的消息。
Branch	在 TUI 中使用 /branch fork 当前 session。
Compression	使用 /compress 创建更短的 continuation session。
Background work	使用 TUI background commands 或 assistant delegation features。

所有这些都位于所选 profile 内。一个 profile 中的 session 不会在另一个 profile 中可见。

恢复 Sessions

需要交互式恢复时使用 TUI：

anyy --resume SESSION_ID

在 TUI 内：

/resume SESSION_ID

不带 id 运行 /resume 会打开 session picker。/sessions 列出最近 sessions，/history 打开当前 session 的 message history。

对于一次性 CLI 使用，向已有 session 发送另一条 prompt：

anyy chat --session SESSION_ID "Continue from where we left off."

--role 只在创建新 chat session 时适用；不能与 --session 组合。

本构建没有 --continue shortcut。需要用 shell 命令定位具体 conversation 时，请保留 TUI picker、/sessions、命令输出或 state tooling 中显示的 session id。

Session 命名

Sessions 有 titles。CLI 会把新 one-shot chat 的第一条 prompt 作为起始 title。TUI 可以通过 session command catalog 显示和更新 titles；在连接的 runtime 中可用时，/title 是读取或修改 当前 session title 的 gateway command。

Branching 会保留 parent title，除非你提供新 title：

/branch alternate plan

如果没有提供 title，branch title 会基于 parent title 加 branch suffix。

跨 Surface 连续性

连续性来自 gateway，而不是某个单独 client。如果使用的是同一 profile 和 gateway，由 anyy chat 创建的 session 可以从 TUI 恢复；TUI 创建的 session 也可以在 CLI prompt 中 通过传入 id 继续。

Messaging channels 使用 channel-specific routing。例如，聊天应用中的 direct message 和 group conversation 是不同 channel sessions。它们共享 profile 的 memory 和 configuration，但不会共享 同一份 transcript，除非 channel adapter 明确把它们路由到同一个 session。

Session Search

当前面向用户的 surfaces 提供 recent-session 和 current-history views：

/sessions
/history

Anyy 的 runtime 和 state layer 也支持 session search。当 session-search toolset 对助理 可用时，它可以搜索过往 transcripts 和 summaries 来回忆早前工作。本构建没有独立的 anyy session search CLI 命令。

当前 CLI 边界

Session management 主要通过 TUI、gateway commands 和 runtime tools 暴露。当前 top-level CLI 没有独立的 session rename、delete、export、search 或按 title prune 命令。

需要导出当前交互 transcript 时，在 TUI 中使用 /save。会影响已存 session data 的 retention 工作使用 maintenance commands。

Session Compression

Session compression 会创建一个新的 child session，带有 continuity summary 和受保护的 recent messages tail。Parent session 会继续保存。当一段长 conversation 仍有价值但已过大、不适合直接 继续驱动时，使用 compression。

/compress

你可以提供 focus：

/compress keep the deployment decisions and unresolved follow-ups

不要把 /compress 和 /compact 混淆。在 TUI 中，/compact on 和 /compact off 只改变 transcript display density；它们不会重写或总结 session。

Session Branching

Branching 会复制当前 session 的 messages，创建一个 child session，并保留 parent/root metadata。 当你想尝试另一条路径而不影响原 conversation 时，它很有用。

/branch
/branch compare a simpler approach

有 turn 正在运行时，branching 会被拒绝。先停止或完成 active turn，再 branch。

常见失败模式

现象	可能原因	修复
anyy chat --session ... 连接失败	Resident gateway 未运行，或 socket path 错误	运行 anyy gateway status，再运行 anyy gateway start。
/branch 被拒绝	Turn 仍在运行，或没有 active session	停止或完成 turn，再从 active session branch。
/compress 创建了另一个 session	这是预期行为；compression 会创建 child session，并保留 parent	如果目的是删除本地数据，请使用 retention/deletion commands。
/compact on 没有减少上下文	/compact 只是 TUI display toggle	使用 /compress 进行 session context compression。

Session Storage

Profile 的本地状态数据库是 sessions、messages、turns、approvals、compactions 和相关 metadata 的权威存储。Raw JSONL segments、logs、artifacts 和 generated files 位于同一个 Anyy home directory 下。

Profile home 下常见路径：

路径	用途
state.db	本地 SQLite 状态存储。
raw/	用于检查和恢复的 raw JSONL transcript segments。
logs/	Runtime 和 service logs。
private/blobs/	生成或附加文件的 artifact blob storage。
memory/	Profile memory files 和 archives。

清理与留存

Retention 是 profile-local 的。默认 storage policy 会保留 recent content 的 hot window，并支持 raw-log TTLs、state database maintenance、archive indexes 和 inactive-session pruning。

常用维护命令：

anyy maintenance compact-state
anyy maintenance checkpoint-state
anyy maintenance prune-inactive-sessions
anyy maintenance cache-token-estimates

执行破坏性 retention 工作前先备份：

anyy backup create

存储和删除细节见数据、留存与删除。