持久記憶

Hermes Agent 擁有有界且經過篩選的持久記憶，可在不同會話間保持記憶。這使得它能夠記住您的偏好、項目、環境以及所學知識。

工作原理

Agent 的記憶由兩個文件組成：

文件	用途	字符限制
MEMORY.md	Agent 的個人筆記 —— 環境事實、約定、學習到的內容	2,200 字符（約 800 個 token）
USER.md	用戶檔案 —— 您的偏好、溝通風格、期望	1,375 字符（約 500 個 token）

這兩個文件均存儲在 ~/.hermes/memories/ 目錄下，並在會話開始時作為凍結快照注入系統提示中。Agent 通過 memory 工具自行管理其記憶 —— 可添加、替換或刪除條目。

信息

字符限制有助於保持記憶聚焦。當記憶已滿時，Agent 會合並或替換條目以騰出空間給新信息。

記憶在系統提示中的呈現方式

在每個會話開始時，記憶條目會從磁盤加載，並以凍結塊的形式渲染到系統提示中：

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed
§
User prefers concise responses, dislikes verbose explanations

格式包含：

• 標頭顯示存儲類型（MEMORY 或 USER PROFILE）
• 使用率百分比和字符計數，使 Agent 瞭解容量情況
• 條目之間使用 §（段落符號）分隔符
• 條目可為多行

凍結快照模式： 系統提示注入僅在會話開始時捕獲一次，會話期間不會更改。這是有意為之的設計 —— 以保留 LLM 的前綴緩存以提升性能。當 Agent 在會話期間添加或刪除記憶條目時，更改會立即持久化到磁盤，但不會在當前會話的系統提示中體現，直到下一次會話開始。工具響應始終顯示實時狀態。

記憶工具操作

Agent 使用 memory 工具執行以下操作：

• add —— 添加新記憶條目
• replace —— 用更新內容替換現有條目（通過 old_text 進行子字符串匹配）
• remove —— 刪除不再相關的條目（通過 old_text 進行子字符串匹配）

沒有 read 操作 —— 記憶內容會在會話開始時自動注入系統提示。Agent 將其記憶視為對話上下文的一部分。

子字符串匹配

replace 和 remove 操作使用短且唯一的子字符串匹配 —— 無需完整條目文本。old_text 參數只需是能唯一標識一個條目的子字符串即可：

# 例如：現有條目裡包含 “dark mode”
memory(action="replace", target="memory",
       old_text="dark mode",
       content="User prefers light mode in VS Code, dark mode in terminal")

如果子字符串匹配多個條目，將返回錯誤並要求提供更具體的匹配。

兩個目標詳解

memory —— Agent 的個人筆記

用於記錄 Agent 需要記住的環境、工作流和經驗教訓信息：

• 環境事實（操作系統、工具、項目結構）
• 項目約定和配置
• 發現的工具缺陷及繞行方案
• 已完成任務的日記條目
• 有效的技能與技術

user —— 用戶檔案

用於記錄關於用戶身份、偏好和溝通風格的信息：

• 姓名、角色、時區
• 溝通偏好（簡潔 vs 詳細、格式偏好）
• 煩惱點及應避免事項
• 工作習慣
• 技術熟練程度

應保存 vs 忽略的內容

應保存（主動保存）

Agent 會自動保存 —— 無需主動請求。它在學習時會保存以下內容：

• 用戶偏好： “我更喜歡 TypeScript 而不是 JavaScript” → 保存至 user
• 環境事實： “此服務器運行 Debian 12 並配備 PostgreSQL 16” → 保存至 memory
• 修正信息： “不要對 Docker 命令使用 sudo，用戶已在 docker 組中” → 保存至 memory
• 約定規範： “項目使用製表符，每行最大 120 字符，採用 Google 風格文檔字符串” → 保存至 memory
• 已完成的工作： “2026-01-15 將數據庫從 MySQL 遷移到 PostgreSQL” → 保存至 memory
• 明確請求： “請記住我的 API 密鑰每月輪換一次” → 保存至 memory

應忽略的內容

