持久化记忆

Hermes Agent 具备一套有限但经过筛选的持久化记忆机制，可以跨会话保留关键信息。这让它能够记住你的偏好、项目背景、运行环境，以及在使用过程中积累下来的经验。

工作原理

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

文件	用途	字符限制
MEMORY.md	代理的个人笔记 — 环境事实、约定、已学习内容	2,200 字符 (~800 个 token)
USER.md	用户档案 — 你的偏好、沟通风格与期望	1,375 字符 (~500 个 token)

这两个文件都存储在 ~/.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 只要包含一段足以唯一定位该条目的文本即可：

# If memory contains "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 内容

容量管理

记忆有严格的字符上限，用来控制系统提示的总体体积：

存储	限制	典型条目数量
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

session_search vs memory

特性	持久化记忆	会话搜索
容量	总共约 1,300 个 token	无限（所有会话）
速度	即时（在系统提示中）	需要搜索 + LLM 摘要处理
使用场景	关键事实始终可用	查找特定过去的对话
管理方式	由代理手动维护	自动化——所有会话均存储
Token 成本	每会话固定成本（约 1,300 个 token）	按需（仅在需要时搜索）

记忆 用于关键事实，必须始终处于上下文中。会话搜索 用于“我们上周是否讨论过 X？”这类查询，当代理需要回忆过去对话的具体细节时使用。

配置

# In ~/.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      # pick a provider and configure it
hermes memory status     # check what's active

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