给 Hermes 装灵魂只要三个 Markdown 文件,大多数人第一步就写错了
三个纯文本文件,加起来一千三百个 token 上下,决定了一件事,你的 Agent 到底是谁。
SOUL.md 定它用什么腔调说话,MEMORY.md 记它学到的环境事实,USER.md 存它对你的了解。这套东西在 Hermes Agent 里没有数据库也没有向量库,就是三个 Markdown 文件,躺在 ~/.hermes/ 目录下,任何编辑器都能改。
我第一次动笔写人设的时候,把项目路径、代码规范、工作流触发词全塞了进去,洋洋洒洒两千字,自我感觉特别完备。跑了几天发现 Agent 越来越怪,换个项目人格就变,前面教过的偏好转头就忘。后来把加载逻辑翻了一遍才反应过来,问题不在写太少,在一开始就没搞清楚三个文件各管哪一摊。
这篇按交付视角,把三层记忆的机制、写法分寸、记忆冻住的原因、安全面和调优清单一次讲完,都是拿踩坑换来的。
三个文件,各管一摊
先看容量账。SOUL.md 是身份层,存人格、语气、行为边界,超过两万字符会被直接截断。MEMORY.md 是事实层,存环境事实、项目约定、工具变通办法,上限 2200 字符,约合 800 token,装 8 到 15 条。USER.md 是画像层,存你的姓名角色、沟通偏好、讨厌的东西,上限 1375 字符,约合 500 token。
三个文件都只在 Hermes 主目录加载,MEMORY.md 和 USER.md 收在 memories 子目录里,不跟项目目录走。这是有意为之,人设属于 Hermes 实例本身,不属于某个项目,切项目不会把人格也切掉。
加载的时候有一条判断规则,老雷的建议是把这句话背下来,跟你到处走的放 SOUL.md,只属于某个项目的放 AGENTS.md。SOUL.md 是系统提示词的一号槽位,只要文件里有内容,就直接顶掉 Hermes 内置的默认身份。把项目路径、仓库规范塞进 SOUL.md,轻则稀释人设,重则顶着两万字符上限被截断,得不偿失。
MEMORY.md 的维护走 memory 工具,只有 add、replace、remove 三个操作,没有 read。原因很直白,记忆在会话启动时整体注入系统提示词,Agent 时时刻刻都看得见,不需要读。replace 和 remove 用短子串匹配,匹配到多条会报错,逼你写得更精确。存什么有讲究,用户偏好、机器环境、纠正过的错误、项目约定这类值得留,琐碎对话、能随时重新发现的事实、大段日志别往里塞。写法上有条好标准,紧凑、信息密集、可操作,比如记下机器是 macOS 14 加 Homebrew 加 Docker,比一句「用户有个项目」值钱一百倍。
USER.md 管的是你这个人。简洁还是详细、要不要术语、道歉会不会让你烦,都归它。社区教程里有个顺手的技巧,跑 /insights 命令,Hermes 会从交互历史里自动提炼画像补进来。

SOUL.md 的分寸感
官方推荐的结构是四段式,Identity 写它是谁,Style 写语气和沟通风格,Avoid 写不该做的事,Defaults 写遇到模糊情况的默认动作。听着像模板,重点其实在分寸,只写真正改变默认行为的内容。
社区沉淀了四条铁律。对语气要具体,写 Direct and no apologies,别写 friendly。说你不想要什么,一句不要用列表符号,比十句正面指令都管用。标明你的专业水平,说自己是高级工程师,它就不再解释基础概念。保持简短,目标三十秒读完,Hermes 本来就在努力做到有帮助和清晰,你写的每一行都得有增量。
SOUL.md 的价值不是重述默认值,是加上真正改变行为的个性。删掉不像你要的声音,比往上堆内容更重要。
和它容易混淆的是 /personality 预设。Hermes 内置了 14 种人格,从通用助手到硬汉侦探叙事都有,一条 /personality pirate 就能临时切到海盗腔,退出会话自动恢复。一个是持久基线人格,一个是会话级皮肤,拿预设当人设用,等于给 Agent 天天换脸。
不想从零写,社区有现成的。Soul Forge 插件带 8 种策划模板,还支持用自然语言描述理想 Agent 自动生成完整 SOUL.md,两条安装命令就能跑起来。ClawSouls 模板市场里连「15 年经验的后端工程师」这种带技术判断偏好的高级模板都有,拿来当起点比自己憋快得多。
记忆为什么是冻住的
Hermes 的记忆是冻结快照模式,系统提示词里的记忆内容在会话启动那一刻拍一张快照,之后整个会话不再更新。会话中 memory add 写入的内容会落盘,但不进当前这份系统提示词,下次开会话才生效。工具的响应会反映磁盘实时状态,所以 Agent 知道自己刚写了什么,只是这场对话里它继续按旧快照行事。
这不是偷懒,是笔账。Hermes 用 Anthropic 的 cache_control 断点做提示词缓存,系统提示词加末尾三条消息组成滚动窗口,多轮对话的输入成本能降 75% 左右。记忆要是每次写入都去改系统提示词,缓存当场失效,75% 的省费直接归零。冻结快照是省钱的代价,不是缺陷。
系统提示词一共 10 层,分三组。稳定层是身份加工具指引,装新技能或改 SOUL.md 才动。上下文层是项目文件,AGENTS.md、CLAUDE.md、.cursorrules 这类,切项目才动,全部要过安全扫描、截断和前置信息剥离。易变层是冻结的记忆快照、技能索引、时间戳、平台提示,每次开会话重建。你就想象一叠纸,最上面是身份证,中间是项目手册,最底下是笔记本,每次新会话把整叠纸拍照交给模型,之后整场对话只看这张照片。
1300 个 token 装不下的,有两条退路。一条是 session_search,全部会话存进 state.db 这个 SQLite 库,FTS5 全文检索,官方口径单次查询 20 毫秒上下,按需调用不占常驻 token。另一条是九种外部记忆提供商,本地零依赖选 Holographic,SQLite 起家,带矛盾检测和信任评分,不可靠的记忆衰减得更快;要跨会话用户建模选 Honcho,方言式推理能维护多 Agent 各自独立的画像。注意同一时间只能激活一个外部提供商,内置那三个文件始终并行跑,不会被替换。

