# 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) |