HermesAgent核心文件解析：MEMORY.md与USER.md功能详解

当Hermes Agent在跨会话中表现出“记忆断层”，例如偏好设置丢失或决策逻辑前后矛盾，根源通常指向两个核心记忆文件：MEMORY.md与USER.md。它们可能未被正确识别，或内部结构存在异常。本文将深入解析这两个文件的功能与协同机制。

一、MEMORY.md：存储环境与工作流的客观事实

MEMORY.md是Hermes Agent的“环境知识库”，其核心职责是持久化记录与运行环境紧密关联的、相对静态的客观事实。这包括服务器特定配置、项目常用部署路径、团队内部代码规范，以及特定工具在特定场景下的行为模式。

该文件有明确的容量限制：上限为 2200 字符。这一强制精简的设计旨在确保仅保留最高价值、最具共识的信息，避免冗余内容挤占上下文窗口，从而保障Agent的推理效率。

其运作机制如下：文件默认位于 ~/.hermes/memories/MEMORY.md。每次启动新会话时，系统会将该文件内容作为“冻结快照”注入系统提示词，构成Agent本次对话的初始知识背景。

编辑此文件时，需注重格式规范。建议严格遵循Markdown语法，并确保每条记录为独立的语义单元。例如：- 默认 Python 环境为 conda base，pip 安装包需加 --no-deps 标志。

关键细节：在同一会话过程中，对MEMORY.md的修改会实时写入磁盘，但变更不会立即在当前会话生效。Agent仍使用会话启动时注入的快照版本。新的内容需等待下一个全新会话才会被加载。

二、USER.md：刻画用户行为模式的人设档案

如果说MEMORY.md记录“客观世界”，那么USER.md则刻画“主观用户”。它作为Hermes Agent的“用户心智模型载体”，其目标并非存储原始对话，而是从交互历史中抽象提炼用户的偏好、决策习惯、常用模式及反馈信号。

其容量上限更为严格，仅为 1375 字符。这迫使内容必须高度聚焦，仅记录最能代表用户行为特征的精髓，而非堆砌聊天记录。正是这种设计支撑了Agent“越用越懂你”的个性化体验。

USER.md与MEMORY.md位于同一目录：~/.hermes/memories/USER.md。两者在会话初始化时一同注入，共同塑造Agent本次对话的“知识”与“人格”。

其典型内容结构示例如下：

• - 输出格式偏好：始终以 YAML 结构返回配置项，禁用 JSON
• - 决策历史：在 CI 失败场景下，优先建议重试而非跳过测试
• - 反馈信号：连续两次未修改 Shell 脚本输出即视为认可风格

当Honcho组件启用后，USER.md的更新不再仅依赖手动编辑。Honcho会自动从日常交互日志中学习，提取新模式并持久化至此文件，形成一个持续演进、越用越精准的智能闭环。

三、双文件协同机制：冻结快照与实时写盘分离

MEMORY.md与USER.md共同构成了Hermes Agent基础记忆层的核心。它们的协同依赖于一套“冻结快照注入 + 实时写盘延迟生效”的机制。

简言之，会话开始时加载的是文件的“快照”；会话中的编辑会“实时写盘”保存，但生效需等待下次会话。此设计一举两得：既保障了单次会话中前缀缓存的稳定性，避免了因中途记忆突变引发的逻辑混乱；又确保了所有有价值的记忆都能被保存并延续至未来会话，实现跨会话连贯性。最终目标是防止无限增长的对话内容撑爆上下文窗口，导致核心推理性能下降。

如何排查这对“双子星”是否工作正常？请按以下步骤操作：

第一步，确认文件是否被成功加载。 在终端执行：hermes doctor --check memory。若正常，输出中会显示明确提示：✓ Memory files loaded successfully。

第二步，检查主配置中的记忆功能是否启用。 打开主配置文件 ~/.hermes/config.yaml，定位 memory 相关段落。需确认此处设置为 enable: true，且 files 列表中包含上述两个文件的完整路径。

第三步，验证 Honcho 组件是否激活。 查看环境配置文件 ~/.hermes/.env，检查是否存在 HONCHO_ENABLED=true 这一行。若缺失，需手动添加并重启Hermes进程，以启用USER.md的自动学习能力。