# 工作階段與記憶體

## 工作階段

### 工作階段如何運作

與代理程式的每次對話都發生在**工作階段**中。工作階段由編碼上下文的鍵識別, , 哪個代理程式、哪個頻道、哪個聊天。

工作階段維護所有訊息、工具呼叫和結果的完整轉錄（僅附加 JSONL）。這個轉錄提供代理程式關於正在進行的對話的上下文。

### 工作階段鍵

工作階段根據上下文自動路由：

| 模式 | 含義 |
|------|------|
| `agent:main:main` | 主要直接對話 |
| `agent:<id>:<channel>:group:<id>` | 特定頻道上的群組聊天 |
| `agent:<id>:<channel>:channel:<id>` | 頻道/房間對話 |
| `cron:<jobId>` | 排程工作執行 |
| `hook:<uuid>` | Webhook 觸發執行 |

### 工作階段生命週期

- **每日重置**, 工作階段在可設定的時間自動重置（預設凌晨 4 點本地時間）。這每天建立一個新的對話上下文，同時保留歷史。
- **閒置過期**, 在可設定的時間段內未活躍的工作階段可以自動重置。
- **手動重置**, 使用 `/new` 或 `/reset` 命令隨時開始新對話。

### 令牌追蹤

工作階段追蹤累積令牌使用量（輸入、輸出、快取讀取、快取寫入），用於成本監控和上下文視窗管理。

---

## 壓縮

### 什麼是壓縮？

當對話接近模型的上下文視窗限制時，Neotask **壓縮**它, , 將較舊的訊息摘要為濃縮概述，並以該摘要加上最近的訊息開始新工作階段。

### 如何運作

1. **偵測**, 監控上下文使用量（預設觸發：上下文視窗的 80%）
2. **摘要**, 較舊的訊息被摘要為壓縮條目
3. **新工作階段**, 以注入頂部摘要的新工作階段開始
4. **保留**, 舊轉錄保留用於歷史，但不再載入至上下文

### 設定

- **啟用/停用**, 切換自動壓縮
- **閾值**, 觸發壓縮的上下文視窗百分比（預設 80%）
- **最少訊息**, 如果訊息少於 N 條則不壓縮

### 手動壓縮

您可以隨時使用 `/compact` 命令手動觸發壓縮。當您想在不丟失重要資訊的情況下重置上下文時，這非常有用。

---

## 記憶體

### 代理程式記憶體

每個代理程式都有一個跨工作階段持久化重要資訊的記憶體系統：

- **MEMORY.md**, 代理程式工作空間中的 markdown 檔案，用於儲存重要事實、偏好和上下文
- **記憶體目錄**, `memory/` 中用於結構化知識的額外檔案

### 向量搜尋

Neotask 支援對代理程式記憶體進行向量相似性搜尋：

1. **索引**, 記憶體檔案使用嵌入進行索引
2. **搜尋**, 代理程式使用自然語言查詢記憶體（「使用者說過他們的 API 偏好是什麼？」）
3. **回憶**, 相關記憶體按相似性排序返回

### 記憶體外掛（LanceDB）

LanceDB 記憶體外掛提供進階向量儲存：

- 持久向量資料庫
- 可設定的區塊大小和重疊
- 高效的相似性搜尋
- 記憶體檔案更改時自動重新索引

### 自動回憶

在工作階段開始時，相關記憶體可以自動回憶並注入至代理程式的上下文。這使代理程式在工作階段間保持連續性，而無需載入整個對話歷史。

---

## 工作階段持久性

所有工作階段資料都儲存在本機：

- **工作階段元資料**, `sessions.json` 追蹤活躍工作階段、最後活動、令牌計數和設定
- **轉錄**, 個別工作階段轉錄儲存為 `.jsonl` 檔案
- **恢復**, 工作階段在 Gateway 重新啟動後仍然存在，不丟失資料

### 清理

- 在可設定時間段（預設 30 天）內未存取的工作階段有資格進行清理
- 手動工作階段管理可透過 UI 或 API 使用
- 壓縮的轉錄會封存，但仍可查看