sidebar_position: 3 title: “持久记忆” description: “Hermes Agent 如何跨会话记住 — MEMORY.md、USER.md 和会话搜索”

持久记忆

Hermes Agent 具有跨会话持久的有界、精心策划的记忆。这让它能记住你的偏好、你的项目、你的环境和它已学到的东西。

工作原理

两个文件组成 Agent 的记忆：

两者都存储在 ~/.hermes/memories/ 中，作为冻结的快照被注入系统提示，在会话开始时。Agent 通过 memory 工具管理自己的记忆 — 它可以添加、替换或删除条目。

::info 字符限制保持记忆专注。当记忆已满时，Agent 整合或替换条目以为新信息腾出空间。

::

记忆如何在系统提示中出现

在每个会话开始，记忆条目从磁盘加载并呈现到系统提示中作为冻结块：

══════════════════════════════════════════════
MEMORY（你的个人笔记）[67% — 1,474/2,200 字符]
══════════════════════════════════════════════
用户的项目是 ~/code/myapi 中的 Rust 网络服务，使用 Axum + SQLx
§
这台机器运行 Ubuntu 22.04，安装了 Docker 和 Podman
§
用户偏好简洁回复，不喜欢冗长解释

格式包括：

• 标题显示哪个存储（MEMORY 或 USER PROFILE）
• 使用百分比和字符计数，以便 Agent 了解容量
• 单个条目由 §（分段符号）分隔符分隔
• 条目可以是多行

冻结快照模式： 系统提示注入在会话开始时被捕获，会话中间不再改变。这是有意的 — 它保留 LLM 的前缀缓存以提高性能。当 Agent 在会话中添加/删除记忆条目时，更改立即持久化到磁盘，但在下一个会话开始前不会出现在系统提示中。工具响应始终显示实时状态。

记忆工具操作

Agent 使用具有这些操作的 memory 工具：

• add — 添加新记忆条目
• replace — 用更新的内容替换现有条目（通过 old_text 使用子字符串匹配）
• remove — 删除不再相关的条目（通过 old_text 使用子字符串匹配）

没有 read 操作 — 记忆内容在会话开始时自动注入系统提示。Agent 将其记忆视为对话上下文的一部分。

子字符串匹配

replace 和 remove 操作使用短唯一子字符串匹配 — 你不需要完整条目文本。old_text 参数只需是唯一标识恰好一个条目的唯一子字符串：

# 如果记忆包含 "User prefers dark mode in all editors"
memory(action="replace", target="memory",
       old_text="dark mode",
       content="用户偏好 VS Code 中的浅色模式，终端中的深色模式")

如果子字符串匹配多个条目，会返回错误，要求更特定的匹配。

两个目标说明

memory — Agent 的个人笔记

对于 Agent 需要记住关于环境、工作流和已学教训的信息：

• 环境事实（OS、工具、项目结构）
• 项目约定和配置
• 发现的工具怪癖和变通方法
• 完成任务日记条目
• 有效的技能和技术

user — 用户档案

对于关于用户身份、偏好和交流风格的信息：

• 名字、角色、时区
• 交流偏好（简洁 vs 详细、格式偏好）
• 讨厌的事情和要避免的东西
• 工作流习惯
• 技术技能水平

保存什么 vs 跳过什么

保存这些（主动）

Agent 自动保存 — 你无需要求。它在学到以下内容时保存：

• 用户偏好： “我更喜欢 TypeScript 而非 JavaScript” → 保存到 user
• 环境事实： “这个服务器运行 Debian 12，带 PostgreSQL 16” → 保存到 memory
• 纠正： “不为 Docker 命令使用 sudo，用户在 docker 组中” → 保存到 memory
• 约定： “项目使用制表符、120 字符行宽、Google 风格文档字符串” → 保存到 memory
• 完成的工作： “2026-01-15 上从 MySQL 迁移到 PostgreSQL” → 保存到 memory
• 显式请求： “记住我的 API 密钥轮换每月发生一次” → 保存到 memory

跳过这些

• 琐碎/明显信息： “用户询问了 Python” — 太含糊而无用
• 容易重新发现的事实： “Python 3.12 支持 f 字符串嵌套” — 可网络搜索这个
• 原始数据转储： 大代码块、日志文件、数据表 — 对记忆太大
• 会话特定的临时内容： 临时文件路径、一次性调试上下文
• 上下文文件中已有的信息： SOUL.md 和 AGENTS.md 内容

容量管理

记忆有严格字符限制以保持系统提示有界：

记忆满时会发生什么

当你尝试添加超过限制的条目时，工具返回错误：

{
  "success": false,
  "error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Replace or remove existing entries first.",
  "current_entries": ["..."],
  "usage": "2,100/2,200"
}

然后 Agent 应该：

1. 读取当前条目（显示在错误响应中）
2. 识别可删除或整合的条目
3. 使用 replace 将相关条目合并成更短版本
4. 然后 add 新条目

最佳做法： 当记忆超过 80% 容量（在系统提示标题中可见）时，在添加新条目前整合条目。例如，将三个单独的“项目使用 X“条目合并成一个综合项目描述条目。

好记忆条目的实例

紧凑、信息密集的条目效果最佳：

# 好：打包多个相关事实
User 运行 macOS 14 Sonoma，使用 Homebrew，装有 Docker Desktop 和 Podman。Shell：zsh with oh-my-zsh。Editor：VS Code with Vim 键绑定。

# 好：特定、可操作的约定
项目 ~/code/api 使用 Go 1.22、sqlc 处理数据库查询、chi 路由。用 'make test' 运行测试。通过 GitHub Actions 进行 CI。

# 好：带上下文的学到的教训
暂存服务器 (10.0.1.50) 需要 SSH 端口 2222，非 22。密钥在 ~/.ssh/staging_ed25519。

# 坏：太含糊
User 有一个项目。

# 坏：太冗长
1 月 5 日 2026 年，用户问我看他们的项目，位于
位于 ~/code/api。我发现它使用 Go 版本 1.22 并...

重复防止

记忆系统自动拒绝完全重复条目。如果你尝试添加已存在的内容，它返回成功，带“无重复添加“消息。

安全扫描

记忆条目在被接受前扫描注入和泄露模式，因为它们被注入系统提示。匹配威胁模式（提示注入、凭证泄露、SSH 后门）或包含不可见 Unicode 字符的内容被阻止。

会话搜索

除 MEMORY.md 和 USER.md 外，Agent 可使用 session_search 工具搜索其过去的对话：

• 所有 CLI 和消息传递会话存储在 SQLite（~/.hermes/state.db）中，带 FTS5 全文搜索
• 搜索查询返回带 Gemini Flash 摘要的相关过去对话
• Agent 可找到它数周前讨论过的东西，即使它们不在其活跃记忆中

hermes sessions list    # 浏览过去的会话

session_search vs memory

记忆用于应始终在上下文中的关键事实。会话搜索用于“我们上周讨论过 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

外部内存提供商

为了获得超越 MEMORY.md 和 USER.md 的更深层、持久的记忆，Hermes 配备 8 个外部记忆提供商插件 — 包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。

外部提供商与内置记忆并行运行（从不替换它），并添加知识图、语义搜索、自动事实提取和跨会话用户建模等功能。

hermes memory setup      # 选择提供商并配置它
hermes memory status     # 检查什么处于活跃

参见 Memory Providers 指南，了解每个提供商的完整详情、设置说明和比较。