HermesAgent偏好持久化：USER.md用户画像配置教程
如果你的 Hermes Agent 在多次对话后，依然记不住你的任务习惯、输出偏好或者身份特征，这通常意味着它的“用户画像”配置文件——也就是 USER.md 文件——没有正确设置或加载。别担心，这并非智能体“健忘”，而是配置环节需要校准。下面，我们就来一步步排查并解决这个问题。
一、确认 USER.md 文件存在并初始化
USER.md 是 Hermes 记忆系统中用于存储用户静态画像的核心文件。它必须存在于一个特定的目录下，并且内容格式正确，智能体才能读取并记住你的偏好。
首先，打开终端，执行以下命令检查文件是否存在：ls -l ~/.hermes/memories/USER.md。
如果系统提示“No such file”，说明文件尚未创建。这时，你需要立即创建它：touch ~/.hermes/memories/USER.md。
文件创建后，还不能是空的。你需要向其中写入最基本的结构化信息，为智能体提供一个初始的“用户画像”。可以执行这样一条命令来快速初始化：echo "# 用户画像n- 姓名: 张三n- 称呼偏好: 杰森n- 常用格式: Markdownn- 语言偏好: 中文（简体）" > ~/.hermes/memories/USER.md。当然，你可以将“张三”、“杰森”等信息替换成你自己的。
二、验证 USER.md 的自动加载状态
文件存在只是第一步。如果主配置文件没有指明要加载它，Hermes 在启动时就会忽略这个文件，导致所有配置信息形同虚设。因此，双向对齐配置层和文件层至关重要。
接下来，编辑 Hermes 的主配置文件：nano ~/.hermes/config.yaml。
找到配置文件中的 memory: 区块。请仔细确认，其下必须包含以下两行内容（注意严格的缩进格式）：
enable: true
files: ["memories/MEMORY.md", "memories/USER.md"]。
保存并退出编辑器后，运行一个诊断命令来验证：hermes doctor --check memory。观察命令的输出，如果一切正常，你应该能看到类似 ✓ User profile loaded from USER.md 的成功提示。
三、通过网关交互动态更新 USER.md
除了手动编辑文件，Hermes 还提供了一个更便捷的方式：通过微信、飞书等消息平台，用自然语言直接告诉它你的新偏好。这个功能依赖于网关模块来解析语义，并自动将信息持久化到 USER.md 文件中。
首先，确保你已经执行过 hermes gateway setup 并成功接入了飞书机器人或微信 Cloudbot。
然后，在你已连接的聊天窗口中，发送一条包含“记住”关键词的指令。例如：请记住我叫林薇，喜欢用表格输出结果，拒绝使用 YAML 格式。
发送后，等待大约5秒钟，让系统完成处理。之后，你可以通过命令检查文件是否已更新：cat ~/.hermes/memories/USER.md | tail -n 3。如果操作成功，文件的末尾应该已经追加了你刚刚告知的新条目。
四、修复 USER.md 编码与权限异常
在某些 Linux 或 WSL 环境中，如果默认的语言环境设置不当，可能会导致写入 USER.md 的中文内容出现乱码，进而使解析失败。同时，不正确的文件权限也可能阻止 Hermes 进程读取该文件。
针对编码问题，可以尝试强制设置 UTF-8 环境变量：export LANG=en_US.UTF-8; export LC_ALL=en_US.UTF-8。
如果怀疑文件本身是其他编码（如 GBK），可以尝试用以下命令转换并重写：iconv -f GBK -t UTF-8 ~/.hermes/memories/USER.md 2>/dev/null | tee ~/.hermes/memories/USER.md。
针对权限问题，一个简单的修正命令是：chmod 644 ~/.hermes/memories/USER.md。这确保了文件所有者有读写权限，而组用户和其他用户只有读取权限，通常这是安全且足够的。
五、绕过文件加载失败的临时注入方案
当 config.yaml 的加载机制出现异常，一时又难以定位根本原因时，可以采用一个临时方案：直接通过环境变量向当前会话注入用户标识。这种方法能让你的偏好立即生效，非常适合用于调试或应急场景。
在启动 Hermes 之前，先设置相关的环境变量。例如：export HERMES_USER_NAME="王磊"; export HERMES_OUTPUT_STYLE="bullet points"。
接着，以注入环境变量的模式启动 CLI：hermes chat --inject-env。
启动后，在对话中输入调试命令：/debug show user。如果操作成功，命令的输出中应该会包含你刚才设置的那些变量值及其对应的语义解释。