hermes教程-持久记忆

工作原理

代理的记忆由两个文件组成：

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

信息

字符限制使记忆保持聚焦。记忆不会自动压缩：当写入会超出限制时，memory 工具会返回错误，而不是静默丢弃条目。然后代理自己腾出空间 — 在同一轮中合并或删除条目，然后重试（参见记忆满时会发生什么）。注意，replace 也受限制约束：用更长的条目替换仍可能溢出，因此新内容必须缩短（或删除另一个条目）才能容纳。

记忆在系统提示中的呈现方式

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

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

格式包括：

• 一个标题，显示是哪个存储（记忆或用户档案）
• 使用百分比和字符数，以便代理知道容量
• 各个条目由 §（章节符号）分隔符分隔
• 条目可以是多行的

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

记忆工具操作

代理使用 memory 工具执行以下操作：

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

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

子字符串匹配

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

## 如果记忆包含 "User prefers dark mode in all editors"
memory(action="replace", target="memory",
       old_text="dark mode",
       content="User prefers light mode in VS Code, dark mode in terminal")

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

两个目标的说明

memory — 代理的个人笔记

用于代理需要记住的关于环境、工作流程和经验教训的信息：

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

user — 用户档案

用于关于用户身份、偏好和沟通风格的信息：

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

应该保存 vs 跳过什么

保存这些（主动保存）

代理会自动保存 — 你不需要要求。它在学到以下内容时保存：

• 用户偏好： "我更喜欢 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 的内容

容量管理

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

记忆满时会发生什么

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

{
  "success": false,
  "error": "Memory at 2,100/2,200 chars. Adding this entry (250 chars) would exceed the limit. Consolidate now: use 'replace' to merge overlapping entries into shorter ones or 'remove' stale or less important entries (see current_entries below), then retry this add — all in this turn.",
  "current_entries": ["..."],
  "usage": "2,100/2,200"
}

然后代理应该：

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

最佳实践： 当记忆容量超过 80%（在系统提示标题中可见）时，在添加新条目之前先合并条目。例如，将三个独立的 "项目使用 X" 条目合并为一个全面的项目描述条目。

良好记忆条目的实际示例

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

## 好：打包多个相关事实
用户运行 macOS 14 Sonoma，使用 Homebrew，安装了 Docker Desktop 和 Podman。Shell：zsh 搭配 oh-my-zsh。编辑器：VS Code 带 Vim 键绑定。
## 好：具体、可操作的约定
项目 ~/code/api 使用 Go 1.22，sqlc 用于数据库查询，chi 路由器。使用 'make test' 运行测试。CI 通过 GitHub Actions。
## 好：带有上下文的经验教训
staging 服务器（10.0.1.50）需要 SSH 端口 2222，而不是 22。密钥位于 ~/.ssh/staging_ed25519。
## 坏：太模糊
用户有一个项目。
## 坏：太冗长
2026 年 1 月 5 日，用户让我查看他们的项目，该项目位于 ~/code/api。我发现它使用 Go 版本 1.22 和...

重复预防

记忆系统自动拒绝完全重复的条目。如果你尝试添加已存在的内容，它会返回成功并显示 "未添加重复项" 的消息。

安全扫描

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

会话搜索

除了 MEMORY.md 和 USER.md 之外，代理还可以使用 session_search 工具搜索其过去的对话：

• 所有 CLI 和消息会话都存储在 SQLite（~/.hermes/state.db）中，并支持 FTS5 全文搜索
• 搜索查询返回数据库中的实际消息 — 没有 LLM 摘要，没有截断
• 代理可以找到几周前讨论过的事情，即使它们不在其活动记忆中
• 代理还可以在找到的任何会话中向前/向后滚动

hermes sessions list    # 浏览过去的会话

参见会话搜索工具了解三种调用形式（发现 / 滚动 / 浏览）和响应格式。

session_search 与 memory 的对比

记忆 用于始终应该在上下文中的关键事实。会话搜索 用于 "我们上周讨论过 X 吗？" 这类查询，代理需要从过去的对话中回忆具体细节。

配置

## 在 ~/.hermes/config.yaml 中
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens
  write_approval: false     # false = 自由写入（默认） | true = 需要审批

控制记忆写入（write_approval）

默认情况下，代理自由保存记忆 — 包括在一轮之后运行的后台自我改进审查。如果你希望先批准保存，请设置 memory.write_approval: true。这是一个简单的开/关门，应用于前台轮次和后台审查：

要完全关闭记忆（而不仅仅是门控），请设置 memory_enabled: false。

从 CLI 或任何消息平台审查暂存的写入：

/memory pending             # 列出暂存的记忆写入（自动写入会标记 [auto]）
/memory approve <id>        # 应用一个（或 'all'）
/memory reject <id>         # 丢弃一个（或 'all'）
/memory approval on         # 打开门（或 'off'）并持久化

这是对 "代理保存了关于我的错误假设" 的答案：设置 write_approval: true，那么每次保存 — 尤其是未经提示的后台保存 — 在进入你的档案之前都会等待你的是/否。

后台审查通知（display.memory_notifications）

在一轮之后，后台自我改进审查可能会静默保存一条记忆或更新一项技能。默认情况下，它会在聊天中显示一条简短的 💾 Memory updated 行，以便你知道发生了。控制其啰嗦程度：

display:
  memory_notifications: on    # off | on（默认） | verbose

这仅控制网关聊天通知。审查本身以及对你的记忆/技能存储的写入不受此设置影响。通过 display.platforms.<platform>.memory_notifications 按平台设置。

控制技能写入（skills.write_approval）

技能使用相同的开/关门，但审查体验不同，因为 SKILL.md 太大，无法在聊天气泡中阅读：

skills:
  write_approval: false     # false = 自由写入（默认） | true = 需要审批

当 write_approval: true 时，技能写入（create / edit / patch / write_file / delete）总是暂存，无论来源如何。你内联审查一行摘要，但完整差异保持在带外：

/skills pending             # 列出暂存的技能写入 + 每个的一行摘要
/skills diff <id>           # 完整统一差异（最好在 CLI 或仪表板中查看）
/skills approve <id>        # 应用它（或 'all'）
/skills reject <id>         # 丢弃它（或 'all'）
/skills approval on         # 打开门（或 'off'）并持久化

在消息平台上，从摘要 + 元数据批准技能，或者当你想要阅读整个更改时，在 CLI / 仪表板 / 暂存文件 ~/.hermes/pending/skills/<id>.json 中打开 /skills diff。完整详情请参见门控代理技能写入。

外部记忆提供者

对于超越 MEMORY.md 和 USER.md 的更深层、持久的记忆，Hermes 附带了 8 个外部记忆提供者插件 — 包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。

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

hermes memory setup      # 选择一个提供者并配置它
hermes memory status     # 检查当前激活的提供者

有关每个提供者的完整详情、设置说明和比较，请参见记忆提供者指南。