持久化内存

Hermes Agent 拥有有界且经过筛选的持久化内存，可在不同会话间保持记忆。这使得它能够记住您的偏好、项目、环境以及所学知识。

工作原理

Agent 的内存由两个文件组成：

文件	用途	字符限制
MEMORY.md	Agent 的个人笔记 —— 环境事实、约定、学习到的内容	2,200 字符（约 800 个 token）
USER.md	用户档案 —— 您的偏好、沟通风格、期望	1,375 字符（约 500 个 token）

这两个文件均存储在 ~/.hermes/memories/ 目录下，并在会话开始时作为冻结快照注入系统提示中。Agent 通过 memory 工具自行管理其内存 —— 可添加、替换或删除条目。

信息

字符限制有助于保持内存聚焦。当内存已满时，Agent 会合并或替换条目以腾出空间给新信息。

内存在系统提示中的呈现方式

在每个会话开始时，内存条目会从磁盘加载，并以冻结块的形式渲染到系统提示中：

══════════════════════════════════════════════
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 参数只需是能唯一标识一个条目的子字符串即可：

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

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

• 环境事实（操作系统、工具、项目结构）
• 项目约定和配置
• 发现的工具缺陷及绕行方案
• 已完成任务的日记条目
• 有效的技能与技术

user —— 用户档案

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

• 姓名、角色、时区
• 沟通偏好（简洁 vs 详细、格式偏好）
• 烦恼点及应避免事项
• 工作习惯
• 技术熟练程度

应保存 vs 忽略的内容

应保存（主动保存）

Agent 会自动保存 —— 无需主动请求。它在学习时会保存以下内容：

• 用户偏好： “我更喜欢 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"
}

此时 Agent 应执行以下步骤：

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 与内存的区别

特性	持久内存	会话搜索
容量	总计约 1,300 个 token	无限制（所有会话）
速度	即时（位于系统提示中）	需要搜索 + LLM 摘要
使用场景	关键事实始终在上下文中	查找特定的过往对话
管理方式	由代理手动维护	自动化 — 所有会话均被存储
令牌成本	每会话固定（约 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

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