永久记忆 (Persistent Memory)

Hermes Agent 拥有受限且经过策划的记忆，可以跨会话持久存在。这使得它能够记住您的偏好、项目、环境以及它所学到的知识。

运作原理

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

文件	用途	字符限制
MEMORY.md	代理的个人笔记 —— 环境事实、约定俗成的习惯、学到的知识	2,200 字符 (~800 tokens)
USER.md	用户概况 —— 您的偏好、沟通风格、期望	1,375 字符 (~500 tokens)

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

信息

字符限制旨在让记忆保持聚焦。当记忆存满时，代理会通过合并或替换条目来为新信息腾出空间。

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

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

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
用户的项目是一个位于 ~/code/myapi 的 Rust Web 服务，使用 Axum + SQLx
§
这台机器运行 Ubuntu 22.04，安装了 Docker 和 Podman
§
用户偏好简洁的回答，不喜欢冗长的解释

该格式包含：

• 显示所属存储库的页眉（MEMORY 或 USER PROFILE）
• 显示使用百分比和字符计数，以便代理了解剩余容量
• 使用 §（分节符号）分隔符区分各条目
• 条目可以包含多行内容

静态快照模式： 系统提示词中的注入内容在会话开始时捕捉一次，且在会话中途 绝不改变。这是有意为之的 —— 这样做可以保留 LLM 的前缀缓存（Prefix Cache）以提升性能。当代理在会话期间添加或删除记忆条目时，更改会立即持久化到磁盘，但直到下一个会话开始前，这些更改都不会出现在系统提示词中。工具的响应则始终显示实时状态。

记忆工具操作

代理通过 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 —— 代理个人笔记

记录代理需要记住的有关环境、工作流及经验教训的信息：

• 环境事实（操作系统、工具、项目结构）
• 项目约定与配置
• 已发现的工具特性与变通方案（Workarounds）
• 已完成任务的日志条目
• 行之有效的技能与技巧

user —— 用户概况

记录有关用户身份、偏好及沟通风格的信息：

• 姓名、角色、时区
• 沟通偏好（简洁 vs 详细，格式偏好）
• 雷区及需要避免的事项
• 工作流习惯
• 技术水平能力

哪些该保存，哪些该忽略

应当保存（主动进行）

代理会自动保存信息 —— 您无需专门要求。当它学到以下内容时会进行保存：

• 用户偏好：“我更喜欢 TypeScript 而非 JavaScript” → 保存至 user
• 环境事实：“此服务器运行带有 PostgreSQL 16 的 Debian 12” → 保存至 memory
• 修正信息：“执行 Docker 命令时不要使用 sudo，用户已在 docker 组中” → 保存至 memory
• 约定俗成：“项目使用制表符（tabs）、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": "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” 条目合并为一个综合的项目描述条目。

优秀内存条目的实际案例

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

# Good: Packs multiple related facts
User runs macOS 14 Sonoma, uses Homebrew, has Docker Desktop and Podman. Shell: zsh with oh-my-zsh. Editor: VS Code with Vim keybindings.

# Good: Specific, actionable convention
Project ~/code/api uses Go 1.22, sqlc for DB queries, chi router. Run tests with 'make test'. CI via GitHub Actions.

# Good: Lesson learned with context
The staging server (10.0.1.50) needs SSH port 2222, not 22. Key is at ~/.ssh/staging_ed25519.

# Bad: Too vague
User has a project.

# Bad: Too verbose
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 全文搜索。
• 搜索查询会返回相关的过往对话，并由 Gemini Flash 进行总结。
• 代理可以找到数周前讨论过的内容，即使这些内容不在其活跃内存中。
• 智能体还可以在它发现的任何会话中进行向前/向后滚动。

hermes sessions list    # Browse past sessions

请参阅 会话搜索工具 以了解三种调用形态（发现 discovery / 滚动 scroll / 浏览 browse）以及响应格式。

session_search 与 memory 对比

特性	持久化记忆 (Persistent Memory)	会话搜索 (Session Search)
容量	总计约 1,300 个 Token	无限制（涵盖所有会话）
速度	即时（内置于系统提示词中）	~20ms FTS5 查询，~1ms 滚动
成本	每次提示词都会产生 Token 费用	免费 —— 无需 LLM 调用
使用场景	需要始终保持在上下文中的关键事实	查找 “我们上周是否讨论过 X？” 这类需要回忆过去对话细节的查询
管理方式	由智能体手动策划	自动 —— 存储所有会话
Token 成本	每个会话固定（约 1,300 个 Token）	按需（仅在需要时搜索）

持久化 记忆 用于应始终处于上下文中的关键事实；会话搜索 则用于需要智能体回溯过去对话具体内容的查询。

配置

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

外部记忆提供商

对于超出 MEMORY.md 和 USER.md 的更深入、持久的记忆，Hermes 内置了 8 个外部记忆提供商插件——包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。

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

hermes memory setup      # 选择一个提供商并进行配置
hermes memory status     # 检查当前启用了什么

有关每个提供商的完整详情、设置说明和对比，请查看 记忆提供商指南。