本文介绍 Hermes Agent 的上下文与记忆文件系统，包括 SOUL.md、AGENTS.md、/personality、MEMORY.md、USER.md 的作用、加载机制与最佳实践。
相关文件位置：~/.hermes/

整体概览

Hermes Agent 有一套完整的”认知文件”系统，分成三类：

类型 文件 作用 生命周期
身份 SOUL.md Agent 是谁、怎么说话 全局永久
项目上下文 AGENTS.md / .hermes.md 等 当前项目的规范与指令 跟随项目
跨会话记忆 MEMORY.md / USER.md Agent 主动积累的事实与用户画像 跨会话持久

三者各司其职，互不替代。理解清楚之后，配置起来会非常顺手。

SOUL.md ⭐️：Agent 的灵魂

SOUL.md 是 Agent 的主要身份，占据系统提示词的第 #1 槽位，完整替换内置的默认身份。它定义的是 Hermes 这个 Agent “是谁”——语气、表达风格、面对分歧时的态度……这些性格层面的东西全在这里。

文件位置

1
2
3
~/.hermes/SOUL.md
# 使用自定义 HERMES_HOME 时：
$HERMES_HOME/SOUL.md

Hermes 只从 HERMES_HOME 加载 SOUL.md，不扫描工作目录。这是刻意的设计——确保 Agent 的人格不会因切换项目而悄悄改变。

关键行为

  • 首次启动时，若文件不存在，Hermes 会自动生成一份默认的 SOUL.md
  • 已有文件永远不会被自动覆盖
  • 文件为空时，Hermes 回退到内置默认身份（”你是 Hermes Agent…”）
  • 内容经过安全扫描和截断后原样注入系统提示词，不添加任何包装文字

应该写什么

✅ 适合放在 SOUL.md：

  • 语气风格（简洁、直接、温和等）
  • 沟通偏好（是否主动反驳、如何处理不确定性）
  • 需要全局回避的表达方式
  • 面对歧义时的默认处理方式

**❌ 不适合放在 SOUL.md**（这些应该去 AGENTS.md）：

  • 具体项目的架构说明
  • 文件路径、端口号、命令
  • 临时性的工作流指令

一个好用的判断标准：如果这件事应该在所有项目里都生效，放 SOUL.md；如果只属于某个项目，放 AGENTS.md。

SOUL.md 示例

官方给了几种风格模板，挑几个实用的：

务实工程师风

1
2
3
4
5
6
7
8
9
10
11
12
13
你是一位务实的高级工程师。
你更关注正确性和实际可行性，而不是听起来很厉害。

## 风格
- 直接了当
- 简洁明了，除非复杂度需要深入解释
- 直接指出不好的想法
- 偏好实用的权衡，而非理想化的抽象

## 避免
- 阿谀奉承
- 炒作语言
- 过度解释显而易见的事情

耐心讲师风

1
2
3
4
5
6
7
8
你是一位耐心的技术老师。
你关注的是理解，而不是表现。

## 风格
- 清晰解释
- 在有帮助时使用示例
- 除非用户暗示，否则不假设已有知识
- 从直觉构建到细节

严格审查风

1
2
3
4
5
6
7
8
你是一位严格的审查者。
你公正，但不会软化重要的批评。

## 风格
- 直接指出薄弱的假设
- 优先考虑正确性而非和谐
- 明确说明风险和权衡
- 偏好直率的清晰，而非模糊的外交

官方推荐的结构：

1
2
3
4
5
6
7
8
9
10
11
# 身份
Hermes 是谁。

# 风格
Hermes 应该如何表达。

# 避免
Hermes 不应该做什么。

# 默认
Hermes 在出现歧义时应该如何处理。

迭代建议

官方给了一个实用的调整流程：

  1. 先看看自动生成的默认文件
  2. 删掉不符合你期望的部分
  3. 加 4–8 行真正定义你想要的语气
  4. 实际聊一段时间
  5. 根据感受再调整

一次性设计完美人格很难，迭代反而更有效。

AGENTS.md ⭐️：项目专属指令

AGENTS.md 是最常用的项目上下文文件，告诉 Agent 这个项目的架构、编码规范和注意事项。

优先级系统：项目上下文只加载其中一种（第一个匹配优先）：

1
.hermes.md / HERMES.md  →  AGENTS.md  →  CLAUDE.md  →  .cursorrules

SOUL.md 始终独立加载，不参与这个优先级竞争。

渐进式子目录发现 ⭐️

这是 Hermes 一个比较独特的设计。启动时只加载工作目录的 AGENTS.md，但当 Agent 在会话中读取到子目录文件时，会实时发现并注入对应子目录的 AGENTS.md：

