---
title: "05 · 記憶與召回"
description: "區分 Hermes curated memory、USER.md、MEMORY.md、凍結快照、session_search、容量治理和外部 memory provider。"
verifiedAt: "2026-05-09"
---

Hermes 的 **memory（長期記憶）不是無限日誌**，而是**精選**長期事實。它的目標是讓新 session 一開始就知道關鍵偏好、環境事實和專案約定，同時把歷史細節留給 `session_search`（會話檢索）按需呼叫。理解這一點比記任何命令都重要——把 memory 當日志寫，結果就是 agent 在錯誤資訊上越用越固執。

官方資料：[Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)、[Memory Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers)、[Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions)、[Honcho](https://hermes-agent.nousresearch.com/docs/user-guide/features/honcho)。

> [!NOTE]
> **先給結論**：`MEMORY.md`（專案記憶）和 `USER.md`（使用者偏好）是**短、穩、可驗證**的長期事實；`session_search` 是歷史會話檢索（FTS5 全文索引）；外部 memory provider 是進階擴充套件，不是新手必選項——基礎三件套用好，多數任務已經夠。

## 官方機制補充

Hermes 的 `memory` 工具**只有三個動作**：`add`、`replace`、`remove`。**沒有** `read` 動作——因為 memory 會在 session 啟動時直接注入 **system prompt（系統提示）**，agent 在當前上下文裡已經能看到啟動快照，不需要主動讀。這是和"無限日誌型記憶"的根本區別。

`replace` 和 `remove` 使用 `old_text` 的**短唯一子串匹配**，不要求複製完整條目。如果子串命中多條，工具會要求更具體的匹配。這個設計適合小容量、高密度 memory，但也要求條目**不要寫得太相似**——否則 replace 時找不到唯一匹配，操作會失敗。

```text
add      -> 新增一条长期事实
replace  -> 用唯一子串定位旧条目并替换
remove   -> 用唯一子串定位旧条目并删除
read     -> 不存在，启动时已注入
```

系統還會拒絕 exact duplicate entries（完全重複條目），並在寫入前掃描 prompt injection（提示注入：惡意文本偽裝成系統指令）、credential exfiltration（憑據外洩：偷偷把 token / 密碼塞進 memory）、SSH backdoor（SSH 後門：寫入未授權登入入口）、invisible Unicode（不可見 Unicode：用零寬字元隱藏惡意內容）等模式。原因很直接：memory 會進入 system prompt（系統提示），所以它本身就是**長期注入面**——任何寫進去的內容下次啟動都會被模型當成權威指令讀。

## 三層記憶機制總覽

Hermes 的記憶並不是單一系統，而是三層各管不同時間尺度，疊在一起才構成"自我改進閉環"的記憶支柱：

```mermaid
flowchart LR
    subgraph S1["啟動注入<br/>每次啟動 system prompt 自帶"]
        M1["MEMORY.md<br/>專案長期事實<br/>~2200 chars"]
        M2["USER.md<br/>使用者偏好畫像<br/>~1375 chars"]
    end
    subgraph S2["當前會話<br/>本輪對話上下文"]
        S3["session 上下文<br/>本次對話的滾動視窗"]
    end
    subgraph S3box["按需檢索<br/>需要時再查"]
        SS["session_search<br/>FTS5 全文索引<br/>歷史所有 session"]
        EXT["External Providers<br/>Honcho / Mem0 等<br/>語義 / 使用者建模"]
    end
    M1 --> S3
    M2 --> S3
    SS -.LLM 摘要.-> S3
    EXT -.外掛式.-> S3
```

三層使用規則：**每次啟動都該帶 → 內建 memory；本次任務用 → 當前對話；歷史回查 → session_search；複雜使用者建模 → 外部 provider**。

## 兩類長期事實

內建記憶在：

```text
~/.hermes/memories/
├── MEMORY.md
└── USER.md
```

<Cards>
  <Card title="MEMORY.md" description="Agent 需要記住的環境和工作事實，例如專案約定、工具坑、已驗證修復結論。" />
  <Card title="USER.md" description="使用者畫像，例如溝通偏好、常用技術堆疊、明確偏好和反覆糾正過的要求。" />
</Cards>

預設容量按官方當前 [memory 配置文件](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)（截至本文核驗日：`MEMORY.md` 2200 chars、`USER.md` 1375 chars）。容量小是**有意設計**——為了讓記憶保持高密度，而不是把聊天曆史變成永久 prompt。**容量小才是優勢**：每次啟動這兩個檔案全文都進系統提示，越短模型越能精準記住。

官方配置鍵在 `~/.hermes/config.yaml` 的 `memory` 段：

```yaml
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375
```

不要為了“多記一點”盲目把限制調大。限制越大，長期 prompt 的噪音和注入面也越大。

## 凍結快照

兩者會在 session 啟動時注入 system prompt。當前 session 中新增或修改的記憶會寫盤，但不會重新整理當前 system prompt；新 session 才能看到。

這個機制的判斷：

- 當前任務馬上需要：直接在當前對話說。
- 以後每次都該知道：寫入 memory。
- 只是可能要回查：留給 session_search。

不要因為“剛儲存的記憶沒立刻生效”就重複寫入。

## 儲存標準

適合儲存：

- 使用者明確偏好。
- 穩定環境事實。
- 專案長期規則。
- 反覆出現的工具問題。
- 已驗證過的修復結論。

不適合儲存：

- 一次性任務細節。
- 大段日誌或程式碼。
- 臨時檔案路徑。
- 可以從專案文件直接讀到的內容。
- 未驗證的猜測。

錯誤記憶比缺少記憶更危險。它會持續影響後續 session，並讓 agent 變得“有依據地錯”。

## session_search

`session_search` 是歷史會話檢索，不是 curated memory。

適合問：

- 之前怎麼修過類似問題。
- 某個長期任務上次停在哪裡。
- 使用者曾經糾正過什麼。
- 某個專案以前跑過哪些命令。

Hermes 把 CLI 和 messaging sessions 寫入 SQLite，並用 FTS5 全文檢索，再由模型總結相關片段。

官方實現裡歷史會話儲存在 `~/.hermes/state.db`。這意味著 `session_search` 更像“查歷史記錄再摘要”，而 memory 更像“每輪啟動都預設攜帶的長期事實”。前者容量大但按需觸發，後者容量小但每次都會進入上下文。

簡單判斷：

```text
每次都该知道 -> memory
偶尔需要回查 -> session_search
当前临时上下文 -> 当前对话
项目长期规则 -> AGENTS.md / CLAUDE.md / .hermes.md
```

## 外部 provider

Hermes 支援多個外部 memory provider（記憶外掛，按官方 [Memory Providers 頁](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers) 當前列表為準）：Honcho（AI 原生使用者建模）、OpenViking、Mem0（流行的 AI 記憶服務）、Hindsight、Holographic、RetainDB、ByteRover、Supermemory 等——多數是 AI-native（AI 原生）記憶服務，提供語義搜尋、使用者建模、知識圖譜等能力。

外部 provider 適合**更復雜**的長期使用者建模、語義搜尋、知識圖譜或自動事實抽取，**但不要一開始就接**。先把內建 memory 用好，再判斷是否需要外部 provider——多數場景內建 `MEMORY.md` + `USER.md` + `session_search` 已經夠。

```bash
hermes memory setup    # 选 provider + 配凭据
hermes memory status   # 查当前激活的 provider 和数据量
```

它們和內建 memory **並行工作**，不替代 `MEMORY.md` / `USER.md`——內建層是"啟動快照"，外部 provider 是"按需查詢的語義檢索層"。**Honcho** 提供官方推薦的 dialectic（辯證式）多代理使用者建模，用 LLM 持續修正使用者畫像，是 Nous Research 自己重點推的能力。

## 記憶治理

推薦規則：

```text
事实必须可验证
偏好必须来自用户明确表达
临时信息不入库
低密度内容先合并再保存
超过 80% 容量就主动压缩
发现错误立即 replace 或 remove
外部内容先提炼再入库
```

好的 memory 會讓 Hermes 越用越貼合；壞的 memory 會讓它越來越固執。

## 何時合併而不是新增

官方建議 memory 超過 80% 容量時先合併。實踐中可以用這組規則判斷：

| 情況 | 動作 |
| --- | --- |
| 同一專案有多條環境事實 | 合併成一條專案畫像 |
| 使用者偏好互相沖突 | replace 成最新明確偏好 |
| 一次性任務已經結束 | remove，不要留長期記憶 |
| 同一工具坑反覆出現 | 合併為“症狀 + 原因 + 修復” |
| 條目來自外部網頁或 issue | 先提煉事實，再決定是否 add |

memory 的目標不是完整，而是穩定。能從專案文件、命令、Git 歷史或官方文件重新讀到的資訊，不應該優先佔用 memory。

## 安全邊界

記憶會**直接進入 system prompt**，所以它是**長期注入面**——任何寫進 memory 的內容會在每次啟動時被模型當成"權威指令"讀取。這意味著兩條鐵律：

1. **來源審查**：外部網頁、issue、聊天記錄、PR 評論裡的原文**不要**直接儲存成 memory。先判斷來源可信度，再提煉成經過驗證的事實——攻擊者可以在 GitHub issue 留下 prompt injection 文本，等你不慎複製進 memory 就長期生效。
2. **不儲存憑據**：API key、token、密碼、私鑰路徑、SSH backdoor、可用於攻擊的連線資訊一律**不入 memory**。需要憑據時走 `~/.hermes/.env` 或作業系統級憑據系統（macOS Keychain / 1Password CLI 等）。Hermes 啟動時會掃描 memory 內容裡的 prompt injection、憑據外洩、SSH backdoor、不可見 Unicode 等模式並拒寫——但你也別故意去試它的下限。

## 官方資料

- [Persistent Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)（MEMORY.md / USER.md / 容量 / 注入機制）
- [Memory Providers](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers)（外部 provider 完整列表）
- [Honcho](https://hermes-agent.nousresearch.com/docs/user-guide/features/honcho)（AI-native dialectic 使用者建模）
- [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions)（session_search 來源）
- [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files)（專案級 AGENTS.md / CLAUDE.md / .hermes.md / 全域性 SOUL.md）

## 下一步

<Cards>
  <Card title="Skills 系統" description="記憶儲存長期事實，skills 沉澱可複用流程——兩者形成 Hermes 自我改進閉環的兩根支柱。" href="/zh-Hant/docs/hermes/understanding/06-skills-system" />
  <Card title="記憶手冊" description="需要具體命令、yaml 欄位和外部 provider 接入步驟，查官方教程中文版。" href="/zh-Hant/docs/hermes/official/01-user-guide/memory" />
</Cards>
