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

Section: Core Features · URL: https://hermesbible.com/docs/user-guide/features/honcho

Honcho 是一個 AI 原生的記憶後端，在 Hermes 內建記憶系統之上加入了辯證推理與深度使用者建模功能。相較於簡單的鍵值儲存，Honcho 透過對話結束後的推理分析，維護一個持續更新的使用者模型——包含偏好、溝通風格、目標與行為模式。

INFO — Honcho 是記憶提供者外掛

Honcho 整合於 Memory Providers 系統中。以下所有功能皆可透過統一的記憶提供者介面使用。

Honcho 的功能新增

辯證推理：每次對話輪次結束後（由 dialecticCadence 控制），Honcho 會分析對話內容並推導出關於使用者偏好、習慣與目標的洞見。這些洞見隨時間累積，讓 Agent 對使用者的理解不斷深化，超越使用者明確表達的內容。辯證支援多輪深度（1–3 輪），並自動選擇 Cold/Warm 提示詞——Cold 問詢聚焦於一般性的使用者事實，Warm 則優先使用 Session 範圍的上下文。

Session 範圍的上下文：基礎上下文現在包含 Session 摘要、使用者表徵與 Peer 名片。這讓 Agent 能感知當前 Session 中已經討論過的內容，減少重複並實現對話連續性。

多 Agent 檔案：當多個 Hermes 實例與同一位使用者對話時（例如程式碼助理與個人助理），Honcho 會維護獨立的「Peer」檔案。每個 Peer 僅能看到自己的觀察與結論，防止上下文交叉污染。

設定

hermes memory setup    # 從提供者清單中選擇 "honcho"

或手動設定：

# ~/.hermes/config.yaml
memory:
  provider: honcho

echo 'HONCHO_API_KEY=***' >> ~/.hermes/.env

至 honcho.dev 取得 API Key。

架構

雙層上下文注入

每次輪次（在 hybrid 或 context 模式下），Honcho 會組裝兩層上下文並注入系統提示詞：

1. 基礎上下文 — Session 摘要、使用者表徵、使用者 Peer 名片、AI 自我表徵與 AI 識別名片。依 contextCadence 刷新。這是「這個使用者是誰」的層級。
2. 辯證補充 — 由 LLM 綜合推導的、關於使用者當前狀態與需求的推理結果。依 dialecticCadence 刷新。這是「此刻什麼最重要」的層級。

兩層上下文會被串接並截斷至 contextTokens 預算（若有設定）。

Cold/Warm 提示詞選擇

辯證會自動在兩種提示詞策略間切換：

• Cold Start（尚無基礎上下文）：一般性查詢——「這個人是誰？他們的偏好、目標與工作風格是什麼？」
• Warm Session（已有基礎上下文）：Session 範圍查詢——「根據本次 Session 目前已討論的內容，關於這位使用者的哪些上下文最為相關？」

此行為會根據基礎上下文是否已填充而自動觸發。

三個正交的設定旋鈕

成本與深度由三個獨立旋鈕控制：

這三者是正交的——你可以設定頻繁的上下文刷新搭配低頻的辯證，或是低頻但深度多輪的辯證。例如：contextCadence: 1, dialecticCadence: 5, dialecticDepth: 2 表示每輪刷新基礎上下文、每 5 輪執行一次辯證、每次辯證執行 2 輪。

辯證深度（多輪）

當 dialecticDepth > 1 時，每次辯證呼叫會執行多輪 .chat()：

• 第 0 輪：Cold 或 Warm 提示詞（如上所述）
• 第 1 輪：自我審計——識別初步評估中的不足，並從近期 Session 中綜合證據
• 第 2 輪：調和——檢查先前輪次之間的矛盾，並產生最終綜合結果

每輪使用比例推理等級（較輕的前導輪、主要輪使用基礎等級）。可透過 dialecticDepthLevels 覆蓋每輪等級——例如深度 3 執行時設定為 ["minimal", "medium", "high"]。

若前一輪已產生強烈訊號（較長且有結構的輸出），後續輪次會提前結束，因此深度 3 並不一定代表 3 次 LLM 呼叫。

Session 啟動預熱

Session 初始化時，Honcho 會在背景以完整設定的 dialecticDepth 執行一次辯證呼叫，並將結果直接傳遞給第 1 輪的上下文組裝。Cold Peer 的單輪預熱通常產出較薄的結果——多輪深度會在使用者開口前完成審計/調和循環。若預熱尚未完成，第 1 輪會退回到有時間限制的同步呼叫。

查詢自適應推理等級

自動注入的辯證會根據查詢長度調整 dialecticReasoningLevel：≥120 字元 +1 級、≥400 字元 +2 級，上限為 reasoningLevelCap（預設 "high"）。設定 reasoningHeuristic: false 可停用此機制，將所有自動呼叫固定為 dialecticReasoningLevel。可用等級：minimal、low、medium、high、max。

設定選項

Honcho 的設定位於 ~/.honcho/config.json（全域）或 $HERMES_HOME/honcho.json（Profile 本地）。設定精靈會自動處理這些配置。

自架 Honcho 的認證設定

當 Hermes 連線至自架 Honcho 伺服器時，hermes honcho setup（與 hermes memory setup）會在基礎 URL 後要求輸入本地 JWT / Bearer Token。貼上使用伺服器 AUTH_JWT_SECRET（Honcho compose 環境變數）簽署的 JWT 以啟用認證存取；若伺服器以 AUTH_USE_AUTH=false 運行則留空。本地 Token 儲存在 Host 區塊中（honcho.json 的 hosts.<host>.apiKey），與雲端 apiKey 分開儲存，因此之後切換 Cloud or local? 提示回 cloud 時不會遺失任何憑證。