• 瑣碎/顯而易見的信息： “用戶詢問了 Python” —— 太模糊，無實際價值
• 易於重新發現的事實： “Python 3.12 支持 f-string 嵌套” —— 可通過網絡搜索獲取
• 原始數據轉儲： 大段代碼、日誌文件、數據表格 —— 超出記憶容量
• 會話特有的一次性信息： 臨時文件路徑、一次性調試上下文
• 已在上下文文件中的信息： SOUL.md 和 AGENTS.md 中的內容

容量管理

記憶具有嚴格的字符限制，以確保系統提示的大小可控：

存儲	限制	典型條目數量
memory	2,200 字符	8–15 條
user	1,375 字符	5–10 條

記憶滿時會發生什麼

當嘗試添加一條超出限制的記憶條目時，工具會返回錯誤：

{
  "success": false,
  "error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Replace or remove existing entries first.",
  "current_entries": ["..."],
  "usage": "2,100/2,200"
}

此時 Agent 應執行以下步驟：

1. 讀取當前條目（錯誤響應中已顯示）
2. 識別可刪除或合併的條目
3. 使用 replace 將相關條目合併為更短版本
4. 然後執行 add 添加新條目

最佳實踐： 當記憶使用率超過 80%（可在系統提示欄頭部查看）時，請在添加新條目前先合併已有條目。例如，將三個獨立的“項目使用 X”條目合併為一條綜合的項目描述條目。

優質記憶條目的實際示例

緊湊且信息密度高的條目效果最佳：

# 好：打包多個相關事實
User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.

# 好：具體、可執行的約定
Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.

# 好：帶上下文的經驗教訓
The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.

# 不好：過於含糊
User has a project.

# 不好：過於冗長
On January 5th, 2026, the user asked me to look at their project which is
located at ~/code/api. I discovered it uses Go version 1.22 and...

重複條目預防

記憶系統會自動拒絕完全重複的條目。若嘗試添加已存在的內容，系統將返回成功狀態，並附帶“未添加重複條目”的消息。

安全掃描

在接收記憶條目前，系統會掃描注入和數據外洩模式，因為這些內容會被注入到系統提示中。匹配威脅模式（如提示注入、憑證外洩、SSH 後門）的內容，或包含不可見 Unicode 字符的內容將被阻止。

會話搜索

除了 MEMORY.md 和 USER.md 外，Agent 還可使用 session_search 工具搜索其過往對話：

• 所有 CLI 和消息會話均存儲在 SQLite 數據庫（~/.hermes/state.db）中，並啟用 FTS5 全文搜索
• 搜索查詢將返回相關的歷史對話，並由 Gemini Flash 提供摘要
• 即使這些內容不在當前活躍記憶中，Agent 也能找回數週前討論過的內容

hermes sessions list    # 瀏覽過去的 sessions

session_search 與記憶的區別

特性	持久記憶	會話搜索
容量	總計約 1,300 個 token	無限制（所有會話）
速度	即時（位於系統提示中）	需要搜索 + LLM 摘要
使用場景	關鍵事實始終在上下文中	查找特定的過往對話
管理方式	由 Agent 手動維護	自動化 — 所有會話均被存儲
令牌成本	每會話固定（約 1,300 個 token）	按需（僅在需要時搜索）

記憶 用於需要始終處於上下文中的關鍵事實。會話搜索 用於“我們上週是否討論過 X？”這類查詢，當 Agent 需要從過往對話中回憶具體細節時使用。

配置

# 在 ~/.hermes/config.yaml 中
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens

外部記憶提供者

為了實現更深入、持久的記憶能力，超越 MEMORY.md 和 USER.md 的範圍，Hermes 隨附 8 個外部記憶提供者插件 —— 包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。

外部提供者與內置記憶並行運行（從不取代內置記憶），並提供知識圖譜、語義搜索、自動事實提取以及跨會話用戶建模等能力。

hermes memory setup      # 選擇一個 provider 並配置它
hermes memory status     # 檢查當前激活的配置

有關每個提供者的完整詳情、設置說明和對比，請參閱 記憶提供者 指南。