TokST 面向人类与 AI 智能体的持久上下文

会话与自动记忆

高级运行时工作流。 长期记忆、上下文、知识库、文件和工作区治理请使用云端 MCP。本机智能体采集、定向任务执行、通信和端点诊断需要安装独立 CLI。

会话以一条可审计时间线记录智能体的正常工作。TokST 采集有效用户请求、最终回复与有价值的工具结果，再生成可阅读的会话整理。会话包含可跨任务复用的事实、决策、偏好、规则或架构时，可提取零条或多条长期记忆。

任务拥有独立文档与流程。会话只记录已经完成的工作，并可在用户后续创建任务时提供上下文。

TokST 会在保存前脱敏凭据、私钥、密码、Cookie、敏感个人数据、原始推理与短期工具输出。

适用场景

会话用于查看 Pi、OpenCode、WorkBuddy、Codex 或 Claude Code 的自动采集、整理版本、提取记忆与诊断。功能开发、事故排查、发布准备、合同审阅和多智能体协作都适合通过会话保留过程。

长期可复用的事实和决策保存在记忆中。定向执行与分派请参考任务文档。

生命周期

阶段记录内容作用
采集用户请求、最终回复与有价值工具结果保留真实工作边界
整理可阅读的结果、证据、风险与后续动作让每个完成单元可追溯
提取零条或多条长期可复用记忆将长期信息与会话历史分开
审核发布、修订或撤销提取记忆让工作区管理者治理长期知识
归档保留审计与搜索记录，隐藏默认列表保持活跃视图聚焦并保留历史

下方显式会话命令通过已连接 CLI Runtime 与既有自动化集成继续可用。自动采集使用相同的隐私、证据、审核与归档规则。

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

云端会话提供工作区权限、智能体身份、用户后台治理和共享审计历史。已连接 Runtime 设备保留内部加密队列，用于桥接投递与脱敏恢复，不形成独立的本地记忆产品。

自动会话采集

模式采集来源适用范围
已连接 RuntimeCLI 桥接器记录本机智能体活动已连接本机端点
自动记忆TokST 接收已连接 ACP 会话或原生客户端桥接事件ACP 客户端、WorkBuddy、OpenCode、Pi、Codex 与 Claude Code

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

每个自动会话都会记录来源、原生或 ACP 会话标识、最近事件、编译状态、自动整理版本和关联长期记忆。会话边界在同时具备有效用户请求和最终结果时创建待确认草稿；通用启动、恢复和关闭事件保留在活动与诊断记录中。原生会话作为完整审计容器，可包含多个独立任务。用户可从已发布整理结果创建正式任务。

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

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

原生桥接与 ACP 连接

支持 ACP 的客户端通过本机 Runtime 连接。运行 tokst start 连接设备，再运行 tokst auto on --agent all 安装并启用 WorkBuddy、OpenCode、Pi、Codex 与 Claude Code 的桥接器。安装后重启所使用的客户端。WorkBuddy 使用 Harness 生命周期；OpenCode 在终端和 macOS App 使用全局插件；Pi 使用全局扩展；Codex 与 Claude Code 使用可与用户已有 Hook 共存的托管 Hook。每个已启用桥接器将原生会话保留为完整审计轨迹，为每项完成任务生成自动整理，并从中提取可复用的长期记忆；恢复会话会持续更新对应整理版本。

OpenCode 终端和 macOS App 从 ~/.config/opencode/plugins/tokst-automatic-memory.ts 自动加载全局插件。外部 ACP Host 通过 tokst acp opencode 使用同一条链路：ACP 宿主启动 TokST，TokST 启动 opencode acp，原始 ACP 请求和响应保持透明转发。使用 tokst 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 status、verify、repair 与 logs 返回同一套客户端状态结构。

每个 ACP 或原生会话稳定映射到一个 TokST Session；其中的任务单元分别映射到自动整理版本和可选长期记忆。tokst status --agent workbuddy 与 tokst status --agent opencode 展示本机服务、桥接器状态、路由、队列和可行动诊断。自动记忆策略由控制台与已连接 Runtime 管理；事件由本机服务处理。

已连接 Runtime

会话、任务与沟通通过已认证 WSS 由已连接 TokST Runtime 处理，同时保持独立记录。自动记忆默认关闭，并按受支持客户端分别开启。使用后台查看、审核、归档和恢复这些记录。云端 MCP 为工作提供长期记忆与上下文。

任务

会话可以为用户创建的任务提供已确认的来源上下文。分派、执行方式、结果、恢复与任务权限请阅读任务指南。

沟通保存长期私信与智能体群组，不会自动创建会话或任务。联系人、投递、流式回复和群组行为请查看沟通。

审核与权限

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

用户后台入口为 控制台 → 会话。页面跟随当前工作区，展示来源、整理版本、提取记忆、诊断、创建者、智能体、知识库、最近活动和快照状态。成员管理自己的候选；Owner 与 Admin 管理整个工作区队列。Realtime 仅刷新当前工作区。自动记忆会在 ACP 会话完成后由已连接的 Agent 整理结果，并在有复用价值时提取长期记忆；出现失败时运行 tokst status 查看连接、权限与脱敏状态。

可靠写入与质量

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

已连接 Runtime 命令请参考 CLI 参考。长期记忆与上下文请使用云端 MCP。