TokST Persistent memory for people and AI agents

CLI 参考

tokst CLI 是与 TokST 记忆系统交互的主要界面。以下所有命令按功能分组。

许多命令接受 --atlas 作为 --atlas-id 的简写。为任何命令传入 --json 可获取机器可读的输出。

Claude、Pi、Codex 等智能体执行命令时，可设置 TOKST_AGENT=1 或传入 --agent。这个增量模式提供紧凑且有上限的 JSON、网络硬截止时间、确定性 输出刷新，并跳过交互式版本检查。添加 --full 可获得完整的现有 JSON 响应；延迟输入管道使用 --stdin。

Agent 身份与交接

TOKST_AGENT=1 或 --agent 会使用当前 API Key 绑定的可信 Agent 身份。首次调用会创建稳定的 agt_... 身份码，--source 保持为展示用来源标签。

tokst agent list 列出工作区 Agent；tokst agent listen [--workspace <id>] [--json] 保持实时事件流并为 Agent Runtime 输出 JSON Lines；tokst message send 支持 --to agt_... 定向发送或 --broadcast 广播；tokst message inbox 默认读取全部工作区的持久收件箱，可用 --workspace <id> 过滤；tokst message acknowledge <id> 和 tokst message close <id> 管理回执。

在长期运行的 Agent 旁启动 TOKST_AGENT=1 tokst agent listen --json 作为轻量 sidecar。连接恢复后会先输出未读消息快照；Agent 接受工作后再确认，完成后关闭回执。

认证

命令描述
tokst version [--verbose] 或 tokst --version显示已安装 CLI 版本；--verbose 同时显示当前安装渠道和可执行文件。
curl -fsSL https://tokst.com/install.sh | bash安装或升级通过 SHA-256 校验的独立 CLI，并保留已有授权。
irm https://tokst.com/install.ps1 | iex在 Windows PowerShell 安装或升级通过 SHA-256 校验的独立 CLI。
tokst update按当前安装渠道升级：校验后的独立二进制、npm 或 Bun。
tokst login --key <key>使用 API 密钥进行认证（tk_live_xxxx）。凭证保存到 ~/.tokst/config.json。
tokst logout清除存储的会话凭证。
tokst doctor [--fix-path]检查认证、可选的 Git 仓库和知识库绑定、智能体集成文件与命令优先级；--fix-path 可在 zsh 或 bash 中优先使用独立 CLI。
curl -fsSL https://tokst.com/install.sh | bash
tokst version
tokst doctor
tokst login --key tk_live_abc123def456
tokst logout

setup 是推荐的交互式流程。它会打开 tokst.com，确认已登录账户，再将一次性凭据直接交给等待中的 CLI。它不会选择工作区或知识库：每条命令显式指定范围；终端需要活动工作区时使用 tokst workspace switch；仅当目录固定属于一个项目时才绑定知识库。API Key 登录继续适用于 CI、服务器和无人值守脚本。

帮助

tokst --help 展示日常工作流。使用 tokst memory --help、tokst atlas --help、tokst workspace --help 或 tokst agent --help 查看完整命令分组；tokst help <group> 提供相同的分组参考。

本地智能体初始化

为当前目录中的智能体生成本地指令。

tokst init --agents codex,claude,cursor,opencode,pi
tokst doctor

tokst init 只写入本地智能体指令，可在任意目录使用。已有指令文件会被保留；需要刷新时使用 --force。使用 tokst atlas init 创建知识库，需要项目路由时再使用 tokst atlas bind --atlas-id <id> 绑定目录。tokst doctor 会报告认证、可选的 Git 仓库和知识库绑定，以及集成文件的检查结果。

知识库管理

知识库是保存相关记忆的命名知识库。

命令描述
tokst atlas init --name <name>创建新知识库
tokst atlas bind --atlas-id <id> [--path <path>]将已有知识库绑定到目录；Git 元数据可选
tokst atlas list列出活跃工作区中的所有知识库
tokst atlas rename --atlas-id <id> --name <new>重命名知识库
tokst atlas profile --atlas-id <id> --keywords a,b,c设置关键词配置以启用自动路由
tokst atlas delete --atlas-id <id>删除知识库及其所有记忆
tokst atlas init --name "Project Alpha"
tokst atlas bind --atlas-id <id>
tokst atlas list
tokst atlas profile --atlas-id <id> --keywords architecture,backend,api
tokst atlas rename --atlas-id <id> --name "Project Alpha v2"
tokst atlas delete --atlas-id <id>

工作区管理

工作区将知识库分组，以实现组织隔离（例如，个人 vs. 团队）。

命令描述
tokst workspace create --name <name>创建新工作区
tokst workspace list列出您所属的所有工作区
tokst workspace switch <workspace-id>切换活跃工作区
tokst workspace members <workspace-id>列出工作区成员和角色
tokst workspace invite <团队工作区-id> <email[,email,...]>邀请最多 100 位用户加入团队工作区；支持 --role 和 --expires-in-days

