<!-- Source: https://hermesbible.com/docs/user-guide/sessions -->

Section: Using Hermes · URL: https://hermesbible.com/docs/user-guide/sessions

Hermes Agent 會自動將每段對話儲存為 Session。Session 支援對話恢復、跨 Session 搜尋，以及完整的對話歷史管理。

Session 的運作方式

每段對話——不論來自 CLI、Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Teams 或其他任何訊息平台——都會以 Session 的形式儲存，並保留完整的訊息記錄。Session 的追蹤方式如下：

1. SQLite 資料庫（~/.hermes/state.db）——結構化的 Session 後設資料，搭配 FTS5 全文搜尋，以及完整的訊息歷史

SQLite 資料庫儲存的內容包括：

• Session ID、來源平台、使用者 ID
• Session 標題（獨特且可讀的名稱）
• 模型名稱與設定
• System prompt 快照
• 完整的訊息歷史（角色、內容、工具呼叫、工具結果）
• Token 計數（input/output）
• 時間戳記（started_at、ended_at）
• 父 Session ID（用於壓縮觸發的 Session 拆分）

哪些內容會計入 Context

Hermes 儲存 Session 歷史是為了恢復對話，但它不會每次都重新傳送所有處理過的資料。每一輪中，模型會看到選定的 system prompt、當前的對話視窗，以及 Hermes 為該輪顯式注入的內容。

媒體附件以「輪次範圍」的方式處理：

• 圖片會以原生方式附加到下一次模型呼叫，或者在活躍模型不支援原生視覺功能時，預先分析為文字描述。
• 音訊會在設定語音轉文字時轉錄為文字。
• 文字文件可以包含其擷取的文字；其他文件類型通常以儲存的本地路徑加上簡短說明來表示。
• 附件路徑和擷取/衍生的文字會出現在對話記錄中，但原始圖片、音訊或二進位檔案位元組不會反覆複製到後續的 prompt 中。

舉例來說，如果使用者傳送一張圖片並要求 Hermes 製作迷因，Hermes 可能會用視覺功能檢視該圖片一次，然後執行圖片處理腳本。後續的對話輪次不會自動在 context 中攜帶原始 JPEG。它們只會攜帶寫入對話的內容，例如使用者的請求、簡短的圖片描述、本地快取路徑或最終的助手回應。

Context 增長最常見的原因不是媒體檔案本身，而是冗長的文字：貼上的轉錄稿、完整的日誌、大量的工具輸出、冗長的差異比對、重複的狀態報告和詳細的除錯輸出。建議使用摘要、檔案路徑、精選摘錄和工具查詢，而非將大型素材直接複製到對話中。

TIP

當 Session 變得太長時使用 /compress，需要全新對話時使用 /new，而 hermes sessions prune 僅在你想刪除已結束的舊 Session 時使用。壓縮會減少活躍的 context；這不是隱私刪除。在 /new 後加上名稱（例如 /new payments-refactor）可以預先設定新 Session 的初始標題——方便之後用 /resume <name> 或在 /sessions 選擇器中找到它。

Session 來源

每個 Session 都會標記其來源平台：

CLI Session 恢復

使用 --continue 或 --resume 從 CLI 恢復先前的對話：

繼續上一個 Session

# 恢復最近的 CLI Session
hermes --continue
hermes -c

# 或使用 chat 子命令
hermes chat --continue
hermes chat -c

這會從 SQLite 資料庫中查詢最近的 cli Session，並載入其完整的對話歷史。

按名稱恢復

如果你已經為 Session 設定了標題（見下方的 Session 命名），可以按名稱恢復：

# 恢復已命名的 Session
hermes -c "my project"

# 如果有多個血緣變體（my project, my project #2, my project #3），
# 系統會自動恢復最近的一個
hermes -c "my project"   # → 恢復 "my project #3"

恢復特定 Session

# 按 ID 恢復特定 Session
hermes --resume 20250305_091523_a1b2c3d4
hermes -r 20250305_091523_a1b2c3d4

# 按標題恢復
hermes --resume "refactoring auth"

# 或使用 chat 子命令
hermes chat --resume 20250305_091523_a1b2c3d4

Session ID 會在你退出 CLI Session 時顯示，也可以透過 hermes sessions list 查找。