1
2
3
4
5
6
7
8
my-project/
├── AGENTS.md              ← 启动时加载（注入系统提示词）
├── frontend/
│   └── AGENTS.md          ← Agent 读取 frontend/ 文件时自动发现
├── backend/
│   └── AGENTS.md          ← Agent 读取 backend/ 文件时自动发现
└── shared/
    └── AGENTS.md          ← Agent 读取 shared/ 文件时自动发现

这样做的好处：

  • 不污染系统提示词：子目录的指令只在需要时才出现
  • 保持 Prompt 缓存稳定：系统提示词在多轮对话中保持不变，有利于 token 缓存命中

AGENTS.md 示例

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
这是一个 Next.js 14 前端 + Python FastAPI 后端的 Web 应用。

## 架构
- 前端：Next.js 14 App Router，位于 `/frontend`
- 后端：FastAPI，位于 `/backend`，使用 SQLAlchemy ORM
- 数据库：PostgreSQL 16
- 部署：Hetzner VPS 上的 Docker Compose

## 代码规范
- 前端全部使用 TypeScript strict 模式
- Python 遵循 PEP 8，所有函数必须加类型注解
- API 响应统一格式：`{data, error, meta}`
- 测试放在 `__tests__/`（前端）或 `tests/`（后端）

## 重要注意事项
- 禁止直接修改数据库迁移文件，必须用 Alembic 命令
- `.env.local` 包含真实 API 密钥，不要提交
- 前端端口 3000，后端端口 8000，数据库端口 5432

AGENTS.md 最佳实践

  1. 控制在 20K 字符以内，Agent 每轮都会读
  2. 用 ## 标题分区：架构、规范、注意事项
  3. 给出具体示例，而非笼统描述
  4. 明确说明不该做的事
  5. 列出关键路径和端口
  6. 项目变化时及时更新——过期的上下文比没有上下文更糟

/personality：会话级临时切换

与 SOUL.md 的区别

SOUL.md /personality
持久性 永久，跨所有会话 仅当前会话
作用 Agent 的基础身份 临时模式叠加
典型场景 设定你想要的默认风格 临时切换为讲师、创意模式等

简单说：SOUL.md 是基础人格，/personality 是临时切换。

用法

在 CLI 或任何消息平台中直接输入：

1
2
3
4
/personality
/personality concise
/personality technical
/personality teacher

内置人格预设

Hermes 自带一批预设，随时可用：

名称 风格
helpful 友好的通用助手
concise 简短直接
technical 详尽准确的技术专家
creative 发散思维
teacher 耐心讲解，多举例
kawaii 卡哇伊风格 ★
catgirl Neko-chan 风格，nya~
pirate 海盗船长风
philosopher 对每个问题深度思考
hype 极度亢奋高能

自定义人格预设

也可以在 config.yaml 里定义自己的预设：

1
2
3
4
5
agent:
  personalities:
    codereviewer: >
      你是一位细致的代码审查者。识别 bug、安全问题、
      性能问题和不清楚的设计选择。要精确且具有建设性。

然后用 /personality codereviewer 切换。

推荐工作流

  1. 在 ~/.hermes/SOUL.md 维护一份稳定的全局人格
  2. 每个项目根目录放 AGENTS.md，Monorepo 在子目录也放
  3. 临时模式切换用 /personality，不污染 SOUL.md

MEMORY.md & USER.md ⭐️：跨会话记忆

这两个文件是 Hermes 的持久记忆，跨会话保留信息。和 SOUL.md / AGENTS.md 的区别在于：这两个文件不是你手动写的，而是 Agent 在对话中主动积累的。

文件 存储内容 字符上限
MEMORY.md Agent 的个人笔记——环境事实、项目约定、踩过的坑 2,200 字符（约 800 token）
USER.md 用户画像——你的偏好、沟通风格、技术背景 1,375 字符（约 500 token）

两个文件都存在 ~/.hermes/memories/，每次会话开始时作为冻结快照注入系统提示词。

注入效果示例

每次对话开始，Agent 会看到类似这样的内容：

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

Header 里显示了当前使用量（67%），Agent 能感知容量，主动管理。

“冻结快照”机制

记忆内容在会话开始时加载一次，会话中途不更新（即便 Agent 在本次对话里新增了记忆条目，也要等下一次会话才能在系统提示词中看到）。这是刻意设计的：保持系统提示词稳定，有利于 LLM 的前缀缓存性能。工具调用的响应里始终显示最新状态。

Agent 自动管理记忆

