# 記憶管理指南

記憶是 TokST 中的基本資訊單元。記憶會被標記並組織到知識庫中；設定的嵌入服務可用時，內容會產生 1536 維向量。

## 記憶類型

選擇最符合您所儲存資訊描述的類型。

| 類型 | 用例 | 範例 |
|---|---|---|
| `fact` | 可驗證的客觀資訊 | "API 閘道 URL 是 https://api.tokst.com" |
| `decision` | 已做出的選擇及其理由 | "選擇 Supabase 而非 Firebase，因為其原生 Postgres 工具" |
| `preference` | 主觀偏好 | "對於簡單的 CRUD 端點，偏好 REST 而非 GraphQL" |
| `task` | 任務、待辦事項或行動項目 | "在週五前將遺留使用者遷移到新的驗證流程" |
| `architecture` | 系統設計或架構說明 | "驗證流程使用 JWT，1 小時過期時長，自動重新整理" |
| `note` | 一般資訊（預設） | "與團隊開會，討論了 Q3 路線圖優先級" |

```bash
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 檔案：

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

智能體使用相同結構記錄已確認的長期資訊。金鑰、私鑰、原始推理和暫時工具輸出保留在目前執行環境中。

## 種類 (Kind)

每條記憶都包含一個 `kind` 欄位，描述其派生方式：

| 種類 | 描述 |
|---|---|
| `raw` | 直接記錄的原始資訊 |
| `summary` | 經過提煉或濃縮的資訊版本 |
| `snapshot` | 上下文的時間點快照 |

種類是自動分配的，但可以覆蓋。

## 來源類型

跟蹤記憶的來源：

| 來源 | 描述 |
|---|---|
| `human` | 透過 CLI 或儀表板由人工記錄 |
| `agent` | 透過 MCP 由 AI 智能體建立 |
| `import` | 從外部系統匯入 |
| `system` | 由 TokST 內部生成（例如，自動路由） |

```bash
tokst remember "Auto-scaling group configured for 2-10 instances" --source-type agent --source codex
```

## 標籤

標籤是用於篩選和發現的逗號分隔標籤。與類型（互斥）不同，標籤是累加的——一條記憶可以有多個標籤。

```bash
tokst remember "Deploy process documented in Notion" --tags deploy,documentation,notion
```

標籤支援篩選搜尋：

```bash
tokst search "deploy" --tags production
tokst search "architecture" --type decision
```

## 搜尋

TokST 使用**關鍵字優先、語意回退**的搜尋流程：

1. **關鍵詞匹配** — 對記憶內容的傳統文字搜尋
2. **語意向量搜尋** — 1536 維空間中的嵌入相似度

關鍵字直接命中會立即回傳並略過嵌入請求。沒有關鍵字結果時，TokST 會產生查詢嵌入，並在驗證使用者及其可存取工作區範圍內執行 1536 維向量搜尋。

```bash
tokst search "database connection issues"       # 語意搜尋
tokst search "Supabase connection string"       # 關鍵詞匹配
tokst search "auth" --type architecture         # 篩選搜尋
tokst search "api" --limit 20 --json            # 帶選項的搜尋
```

## 上下文快照

`context` 指令生成目前知識庫中最近記憶的格式化快照。這對於為 AI 智能體提供對話上下文特別有用。

```bash
tokst context                         # 目前知識庫
tokst context --atlas <id>            # 指定知識庫
tokst context --limit 50              # 更多記憶
```

輸出包括記憶內容、類型、標籤和時間戳，採用人類和智能體均可讀的格式。

## 記憶生命週期

記憶經歷三個狀態：

```
活躍  -->  已歸檔  -->  已刪除
```

| 狀態 | 描述 | 在搜尋中可見？ | 可恢復？ |
|---|---|---|---|
| **活躍** | 正常，可搜尋 | 是 | — |
| **已歸檔** | 軟隱藏，不出現在預設結果中 | 否 | 是（`restore`） |
| **已刪除** | 永久移除 | 否 | 否 |

```bash
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` |

```bash
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` 標誌附加檔案。請參閱[檔案附件指南](attachments)了解詳情。

```bash
tokst remember "Sprint planning notes" --file sprint-planning.pdf
tokst memory attach <id> --file diagram.png
```

## 批量匯入

從資料夾批量匯入檔案為記憶。文字檔案（md、程式碼、json、csv 等）自動提取內容；二進位檔案作為附件上傳。

```bash
tokst import ./docs --dry-run                  # 預覽
tokst import ./docs --type note --tags imported # 匯入
```

請參閱 [CLI 參考](cli#批量匯入) 了解所有參數。

## 最佳實踐

- **一致使用類型** — 這使篩選搜尋更可靠
- **多用標籤** — 標籤是跨領域組織的主要機制
- **歸檔而非刪除** — 歸檔的記憶在需要時可以恢復
- **取得上下文快照** — 在智能體工作階段前執行 `tokst context` 以提供背景資訊
- **追加到現有記憶** — 在添加相關資訊時使用 `append` 而非建立重複內容