指针架构,生产环境跑出来的懒办法
机制讲完说实践。我的知识库每天被 Claude Code 改上百个文件,品牌信息、工具列表、工作流触发词随时在动。把这些硬编码进 SOUL.md 和 MEMORY.md,过时的记忆会让 Agent 基于错误前提做决策,比没有记忆还危险。
方案是把三个配置文件的内容归零,只存路径和导航方法,所有事实让 Hermes 对话中现场 read_file 去读。
SOUL.md 写身份、语言规则,再加四步导航,先读总路由表,按问题里的触发词定位子目录,读子目录的路由继续往下,找到具体文件现场取内容。不在 SOUL、MEMORY、USER 里复制知识库内容,知识库是唯一真值源,这条红线是指针架构的灵魂。配置文件里放的是怎么找到内容的方法,不是内容本身。Claude Code 改了知识库的任何文件,Hermes 下次对话自动感知,维护成本为零。
USER.md 一共三行。身份一句话,沟通偏好一句话,详细档案给一个知识库路径指针,不在画像里堆细节。
配套的 Discord 服务器按职责拆成 12 个频道,每个频道的 channel_prompts 只放导航指令。品牌判断不靠模型猜,进频道即路由,把开放问题变成确定性匹配,这一招在官方文档和社区案例里都找不到对标。
还有个坑值得单独记一笔。上下文压缩默认跟主模型走,主模型限流返回 429 的时候,压缩任务跟着挂,Agent 一口气丢掉整个对话上下文,别问老雷是怎么知道的。解法是给 auxiliary 的视觉和压缩两个辅助位显式配独立 Provider,视觉给 Gemini Flash,压缩单独配一份,切模型只改一处。
安全面和调优清单
记忆条目会被注入系统提示词,这就成了最隐蔽的提示词注入向量,社区安全分析把它排在传统扫描器够不着的攻击面第一位。别扭的地方在于,记忆是 Agent 自己写进去的,看起来完全合法。有人往记忆里塞一句 ignore previous instructions,你的 Agent 就慢慢变节,查配置查日志都查不出来。
Hermes 的对策是三道扫描,SOUL.md 加载时、记忆写入前、上下文文件加载时各一道,查注入模式、凭据泄露、SSH 后门、不可见 Unicode 字符。保险起见把 memory 的写入审批打开,每条写入先暂存,用 /memory 的 approve 命令一条条放行。多平台部署的务必开,Discord 和 Telegram 里第三方发的消息也可能触发记忆写入,你不知道屏幕对面是谁。
调优官方给了四步,我压缩成一份可以今天执行的清单。
一,别从空白写起,首次启动 Hermes 会自动生成一份默认 SOUL.md,从它开始改。
二,删掉不像你要的声音,不想要温和语气,就把相关描述整个删了。
三,加 4 到 8 行核心定义,语气写具体,多写不要什么,标明专业水平。
四,对话里迭代,Agent 解释太多就加一行保持紧凑,太客气就加一行不要道歉不要对冲。
排障也是四条。改了没生效,先确认改的是 ~/.hermes/SOUL.md 而不是仓库里的同名文件,再确认重启了会话,冻结快照模式下中途改文件不生效。部分内容被忽略,查三样,被更高优先级指令覆盖、文件内部指引冲突、超长截断、触发安全扫描,挨个排除。Agent 变得太项目化,把项目指令挪去 AGENTS.md,SOUL.md 只留人格。记忆满了,工具会报错并列出当前用量,合并冗余、删掉过时条目再试,容量到 80% 就该主动精简。
说到底,人设工程不是把 Agent 调教得更聪明,是把你的预期写清楚。三个 Markdown 文件,成本接近零,效果却能贯穿每一次会话,这是我在 Agent 落地里见过性价比最高的一件事。它也正好印证了老雷AI实验室反复讲的那条路径,把确定性的规则交给文件,把不确定的判断交给模型。
今天就可以动手,打开 ~/.hermes/ 看一眼你的三个文件,把项目路径删掉,把语气写具体。十分钟后,你的 Agent 就换了一副性格。
