---
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="/docs/hermes/official/01-user-guide/skills" />
  <Card title="记忆与召回原理" description="继续理解 curated memory 和 session_search 的边界，以及外部 provider 的定位。" href="/docs/hermes/understanding/05-memory-and-recall" />
</Cards>
