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

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

Hermes Agent 具備有界、策劃式的記憶系統，可在不同 session 之間持久保存。這讓它能記住你的偏好、專案、環境，以及學到的經驗。

運作方式

Agent 的記憶由兩個檔案組成：

兩者都儲存在 ~/.hermes/memories/，並在 session 啟動時以凍結快照的形式注入系統提示。Agent 透過 memory 工具管理自己的記憶 — 可以新增、取代或移除項目。

INFO

字元上限是為了讓記憶保持精簡。記憶不會自動壓縮：當寫入即將超出上限時， memory 工具會回傳錯誤，而非靜默丟棄項目。Agent 接著會自行騰出空間 — 在 同一輪中整合或移除項目後再重試（參見記憶已滿時會怎樣）。 注意 replace 也受上限限制：將一個項目替換為更長的內容仍可能超出上限， 因此必須縮短新內容（或移除另一個項目）才能符合。

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

每次 session 啟動時，記憶項目會從磁碟載入，並以凍結區塊的形式渲染到系統提示中：

══════════════════════════════════════════════
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 了解剩餘容量
• 以 §（§ 符號）分隔的各個項目
• 項目可以是多行的

凍結快照模式： 系統提示注入在 session 啟動時擷取一次，並在整個 session 中保持不變。這是故意的 — 為了保護 LLM 的前綴快取以提升效能。當 Agent 在 session 中新增/移除記憶項目時，變更會立即持久保存到磁碟，但要到下一個 session 啟動時才會出現在系統提示中。工具回應則永遠顯示即時狀態。

Memory 工具動作

Agent 使用 memory 工具的以下動作：

• add — 新增記憶項目
• replace — 用更新的內容取代現有項目（透過 old_text 進行子字串比對）
• remove — 移除不再相關的項目（透過 old_text 進行子字串比對）

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

子字串比對

replace 和 remove 動作使用短唯一子字串比對 — 你不需要完整的項目文字。old_text 參數只需是能唯一識別某個項目的子字串：

# 如果記憶中包含 "User prefers dark mode in all editors"
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
• 慣例：「專案使用 tabs、120 字元行寬、Google 風格的 docstrings」→ 儲存到 memory
• 已完成的工作：「2026-01-15 已將資料庫從 MySQL 遷移到 PostgreSQL」→ 儲存到 memory
• 明確請求：「記住我的 API key 輪替是每月一次」→ 儲存到 memory

跳過這些

• 瑣碎/顯而易見的資訊：「使用者問了 Python 的問題」— 太模糊，沒有用處
• 容易重新找到的事實：「Python 3.12 支援 f-string 嵌套」— 可以搜尋到的
• 原始資料傾印： 大型程式碼區塊、日誌檔案、資料表格 — 太大，不適合記憶
• Session 專屬的暫存內容： 暫時的檔案路徑、一次性偵錯上下文
• 已在情境檔案中的資訊： SOUL.md 和 AGENTS.md 的內容

容量管理

記憶有嚴格的字元上限，以確保系統提示保持有界：

記憶已滿時會怎樣

當你嘗試新增一個會超出上限的項目時，工具會回傳錯誤：

{
  "success": false,
  "error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Consolidate now: use 'replace' to merge overlapping entries into shorter ones or 'remove' stale or less important entries (see current_entries below), then retry this add — all in this turn.",
  "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...

重複防護

記憶系統會自動拒絕完全重複的項目。如果你嘗試新增已存在的內容，會回傳成功但附帶「未新增重複項目」的訊息。

安全掃描

記憶項目在接受前會經過注入和外洩模式的掃描，因為它們會被注入到系統提示中。符合威脅模式（prompt injection、憑證外洩、SSH 後門）或包含不可見 Unicode 字元的內容會被封鎖。

Session 搜尋

除了 MEMORY.md 和 USER.md，Agent 可以使用 session_search 工具搜尋過去的對話：

• 所有 CLI 和訊息 session 都儲存在 SQLite（~/.hermes/state.db）中，支援 FTS5 全文搜尋
• 搜尋查詢從資料庫回傳實際訊息 — 沒有 LLM 摘要、沒有截斷
• Agent 可以找到幾週前討論過的東西，即使它們不在主動記憶中
• Agent 也可以在找到的任何 session 中向前/向後捲動

hermes sessions list    # 瀏覽過去的 session

參見 Session 搜尋工具 了解三種呼叫形式（discovery / scroll / browse）和回應格式。

session_search vs memory

記憶用於應始終在上下文中的關鍵事實。Session 搜尋用於「我們上週有沒有討論過 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
  write_approval: false     # false = 自由寫入（預設）| true = 需要批准

控制記憶寫入（write_approval）

預設情況下，Agent 可以自由儲存記憶 — 包括在每一輪之後運行的背景自我改進審查。如果你希望先批准再儲存，設定 memory.write_approval: true。這是一個簡單的開關門檻，套用到前景對話和背景審查：

要完全關閉記憶（不只是設定門檻），設定 memory_enabled: false。

從 CLI 或任何訊息平台審查暫存的寫入：

/memory pending             # 列出暫存的記憶寫入（自動的會標記 [auto]）
/memory approve <id>        # 套用一個（或 'all'）
/memory reject <id>         # 放棄一個（或 'all'）
/memory approval on         # 開啟門檻（或 'off'）並持久保存

這就是「Agent 儲存了一個關於我的錯誤假設」的解法：設定 write_approval: true，每次儲存 — 特別是那些未經提示的背景儲存 — 都要等 你說 yes/no 才會進入你的檔案。

背景審查通知（display.memory_notifications）

在一輪對話之後，背景自我改進審查可能會靜默儲存記憶 或更新技能。預設會在聊天中顯示一行 💾 Memory updated，讓你知道發生了什麼。控制通知的詳細程度：

display:
  memory_notifications: off    # off | on（預設） | verbose

這只控制聊天通知。審查本身以及對你記憶/技能儲存空間的寫入不受此設定影響。 可透過 display.platforms.<platform>.memory_notifications 按平台設定。

控制技能寫入（skills.write_approval）

技能使用相同的開關門檻，但審查 UX 不同，因為 SKILL.md 太大了，無法在聊天气泡中閱讀：

skills:
  write_approval: false     # false = 自由寫入（預設）| true = 需要批准

當 write_approval: true 時，技能寫入（create / edit / patch / write_file / delete）無論來源如何，永遠會暫存。你會在對話中看到一行摘要， 但完整的差異需要在對話外查看：

/skills pending             # 列出暫存的技能寫入 + 每個的一行摘要
/skills diff <id>           # 完整的 unified diff（建議在 CLI 或儀表板中查看）
/skills approve <id>        # 套用（或 'all'）
/skills reject <id>         # 放棄（或 'all'）
/skills approval on         # 開啟門檻（或 'off'）並持久保存

在訊息平台上，可以根據摘要和中繼資料批准技能，或在 CLI / 儀表板 / ~/.hermes/pending/skills/<id>.json 中的暫存檔案開啟 /skills diff 查看完整變更。 詳見 控制 Agent 技能寫入。

外部記憶提供者

對於超出 MEMORY.md 和 USER.md 的更深層、更持久的記憶，Hermes 內建了 8 個外部記憶提供者插件 — 包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。

外部提供者與內建記憶並行運作（永遠不會取代它），並增加知識圖譜、語意搜尋、自動事實擷取和跨 session 使用者建模等功能。

hermes memory setup      # 選擇一個提供者並設定它
hermes memory status     # 檢查哪些正在使用

參見 記憶提供者 指南，了解每個提供者的完整詳情、設定說明和比較。

---

---

記憶提供者