完整設定參考

Session 策略控制 Honcho Session 與你的工作如何對應：

• per-session — 每次 hermes 執行都獲得全新 Session。乾淨的開始，透過工具記憶。建議新使用者使用。
• per-directory — 每個工作目錄一個 Honcho Session。上下文跨執行累積。
• per-repo — 每個 Git 儲存庫一個 Session。
• global — 跨所有目錄共用單一 Session。

回憶模式控制記憶如何流入對話：

• hybrid — 上下文自動注入系統提示詞，同時提供工具（模型自行決定何時查詢）。
• context — 僅自動注入，隱藏工具。
• tools — 僅提供工具，無自動注入。Agent 必須明確呼叫 honcho_reasoning、honcho_search 等。

各回憶模式的設定：

在 tools 模式下，模型完全掌控——它在想要的時候呼叫 honcho_reasoning，並自行選擇 reasoning_level。節奏與預算設定僅適用於有自動注入的模式（hybrid 與 context）。

Gateway 證別映射

這些設定僅在你運行 Hermes gateway 時有意義——這是使用者以平台原生執行時 ID（Telegram UID、Discord Snowflake、Slack User）到達的單一入口。CLI、TUI 與桌面 Session 沒有執行時 ID，始終解析為 peerName，因此在非 Gateway 環境下這些鍵值無作用。

設定精靈會偵測是否連接了 Gateway 平台，若無則跳過此步驟。執行時會詢問一個問題——誰與此 Gateway 對話？——並衍生對應鍵值：

在提示處選擇 [e] 可直接設定這三個鍵值。

解析器會依序嘗試鍵值，首次匹配生效：pinUserPeer → userPeerAliases[id] → runtimePeerPrefix + id → 原始執行時 ID → peerName → Session 鍵回退。

WARNING — 取消 Pin 會孤立共用記憶

將 pinUserPeer 從 true 切換為 false 不會遷移資料——在 peerName 下累積的記憶會留在原處，而平台使用者會解析為全新的空 Peer。若要保留你自己的連續性，請選擇共用池路徑，讓你的執行時 ID 別名回 peerName。精靈在偵測到此轉換時會自動提供此引導。

NOTE — 已棄用的鍵值

pinPeerName 是 pinUserPeer 的舊版別名——仍會讀取以保持向後相容（兩者皆設定時 pinUserPeer 優先），但不會寫入。重新執行設定會將其遷移至正規鍵值。

觀察（Directional vs. Unified）

Honcho 將對話建模為 Peer 之間交換訊息。每個 Peer 有兩個觀察開關，與 Honcho 的 SessionPeerConfig 一一對應：

兩個 Peer × 兩個開關 = 四個標誌。observationMode 是一個簡寫預設：

使用明確的 observation 區塊覆蓋預設值以進行細粒度控制：

"observation": {
  "user": { "observeMe": true,  "observeOthers": true },
  "ai":   { "observeMe": true,  "observeOthers": false }
}

常見模式：

透過 Honcho 儀表板 設定的伺服器端開關會覆蓋本地預設值——Hermes 在 Session 初始化時會將其同步回來。

工具

當 Honcho 作為記憶提供者啟用時，會有五個工具可用：

CLI 指令

hermes honcho 子指令僅在 Honcho 為啟用的記憶提供者時才會註冊（config.yaml 中的 memory.provider: honcho）。全新安裝時，請直接使用 hermes memory setup honcho（或執行 hermes memory setup 並從清單中選擇）；hermes honcho 子指令會在下次呼叫時出現。

hermes memory setup honcho    # 直接設定 Honcho（在啟用前即可使用）
hermes honcho status          # 連線狀態、設定與關鍵設定
hermes honcho setup           # 重新導向至 `hermes memory setup`（啟用後的別名）
hermes honcho strategy        # 顯示或設定 Session 策略（per-session/per-directory/per-repo/global）
hermes honcho peer            # 顯示或更新 Peer 名稱與辯證推理等級
hermes honcho mode            # 顯示或設定回憶模式（hybrid/context/tools）
hermes honcho tokens          # 顯示或設定上下文與辯證的 Token 預算
hermes honcho identity        # 設定或顯示 AI Peer 的 Honcho 身份
hermes honcho sync            # 將 Honcho 設定同步至所有現有 Profile
hermes honcho peers           # 顯示所有 Profile 的 Peer 身份
hermes honcho sessions        # 列出已知的 Honcho Session 映射
hermes honcho map             # 將目前目錄映射至 Honcho Session 名稱
hermes honcho enable          # 為啟用的 Profile 啟用 Honcho
hermes honcho disable         # 為啟用的 Profile 停用 Honcho
hermes honcho migrate         # 從 openclaw-honcho 逐步遷移指南

從 hermes honcho 遷移

若你之前使用過獨立的 hermes honcho setup：

1. 你現有的設定（honcho.json 或 ~/.honcho/config.json）會被保留
2. 你伺服器端的資料（記憶、結論、使用者檔案）完好無損
3. 在 config.yaml 中設定 memory.provider: honcho 以重新啟用

無需重新登入或重新設定。執行 hermes memory setup 並選擇 "honcho"——精靈會偵測到你現有的設定。

完整文件

請參閱 Memory Providers — Honcho 取得完整參考。

---

---

Provider Routing