会话记忆
会话记忆为长期智能体任务提供可持续、可审核的生命周期。会话从工作区和知识库上下文开始，持续积累已确认的候选知识与进度检查点，最后生成紧凑快照。下一位用户或智能体可以带着决策、当前进度和下一步动作继续工作。
TokST 只保存通过会话工具显式提交的内容。凭据、私钥、缺乏明确用途的隐私数据、原始推理过程和短期工具输出保留在当前运行环境中。
适用场景
多步骤工作、需要交接的任务、需要留存审核过程的事项适合建立会话。例如功能开发、事故排查、发布准备、合同审阅和多智能体协作。
单条长期事实适合直接创建记忆。会话记忆同时保存该事实形成过程中的进度、交接点和审核记录。
生命周期
| 阶段 | 记录内容 | 作用 |
|---|---|---|
| 开始 | 任务、工作区/知识库范围与返回的上下文 | 建立工作边界，减少重复组织上下文 |
| 捕获 | 候选事实、决策、偏好、任务、架构或普通说明 | 将已确认的长期信息与原始工作材料分开 |
| 检查点 | 简洁进度摘要与下一步动作 | 支持交接和中断后的恢复 |
| 完成 | 最终摘要与不可变会话快照 | 为任务生成紧凑的完成记录 |
| 审核 | 编译、驳回或撤销候选内容 | 让工作区管理者治理正式记忆 |
| 归档 | 保留审计与搜索记录，隐藏默认列表 | 保持活跃工作区聚焦且保留历史 |
finalize 默认把待处理候选内容编译为正式记忆。使用 --no-compile 可将候选保留给管理者审核。撤销已编译候选会归档其关联的正式记忆，并保留完整审计链路。
CLI 工作流
智能体运行使用 TOKST_AGENT=1，输出保持结构化，服务端会从 API 密钥注入可信智能体身份。
# 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
常用后续命令：
# 查看会话、候选、检查点、快照和范围内上下文。
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、状态、错误和后续事项。系统会清理重复表述、原始推理、流式片段和重复工具元数据。会话详情提供完整结果证据与任务记忆链接，正式记忆提供清晰、可检索的结构化内容；每项任务完成后自动保存一条正式记忆，用户可从会话详情撤销并归档关联记忆。
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 绝对路径重建插件。
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 参考、MCP 参考 和 REST API 参考。