記憶管理指南
記憶是 TokST 中的基本資訊單元。記憶會被標記並組織到知識庫中；設定的嵌入服務可用時，內容會產生 1536 維向量。
記憶類型
選擇最符合您所儲存資訊描述的類型。
| 類型 | 用例 | 範例 |
|---|---|---|
fact | 可驗證的客觀資訊 | "API 閘道 URL 是 https://api.tokst.com" |
decision | 已做出的選擇及其理由 | "選擇 Supabase 而非 Firebase，因為其原生 Postgres 工具" |
preference | 主觀偏好 | "對於簡單的 CRUD 端點，偏好 REST 而非 GraphQL" |
task | 任務、待辦事項或行動項目 | "在週五前將遺留使用者遷移到新的驗證流程" |
architecture | 系統設計或架構說明 | "驗證流程使用 JWT，1 小時過期時長，自動重新整理" |
note | 一般資訊（預設） | "與團隊開會，討論了 Q3 路線圖優先級" |
tokst remember "The database runs on Supabase Postgres" --type fact
tokst remember "Use Turborepo for monorepo management" --type decision --tags architecture,infra
使用結構化 Markdown
短事實適合直接使用純文字。決策、架構、會議紀要和工作適合使用 Markdown，使記憶在後台中易於閱讀和檢索。
| 類型 | 建議結構 |
|---|---|
fact | 結論、來源、適用範圍 |
decision | 決策、背景、理由、影響 |
preference | 偏好、適用情境、避免事項 |
task | 目標、工作清單、完成標準 |
architecture | 目標、組成、資料流、約束 |
note | 摘要、內容、後續行動 |
後台編輯器提供以上範本和 Markdown 格式工具。CLI 寫入長內容時，建議使用 Markdown 檔案：
tokst remember --type decision --tags api,auth --stdin < decision.md
智能體使用相同結構記錄已確認的長期資訊。金鑰、私鑰、原始推理和暫時工具輸出保留在目前執行環境中。
種類 (Kind)
每條記憶都包含一個 kind 欄位，描述其派生方式：
| 種類 | 描述 |
|---|---|
raw | 直接記錄的原始資訊 |
summary | 經過提煉或濃縮的資訊版本 |
snapshot | 上下文的時間點快照 |
種類是自動分配的，但可以覆蓋。
來源類型
跟蹤記憶的來源：
| 來源 | 描述 |
|---|---|
human | 透過 CLI 或儀表板由人工記錄 |
agent | 透過 MCP 由 AI 智能體建立 |
import | 從外部系統匯入 |
system | 由 TokST 內部生成（例如，自動路由） |
tokst remember "Auto-scaling group configured for 2-10 instances" --source-type agent --source codex
標籤
標籤是用於篩選和發現的逗號分隔標籤。與類型（互斥）不同，標籤是累加的——一條記憶可以有多個標籤。
tokst remember "Deploy process documented in Notion" --tags deploy,documentation,notion
標籤支援篩選搜尋：
tokst search "deploy" --tags production
tokst search "architecture" --type decision
搜尋
TokST 使用關鍵字優先、語意回退的搜尋流程：
- 關鍵詞匹配 — 對記憶內容的傳統文字搜尋
- 語意向量搜尋 — 1536 維空間中的嵌入相似度
關鍵字直接命中會立即回傳並略過嵌入請求。沒有關鍵字結果時，TokST 會產生查詢嵌入，並在驗證使用者及其可存取工作區範圍內執行 1536 維向量搜尋。
tokst search "database connection issues" # 語意搜尋
tokst search "Supabase connection string" # 關鍵詞匹配
tokst search "auth" --type architecture # 篩選搜尋
tokst search "api" --limit 20 --json # 帶選項的搜尋
上下文快照
context 指令生成目前知識庫中最近記憶的格式化快照。這對於為 AI 智能體提供對話上下文特別有用。
tokst context # 目前知識庫
tokst context --atlas <id> # 指定知識庫
tokst context --limit 50 # 更多記憶
輸出包括記憶內容、類型、標籤和時間戳，採用人類和智能體均可讀的格式。
記憶生命週期
記憶經歷三個狀態：
活躍 --> 已歸檔 --> 已刪除
| 狀態 | 描述 | 在搜尋中可見？ | 可恢復？ |
|---|---|---|---|
| 活躍 | 正常，可搜尋 | 是 | — |
| 已歸檔 | 軟隱藏，不出現在預設結果中 | 否 | 是（restore） |
| 已刪除 | 永久移除 | 否 | 否 |
tokst memory archive <id> # 軟隱藏
tokst memory restore <id> # 恢復
tokst memory delete <id> # 永久刪除
可信記憶生命週期
對於事實、決策和規則等需要明確來源或審核軌跡的內容，可使用可信中繼資料。
| 欄位 | 用途 |
|---|---|
evidence | 支撐記憶的 URL 或檔案路徑 |
confidence | 0 到 1 的可信度評分 |
validUntil | 可選 ISO 時間，到期後記錄需要複核 |
reviewStatus | unreviewed、verified、needs_review 或 superseded |
tokst memory verify mem_xxx --evidence https://example.com/policy --confidence 0.95
tokst memory verify mem_xxx --valid-until 2027-01-01T00:00:00Z
tokst memory supersede mem_old mem_new
驗證會保留原記憶並標記為已審核。取代會將舊記憶連結到新記憶，並將舊記錄標記為 superseded，便於持續追溯歷史上下文。
嵌入
儲存記憶或修改內容時，TokST 會請求嵌入向量。嵌入過程：
- 在服務已設定且可用時產生 1536 維向量
- 在寫入時在伺服器端執行
- 是透明的——您永遠不需要直接操作向量
- 為語意回退查詢提供支援
嵌入服務未設定時仍可寫入記憶，關鍵字搜尋繼續可用；產生嵌入後即可使用語意回退。
檔案附件
記憶可以透過 --file 標誌附加檔案。請參閱檔案附件指南了解詳情。
tokst remember "Sprint planning notes" --file sprint-planning.pdf
tokst memory attach <id> --file diagram.png
批量匯入
從資料夾批量匯入檔案為記憶。文字檔案（md、程式碼、json、csv 等）自動提取內容；二進位檔案作為附件上傳。
tokst import ./docs --dry-run # 預覽
tokst import ./docs --type note --tags imported # 匯入
請參閱 CLI 參考 了解所有參數。
最佳實踐
- 一致使用類型 — 這使篩選搜尋更可靠
- 多用標籤 — 標籤是跨領域組織的主要機制
- 歸檔而非刪除 — 歸檔的記憶在需要時可以恢復
- 取得上下文快照 — 在智能體工作階段前執行
tokst context以提供背景資訊 - 追加到現有記憶 — 在添加相關資訊時使用
append而非建立重複內容