---
title: "使用記憶系統"
description: "理解 Hermes 的 MEMORY.md、USER.md、凍結快照、memory tool、session_search、容量限制、安全掃描和外部 memory provider。"
verifiedAt: "2026-05-09"
---

Hermes 的內建記憶是 **bounded curated memory（有界精選記憶）**：容量有限，內容要精選。它**不是**無限日誌，也**不是**把所有聊天曆史塞進 prompt，而是讓新 session 一開始就知道關鍵偏好、環境事實和專案約定——記憶條目應該像精煉筆記，不是日記流水賬。

官方資料：[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)、[Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files)。

> [!NOTE]
> **先給結論**：`MEMORY.md` 存**環境和專案事實**，`USER.md` 存**使用者偏好**；兩者只在 session 啟動時注入為**凍結快照**（frozen snapshot，本輪對話內修改不會反映回當前 prompt）；歷史細節用 `session_search`（FTS5 全文檢索）查，不要硬塞進記憶。

## 兩個內建記憶檔案

內建記憶位於：

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

<Cards>
  <Card title="MEMORY.md" description="Agent 的個人筆記：環境事實、專案約定、工具坑、已驗證結論。預設 2200 字元左右。" />
  <Card title="USER.md" description="使用者畫像：溝通偏好、身份、習慣、明確要求。預設 1375 字元左右。" />
</Cards>

官方預設限制按當前 [Memory 配置文件](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)（截至本文核驗日：`MEMORY.md` ~2200 chars、`USER.md` ~1375 chars）。**這個限制是設計，不是缺陷**——它強迫記憶保持**短、準、穩定**。容量越大，每次啟動 system prompt 的"權威指令"越多，模型反而更容易被舊錯誤帶偏。

## 凍結快照機制

每個 session 啟動時，Hermes 會把記憶讀入 system prompt，形成凍結快照。當前 session 中新增、替換或刪除的記憶會立刻寫盤，但不會重新整理當前 prompt；新 session 才能看到。

這個設計的好處是保持 prompt prefix 穩定，減少執行中上下文漂移。代價是你不能指望“剛儲存的記憶”馬上影響當前對話。

實際使用時按這個原則：

- 當前任務需要立即生效：直接在當前對話說明。
- 長期事實需要下次也生效：寫入 memory。
- 歷史任務需要回查：用 session_search。

## memory tool 的動作

Agent 用 `memory` tool 管理條目：

- `add`：新增記憶。
- `replace`：用 `old_text` 的唯一子串匹配並替換。
- `remove`：用 `old_text` 的唯一子串匹配並刪除。

示例：

```python
memory(
    action="replace",
    target="memory",
    old_text="dark mode",
    content="User prefers light mode in VS Code, dark mode in terminal",
)
```

`replace` 和 `remove` 依賴唯一子串。如果匹配到多條，工具會要求更具體的 `old_text`。這比整段複製更適合維護短記憶。

## 該儲存什麼

適合儲存到 `MEMORY.md`：

- 穩定環境事實，例如 OS、shell、主要工具、伺服器埠。
- 專案長期規則，例如測試命令、部署方式、目錄約定。
- 已驗證過的修復結論。
- 反覆出現的工具問題和 workaround。
- 任務完成後的高價值索引，而不是完整過程。

適合儲存到 `USER.md`：

- 溝通偏好。
- 格式偏好。
- 技術水平和工作習慣。
- 明確要求以後都遵守的規則。

不適合儲存：

- 大段日誌、程式碼、表格。
- 一次性臨時路徑。
- 能輕易重新查到的通用知識。
- 已經存在於 `AGENTS.md`、`CLAUDE.md`、`SOUL.md` 或專案文件裡的內容。
- 不確定、未驗證、可能過期的猜測。

錯誤記憶比沒有記憶更危險。錯但持久，會汙染後續 session。

## 容量管理

配置示例：

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

容量超過 80% 時，不要繼續堆條目。先合併、替換或刪除低價值內容。

