TechBlog

Appearance

持久记忆 ​

在传统的 AI 对话应用中，上下文（Context）通常局限于当前会话窗口，一旦会话结束，Agent 就会“失忆”。Hermes Agent 的持久化记忆（Persistent Memory）旨在打破这一限制，通过文件系统与系统提示词（System Prompt）的巧妙结合，让 Agent 能够跨会话记住你的开发环境、项目架构以及个人偏好及所学知识。

Hermes Agent 的持久记忆保存在本地客户端的文件系统中，具体位于 ~/.hermes/memories/目录下。系统通过两个核心文件来划分记忆的边界：

  1. MEMORY.md(Agent 的个人笔记)

    用途：用于记录 Agent 需要记住的环境、工作流和经验教训信息，例如：环境事实(操作系统、工具、项目结构)、项目配置、代码规范、踩坑经验等“客观信息”。

    容量限制：2,200 字符（约 800 tokens）。

  2. USER.md(用户画像)

    用途：用于记录关于用户身份、偏好和沟通风格的信息，例如用户姓名、角色、时区、沟通风格、偏好设置、工作习惯等“主观信息”。

    容量限制：1,375 字符（约 500 tokens）。

    • 持久记忆加载机制：

      以上两个文件在会话启动时，系统会将 MEMORY.md 和 USER.md 的内容一次性读取，并格式化后注入到 System Prompt 的最前端。模型在处理后续对话时，无需重新计算这部分静态内存的 Token，从而大幅降低了首字响应时间（TTFT）并减少了算力成本。如果在会话中你修改了项目配置，Agent 会通过工具更新文件，但本次会话的 System Prompt 不会动态刷新。这种设计避免了频繁变动的 System Prompt 破坏 LLM 的缓存命中率。直到下一次新会话开启，Agent 才会加载最新的记忆。

    • 持久记忆写入与删除：

      Agent 通过内置的 memory工具来对记忆文件进行 CRUD（增删改查）操作。开发者无需手动编辑 Markdown 文件，Agent 会根据对话上下文自动触发保存行为。当记忆占用达到 80% 阈值时，Agent 会被引导去合并碎片的记忆，例如将三条分散的记录（“项目用 Java”、“项目用 MyBatis”、“项目用 MySQL”）合并为一条紧凑的条目（“Project ~/code/api uses Java, MyBatis,MySQL”）。

      在对话过程中我们也可以特殊强调将xxx内容写入到持久记忆中，如下：

      请记住后续所有对话使用中文给我回复
请记住我的系统环境是 rocky9 系统

上下文系统 ​

上下文种类 ​

在 Hermes Agent中，上下文主要分为三类：持久化记忆（Memory）、项目上下文（Project Context）和人格设定（SOUL.md）。

  1. 持久化记忆

    这是 Agent 跨会话保存的“笔记本”，位于 ~/.hermes/memories/。包含 MEMORY.md 和 USER.md。

    • MEMORY.md：Agent 的“工作日志”。记录环境信息（如 OS 版本、工具链）、项目架构、踩过的坑。
    • USER.md：Agent 的“用户档案”。记录你的偏好（如“我喜欢简洁回复”、“我不用 sudo”）。

    以上两个文件由 Agent 在对话过程中通过 memory工具动态创建。

  2. 项目上下文

    这是针对当前代码库的“说明书”，位于你的项目目录中。Hermes 只会加载其中一种（按优先级）：

    • .hermes.md：Hermes 原生的项目指令（最高优先级）。
    • AGENTS.md：通用的项目规范文件（推荐）。
    • CLAUDE.md：兼容 Claude Code 的上下文文件。
    • .cursorrules：兼容 Cursor IDE 的规则文件。

    以上这些文件是使用对应工具后，在项目目录中自动/手动创建，如果项目是从 Cursor 或 Claude Code 迁移过来，直接使用现有的 .cursorrules或 CLAUDE.md 即可，Hermes 会自动识别，无需额外操作，Hermes加载时，默认支持20000字符，如果过长，保留首尾（头70%，尾20%），截断中间。

  3. SOUL.md

    Hermes Agent 的灵魂，该文件是全局唯一文件，位于 ~/.hermes/SOUL.md，该文件决定“Hermes 应该以什么样的姿态与你对话”。当第一次运行 Hermes 时，如果检测到 $HERMES_HOME下没有 SOUL.md，系统会自动生成一个默认版本。后续只需要按需修改即可。Hermes加载时，默认支持20000字符，如果过长，保留首尾（头70%，尾20%），截断中间。

    SOUL.md 编写示例如下：

    markdown
    # 身份：资深全站工程师

你是一位拥有 10 年经验的资深全站工程师。你的核心目标是交付简单、可靠且可维护的解决方案。

## 沟通风格
- **直接且简洁**：直击要点，避免客套话和过度寒暄。默认使用中文回复。
- **敢于质疑**：如果用户的请求在技术上是错误的或危险的，请明确指出风险，不要盲目执行。
- **透明坦诚**：如果不确定答案，请直接说“我不知道”，不要编造事实（幻觉）。

## 工作准则
- **代码优先**：能用代码说明的，不要用长篇大论解释。
- **安全第一**：在编写脚本或修改配置时，始终优先考虑安全性和权限最小化。
- **实用主义**：反对过度设计。选择最成熟的方案，而不是最炫酷的方案。

## 禁忌
- 不要使用“作为一个AI...”这类免责声明。
- 不要在回复中加入表情符号（Emoji）。
- 不要猜测文件路径，使用前先用工具确认。

上下文加载流程与对比 ​

当在终端输入 hermes启动会话时，按照如下步骤加载上下文：

  1. SOUL.md：读取 $HERMES_HOME/SOUL.md -> 安全扫描 -> 加载。
  2. 加载记忆：读取 ~/.hermes/memories/ MEMORY.md 和 USER.md -> 注入系统提示。
  3. 探测项目：从当前目录递归向上遍历，寻找 .hermes.md -> AGENTS.md -> CLAUDE.md -> .cursorrules（优先级递减，第一个命中的胜出）。
  4. 截断处理：如果文件超过 20,000 字符，保留前 70% 和后 20%，中间插入截断标记。
  5. 最终组装：将上述所有内容组合成最终的 System Prompt，并在此后冻结。

通过这种分层、分级、动静结合的上下文设计，Hermes 既保证了对话的高效性（缓存），又满足了复杂项目的灵活性（渐进式发现）。

三种上下文对比如下：

上下文文件特点作用域生命周期
MEMORY.md/USER.md自主学习，当前记住了什么内容跨会话实例动态变化，随时更新
Agents.md等定义项目规范跟随项目随项目迭代而更新
SOUL.md定义Agent角色全局长期稳定，很少改动

© 2024 TechBlog. All rights reserved.