好奇心花园🪴

搜索

SearchSearch

最近的笔记

Persistent Memory（持久记忆）

2026年5月24日11分钟阅读

Persistent Memory（持久记忆）

Hermes Agent 拥有有限、经过整理的跨会话持久记忆。这使它能够记住您的偏好、项目、环境以及学到的东西。

工作原理

两个文件构成了代理的记忆：

文件用途字符限制
MEMORY.md代理的个人笔记——环境事实、约定、学到的东西2,200 字符（约 800 令牌）
USER.md用户画像——您的偏好、沟通风格、期望1,375 字符（约 500 令牌）

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

:::info 字符限制使记忆保持聚焦。当记忆满时，代理会合并或替换条目以腾出空间给新信息。 :::

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

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

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed
§
User prefers concise responses, dislikes verbose explanations

格式包括：

  • 显示哪个存储（MEMORY 或 USER PROFILE）的标头
  • 使用百分比和字符计数，以便代理知道容量
  • 由 §（节符号）分隔符分隔的各个条目
  • 条目可以多行

冻结快照模式： 系统提示注入在会话开始时捕获一次，在整个会话中从不更改。这是有意为之——它保留了 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 内容

容量管理

记忆有严格的字符限制，以保持系统提示的大小可控：

存储限制典型条目数
memory2,200 字符8-15 个条目
user1,375 字符5-10 个条目

当记忆满时会发生什么

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

{
  "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"
}

然后代理应该：

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

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

良好记忆条目的实际示例

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

# 好：打包多个相关事实
User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.

# 好：具体的、可操作的约定
Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.

# 好：带上下文的经验教训
The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.

# 差：太模糊
User has a project.

# 差：太冗长
On January 5th, 2026, the user asked me to look at their project which is
located at ~/code/api. I discovered it uses Go version 1.22 and...

重复预防

记忆系统自动拒绝完全重复的条目。如果您尝试添加已经存在的内容，它会返回成功并附带”没有添加重复项”的消息。

安全扫描

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

会话搜索

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

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

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

session_search vs memory

特性持久记忆会话搜索
容量约 1,300 令牌总计无限（所有会话）
速度即时（在系统提示中）约 20ms FTS5 查询，约 1ms 滚动
成本每条提示中的令牌成本免费——无 LLM 调用
使用场景关键事实始终可用查找特定的过去对话
管理由代理手动整理自动——所有会话都存储
令牌成本每会话固定（约 1,300 令牌）按需（需要时搜索）

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

配置

# 在 ~/.hermes/config.yaml 中
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # 约 800 令牌
  user_char_limit: 1375     # 约 500 令牌

外部记忆提供者

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

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

hermes memory setup      # 选择提供者并进行配置
hermes memory status     # 检查活动的提供者

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

关系图谱

反向链接