记忆系统

Hermes Agent 拥有有限且经过筛选的持久记忆，能够在会话之间保持。这让 Agent 可以记住你的偏好、项目、环境和它学到的知识。

工作原理

两个文件构成了 Agent 的记忆：

文件	用途	字符限制
MEMORY.md	Agent 的个人笔记——环境事实、约定、学到的经验	2,200 字符（约 800 Token）
USER.md	用户画像——你的偏好、沟通风格、期望	1,375 字符（约 500 Token）

两者都存储在 ~/.hermes/memories/ 中，并在会话开始时作为冻结快照注入系统提示。Agent 通过 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）
使用百分比和字符计数，让 Agent 了解容量
各条目用 §（章节符号）分隔符分隔
条目可以多行

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

记忆工具操作

Agent 使用 memory 工具的以下操作：

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

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

子串匹配

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 — Agent 的个人笔记

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

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

user — 用户画像

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

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

保存 vs 跳过的内容

主动保存这些

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

用户偏好：“我更喜欢 TypeScript 而非 JavaScript” → 保存到 user
环境事实：“这台服务器运行 Debian 12 和 PostgreSQL 16” → 保存到 memory
纠正：“不要用 sudo 运行 Docker 命令，用户在 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"
}

Agent 应该：

阅读当前条目（在错误响应中显示）
识别可以移除或合并的条目
使用 replace 将相关条目合并为更短的版本
然后添加新条目

最佳实践：当记忆使用超过 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，Agent 还可以使用 session_search 工具搜索其过去的对话：

所有 CLI 和消息会话存储在 SQLite（~/.hermes/state.db）中，支持 FTS5 全文搜索
搜索查询返回数据库中的实际消息——不经过 LLM 摘要，不截断
Agent 可以找到几周前讨论的内容，即使不在其活跃记忆中
Agent 还可以在找到的任何会话中前后滚动浏览

hermes sessions list  # 浏览过去的会话

session_search vs memory

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

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

配置

# 在 ~/.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   # 检查激活状态