---
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="/docs/hermes/understanding/06-skills-system" />
  <Card title="记忆手册" description="需要具体命令、yaml 字段和外部 provider 接入步骤，查官方教程中文版。" href="/docs/hermes/official/01-user-guide/memory" />
</Cards>
