# TokST 文档

TokST 是面向 AI 智能体的**共享记忆与状态层**。它为人、智能体和应用提供一个持久位置，用于记录事实、决策、偏好、任务、架构说明及相关文件。

智能体可以在会话开始时取回准确的项目上下文，在工作过程中补充新知识，并把结构化历史交给下一个智能体。同一份数据可通过 CLI、网页控制台、MCP 和 REST API 持续访问。

## 会话记忆

会话记忆让多步骤智能体任务具备可恢复、可审核的持续上下文。智能体以知识库范围内的上下文建立会话，将已确认的长期信息保存为候选内容，在交接前记录检查点，并在任务结束时生成紧凑快照。Owner 和 Admin 可在会话控制台编译、驳回或撤销候选内容；撤销会归档关联的正式记忆并保留审计链路。

TokST 仅保存这些调用中提交的结构化信息。凭据、隐私数据、原始推理和短期工具输出保留在当前智能体运行环境中。

完整的生命周期规则、CLI 与 MCP 操作流、审核权限、可靠重试、本地行为和后台治理请阅读[会话记忆指南](/docs/sessions)。

## 为什么需要 TokST

AI 会话有明确的时间边界，项目则会持续数周甚至数年。重要上下文通常分散在聊天记录、本地笔记、代码仓库和不同工具中。TokST 将这些上下文整理为可管理的知识层，提供稳定的归属关系、明确的作用域、可搜索的记录和可审查的生命周期。

TokST 适合以下工作流：

- 保存产品与架构决策及其理由
- 在多个智能体之间延续编码规范和用户偏好
- 在智能体开始工作前生成聚焦的上下文快照
- 将已完成工作、待办事项和已知风险交接给另一个智能体
- 将参考文档和文件放在对应记忆旁边
- 通过清晰边界区分个人、项目和团队知识

## 数据如何组织

TokST 使用简单的层级结构，让每条记忆都有明确归属。

| 层级 | 作用 | 示例 |
|---|---|---|
| **工作区（Workspace）** | 个人或团队的归属与访问边界 | `平台团队` |
| **知识库（Atlas）** | 围绕项目、主题或工作流组织的知识集合 | `生产运维` |
| **记忆（Memory）** | 带有类型、标签、来源和生命周期状态的可搜索知识单元 | `周五发布需要审批` |
| **附件（Attachment）** | 与某条记忆关联的文件 | `发布检查清单.pdf` |

一个工作区可以包含多个知识库。每个知识库都可以配置路由关键词；创建记忆时未指定知识库，TokST 可以根据关键词将其分配到相关知识库。

## 可以保存哪些内容

每条记忆属于六种类型之一。统一的类型有助于生成清晰的上下文快照，也便于按类型检索。

| 类型 | 适用内容 |
|---|---|
| `fact` | 已确认的事实和稳定的参考信息 |
| `decision` | 选择、理由及其影响 |
| `preference` | 个人、团队或项目约定 |
| `task` | 待办工作、后续事项和行动项 |
| `architecture` | 系统边界、组件关系和技术设计 |
| `note` | 其他通用上下文 |

记忆还可以包含标题、标签、来源信息、时间戳和附件。网页控制台支持最大 500 MB 的文件；远端 MCP 支持单文件最大 50 MB。

## 记忆工作流

1. **完成认证**：使用网页控制台登录，或创建 `tk_live_...` API 密钥。
2. **选择工作区和知识库**：确定数据归属与主题范围。
3. **写入记忆**：记录事实、决策、偏好、任务、架构或普通笔记。
4. **取回上下文**：通过搜索查找具体内容，或生成分组上下文快照。
5. **维护记录**：更新、追加、归档、恢复或删除记忆。
6. **继续协作**：让另一个智能体或工具读取同一份共享状态。

基础 CLI 工作流保持简洁：

```bash
tokst login
tokst remember "生产发布需要审批" --type decision --tags release,policy
tokst search "发布审批"
tokst context
```

智能体通过 MCP 执行同一套流程，对应工具包括 `tokst_remember`、`tokst_search` 和 `tokst_context`。

## 搜索与上下文

TokST 使用**关键词优先、语义检索补充**的搜索流程。直接文字匹配会立即返回。嵌入服务可用且关键词未命中时，TokST 会在认证用户可访问的范围内搜索 1536 维向量。

搜索适合回答具体问题。上下文快照适合在工作开始前，为智能体提供一份紧凑的分组视图，其中包含近期事实、决策、偏好、任务、架构记录和笔记。

## 选择使用方式

所有入口都使用同一套工作区、知识库、记忆和访问规则。

| 使用方式 | 适合场景 | 入口 |
|---|---|---|
| **网页控制台** | 浏览、编辑、账户管理和大文件上传 | [打开控制台](https://tokst.com/dashboard) |
| **CLI** | 终端工作流、脚本、批量导入和本地智能体会话 | `curl -fsSL https://tokst.com/install.sh \| bash` |
| **远端 MCP** | 支持 Streamable HTTP 的 ChatGPT 和远端智能体 | `https://api.tokst.com/mcp` — 51 个工具；设置 `TOKST_MCP_TOOLSET=core` 时为 11 个核心工具 |
| **本地 MCP** | 桌面客户端和本地 stdio 集成 | 执行安装脚本后使用 `bun x -y @tokst/mcp-server` — 51 个工具 |
| **REST API** | 产品集成和自定义自动化 | `https://api.tokst.com/v1` — 49 个需认证接口 |
| **智能体技能** | 通过一份公开文档让智能体掌握 TokST 工作流 | `https://tokst.com/skill.md` |

## 安全与数据边界

- API 密钥继承其所有者可用的账户和工作区权限。
- 记忆搜索与资源读取始终受认证用户可访问工作区约束。
- API 密钥应保存在环境变量、密钥管理器或客户端配置中。
- 附件签名下载链接有效期为 15 分钟。
- 归档后的记忆可以恢复；删除会永久移除记录及其存储的附件对象。

## 从这里开始

| 目标 | 指南 |
|---|---|
| 保存第一条记忆 | [快速入门](/docs/getting-started) |
| 为 AI 智能体增加持久记忆 | [智能体设置](/docs/agent-setup) |
| 运行并治理持续的智能体任务 | [会话记忆指南](/docs/sessions) |
| 了解智能体身份、昵称与交接 | [智能体身份](/docs/agent-identity) |
| 让智能体通过一个链接自行安装 | [技能指南](/docs/skill) |
| 在终端中使用 TokST | [CLI 参考](/docs/cli) |
| 连接 ChatGPT、Claude Desktop、Cursor 或 Codex | [MCP 服务器](/docs/mcp) |
| 将 TokST 集成到应用 | [REST API](/docs/rest-api) |
| 了解类型、搜索和生命周期 | [记忆管理](/docs/memories) |
| 组织知识边界 | [工作区](/docs/workspaces)与[知识库](/docs/atlases) |
| 添加相关文件 | [文件附件](/docs/attachments) |
| 管理凭据与配额 | [API 密钥](/docs/api-keys) |
| 邀请新用户并管理 Pro 权益 | [邀请与权益](/docs/referrals) |
| 处理安装、连接、本地模式或智能体问题 | [帮助中心](/help) |
| 查看已发布能力 | [版本历史](/docs/changelog) |