# 会话记忆

会话记忆为长期智能体任务提供可持续、可审核的生命周期。会话从工作区和知识库上下文开始，持续积累已确认的候选知识与进度检查点，最后生成紧凑快照。下一位用户或智能体可以带着决策、当前进度和下一步动作继续工作。

TokST 只保存通过会话工具显式提交的内容。凭据、私钥、缺乏明确用途的隐私数据、原始推理过程和短期工具输出保留在当前运行环境中。

## 适用场景

多步骤工作、需要交接的任务、需要留存审核过程的事项适合建立会话。例如功能开发、事故排查、发布准备、合同审阅和多智能体协作。

单条长期事实适合直接创建记忆。会话记忆同时保存该事实形成过程中的进度、交接点和审核记录。

## 生命周期

| 阶段 | 记录内容 | 作用 |
|---|---|---|
| 开始 | 任务、工作区/知识库范围与返回的上下文 | 建立工作边界，减少重复组织上下文 |
| 捕获 | 候选事实、决策、偏好、任务、架构或普通说明 | 将已确认的长期信息与原始工作材料分开 |
| 检查点 | 简洁进度摘要与下一步动作 | 支持交接和中断后的恢复 |
| 完成 | 最终摘要与不可变会话快照 | 为任务生成紧凑的完成记录 |
| 审核 | 编译、驳回或撤销候选内容 | 让工作区管理者治理正式记忆 |
| 归档 | 保留审计与搜索记录，隐藏默认列表 | 保持活跃工作区聚焦且保留历史 |

`finalize` 默认把待处理候选内容编译为正式记忆。使用 `--no-compile` 可将候选保留给管理者审核。撤销已编译候选会归档其关联的正式记忆，并保留完整审计链路。

## CLI 工作流

智能体运行使用 `TOKST_AGENT=1`，输出保持结构化，服务端会从 API 密钥注入可信智能体身份。

```bash
# 1. 从本任务需要的知识库上下文开始。
TOKST_AGENT=1 tokst session start \
  --atlas-id <atlas-id> \
  --task "实现工作区邀请到期机制" \
  --idempotency-key invite-expiry-v1 \
  --json

# 2. 仅捕获已确认、可复用的结论。
TOKST_AGENT=1 tokst session capture \
  --session <ses-id> \
  "待处理邀请会在所选有效期结束后过期。" \
  --kind decision \
  --title "邀请到期规则" \
  --tags workspace,invitations \
  --confidence 0.95 \
  --source-event-id issue-482-decision \
  --json

# 3. 交接或长时间暂停前保存检查点。
TOKST_AGENT=1 tokst session checkpoint \
  --session <ses-id> \
  "迁移与 API 已完成；下一步验证用户后台。" \
  --json

# 4. 完成任务，默认编译候选为正式记忆。
TOKST_AGENT=1 tokst session finalize \
  --session <ses-id> \
  "已完成到期流程并记录用户后台验证事项。" \
  --json
```

常用后续命令：

```bash
# 查看会话、候选、检查点、快照和范围内上下文。
tokst session status <ses-id> --json

# 列出当前工作区中自己的会话。
tokst session list --workspace <workspace-id> --status active --json

# Owner/Admin：查看整个工作区，包括已归档会话。
tokst session list --workspace <workspace-id> --scope managed --archived --json

# 先查看工作区待审核候选队列，再打开具体会话。
tokst session candidates --workspace <workspace-id> --scope managed --status pending --json

# Owner/Admin：审核候选内容。
tokst session candidate --session <ses-id> --candidate <candidate-id> --action compile --json
tokst session candidate --session <ses-id> --candidate <candidate-id> --action dismiss --reason "已被替代" --json
tokst session candidate --session <ses-id> --candidate <candidate-id> --action revert --reason "决策错误" --json

# 归档保留历史；恢复会重新显示该会话。
tokst session archive <ses-id> --reason "工作完成" --json
tokst session restore <ses-id> --json
```