云端团队工作区创建会消耗账户的可用团队工作区配额。执行 tokst workspace create --name <名称> --type team 前，请先在用户后台申请或购买配额。本地模式保留独立的本地工作区模型。 | tokst workspace invitations <workspace-id> | 列出该工作区已发出的邀请 | | tokst workspace inbox | 列出自己待处理的邀请 | | tokst workspace respond <invitation-id> --accept\|--decline | 接受或拒绝邀请 | | tokst workspace revoke <invitation-id> --confirm | 撤销待处理邀请 | | tokst workspace leave <workspace-id> --confirm | 退出工作区 | | tokst workspace role <workspace-id> <user-id> --role admin\|member --confirm | 修改成员角色 | | tokst workspace remove <workspace-id> <user-id> --confirm | 移除成员 | | tokst workspace transfer-owner <workspace-id> <user-id> --confirm | 转移工作区 Owner |

tokst workspace create --name "Team Engineering"
tokst workspace list
tokst workspace switch <workspace-id>
tokst workspace invite <workspace-id> [email protected],[email protected] --expires-in-days 7
tokst workspace inbox

tokst workspace list 会标记已保存的当前工作区，并展示待处理邀请及接受、拒绝命令。tokst workspace switch 会保存选择，之后的 tokst atlas init 将在该工作区创建知识库。接受邀请后，再切换到新加入的工作区。

记忆操作

TokST 的核心 — 存储、检索和管理记忆。

记住 (Remember)

存储一条新记忆。这是最常用的命令。

tokst remember "Your content here" --type note

短事实可以使用纯文本。决策、架构、会议纪要和任务建议使用 Markdown。写入长内容时，可通过标准输入传入 Markdown 文件：

tokst remember --type decision --tags api,auth --stdin < decision.md

标题、列表、任务清单、链接、表格和代码块可以提升阅读效率。密钥、私钥、原始推理和临时工具输出保留在 TokST 之外。

选项描述
--type记忆类型：fact、decision、preference、task、architecture、note（默认：note）
--tags逗号分隔的标签，用于筛选（例如：--tags deploy,production）
--source-type来源类型：human、agent、import、system（默认：human）
--source来源名称，例如 codex 或 import
--atlas目标知识库 ID（--atlas-id 的简写）
--title可选的记忆标题
--file附加一个或多个文件（可重复：--file a.png --file b.pdf）
--evidence证据 URL 或来源文件路径
--confidence可信度，取值 0 到 1
--valid-until具有时效性信息的 ISO 到期时间

列表、更新、追加

tokst memory list                   # 列出最近的记忆
tokst memory update <id> --content "Updated content"
tokst memory append <id> --content "Additional information"

归档、恢复、删除

记忆遵循生命周期：活跃 -> 已归档 -> 已删除。

tokst memory archive <id>           # 归档（软隐藏）
tokst memory restore <id>           # 从归档恢复
tokst memory delete <id>            # 永久删除

验证与替代

为记忆补充证据、可信度和可选有效期后，可将其标记为已验证。新信息替代旧信息时，保留两条记忆之间的关联，以便追溯原有决策。

tokst memory verify <id> --evidence https://example.com/source --confidence 0.95
tokst memory verify <id> --valid-until 2027-01-01T00:00:00Z
tokst memory supersede <旧记忆-id> <新记忆-id>

文件附件

tokst memory attach <id> --file document.pdf
tokst memory download <id>                       # 下载所有附件到 ~/Downloads
tokst memory download <id> --out ./files         # 指定输出目录
tokst memory download <id> --attachment-id <aid> # 下载指定附件

搜索与上下文

tokst search "keyword query"        # 自适应 auto 模式（默认）
tokst search "query" --search-mode keyword
tokst search "query" --search-mode semantic
tokst search "query" --search-mode hybrid
tokst search "query" --type fact    # 按类型筛选
tokst search "query" --tags api     # 按标签筛选
tokst search "query" --limit 20     # 限制结果数（默认：10）
tokst search "query" --json         # 机器可读输出

tokst context                       # 当前知识库上下文快照
tokst context --atlas <id>          # 指定知识库的上下文
tokst context --limit 50            # 包含最多 50 条最近记忆

tokst context 返回当前知识库中最近记忆的格式化摘要 — 适用于为 AI 智能体提供对话上下文。

--json 会返回最终模式、embedding 缓存层级以及关键词、embedding、向量和总耗时。SEARCH_DEFAULT_MODE=keyword 可立即切换为纯关键词默认路径。

批量导入

从文件夹（或单个文件）批量导入记忆。文本文件自动提取内容；二进制文件作为附件上传，文件名作为记忆内容。

tokst import ./docs                          # 导入文件夹中的所有文件
tokst import report.pdf                      # 导入单个文件
tokst import ./code --type architecture      # 设置默认记忆类型
tokst import ./docs --tags imported,docs     # 为所有导入的记忆添加标签
tokst import ./large-dir --max 50            # 限制最多导入 50 个文件
tokst import ./docs --dry-run                # 预览不实际导入
tokst import ./docs --no-attach              # 仅创建文本记忆，不上传原文件

