一、上下文文件：告诉 Agent「你是谁、在什么项目里」

1. 什么是上下文文件

Hermes 会自动发现并加载一些说明文件，用来描述「项目规则」和「Agent 人格」。分两类：

  • 项目上下文文件：描述当前仓库/目录的规则约定

  • SOUL.md：描述这个 Hermes 实例的人格和沟通风格

2. 支持的上下文文件

文件

用途

优先级

.hermes.md / HERMES.md

Hermes 专用项目说明

最高

AGENTS.md

项目说明、架构、约定

次之

CLAUDE.md

兼容 Claude Code

再次

.cursorrules

兼容 Cursor 规则

再次

SOUL.md

Agent 人格（独立加载）

不参与竞争

3. 加载流程

启动加载（会话开始时）：

  1. 从当前目录向上查找项目上下文文件（到 git root）

  2. 按 .hermes.md → AGENTS.md → CLAUDE.md → .cursorrules 优先级只加载一种

  3. 超过 20,000 字符会截断：保留前 70% 和后 20%

渐进加载（会话进行中）：Agent 调用工具碰到文件路径时，会从路径所在目录向上查 5 层父目录，按优先级加载首个匹配的文件（超过 8,000 字符截断）。

重要经验：重要规则要放在文件开头或结尾，因为截断时保留的是头尾。

4. 安全扫描（防提示词注入）

Hermes 加载上下文文件前会做安全扫描，命中以下内容会阻止加载：

  • 指令覆盖（"ignore previous instructions"）

  • 欺骗行为（"do not tell the user"）

  • 系统提示词覆盖

  • 隐藏 HTML 注释 / 隐藏 div

  • 凭证外泄（curl ... $API_KEY）

  • 敏感文件读取（cat .env）

  • 不可见字符（零宽空格等）

被阻止的文件位置会替换成 [BLOCKED: ... prompt injection ...]。

5. @ 上下文引用

对话中可以用 @file 和 @url 注入上下文：

@file:README.md  这个项目 README 写了什么？
@url:https://example.com/doc  根据这个文档回答

配合 Tab 补全可以快速引用文件路径。

6. SOUL.md 与人格

SOUL.md 是 Agent 的「灵魂」，拼在系统提示词开头。默认在 ~/.hermes/SOUL.md。

适合写：语气、风格、直接程度、默认互动方式、不希望出现的表达。

不适合写：项目规则、文件路径（这些放 AGENTS.md）。

/personality 可以临时切换人格（不改 SOUL.md），内置 14 种：

人格

说明

helpful

友好通用助手

concise

简短直接

technical

技术专家模式

teacher

耐心教学

creative

创新发散

philosopher

哲学家式追问

...

还有 kawaii、pirate、shakespeare、noir 等

二、持久记忆：跨会话记住关键信息

1. 记忆系统是什么

Hermes 有一套「有容量上限、由 Agent 自己维护」的记忆系统。它会跨会话保存你的偏好、项目环境、工具习惯，并在新会话开始时注入系统提示词。

记忆由两个文件组成，在 ~/.hermes/memories/：

文件

用途

上限

MEMORY.md

Agent 的笔记：环境事实、项目约定、经验教训

2,200 字符

USER.md

用户画像：你的信息、风格、习惯

1,375 字符

2. 记忆长什么样

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

§ 分隔不同条目，标题显示容量占用。

3. memory 工具的用法

Agent 通过 memory 工具管理记忆，三个动作：

动作

用途

add

添加新条目

replace

替换（用 old_text 匹配）

remove

删除（用 old_text 匹配）

例子（Agent 内部调用）：

memory(action="replace", target="memory",
       old_text="dark mode",
       content="User prefers light mode in VS Code, dark mode in terminal")

4. 什么该记、什么不该记

该记：

  • 用户偏好（"用户喜欢 TypeScript"）

  • 环境事实（"这台服务器跑 Debian 12 + PostgreSQL 16"）

  • 用户纠正（"Docker 不要用 sudo，已在 docker 组"）

  • 项目约定（"tabs、120 字符行宽"）

  • 显式要求（"API key 每月轮换"）

不该记：

  • 太模糊的信息

  • 能轻易重新查到的通用知识

  • 大段代码、日志

  • 临时任务状态、一次性路径

  • 已写在 SOUL.md / AGENTS.md 里的内容

写法要点：写成陈述性事实，不是指令。

  • ✓ User prefers concise responses

  • ✗ Always respond concisely

5. 记忆 vs 会话搜索

对比

持久记忆

session_search

容量

很小（~1300 tokens）

所有历史会话

速度

开始时直接注入

按需查询（~20ms）

用途

一直要用的关键事实

查过去某次讨论

简单记：memory 存"以后经常要用的稳定事实"，session_search 答"上次我们聊过啥"。

6. 外部记忆提供商（进阶）

内置记忆不够用的话，可以接入外部记忆提供商（同一时间只能启用一个）：

hermes memory setup    # 交互式配置
hermes memory status   # 查看状态
hermes memory off      # 关闭

入门推荐 honcho 或 mem0；需要知识图谱、实体关系再考虑 hindsight；要混合检索、冲突检测看 retaindb 等。