好的記憶寫法：

```text
Project ~/code/api uses Go 1.22, chi, sqlc. Test with make test. CI runs GitHub Actions.
```

不好的記憶寫法：

```text
The user has a project and asked me some questions about it yesterday.
```

記憶要能直接改變下次 agent 的行動，不只是記錄“發生過聊天”。

## 安全掃描

官方文件說明，記憶寫入前會掃描 prompt injection（提示注入：惡意文本偽裝成系統指令）、credential exfiltration（憑據外洩：偷塞 token/密碼）、SSH backdoor（SSH 後門：植入未授權登入入口）、不可見 Unicode（用零寬字元藏惡意內容）等威脅模式。原因很直接：記憶會進入 system prompt（系統提示），惡意記憶等於**長期注入**——下次啟動模型仍會把它當權威讀取。

不要把外部網頁、issue、聊天記錄裡的原文直接儲存為記憶。先提煉成你驗證過的事實，再寫入。

## session_search

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

適合回查：

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

Hermes 會把 CLI 和 messaging sessions 存到 SQLite，並用 FTS5 做全文檢索，再用模型總結相關結果。

```bash
hermes sessions list
```

簡單區分：

```text
memory         -> 每个 session 都该知道的关键事实
session_search -> 需要时再查的历史细节
```

## 外部 memory provider

Hermes 還支援 Honcho（AI 原生使用者建模，Nous Research 推薦）、OpenViking、Mem0（流行 AI 記憶服務）、Hindsight、Holographic、RetainDB、ByteRover、Supermemory 等外部 memory provider（記憶外掛）。它們提供更深的使用者建模、語義搜尋、知識圖譜或自動事實抽取。

它們和內建 memory 並行工作，不替代 `MEMORY.md` / `USER.md`。

```bash
hermes memory setup
hermes memory status
```

只有當內建 memory 和 session_search 的邊界已經清楚，再考慮外部 provider。否則只是把錯誤記憶擴散到更復雜的系統裡。

## 驗收清單

健康的記憶系統應該滿足下面 6 項。任何一項答不上來 = 記憶使用方式還需要調整：

- 新 session 啟動時能看到關鍵偏好和環境事實——驗證：開新 chat，問"你知道我用什麼 OS / 專案用什麼堆疊"
- 錯誤記憶能被 `replace` 或 `remove`——驗證：故意新增錯誤條目，再用唯一子串刪掉
- 容量長期不接近滿載（≤80%）——驗證：`hermes memory status` 看佔比
- 一次性日誌**沒有**進入 curated memory——驗證：grep MEMORY.md 看有沒有大段輸出貼上
- 需要回查歷史時用 `session_search` 工具（這是 agent 在對話裡自己呼叫的內部工具，不是 CLI 命令；使用者在 CLI 用 `hermes sessions list` / `hermes sessions browse` 看 session 清單，跨 session 全文檢索讓 agent 用 `session_search` 完成）
- 外部 provider 沒有替代人工判斷和安全審查——驗證：開了 Honcho 等仍然能解釋"為什麼這條資訊值得長期記"

## 官方資料

- [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)（外部 provider 完整列表）
- [Honcho](https://hermes-agent.nousresearch.com/docs/user-guide/features/honcho)（dialectic 使用者建模）
- [Sessions](https://hermes-agent.nousresearch.com/docs/user-guide/sessions)（session_search 來源 + sqlite/FTS5 實現）
- [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files)（專案級 context vs 全域性 SOUL.md / 長期 memory 的邊界）

## 下一步

<Cards>
  <Card title="技能系統" description="記憶解決長期事實，skill 解決可複用流程——兩者是 Hermes 持久化能力的左右手。" href="/zh-Hant/docs/hermes/official/01-user-guide/skills" />
  <Card title="記憶與召回原理" description="繼續理解 curated memory 和 session_search 的邊界，以及外部 provider 的定位。" href="/zh-Hant/docs/hermes/understanding/05-memory-and-recall" />
</Cards>
