持久记忆

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]
══════════════════════════════════════════════
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 工具的动作

智能体通过 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")

如果子串匹配到多个条目，工具会返回错误，并要求提供更具体的匹配内容。

两个 target 的区别

memory：智能体自己的笔记

适合保存智能体需要记住的环境、工作流和经验：

• 环境事实（OS、工具、项目结构）
• 项目约定与配置
• 发现的工具特性与绕坑方法
• 已完成任务的简要记录
• 有效的技能和方法

user：用户画像

适合保存与用户身份、偏好、沟通风格相关的信息：

• 姓名、角色、时区
• 沟通偏好（简洁还是详细、格式偏好）
• 反感的表达方式或需要避免的内容
• 工作习惯
• 技术熟练度

应该保存什么，不应该保存什么

应主动保存的内容

智能体会自动保存，无需你额外要求。典型场景包括：

• 用户偏好：如 “我更喜欢 TypeScript 而不是 JavaScript” → 保存到 user
• 环境事实：如 “这台服务器运行 Debian 12 和 PostgreSQL 16” → 保存到 memory
• 纠正信息：如 “Docker 命令不要加 sudo，用户已经在 docker 组里” → 保存到 memory
• 约定：如 “项目使用 tab、120 列宽、Google 风格 docstring” → 保存到 memory
• 已完成的工作：如 “2026-01-15 已把数据库从 MySQL 迁到 PostgreSQL” → 保存到 memory
• 明确要求记住的事情：如 “记住我的 API key 每月轮换一次” → 保存到 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%（系统提示头部可见）时，应先整合条目再继续新增。例如把三条零散的 “project uses 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...

防重复

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

安全扫描

由于记忆内容会被注入系统提示，因此在接受前会先扫描注入和信息外泄模式。若内容匹配风险模式（如 prompt injection、凭据外泄、SSH 后门）或包含不可见 Unicode 字符，就会被拦截。

会话搜索

除了 MEMORY.md 和 USER.md 之外，智能体还可以通过 session_search 工具搜索过去的会话：

• 所有 CLI 与消息平台会话都会存入 SQLite（~/.hermes/state.db），并使用 FTS5 做全文搜索
• 搜索结果会返回相关历史会话，并用 Gemini Flash 做摘要
• 即使某件事不在活跃记忆中，智能体仍可以找回几周前讨论过的内容

hermes sessions list    # Browse past sessions

session_search 与 memory 的区别

特性	Persistent Memory	Session Search
容量	总计约 1,300 tokens	无上限（所有历史会话）
速度	即时可用（已在系统提示中）	需要搜索 + LLM 摘要
使用场景	应始终在上下文中的关键事实	查找某次历史对话中的具体内容
管理方式	由智能体手工维护	自动保存所有会话
Token 成本	每个会话固定约 1,300 tokens	按需发生

Memory 适合存放必须始终在上下文中的关键事实；Session Search 更适合 “我们上周是不是聊过 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

外部记忆大模型提供商（provider）

如果你需要比 MEMORY.md / USER.md 更深层、更持久的记忆能力，Hermes 还内置了 8 个外部记忆大模型提供商（provider）插件，包括 Honcho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover 和 Supermemory。

这些外部大模型提供商（provider）始终与内置记忆并存（不会替代内置记忆），并额外提供知识图谱、语义搜索、自动事实提取、跨会话用户建模等能力。

hermes memory setup      # pick a provider and configure it
hermes memory status     # check what's active

完整信息见 Memory Providers。