本地运行时使用相同的 `tokst local session ...` 生命周期，并将会话、候选、检查点、快照和编译后的记忆写入本地 SQLite。云端会话提供工作区权限、智能体身份、后台治理和共享审计历史。

## 自动会话采集

| 模式 | 采集来源 | 适用范围 |
|---|---|---|
| 辅助模式 | 智能体遵循 Skill 或 MCP 指令调用会话工具 | 所有 MCP 与 REST 客户端 |
| 自动记忆 | TokST 接收已连接 ACP 会话或原生客户端桥接事件 | ACP 客户端、WorkBuddy、OpenCode、Pi、Codex 与 Claude Code |

自动记忆在用户设备上运行。TokST 在本机脱敏 API 密钥、Token、密码、Cookie 和私钥。云端会话保留已脱敏的用户请求、智能体最终回复和有效工具结果，供会话详情追溯；原始推理、流式片段和敏感内容会即时丢弃。

每个自动会话都会记录来源、原生或 ACP 会话标识、最近事件、编译状态和正式记忆链接。原生会话作为完整审计容器，可包含多个独立任务；每个完成的任务生成一条正式记忆，针对同一任务的追问会更新对应记忆并保留版本追溯。

自动归纳会保留当前任务的确认事实、决策、变更、任务和架构信息，并完整保留有效表格行、数字、单位、路径、命令、URL、状态、错误和后续事项。系统会清理重复表述、原始推理、流式片段和重复工具元数据。会话详情提供完整结果证据与任务记忆链接，正式记忆提供清晰、可检索的结构化内容；每项任务完成后自动保存一条正式记忆，用户可从会话详情撤销并归档关联记忆。

```bash
tokst auto on
tokst acp proxy -- <acp-agent-command> [args]
tokst acp opencode
tokst auto status
tokst auto privacy --retain-raw 0
```

### 原生桥接与 ACP 连接

支持 ACP 的客户端通过本机代理连接。`tokst auto on --agent all` 会检测并安装 WorkBuddy、OpenCode、Pi、Codex 与 Claude Code 的桥接器，然后启动本机服务。安装后重启所使用的客户端。WorkBuddy 使用 Harness 生命周期；OpenCode 在终端和 macOS App 使用全局插件；Pi 使用全局扩展；Codex 与 Claude Code 使用可与用户已有 Hook 共存的托管 Hook。每个桥接器将原生会话保留为完整审计轨迹，并基于每项已确认任务和结果生成一条可撤销 Markdown 记忆；恢复会话会持续更新对应记忆。

OpenCode 终端和 macOS App 从 `~/.config/opencode/plugins/tokst-automatic-memory.ts` 自动加载全局插件。外部 ACP Host 通过 `tokst acp opencode` 使用同一条链路：ACP 宿主启动 TokST，TokST 启动 `opencode acp`，原始 ACP 请求和响应保持透明转发。使用 `tokst auto status --agent opencode` 查看原生与 ACP 状态；`tokst auto repair --agent opencode` 会按当前 TokST 绝对路径重建插件。

```bash
tokst auto on --command <acp-agent-command>
tokst acp proxy -- <acp-agent-command> [args]
tokst acp opencode
tokst auto verify --agent all --json
```

Pi 直接会话使用全局桥接器；`tokst acp pi --doctor` 用于检查可选的 Pi ACP Host 适配器。Codex 与 Claude Code 通过已登录的本机客户端完成归纳。Claude Desktop 使用 MCP 辅助记录，界面状态固定标记为“辅助记录”。

启用自动记忆时会自动安装并启动用户级服务：macOS 使用 `launchd`，Linux 使用 `systemd --user`，Windows 使用登录任务。服务在网络中断时排队保存已脱敏 ACP 与原生桥接事件，并以稳定事件 ID 补传。`tokst auto status`、`verify`、`repair` 与 `logs` 返回同一套客户端状态结构。

