技能介绍

要解决的问题

多轮对话中的上下文丢失是个老问题：当 Agent 处理长周期任务时，临时堆叠的对话历史会逐渐淹没关键决策依据。传统方案依赖手动传递上下文或调用外部数据库，但前者增加冗余 token 消耗，后者引入额外的基础设施维护成本。尤其当团队协作时，不同成员的会话间缺乏共享记忆层，导致重复推理和信息断层。

技能如何工作

TokST Memory 采用「双模存储」架构，在云端与本地之间建立弹性边界：

云端模式：通过 tokst setup 完成浏览器授权后，数据存入 TokST 账户的 workspace，支持跨设备同步与团队共享。CI 环境可直接使用 API key 完成鉴权。
本地模式：所有记忆条目、附件与 FTS5 全文索引均存储于当前设备的 SQLite profile 文件，适合离线开发或合规敏感场景。

核心操作围绕 tokst remember 命令展开，需显式指定记忆类型（如 fact、decision、architecture）。例如，捕获系统设计决策时，命令需包含 Decision / Context / Rationale / Impact 四要素，最终生成结构化 Markdown 条目。--json 参数可输出机器可读格式，TOKST_AGENT=1 环境变量则会压缩输出范围以适配子进程调用。

Session 机制解决多步骤任务的上下文接力：每个 Session 初始化时携带 scoped context，执行过程中记录候选记忆并保存 checkpoint，最终通过 tokst session finalize 生成快照。可选的 Session Relay 功能可自动提取对话中的潜在记忆条目，但需注意其仅作为补充手段——正式记忆仍需 Agent 显式捕获。

适用边界与注意点

数据隔离原则：本地模式的附件永不上传云端，即使绑定 Cloud Atlas 后，附件仍保留在原设备。
敏感信息过滤：Agent 操作规则明确要求「排除机密、凭证与临时推理过程」，Relay 的自动提取功能会提前移除高风险内容。
工具适配限制：MCP 模式提供 53 个工具，但需根据客户端类型选择 OAuth 或静态 API key 鉴权。本地 stdio MCP 必须先执行 tokst setup --local。
故障恢复路径：遇到 command not found 时需重启终端；本地写入失败应优先备份 profile 再修复。