Skip to main content
這個單元解決什麼問題Hermes-Agent 是 Nous Research 開源的 AI 代理框架,以「可自我成長的代理」為定位。它不綁定任何推論後端,也不強制使用 Hermes 模型家族,用一組 Markdown 檔定義代理的人格、記憶與指令,並透過三層 system prompt 組裝把這些檔案有紀律地注入。本單元解剖它的由來、核心技術、系統結構與 md 檔設計,讓你看懂「極簡外殼」背後的設計選擇與取捨代價。

學習目標

  • 能說清 Hermes-Agent 的由來與定位:它是代理框架,而非推論模型,由 Nous Research 維護,MIT 授權
  • 能描述其核心架構:AIAgent 主迴圈、三層 system prompt 組裝、多後端工具分派、SQLite 狀態儲存
  • 能說出 SOUL.mdMEMORY.mdUSER.mdAGENTS.md 各自在 prompt 組裝中的層次與職責
  • 能指出極簡 md 檔設計的取捨代價:易於理解與外部化,卻在高並發或多代理場景下缺乏結構化版本管控
  • 能用一句生活比喻概括這個系統的本質
  • 能與 05-1 OpenClaw 的多 md 檔設計做正面對位

1. 由來與定位

Hermes-Agent 由 Nous Research 開源維護,定位為「The agent that grows with you」(官方倉庫 [1] 截至 2026-05)。它是 Nous Research 獨立開源的全新框架,不衍生自 OpenClaw;提供的 hermes claw migrate 指令是給既有 OpenClaw 使用者遷移設定、記憶與 skill 的轉換工具,兩者為不同 org 的獨立專案(官方文件 [2] 截至 2026-05)。 幾個常見誤會要先釐清:
  • 它不是 Hermes 模型家族。 Hermes-3-405B、Hermes-3-70B 等是 Nous Research 訓練的開源 LLM,與 Hermes-Agent 框架是兩個獨立產品。Hermes-Agent 不綁定任何推論後端,支援 OpenRouter、Anthropic、OpenAI、Google、vLLM、llama.cpp 等任何 OpenAI-compatible API;Hermes 模型只是 Nous Portal 的預設首選入口
  • 它不是輕量 SDK。 雖然 md 檔介面簡潔,但它定位為「可在 $5 VPS 或 GPU 叢集執行、透過 Telegram/Discord 等多平台互動」的全功能 agentic harness,內建子代理委派、SQLite 狀態儲存、跨 session 記憶
  • 授權為 MIT(截至 2026-05 倉庫 LICENSE 檔),可商用、可改、可閉源重發
命名澄清「Hermes」在 Nous Research 的命名體系裡同時指三件事:Hermes 模型家族(LLM)、Hermes-Agent(代理框架)、Nous Portal(推論訂閱服務)。本單元談的是第二個,必要時會用全名「Hermes-Agent」以免混淆。

2. 核心技術

Hermes-Agent 的技術堆疊可拆成五個軸: 相對於 OpenClaw 的「多 md 檔 + 多管道路由」設計,Hermes-Agent 的極簡性表現在三個地方:
  1. prompt 組裝是三層而非散落各處。 agent/prompt_builder.py 負責把 stable / context / volatile 三層拼成 system prompt,每層有明確的 slot 編號與注入策略
  2. 推論後端完全可插拔。 任何能接受 OpenAI 相容 API 的服務都能接,這是給「不依賴單一供應商」的設計選擇
  3. 狀態是 SQLite 而非純檔案。 OpenClaw 的記憶主要靠 MEMORY.md + memory/YYYY-MM-DD.md;Hermes-Agent 多了一層 SQLite 與 FTS5,支援跨 session 全文搜尋與 LLM 摘要回溯
三層 prompt 組裝的設計理由把 prompt 拆層而非寫成一大段,是因為不同層的「變動頻率」與「快取命中需求」不同:stable 層(人格)幾乎不變,prefix cache 命中率最高;context 層(專案指令)隨 CWD 變動;volatile 層(使用者與記憶)每 session 重抓。分層讓你只重抓有變動的部分,省推論成本。Hermes-Agent 進一步把 volatile 層「凍結快照」,session 中的記憶操作只寫磁碟,下次 session 才生效(Prompt Assembly 文件 [3] 截至 2026-05)。這個設計的權衡見第 4 節

2.5 為什麼能「自我成長」:代理自己策展記憶,下個 session 回注

