持久化记忆

Hermes Agent 拥有有限的、精选的记忆，并且这些记忆会跨会话持久化。这使得它能够记住你的偏好、你的项目、你的环境以及它学到的所有事情。

工作原理

Agent 的记忆由两个文件组成：

文件	用途	字符限制
MEMORY.md	Agent 的个人笔记 — 环境事实、约定、学到的知识	2,200 字符 (~800 tokens)
USER.md	用户资料 — 你的偏好、沟通风格、期望	1,375 字符 (~500 tokens)

这两个文件都存储在 ~/.hermes/memories/ 中，并在会话开始时作为固化快照注入到系统提示词（system prompt）中。Agent 通过 memory 工具管理自己的记忆——它可以添加、替换或删除条目。

信息

字符限制保持了记忆的聚焦性。当记忆空间不足时，Agent 会整合或替换条目，为新信息腾出空间。

记忆如何在系统提示词中显示

在每个会话开始时，记忆条目会从磁盘加载，并渲染成一个固化的块显示在系统提示词中：

══════════════════════════════════════════════
MEMORY (您的个人笔记) [67% — 1,474/2,200 字符]
══════════════════════════════════════════════
用户项目是一个使用 Axum + SQLx 的 Rust Web 服务，位于 ~/code/myapi
§
这台机器运行 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 参数只需要一个能够唯一标识单个条目的唯一子字符串：

# 如果记忆包含 "用户偏好所有编辑器使用深色模式"
memory(action="replace", target="memory",
       old_text="深色模式",
       content="用户偏好 VS Code 使用浅色模式，终端使用深色模式")

如果子字符串匹配到多个条目，系统会返回错误，要求提供更具体的匹配。

两个目标解释

memory — Agent 的个人笔记

用于 Agent 需要记住的环境、工作流程和经验教训：

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

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-string 嵌套" — 可以通过网络搜索查到
• 原始数据倾倒： 大型代码块、日志文件、数据表 — 对记忆来说太大了
• 会话特定的临时信息： 临时文件路径、一次性调试上下文
• 已在上下文文件中的信息： SOUL.md 和 AGENTS.md 的内容

容量管理

记忆有严格的字符限制，以保持系统提示词的边界性：

存储区	限制	典型条目数
memory	2,200 字符	8-15 个条目
user	1,375 字符	5-10 个条目

记忆满载时会发生什么

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

{
  "success": false,
  "error": "记忆已达到 2,100/2,200 字符。添加此条目（250 字符）将超出限制。请先替换或删除现有条目。",
  "current_entries": ["..."],
  "usage": "2,100/2,200"
}

此时 Agent 应该：

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

最佳实践： 当记忆容量超过 80%（在系统提示词头部可见）时，应先整合条目，然后再添加新条目。例如，将三个独立的“项目使用 X”条目合并成一个全面的项目描述条目。

良好记忆条目的实际示例

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

# 良好：打包多个相关事实
用户运行 macOS 14 Sonoma，使用 Homebrew，安装了 Docker Desktop 和 Podman。Shell：zsh with oh-my-zsh。编辑器：VS Code，使用 Vim 键绑定。

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

# 良好：带有上下文的经验教训
暂存服务器 (10.0.1.50) 需要 SSH 端口 2222，而不是 22。密钥位于 ~/.ssh/staging_ed25519。

# 差：过于模糊
用户有一个项目。

# 差：过于冗长
在 2026 年 1 月 5 日，用户要求我查看他们位于 ~/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 与 memory 的区别

特性	持久化记忆	会话搜索
容量	总计约 1,300 tokens	无限（所有会话）
速度	即时（在系统提示词中）	需要搜索 + LLM 总结
用例	始终可用的关键事实	查找特定的过往对话
管理	由 Agent 手动策划	自动 — 存储所有会话
Token 成本	每个会话固定 (~1,300 tokens)	按需（需要时搜索）

记忆用于始终在上下文中的关键事实。会话搜索用于“我们上周讨论过 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 指南，了解每个提供商的完整细节、设置说明和比较。