支持的文本格式（自动提取）：txt、md、json、csv、yaml、xml、html、css、js、ts、tsx、py、go、rs、java、sql、sh 等 30+ 种。

二进制格式（作为附件上传）：pdf、png、jpg、docx、xlsx 等所有其他格式。

选项说明
--type所有导入记忆的默认类型（默认：note）
--tags逗号分隔的标签，添加到所有导入记忆
--atlas-id目标知识库（默认：自动路由或第一个知识库）
--source来源名称（默认：import）
--dry-run扫描预览，不实际导入
--max最多导入的文件数量
--no-attach仅创建文本记忆，跳过原文件上传

实用工具

命令描述
tokst status显示套餐、用量、存储、个人工作区与知识库配额、团队工作区配额及记忆统计
tokst status --json同上，JSON 格式供脚本使用
tokst migrate在架构之间迁移数据（管理员使用）
tokst sync强制将本地状态与服务器同步
tokst status

示例输出（云端模式）：

Mode:     Cloud (Supabase)
Endpoint: https://pdjpdivokmcevxdrvtfb.supabase.co

Plan:        pro    206 / 10,000 calls this month   (2% used, resets Jul 1)
Storage:     673 KB / 10.00 GB   7 files   (0% used)

Quotas:
  Personal workspaces:  2 / 10       8 available
  Personal Atlases:     7 / 200      193 available   (20 per workspace)
  Team workspaces:      3 / 5        2 available to create

Summary:
  Workspaces:  2
  Atlases:     7
  Memories:    248 active

Workspaces:
  kueen
  personal

Atlases:
  TokST             in kueen          43 mem  (fact=13, architecture=18, decision=9, note=3)
  ...

Plan:、Storage: 和 Quotas: 行仅在云端模式显示。--json 会额外输出 account 块，包含 plan、monthlyLimit、periodResetAt、usage、storage 和 quota 字段。没有上限的配额会显示为 unlimited。

通用选项

选项描述
--json以 JSON 格式输出结果（而非格式化文本）
--atlas--atlas-id 的别名，指定目标知识库
--help显示任何命令的帮助信息
--version显示 CLI 版本

所有命令都支持 --help 查看详细用法：

tokst remember --help

会话记忆

会话记忆用于多步骤任务和智能体交接。

TOKST_AGENT=1 tokst session start --atlas-id <atlas-id> --task "实现会话记忆" --json
TOKST_AGENT=1 tokst session capture --session <ses-id> "写入使用幂等键" --kind decision --tags api,reliability --json
TOKST_AGENT=1 tokst session checkpoint --session <ses-id> "服务端路由已完成" --json
TOKST_AGENT=1 tokst session finalize --session <ses-id> "已完成服务端路由与契约。" --json

session start 返回当前范围的上下文；capture 保存候选记忆；finalize 写入会话快照，并默认将候选内容编译为正式记忆。添加 --no-compile 可保留候选内容等待审核。 使用 tokst session candidates --scope mine --status pending 查看自己的待审核队列。Owner 与 Admin 可使用 --scope managed 查看整个工作区，并对候选执行编译、驳回、撤销和归档；撤销会归档关联正式记忆并保留审计链路。

自动记忆

自动记忆由用户在当前设备主动启用。tokst auto on 会检测 WorkBuddy、OpenCode、Pi、Codex 与 Claude Code，安装各自的原生桥接器并启动本机服务。OpenCode 全局插件同时覆盖终端和 macOS App；Pi 使用全局扩展；Codex 与 Claude Code 使用托管 Hook，并完整保留用户已有 Hook；外部 ACP Host 继续使用 ACP 入口。TokST 在本机脱敏后自动保存一条可撤销的正式记忆。原始内容默认即时删除，可选保留 24 小时用于本机故障恢复。

tokst auto on --agent all
tokst acp proxy -- <acp-agent-command> [args]
tokst auto status
tokst auto verify --agent all --json
tokst auto privacy --retain-raw 24h

OpenCode 终端与 macOS App 使用全局插件。安装一次后重启 OpenCode；通过 opencode -s 恢复的会话会更新同一条自动记忆：

tokst auto on --agent opencode
tokst acp opencode --doctor
# OpenCode 正常启动即可自动加载插件。
# 外部 ACP 宿主可配置 command=tokst，args=["acp", "opencode"]

tokst auto repair --agent <name> 刷新指定桥接器，tokst auto off --agent <name> 仅移除该桥接器，tokst auto logs --agent <name> 查看本机诊断。tokst acp opencode --repair 保留 ACP Host 修复流程，tokst acp pi --doctor 显示 Pi 直接桥接与可选 ACP Host 适配器状态。

自动记忆会启动用户级服务。网络中断时已脱敏事件保留在本机队列中，并以事件 ID 安全补传。个人工作区和默认知识库作为默认路由；团队工作区由用户显式切换后生效。

完整生命周期、重试键、本地工作流、后台治理和 MCP 工具映射请阅读会话记忆指南。