Agent 通过 memory 工具自主管理这两个文件，支持三个操作：

  • add：新增一条记忆
  • replace：用子串匹配找到旧条目，替换为新内容
  • remove：删除不再需要的条目

你不需要手动去写这两个文件，也不需要提醒 Agent 去记——它会主动保存有价值的信息。

哪些内容会被保存

会主动保存（不用你说）：

  • 用户偏好："我更喜欢 TypeScript 而不是 JavaScript" → 存入 USER.md
  • 环境信息："这台服务器运行 Debian 12，装有 PostgreSQL 16" → 存入 MEMORY.md
  • 踩坑修正："不要用 sudo 运行 Docker 命令，用户已在 docker 组中" → 存入 MEMORY.md
  • 项目约定："项目使用 tab 缩进，120 字符行宽，Google 风格文档字符串" → 存入 MEMORY.md
  • 完成记录："2026-01-15 将数据库从 MySQL 迁移到 PostgreSQL" → 存入 MEMORY.md
  • 明确要求："记住我的 API 密钥每月轮换一次" → 存入 MEMORY.md

不会保存（刻意跳过）：

  • 太模糊的信息：”用户问了关于 Python 的问题”
  • 搜一下就能查到的事实：”Python 3.12 支持 f-string 嵌套”
  • 大段代码/日志/数据表
  • 只在本次会话有用的临时信息
  • SOUL.md 和 AGENTS.md 里已经有的内容

好的记忆条目长什么样

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# Good：信息密度高，多个相关事实合并
用户运行 macOS 14 Sonoma，使用 Homebrew，装有 Docker Desktop 和 Podman。Shell：zsh + oh-my-zsh。编辑器：VS Code + Vim 键位。

# Good：具体且可操作
项目 ~/code/api 使用 Go 1.22，sqlc 生成数据库查询，chi 路由。运行测试用 'make test'。CI 使用 GitHub Actions。

# Good：踩坑经验，含上下文
staging 服务器 (10.0.1.50) 需要 SSH 端口 2222，不是 22。密钥在 ~/.ssh/staging_ed25519。

# Bad：太模糊
用户有个项目。

# Bad：太啰嗦
2026 年 1 月 5 日，用户让我看他的项目，
位于 ~/code/api。我发现它使用 Go 1.22 版本，并且...

容量管理

存储 上限 典型条目数
MEMORY.md 2,200 字符 8–15 条
USER.md 1,375 字符 5–10 条

容量满时，Agent 会自动合并或删除旧条目来腾出空间。系统提示词的 Header 里显示当前使用百分比，Agent 能感知何时需要整理。

手动配置

1
2
3
4
5
6
# ~/.hermes/config.yaml
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200   # ~800 tokens
  user_char_limit: 1375     # ~500 tokens

三者的对比与分工

这是最容易混淆的地方，整理一张表：

SOUL.md AGENTS.md MEMORY.md / USER.md
写的人 你手动写 你手动写 Agent 自动积累
内容 人格、语气、风格 项目规范、架构、约定 环境事实、用户偏好
范围 全局，跟着 Hermes 实例 跟着项目目录 全局，跨所有会话
变化频率 很少改 项目更新时改 Agent 持续自动更新
放什么 “要直接，别废话” “用 pytest，别用 unittest” “staging 服务器端口是 2222”

完整提示词层级

Hermes 构建每次请求的系统提示词，按以下顺序叠加：

  1. **SOUL.md**（Agent 身份）
  2. 工具感知行为指导
  3. **MEMORY.md + USER.md**（持久记忆）
  4. 技能指导（Skills）
  5. AGENTS.md 等上下文文件
  6. 时间戳
  7. 平台格式提示
  8. 可选覆盖（/personality）

SOUL.md 是整个栈的基础，记忆紧随其后，项目上下文在中层，/personality 在最顶层临时覆盖。

常见问题

Q：编辑了 SOUL.md，但 Hermes 说话方式没变？

检查：

  • 编辑的是 ~/.hermes/SOUL.md 而不是项目目录下某个同名文件
  • 文件不为空
  • 已重启会话
  • 是否有 /personality 覆盖在生效

Q：SOUL.md 里的部分内容 Hermes 好像没在遵守？

可能原因：

  • 文件过长被截断（上限约 20,000 字符）
  • 存在相互矛盾的指令
  • 某些内容触发了安全扫描被屏蔽
  • 更高优先级的指令（如 /personality）覆盖了它

Q：SOUL.md 写着写着变成了项目说明？

把项目相关的内容移到 AGENTS.md，SOUL.md 只留身份和风格。

参考