恢復時的對話摘要

當你恢復 Session 時，Hermes 會在輸入提示之前，以樣式化的面板顯示先前對話的精簡摘要：

<p className="docs-figure-caption">Resume 模式會在返回即時提示之前，顯示包含近期使用者和助手訊息的精簡摘要面板。</p>

摘要的呈現方式：

• 顯示使用者訊息（金色 ●）和助手回應（綠色 ◆）
• 截斷過長的訊息（使用者 300 字元，助手 200 字元 / 3 行）
• 摺疊工具呼叫為計數與工具名稱（例如 [3 tool calls: terminal, web_search]）
• 隱藏系統訊息、工具結果和內部推理過程
• 限制在最近 10 組對話，並顯示「... N earlier messages ...」指示器
• 使用暗淡樣式與活躍對話區分

要停用摘要並保持最小化的單行顯示行為，請在 ~/.hermes/config.yaml 中設定：

display:
  resume_display: minimal   # 預設：full

TIP

Session ID 的格式為 YYYYMMDD_HHMMSS_<hex>——CLI/TUI Session 使用 6 位元組的 hex 尾碼（例如 20250305_091523_a1b2c3），Gateway Session 使用 8 位元組的尾碼（例如 20250305_091523_a1b2c3d4）。你可以用 ID（完整或唯一前綴）或標題來恢復——兩者都支援 -c 和 -r。

跨平台交接

在 CLI Session 中使用 /handoff <platform> 將即時對話轉移到訊息平台的主頻道。Agent 會從 CLI 離開的地方繼續——相同的 Session ID、完整的角色感知對話記錄、工具呼叫等全部保留。

# 在 CLI Session 中
/handoff telegram

運作流程：

1. CLI 驗證 <platform> 已啟用並設定了主頻道（在目標聊天室中執行一次 /sethome 來設定）。

2. CLI 將 Session 標記為待交接，並阻塞式輪詢 Gateway。如果 Agent 正在處理中——請等待當前回應完成。

3. Gateway 監聽器取得交接控制權，並向目標適配器請求一個新的討論串：

   • Telegram——開啟新的論壇主題（如果聊天室啟用了 Bot API 9.4+ 的 Topics 模式，則為 DM 主題；否則為論壇超級群組主題）。
   • Discord——在主文字頻道下建立一個 1440 分鐘自動歸檔的討論串。
   • Slack——發布種子訊息並以其 ts 作為討論串錨點。
   • WhatsApp / Signal / Matrix / SMS——不支援原生討論串，直接回退到主頻道。

4. Gateway 將目標金鑰重新綁定到你現有的 CLI Session ID，然後建立一個合成的使用者回合，要求 Agent 確認並總結。回應會出現在新的討論串中。

5. 當 Gateway 確認成功後，CLI 會顯示 /resume 提示並正常退出：

   ↻ Handoff complete. The session is now active on telegram.
     Resume it on this CLI later with: /resume my-session-title
   

6. 從那時起，對話就在該平台上進行。在新的討論串中回覆——該頻道中任何有權限的使用者都會共享同一個 Session，因為討論串 Session 不使用 user_id 作為鍵值，所以後續的真實使用者訊息會無縫加入。

恢復回 CLI： 當你想回到桌面端時，只需執行 /resume <title>（或在 shell 中執行 hermes -r "<title>"）即可從平台離開的地方繼續。

失敗模式：

• 未設定主頻道 → CLI 拒絕並顯示 /sethome 提示。
• 平台未啟用 / Gateway 未運行 → CLI 在 60 秒後超時並顯示明確的訊息，你的 CLI Session 會保持不變。
• 討論串建立失敗（權限不足、Topics 模式關閉）→ 直接回退到主頻道並仍然完成；雖然沒有討論串隔離，但交接本身仍然有效。
• adapter.send 失敗（速率限制、暫時性 API 錯誤）→ 交接標記為失敗並附上原因；該列會被清除，方便你重試。

值得了解的限制： 對於不支援討論串且使用多使用者群組主頻道的非討論串平台，合成回合會以 DM 風格的 Session 作為鍵值。這適用於自我 DM 主頻道（典型的設定方式），但不適合真正共享的群組聊天。討論串支援涵蓋 Telegram / Discord / Slack——這是最常見的情況——所以大多數設定不會遇到這個問題。