「grows with you」的機制不是背景自動摘要,而是 agent 主動策展自己的記憶(Memory 文件 [4] 截至 2026-06)。拆開看:
  1. 兩份有上限的記憶檔MEMORY.md(上限 2,200 字元,約 800 token)記「環境事實、慣例、學到的東西」,USER.md(上限 1,375 字元,約 500 token)記「你的偏好、溝通風格、期待」,都放在 ~/.hermes/memories/
  2. 由 agent 透過 memory 工具自己增刪改:不是有個背景程序自動蒸餾,而是 agent 在互動中判斷「這條值得記」,主動 add / replace / remove 寫進上面兩份檔。字元上限是關鍵設計:它強迫 agent 篩選與合併(consolidation),而非無限堆積,所以成長是被策展(curated)的濃縮,不是流水帳。
  3. 下個 session 回注:session 起始時,這兩份檔被凍結成快照、注入 volatile 層(見上面三層組裝)。agent 於是帶著「上次記下的你與這份工作」開場,行為更貼合。
另有一層 SQLite + FTS5 完整歷史~/.hermes/state.db),存所有 CLI 與訊息 session,可用 session_search 工具撈回過去的原始訊息。注意它和上面的「主動記憶」是兩套獨立系統:SQLite 是可搜尋的詳盡日誌,MEMORY.mdUSER.md 是 agent 精選的長期筆記;前者不會自動蒸餾成後者。 關鍵推論:成長發生在 session 之間,不在 session 之內,這正是 volatile 凍結的直接後果。一個 session 就是「讀上次的記憶 → 做事 → 把值得記的寫進磁碟」,下次再讀。這也說明了為什麼 SOUL.md(人格)固定不變、而 MEMORY.mdUSER.md(學習)會長:人格是你預先定義的常數,成長只發生在記憶層。 記憶只是成長的一臂。另一臂是 skill 自我演化:agent 能自己寫 skill,curator.py 在背景維護這些「agent 自建 skill」的生命週期,追蹤使用頻率,把久未用的 skill 從 active 轉 stale(預設 30 天)、再轉 archived(90 天封存),並週期性派一個輔助模型 review,提議整併重疊或修補漂移。它只碰 agent 自建的 skill,不動倉庫內建或 hub 安裝的 skill,且永不自動刪除,最壞只到可復原的封存(Curator 文件 [5] 截至 2026-06)。所以「成長」有兩條線:記憶層(你與工作的事實)與技能層(agent 自己累積、自己汰換的能力)。
與 OpenClaw 的成長機制差異兩者都靠 agent 主動寫記憶檔來成長;Hermes-Agent 的記憶檔有字元上限、強制 consolidation,另有 SQLite + FTS5 的完整歷史可搜尋回溯。差別在「精選的嚴格度」與「可回溯的詳盡度」,不在自動化程度。

3. 系統結構

Hermes-Agent 的入口點分四個,各自服務不同情境:
hermes-agent/
cli.py · CLI 入口(hermes 指令)
run_agent.py · AIAgent 主迴圈
hermes_state.py · SQLite 狀態資料庫
model_tools.py · 工具探索與分派
toolsets.py · 28 個 toolset 分組
gateway/
run.py · Gateway 入口(多管道長連)
agent/
prompt_builder.py · 三層 system prompt 組裝
system_prompt.py · 各層 slot 定義
memory_manager.py · 記憶管理
curator.py · agent 自建 skill 的背景 lifecycle 維護
skills/
SKILL.md · 技能格式定義
adapters/
· 第三方整合(Telegram、Discord、ACP 等)
核心元件與職責: 子代理委派透過 delegate_task 工具觸發:預設 3 個並發子代理,每個子代理獲得獨立 context 與 terminal session(官方文件 [2] 截至 2026-05)。terminal 後端有六種:local、Docker、SSH、Singularity、Modal、Daytona,提供從「本機直接執行」到「雲端隔離環境」的彈性。
一次典型的 agent turn 內部流程
1

使用者在 Telegram 傳訊息

Telegram adapter 收到訊息,丟進 Gateway。
2

Gateway 找對應 session

把訊息丟給 AIAgent
3

AIAgent 呼叫 prompt_builder 組裝三層 prompt

SOUL.md(stable)+ AGENTS.md(context,CWD 往上走到 git root)+ MEMORY.md + USER.md(volatile,從 SQLite 凍結快照)。
4

拼好後送進模型

模型回應可能含 tool_call;model_tools 依模型與工具設定分派,可能呼叫 delegate_task 起子代理。
5

子代理回傳結果

主代理整理後回 Telegram;狀態寫回 SQLite。
這條鏈裡的每個環節都是可被替換或關閉的,這是「極簡外殼」的真意:核心骨架不複雜,但每個接點都暴露成可設定。

使用者側設定目錄:~/.hermes/