每个 ACP 或原生会话稳定映射到一个 TokST Session；其中的任务单元分别映射到正式记忆。`tokst auto status --agent workbuddy` 与 `tokst auto status --agent opencode` 展示本机服务、桥接器状态、路由、队列和可行动诊断。Auto API 保存用户与工作区策略；事件由本机服务处理。

## MCP 工作流

云端 MCP 与 stdio MCP 提供以下会话工具。本地 MCP 保留相同的主动会话生命周期与候选治理；ACP 专属的恢复和自动记忆撤销由云端接口提供，因为其审计链路和正式记忆保存在共享服务中。

| 工具 | 用途 |
|---|---|
| `tokst_session_start` | 创建范围内任务并读取上下文 |
| `tokst_session_capture` | 添加候选内容，可包含类型、标签、标题、置信度和来源事件 ID |
| `tokst_session_checkpoint` | 保存进度与下一步动作 |
| `tokst_session_finalize` | 生成最终快照，并可选择编译候选内容 |
| `tokst_session_status` | 查看会话状态与恢复上下文 |
| `tokst_session_list` | 列出个人或受管理的工作区会话 |
| `tokst_session_moderate_candidate` | 编译、驳回或撤销候选内容 |
| `tokst_session_archive` | 归档或恢复会话 |
| `tokst_session_reopen` | 云端/stdio MCP：恢复 ACP 会话并保持自动记忆标识 |
| `tokst_session_revert_automatic_memory` | 云端/stdio MCP：归档 ACP 会话的自动记忆并保留审计 |
| `tokst_auto_status` | 读取自动记忆策略与本机连接状态 |
| `tokst_auto_configure` | 为工作区或知识库启用、暂停或设置自动记忆路由 |

建议将以下规则加入智能体项目指令：重大工作开始前创建会话；仅捕获已确认的长期内容；交接前创建检查点；完成后结束会话；密钥和原始推理不写入 TokST。`tokst agent listen` 收到工作区交接后，接收智能体应恢复指定会话或创建新会话，并在确认交接后创建检查点。

## 审核与权限

| 角色 | 会话权限 |
|---|---|
| Member | 在可访问工作区中创建、读取、捕获、完成和归档本人会话 |
| Admin | 查看受管理的工作区会话，并治理该工作区全部候选内容 |
| Owner | 具备 Admin 治理权限，并可查看完整工作区审计 |
| 系统管理员 | 在独立系统管理员后台只读审计跨工作区会话 |

用户后台入口为 **控制台 → 会话**。页面跟随当前工作区，顶部提供待审核候选队列，展示来源会话、置信度、内容和处理状态。成员管理自己的候选；Owner 与 Admin 管理整个工作区队列。会话视图同时展示状态、任务、创建者、智能体、知识库、检查点、最近活动和快照状态。Realtime 仅刷新当前工作区。自动记忆会在 ACP 会话结束时由已连接的 Agent 生成一条可撤销记忆；出现失败时运行 `tokst auto status` 查看连接、权限与脱敏状态。

## 可靠写入与质量

- 客户端可能重试创建会话时，传入 `--idempotency-key`；同一键会返回已有会话。
- 同一来源事件可能重复投递时，传入 `--source-event-id`；同一事件会返回已有候选内容。
- 重复 `finalize` 会安全返回已完成结果，避免生成竞争摘要。
- 置信度用于描述证据质量。低于 `0.6` 的候选会进入低置信度质量视图，供管理者审核。
- 内容保持具体且可独立复用。检查点使用几句话说明当前进度、阻塞项和下一步动作。

接口细节请参考 [CLI 参考](/docs/cli#会话记忆)、[MCP 参考](/docs/mcp#会话记忆协议) 和 [REST API 参考](/docs/rest-api#会话记忆-api)。