Session 命名

為 Session 設定人類可讀的標題，方便你查找和恢復。

自動生成的標題

Hermes 會在第一次對話後自動為每個 Session 生成一個簡短的描述性標題（3–7 個字）。這是在背景執行緒中使用快速輔助模型完成的，因此不會增加延遲。當你使用 hermes sessions list 或 hermes sessions browse 瀏覽 Session 時，會看到自動生成的標題。

自動命名只會觸發一次，如果你已經手動設定過標題則會跳過。

手動設定標題

在任何聊天 Session（CLI 或 Gateway）中使用 /title 斜線命令：

/title my research project

標題會立即套用。如果 Session 尚未在資料庫中建立（例如你在發送第一條訊息之前執行 /title），它會被排入佇列，待 Session 啟動後再套用。

你也可以從命令列重新命名現有的 Session：

hermes sessions rename 20250305_091523_a1b2c3d4 "refactoring auth module"

標題規則

• 獨特——不能有兩個 Session 共享相同的標題
• 最多 100 個字元——保持列表輸出的整潔
• 自動清理——控制字元、零寬字元和 RTL 覆寫會被自動移除
• 支援一般 Unicode——表情符號、中日韓文字、帶重音的字元都可以使用

壓縮時的自動血緣追蹤

當 Session 的 context 被壓縮（透過 /compress 手動或自動執行）時，Hermes 會建立一個新的延續 Session。如果原始 Session 有標題，新 Session 會自動獲得一個帶編號的標題：

"my project" → "my project #2" → "my project #3"

當你按名稱恢復（hermes -c "my project"）時，系統會自動選擇血緣中最近的 Session。

訊息平台中的 /title

/title 命令在所有 Gateway 平台（Telegram、Discord、Slack、WhatsApp）中都可以使用：

• /title My Research——設定 Session 標題
• /title——顯示當前標題

Session 管理命令

Hermes 透過 hermes sessions 提供完整的 Session 管理命令：

列出 Session

# 列出最近的 Session（預設：最近 20 個）
hermes sessions list

# 按平台篩選
hermes sessions list --source telegram

# 顯示更多 Session
hermes sessions list --limit 50

當 Session 有標題時，輸出會顯示標題、預覽和相對時間戳記：

Title                  Preview                                  Last Active   ID
────────────────────────────────────────────────────────────────────────────────────────────────
refactoring auth       Help me refactor the auth module please   2h ago        20250305_091523_a
my project #3          Can you check the test failures?          yesterday     20250304_143022_e
—                      What's the weather in Las Vegas?          3d ago        20250303_101500_f

當沒有 Session 有標題時，會使用更簡潔的格式：

Preview                                            Last Active   Src    ID
──────────────────────────────────────────────────────────────────────────────────────
Help me refactor the auth module please             2h ago        cli    20250305_091523_a
What's the weather in Las Vegas?                    3d ago        tele   20250303_101500_f

匯出 Session

# 將所有 Session 匯出為 JSONL 檔案
hermes sessions export backup.jsonl

# 匯出特定平台的 Session
hermes sessions export telegram-history.jsonl --source telegram

# 匯出單一 Session
hermes sessions export session.jsonl --session-id 20250305_091523_a1b2c3d4

匯出的檔案每行包含一個 JSON 物件，包含完整的 Session 後設資料和所有訊息。

刪除 Session

# 刪除特定 Session（需確認）
hermes sessions delete 20250305_091523_a1b2c3d4

# 不需確認直接刪除
hermes sessions delete 20250305_091523_a1b2c3d4 --yes

重新命名 Session

# 設定或更改 Session 標題
hermes sessions rename 20250305_091523_a1b2c3d4 "debugging auth flow"

# CLI 中的多字詞標題不需要加引號
hermes sessions rename 20250305_091523_a1b2c3d4 debugging auth flow

如果標題已被另一個 Session 使用，會顯示錯誤。

清理舊 Session

# 刪除 90 天以上的已結束 Session（預設）
hermes sessions prune

# 自訂天數門檻
hermes sessions prune --older-than 30

