Sand Seeds
Github Repo

Hermes Agent 的记忆、工具和网关架构

Hermes Agent 之所以不像普通 chatbot，是因为它不是只处理当前对话。它有会话存储、长期记忆、技能系统、工具注册表和消息网关。

这篇只看三个基础模块：记忆、工具、网关。

记忆不是聊天记录

很多人说 Agent 要有 memory，但 memory 不是简单把所有聊天记录塞进上下文。

Hermes Agent 至少有几层不同的“记住”：

  • MEMORY.md：长期事实和稳定偏好
  • USER.md：用户画像
  • SQLite session storage：完整会话历史
  • FTS5 搜索：跨会话检索
  • Skills：从任务中沉淀出来的流程性记忆

这些东西分工不同。长期记忆适合保存稳定事实，session storage 适合回查过去发生过什么，Skill 则适合保存“以后遇到类似任务应该怎么做”。

SQLite session storage

Hermes 使用 ~/.hermes/state.db 保存会话状态。里面包括：

  • sessions：会话元数据、token、成本、模型配置
  • messages：完整消息历史
  • messages_fts：全文搜索索引
  • messages_fts_trigram：支持 CJK 和子串搜索
  • state_meta：元信息
  • schema_version：迁移版本

这个设计让 Hermes 可以跨 CLI 和 Gateway 共享会话历史，也能通过 session_search 查找过去任务。

这比“把最近几轮聊天塞进 prompt”更像一个长期运行系统。

Prompt 里的记忆快照

Hermes 的 Prompt Assembly 会把当前记忆快照放进 system prompt 的 volatile tier。也就是说，记忆会进入新会话的上下文，但中途写入 memory 后，不一定立刻修改当前已经构建好的 cached system prompt。

这个设计避免了一个常见问题：如果每次写 memory 都动态改 system prompt，缓存、语义和调试都会变复杂。

更稳的做法是：把 memory 当作可持久化状态，在新 session 或压缩重建时再形成新的快照。

工具系统：注册、过滤、调度

Hermes 的工具系统采用中心 registry。

每个工具模块会声明：

  • 工具名
  • 所属 toolset
  • OpenAI function-calling schema
  • handler
  • 可用性检查 check_fn
  • 是否异步

启动或加载工具时，Hermes 会扫描工具模块，把可用工具注册到 registry。构建模型工具 schema 时，再根据 enabled/disabled toolsets 和 check_fn 过滤。

这有几个好处：

  • 不可用工具不会暴露给模型
  • 工具可以按平台或场景分组
  • MCP 工具和插件工具可以动态加入
  • handler 异常会包装成 JSON 错误返回给模型，而不是直接炸掉 Agent Loop

Toolset 为什么重要

Agent 的工具越多，模型越容易选错工具，prompt 也越重。

Toolset 的作用就是把工具按场景打包。比如 CLI、Telegram、ACP、MCP、terminal、browser 都可以有不同工具组合。

一个成熟 Agent 不应该在每个场景都暴露所有工具。好的工具面应该是刚好够用。

Gateway：让 Agent 住进聊天平台

Gateway 是 Hermes 的多平台消息接入层。Telegram、Discord、Slack 等平台都有 adapter，adapter 会把平台原始事件标准化成 MessageEvent，再交给 GatewayRunner。

简化流程：

1Platform Event 2 | 3Platform Adapter 4 | 5MessageEvent 6 | 7GatewayRunner._handle_message() 8 | 9Slash command / AIAgent / Queue 10 | 11SessionStore 12 | 13Platform Response

Gateway 还负责授权、配对、运行中消息队列、/stop、/approve、/deny 等命令分发。

这就是 Hermes 能长期挂在 Telegram 或 Slack 里的基础。

为什么需要消息守卫

如果 Agent 正在跑一个长任务，用户又发来新消息，系统不能简单把消息直接丢进当前循环。

Hermes Gateway 有两层 guard：

  • adapter 层检测 active session，把消息排队并设置 interrupt
  • runner 层处理 /stop、/new、/queue、/status、/approve、/deny 等特殊命令

这样 Agent 可以被安全中断，也能避免多个消息同时修改同一会话状态。

这三层如何配合

记忆、工具和网关不是独立功能，它们会在一次真实任务中串起来：

1用户从 Telegram 发任务 2 ↓ 3Gateway 标准化消息并确认授权 4 ↓ 5AIAgent 读取 session 和 memory 6 ↓ 7Prompt Builder 注入上下文和 skills 8 ↓ 9模型选择工具 10 ↓ 11Tool Registry 执行 handler 12 ↓ 13结果写回 session storage 14 ↓ 15必要时沉淀 memory 或 skill 16 ↓ 17Gateway 把进度和最终结果发回平台

这就是 Hermes Agent 的基础架构闭环：入口、上下文、行动、记忆、再入口。

小结

Hermes Agent 的关键不是“能不能调模型”，而是能不能把模型调用组织成一个长期运行的系统。

记忆让它跨会话，工具让它能行动，网关让它存在于用户实际工作的地方。三者和 Agent Loop 结合后，Hermes 才真正从聊天工具变成 Agent Runtime。

参考资料：