上面的 hermes-agent/ 是原始碼結構(開發者視角)。日常你實際編輯的是另一棵樹:執行期的設定目錄 HERMES_HOME,預設 ~/.hermes/(Linux、macOS、WSL2;Windows native 為 %LOCALAPPDATA%\hermes\)。它支援 profiles,每個隔離實例有自己的 HERMES_HOME(Configuration 文件 [6] 截至 2026-06)。
~/.hermes/
config.yaml · 主設定(非機密):模型、terminal、記憶上限、壓縮、安全
.env · 機密:API key、各平台 token、password
auth.json · OAuth 憑證
SOUL.md · 代理人格(system prompt stable slot #1)
memories/
MEMORY.md · 跨 session 記憶,上限 2,200 字元
USER.md · 使用者偏好,上限 1,375 字元
skills/
· 代理自建 skill(curator 維護生命週期)
cron/
· 排程任務
sessions/
· Gateway 對話狀態
logs/
agent.log · errors.log · gateway.log
state.db · SQLite + FTS5 完整歷史
設定的核心切分是兩層:config.yaml(非機密、可進版控)與 .env(機密、永不進版控)。config.yaml${VAR_NAME} 語法引用 .env 的環境變數,API key 不寫進 config.yaml。倉庫根目錄附一份 cli-config.yaml.example(含完整行內說明)當起手範本。精選關鍵欄位(截至 2026-06):
.envstate.db 永不進公開版控config.yaml 設計上就是要進版控的非機密設定;但 .env(API key、平台 token)與 state.db(含所有原始對話內容)一旦進公開 repo 就是憑證外洩與隱私事故。把 ~/.hermes/.env~/.hermes/state.db~/.hermes/auth.json 加進 .gitignore,只 commit config.yamlcli-config.yaml.example

4. 自訂 md 檔:SOUL.md 等的角色

Hermes-Agent 的 md 檔清單比 OpenClaw 精簡,但每個都對應 prompt 組裝的特定 slot。以下清單與職責來自 agent/system_prompt.py 的三層組裝順序(Prompt Assembly 文件 [3] 截至 2026-05): 幾個關鍵設計點:
  • SOUL.md 只從 HERMES_HOME 載入,不隨 CWD 改變。這個設計確保人格跨專案穩定:你在 A 專案寫的人格,不會被 B 專案的 AGENTS.md 覆寫
  • 預設 SOUL.md 自動植入:首次啟動時由 hermes_cli/default_soul.py 寫入,內容為簡短的身份宣告。改之前先讀這份預設,你就知道「如果我把這整段刪掉,會發生什麼」
  • volatile 層凍結快照:session 起始時 MEMORY.mdUSER.md 的內容被凍結成 snapshot 注入 system prompt,session 中的記憶操作僅寫入磁碟,下次 session 才生效。這個設計保護 LLM prefix cache 穩定性(同一個 session 內的 prompt 前綴不變),代價是「session 內的自我改進要等下一輪才看得到」
  • 子代理委派時的例外:呼叫 delegate_task 啟動子代理時(skip_context_files),SOUL.md 不載入,改用硬編碼的 DEFAULT_AGENT_IDENTITY。子代理不繼承主人格,這是給「不同任務用不同人格」的彈性
volatile 凍結的代價你在 session 中間對 MEMORY.md 的修改,這個 session 內不會被這個 session 自己讀到。如果你預期「我說一句、它記一句、下一句就用到」,會失望。把它想成「每天晚上寫日記、明早起床才看得到」。
05-1 OpenClaw 的對位:

5. 一句生活比喻

Hermes-Agent 像一個有內建「自我契約」與「晨間簡報」機制的實習生:他出門上班前會把三份文件從家裡($HERMES_HOME)抓出來讀,分別是「我是誰」(SOUL.md)、「昨天我學到什麼」(MEMORY.md)、「老闆喜歡什麼」(USER.md),進到辦公室再讀一份專案手冊(AGENTS.md,從最近的專案資料夾往上找)。這三份家裡的文件今天之內不會再改(凍結快照),他寫筆記也只能寫進抽屜、明早才讀得到;而他偶爾會把工作分派給三個彼此獨立的助理(子代理),這些助理不繼承他的內建契約,只執行你指派的特定任務。人不是固定的,是每天早上重組一次;而重組的來源(家裡那三份文件)是你替他寫好的、可版控的。

6. 極簡設計的取捨

6.1 你得到的好處

  • 人可讀、可版控、可跨平台移植。 所有「代理是誰、要記什麼、要怎麼做」都用 md 檔或可 diff 的 SQLite 表達,沒有閉源的二進位設定
  • prefix cache 友好。 volatile 凍結快照讓同一 session 內的 prompt 前綴穩定,模型成本下降
  • 不綁供應商。 任何 OpenAI-compatible API 都能接,這在 2026 年的供應商快速變動環境裡是實質的戰略選項
  • Skill 漸進揭露。 Level 0 只載入 skills index(約 3k tokens),Level 1 才載入完整 skill 內容,是給「裝很多 skill 但不是每個 session 都用」的成本控制

6.2 你付出的代價

  • 純文字格式缺乏結構化 schema 驗證。 md 檔沒有型別檢查,personality drift(人格漂移)難以量化:你怎麼知道 SOUL.md 改了三輪後沒有把語氣推離原本的設計?
  • volatile 凍結使 session 中記憶延遲生效。 與即時感知不符,UX 上有摩擦
  • 多代理場景的人格差異化:子代理用硬編碼的 DEFAULT_AGENT_IDENTITY,但如何為不同子代理注入不同人格?官方文件未說明是否提供子代理的 SOUL.md override 機制。
  • SQLite 是單機儲存。 如果你想在多台機器之間同步 session 歷史,要自己接 sync layer(filesystem watcher、Syncthing、或自架 S3 相容層)
什麼時候選 Hermes-Agent 而不是 OpenClaw
  • 你的工作流是「一個 daemon 服務多個管道的同一個我」:選 Hermes-Agent,極簡設計剛好
  • 你的工作流是「同一個 daemon 跑多個獨立人格的 agent 各自服務不同場景」:選 OpenClaw,多管道路由 + 隔離 session 設計更貼合
  • 你的工作流是「個人本地實驗、不需要企業硬化」:兩者皆可,看你偏好 Python 或 TypeScript
  • 你的工作流是「要上 production / 企業環境」:兩個都不夠,要疊 05-3 NemoClaw 的硬化外殼

動手做

1

改 SOUL.md 驗證 identity slot

~/.hermes/SOUL.md 換成自訂人格(例如「語氣直白、結論先行、拒絕行銷腔、不用 emoji」),重啟 hermes 觀察新 session 開頭 agent 的語氣變化。記得:session 內改 SOUL.md 對當前 session 無效,必須重啟。
2

觀察 volatile 凍結行為

hermes memory 指令觀察 MEMORY.md 的增刪記錄;然後在 session 內要求 agent 記下某件事,觀察它寫入磁碟的時機(session 結束時)與下次 session 開始讀回來的時機(session 啟動時)。
3

讀 prompt_builder.py 的原始碼

直接 clone 倉庫讀 agent/prompt_builder.pyagent/system_prompt.py,體會「三層組裝」在程式碼裡的形狀。這比讀文件更能掌握實作。

常見誤區

  • 誤以為 Hermes-Agent 只能搭配 Hermes 系列模型:實際上任何 OpenAI-compatible API 皆可(OpenRouter、Anthropic、OpenAI、Google、vLLM、llama.cpp 等)
  • 誤以為修改 SOUL.md 當前 session 立即生效:實際上需重啟代理,因為 volatile 層在 session 起始時凍結快照
  • 誤以為 AGENTS.mdSOUL.md 功能相同:兩者分屬不同 prompt 層次(context vs stable)與生效範圍(CWD 往上找 vs HERMES_HOME 唯一)
  • 把 SQLite 狀態當成可丟棄的快取:SQLite 含 session search 與 LLM 摘要回溯的依據,誤刪會讓「上次對話為什麼這樣做」變成不可考;備份策略應包含 SQLite 檔
  • 子代理期待主人格delegate_task 啟動的子代理不繼承 SOUL.md,直接使用 DEFAULT_AGENT_IDENTITY。如果你需要子代理有特定人格,要自己在呼叫時傳入 context 或事先建立子代理專屬的 SOUL.md;官方文件未明確說明是否有原生 override 支援。

自我檢核

通過本單元的標準
  1. 能畫出 stable → context → volatile 三層 system prompt 的各個 slot 及其對應檔案嗎?
  2. 能解釋為什麼 volatile 層採用凍結快照而非即時注入,以及這對記憶一致性與推論成本各有什麼影響?
  3. 能說出 SOUL.md 為何固定從 $HERMES_HOME 載入、不隨 CWD 改變的設計理由嗎?
  4. 能指出 Hermes-Agent 相對於 05-1 OpenClaw 在「人格檔、記憶儲存、心跳支援」三個維度上的差異嗎?
  5. 你的工作流是「一個我服務多管道」還是「多個我各服務不同場景」?這個選擇會導向哪個框架?

來源與延伸閱讀

事實主張依官方文件,快變動項標註截至 2026-05。