# 只清理特定平台的 Session
hermes sessions prune --source telegram --older-than 60

# 跳過確認
hermes sessions prune --older-than 30 --yes

INFO

清理只會刪除已結束的 Session（已明確結束或自動重設的 Session）。活躍的 Session 永遠不會被清理。

Session 統計

hermes sessions stats

輸出：

Total sessions: 142
Total messages: 3847
  cli: 89 sessions
  telegram: 38 sessions
  discord: 15 sessions
Database size: 12.4 MB

如需更深入的分析——包括 token 使用量、成本估算、工具分析和活動模式——請使用 hermes insights。

Session 搜尋工具

Agent 內建了 session_search 工具，使用 SQLite 的 FTS5 引擎對所有過去的對話進行全文搜尋——並且允許 Agent 滾動瀏覽找到的任何 Session。沒有 LLM 呼叫、沒有摘要、沒有截斷。每一種呼叫形式都會從資料庫傳回實際的訊息。

三種呼叫形式

工具會根據你設定的參數來推斷你的意圖。沒有 mode 參數。

1. 探索——傳入 query：

session_search(query="auth refactor", limit=3)

執行 FTS5，按 Session 血緣去重，回傳前 N 個 Session。每個結果包含：

• session_id、title、when、source
• snippet——FTS5 高亮標記的匹配摘要
• bookend_start——Session 的前 3 則使用者+助手訊息（目標/開端）
• messages——FTS5 匹配處 ±5 則訊息，錨點訊息已標記（匹配在上下文中的位置）
• bookend_end——Session 的最後 3 則使用者+助手訊息（結論/決策）
• match_message_id、messages_before、messages_after

Bookend 加上視窗可以在不花費整個對話記錄的情況下，重建目標 → 匹配 → 結論。在真實的 Session 資料庫上，典型的執行時間約為 15–50 毫秒。

2. 滾動——傳入 session_id + around_message_id：

session_search(session_id="20260510_174648_805cc2", around_message_id=590803, window=10)

回傳以錨點為中心的 ±window 則訊息視窗。沒有 FTS5、沒有 bookend——只有訊息切片。當你在探索呼叫後需要比 ±5 預設視窗更多的上下文時使用。

• 要向前滾動：將 messages[-1].id 傳回作為 around_message_id
• 要向後滾動：將 messages[0].id 傳回作為 around_message_id
• 邊界訊息會同時出現在兩個視窗中，作為方向標記
• 當 messages_before 或 messages_after 小於 window 時，你已經到達 Session 的開頭或結尾

典型的執行時間：每次滾動呼叫 1–2 毫秒。

3. 瀏覽——不傳參數：

session_search()

按時間順序回傳最近的 Session（標題、預覽、時間戳記）。當使用者詢問「我之前在做什麼」而沒有指定主題時很有用。

FTS5 查詢語法

關鍵字模式支援標準的 FTS5 查詢語法：

• 簡單關鍵字：docker deployment（FTS5 預設使用 AND）
• 片語："exact phrase"
• 布林運算：docker OR kubernetes、python NOT java
• 前綴匹配：deploy*

可選參數

• sort——newest 或 oldest，在 FTS5 排序之上。省略時僅按相關性排序（預設；適合探索式回憶）。newest 適合「我們上次 X 做到哪裡了」的問題，oldest 適合「X 是怎麼開始的」的問題。
• role_filter——以逗號分隔的角色篩選。探索模式預設為 user,assistant（工具輸出通常是雜訊）。傳入 user,assistant,tool 以包含工具輸出（除錯工具行為），或 tool 以僅搜尋工具輸出。

使用時機

Agent 會被提示自動使用 Session 搜尋：

「當使用者提及先前對話中的內容，或你認為存在相關的先前上下文時，使用 session_search 來回憶，再要求他們重複。」

典型的觸發情境：「我們之前做過這個」、「記得上次嗎」、「上一次」、「如同我之前提到的」，或任何對專案/人物/概念的引用——只要它不在當前的對話視窗中。

各平台的 Session 追蹤

Gateway Session

在訊息平台上，Session 使用從訊息來源構建的決定性 Session 金鑰：

當 Hermes 無法取得共享聊天的參與者識別碼時，會回退為該房間使用一個共享 Session。

共享 vs. 隔離的群組 Session

預設情況下，Hermes 在 config.yaml 中使用 group_sessions_per_user: true。這意味著：

• Alice 和 Bob 可以在同一個 Discord 頻道中與 Hermes 對話，而無需共享對話記錄歷史
• 一個使用者的長篇工具密集任務不會污染另一個使用者的 context 視窗
• 中斷處理也按使用者分隔，因為執行中 Agent 的金鑰會與隔離的 Session 金鑰匹配

如果你想要一個共享的「房間大腦」，請設定：

group_sessions_per_user: false

這會將群組/頻道恢復為每個房間一個共享 Session，雖然保留了共享的對話上下文，但同時也會共享 token 成本、中斷狀態和 context 增長。

Session 重設策略

Gateway Session 會根據可設定的策略自動重設：

• idle——在 N 分鐘不活動後重設
• daily——每天在特定時間重設
• both——以先到者為準（idle 或 daily）
• none——永遠不自動重設

在 Session 被自動重設之前，Agent 會有一輪的時間來儲存對話中的重要記憶或技能。

具有活躍背景處理程序的 Session 永遠不會被自動重設，無論策略設定為何。

儲存位置

SQLite 資料庫使用 WAL 模式，支援並行讀取者和單一寫入者，非常適合 Gateway 的多平台架構。

NOTE — 舊版 JSONL 對話記錄

在 state.db 成為正式儲存庫之前建立的 Session，可能在 ~/.hermes/sessions/ 中殘留 *.jsonl 檔案。Hermes 不再寫入或讀取這些檔案。在確認對應的 Session 存在於 state.db 後，可以安全刪除。

資料庫結構

state.db 中的主要資料表：

• sessions——Session 後設資料（id、source、user_id、model、title、時間戳記、token 計數）。標題有唯一索引（允許 NULL 標題，只有非 NULL 值必須唯一）。
• messages——完整的訊息歷史（role、content、tool_calls、tool_name、token_count）
• messages_fts——FTS5 虛擬資料表，用於訊息內容的全文搜尋

Session 過期與清理

自動清理

• Gateway Session 根據設定的重設策略自動重設
• 在重設之前，Agent 會儲存即將過期的 Session 中的記憶和技能
• 選擇性自動清理：當 sessions.auto_prune 為 true 時，超過 sessions.retention_days（預設 90 天）的已結束 Session 會在 CLI/Gateway 啟動時被清理
• 在實際移除資料列的清理之後，state.db 會執行 VACUUM 以回收磁碟空間（SQLite 在純 DELETE 操作後不會縮減檔案大小）
• 清理最多每 sessions.min_interval_hours（預設 24 小時）執行一次；最後執行的時間戳記記錄在 state.db 內部，因此在同一個 HERMES_HOME 中的所有 Hermes 流程都會共享

預設為關閉——Session 歷史對 session_search 的回憶功能很有價值，靜默刪除可能會讓使用者感到意外。在 ~/.hermes/config.yaml 中啟用：

sessions:
  auto_prune: true          # 選擇啟用——預設為 false
  retention_days: 90        # 保留已結束的 Session 天數
  vacuum_after_prune: true  # 在清理掃描後回收磁碟空間
  min_interval_hours: 24    # 不要更頻繁地重新執行掃描

活躍的 Session 永遠不會被自動清理，無論存在多久。

手動清理

# 清理 90 天以上的 Session
hermes sessions prune

# 刪除特定 Session
hermes sessions delete <session_id>

# 清理前先匯出（備份）
hermes sessions export backup.jsonl
hermes sessions prune --older-than 30 --yes

TIP

資料庫的增長速度很慢（典型值：數百個 Session 約 10-15 MB），而 Session 歷史驅動了跨過去對話的 session_search 回憶功能，因此自動清理預設關閉。如果你運行大量的 Gateway/Cron 工作負載，state.db 明顯影響了效能（已觀察到的失敗模式：約 1000 個 Session 的 384 MB state.db 導致 FTS5 插入和 /resume 列表變慢），請啟用它。使用 hermes sessions prune 進行一次性清理，無需開啟自動掃描。

---

---

Profiles：運行多個 Agent