Hermes Agent 技术架构深度解析：110K+ Star，自进化 AI Agent 架构设计

2026 年 2 月Nous Research 发布了一个叫 Hermes Agent 的开源项目。两个月后GitHub Star 数冲到 96,000截止发稿已经 110K贡献者超过 240 人Commit 数超过 4,800 次。数据很猛但说实话开源项目 Star 涨得快不一定代表技术强。翻了代码库和官方文档之后我的判断是这个项目在架构设计上确实有东西 - 尤其是它把闭环学习Closed Learning Loop做成了原生能力不是事后打补丁而是从 Day 1 就融入了核心架构。当前市面上大部分 Agent 框架的思路是让 LLM 更好地调用工具。Hermes Agent 的思路不一样让 Agent 越用越聪明。这个方向差异决定了整个架构的设计取舍。这篇文章从源码出发把 Hermes Agent 的架构拆开来看。重点不是介绍它有什么功能README 写得够详细了而是分析它为什么这样设计以及这些设计决策背后的取舍。项目定位与核心差异化Hermes Agent 的官方定位是self-improving AI agent- 自进化 AI Agent。这个定位和市面上绝大多数 Agent 框架拉开了距离。大多数 Agent 框架解决的问题是怎么让 LLM 更好地调用工具。Hermes Agent 解决的是怎么让 Agent 越用越聪明。具体来说它的闭环学习包含五个环节策划记忆任务完成后Agent 自主判断什么值得记住创建 Skill识别重复模式自动生成 Markdown 格式的 Skill 文件Skill 自改进现有 Skill 失败时自动优化FTS5 召回按需检索历史对话SQLite 全文索引用户建模从行为推断偏好Honcho 方言式建模完成任务 → 策划记忆 → 创建 Skill → Skill 自改进 → FTS5 召回 → 用户建模 → 循环这套机制对应认知科学的三种记忆类型情景记忆会话历史、语义记忆MEMORY.md 持久事实、程序性记忆Skill 文件。项目采用 MIT 协议开源技术栈以 Python 3.11 为主支持 OpenAI、Anthropic、Bedrock、OpenRouter 等多种模型后端。官方列出的支持列表包括 Nous Portal、OpenRouter200 模型、NVIDIA NIM、OpenAI GPT-5.x、Anthropic Claude Opus 4.6、Google Gemini 3.1 Pro、DeepSeek、Hugging Face20 开放模型、Ollama本地模型等。切换模型只需一条hermes model命令不需要改代码。核心架构概览先看目录结构能快速理解系统的职责划分目录/文件职责run_agent.pyAIAgent 主类Agent 循环核心tools/40 工具实现终端、浏览器、文件、搜索、MCPtoolsets.pyToolset 定义和组合系统agent/prompt_builder.pySystem Prompt 组装器agent/memory_manager.py记忆管理双 Provider 架构agent/context_engine.py上下文引擎可插拔agent/context_compressor.py轨迹压缩器hermes_state.pySQLite 状态存储FTS5 全文搜索gateway/run.py多平台消息网关skills/内置 Skill 库24 个分类plugins/插件系统hermes_cli/CLI 接口51 个模块environments/执行环境后端local/Docker/SSH/Daytona/Singularity/Modal系统架构总览图图 1Hermes Agent 系统架构总览架构上的几个关键设计决策Agent 循环和工具执行在同一进程通过run_agent.py中的AIAgent类管理整个生命周期没有用微服务那套东西工具自注册模式每个工具文件在模块级别调用registry.register()声明自己不需要中心化的注册表上下文压缩可插拔ContextEngine是抽象基类默认实现是ContextCompressor可以替换状态存储用 SQLite WAL单文件数据库支持多读者 单写者适合网关的多平台并发场景MCP 双向支持既能作为 MCP 客户端连接外部工具服务器也能作为 MCP 服务端被 Cursor、VS Code 等接入还有一个值得注意的设计Profile 系统。v0.6.0 引入了多实例 Profile每个 Profile 拥有独立的配置、记忆库、会话历史、Skill 集合和工具权限。这意味着你可以在同一台机器上跑多个独立的 Agent 实例互不干扰 - 比如一个用于工作项目一个用于个人自动化。内存占用方面不跑本地 LLM 的情况下Agent 进程本身占用不到 500MB。官方宣称可以在 $5/月的 VPS 上运行这个数据从架构上看是合理的 - SQLite 很轻Agent 实例的主要开销在对话历史的内存占用上。Agent 循环深度拆解run_agent.py中的AIAgent类是整个系统的心脏。它管理对话流、工具执行、响应处理的全流程。Agent 循环的基本流程是接收用户消息 → 构建请求含 system prompt 记忆 上下文 → 调用 LLM → 解析响应 → 如果包含工具调用则执行工具 → 把工具结果加入上下文 → 再次调用 LLM → 直到 LLM 不再请求工具调用 → 返回最终响应。这个循环有几个关键的控制机制值得展开说说。迭代预算控制Agent 循环不是无限运行的。IterationBudget类实现了一个线程安全的迭代计数器用来看住 Agent 的执行预算父 Agent 默认 90 次迭代子 Agent 默认 50 次迭代这个设计解决的是一个很实际的问题Agent 有时候会陷入死循环反复调用同一个工具。迭代预算到了就强制停止防止 token 烧穿。并行工具执行Agent 循环中的一个关键判断逻辑在_should_parallelize_tool_batch()方法中。它把工具分成三类分类策略典型工具_NEVER_PARALLEL_TOOLS永远不并行clarify需要用户交互_PARALLEL_SAFE_TOOLS只读安全可并行web_search,read_file_PATH_SCOPED_TOOLS路径隔离条件并行read_file,write_file,patch最大并发工作线程数硬编码为 8_MAX_TOOL_WORKERS。这个设计说明团队对 Agent 的实际使用场景做过深入思考。比如web_search和read_file都是纯读操作并行执行完全安全。但write_file和patch操作同一文件时就有冲突风险所以需要路径隔离检查。中断与转向机制Agent 在执行过程中可能会收到用户的新指令。Hermes Agent 的处理方式是_interrupt_requested_pending_steer双标志位设计不打断当前正在执行的工具等工具批次完成后再处理注入转向指令把用户的新需求作为_pending_steer注入下一轮对话这个选择很务实。如果强行中断正在执行的write_file可能导致文件写了一半。等工具批次完成再转向保证了操作的原子性。多 API 模式AIAgent支持四种 API 模式chat_completions、codex_responses、anthropic_messages、bedrock_converse。模型提供商路由是自动检测的支持 OpenAI、Anthropic、Bedrock、OpenRouter、Copilot ACP 等。这意味着同一套 Agent 逻辑可以无缝切换底层模型不需要改业务代码。从代码结构看模型提供商的检测逻辑在AIAgent的初始化阶段完成之后整个会话期间保持不变。如果需要切换模型需要创建新的 Agent 实例。PromptBuilder 也是这个环节的关键组件。agent/prompt_builder.py负责组装完整的 system prompt包含多个层次DEFAULT_AGENT_IDENTITY核心身份定义、平台特定提示、技能索引、上下文文件、记忆快照等。其中MEMORY_GUIDANCE区分了声明式事实和命令式指令告诉模型记忆内容应该怎么用。TOOL_USE_ENFORCEMENT_GUIDANCE则指导模型如何正确使用工具。PromptBuilder 还有一个两级缓存机制来加速 Skill 索引的读取LRU 缓存内存中 磁盘快照持久化。这在 Skill 数量很多的时候能明显减少启动时间。Agent 循环流程图图 2Agent 循环流程图 — 迭代预算控制、并行工具执行、中断与转向机制工具系统自注册 Toolset 组合ToolRegistry 自注册模式工具系统的核心在tools/registry.py。它采用了一个很优雅的自注册模式每个工具文件在模块级别调用registry.register()声明自己的 schema、handler、toolset 归属。注册表用threading.RLock()保证线程安全读取时做快照。# tools/registry.py 中的 ToolEntry 结构简化class ToolEntry: name: str # 工具名 toolset: str # 所属工具集 schema: dict # JSON Schema handler: callable # 处理函数 check_fn: callable # 检查函数 requires_env: bool # 是否需要执行环境 is_async: bool # 是否异步 description: str # 描述 emoji: str # 显示图标发现机制也很有意思discover_builtin_tools()通过 AST 分析检测哪些.py文件包含registry.register()调用不需要手动维护工具列表。动态注册/注销场景主要用于 MCP 服务器刷新MCP 工具上线时调用register()下线时调用deregister()。Toolset 组合系统toolsets.py实现了一个组合式工具集系统。Toolset 之间可以互相includes支持递归解析。核心工具列表_HERMES_CORE_TOOLS包含 63 个工具所有平台共享类别工具举例Webweb_search,web_extract终端terminal,process文件read_file,write_file,patch,search_files视觉vision_analyze,image_generate技能skills_list,skill_view,skill_manage浏览器browser_navigate等 11 个浏览器工具规划todo,memory代码执行execute_code,delegate_task定时任务cronjob其他send_message, Home Assistant,session_search,clarify平台特定 toolset 如hermes-cli、hermes-telegram、hermes-discord等有 20 多个。hermes-gateway是所有平台工具的并集。这种组合式设计的好处是新接入一个平台时只需要定义该平台特有的工具然后 includes 核心工具集就行。比如新增一个飞书适配器只需要定义飞书的消息发送、消息格式化等平台特有工具然后引用hermes-gateway的基础工具集。从代码组织上看这种设计避免了工具的重复定义。一个web_search工具只存在一份实现但可以通过不同的 toolset 暴露给不同的平台。同时MCP 协议的支持mcp_serve.py让 Hermes Agent 可以接入 6,000 外部应用这些 MCP 工具通过动态注册机制集成到 ToolRegistry 中。记忆与学习闭环这是 Hermes Agent 和其他 Agent 框架拉开差距的地方。双文件记忆架构agent/memory_manager.py中的MemoryManager采用双 Provider 架构一个内置 Provider管理 MEMORY.md 和 USER.md 最多一个外部 Provider如 Honcho。两个记忆文件的分工很明确MEMORY.mdAgent 的个人笔记。记录环境事实、项目约定、工具的使用技巧USER.mdAgent 对用户的认知。记录偏好、沟通风格、期望记忆注入时使用memory-context标签做上下文围栏防止模型把记忆上下文误认为新的用户输入。tools/memory_tool.py中还有一个安全扫描机制检测注入/泄露模式 - 比如记忆内容中是否包含试图操控模型行为的恶意指令。记忆条目之间用§section sign分隔。这个选择挺有意思的用一个不太常见的字符做分隔符降低了和正文内容冲突的概率。冻结快照模式这个设计解决了一个很实际的问题系统提示的稳定性。会话开始时MemoryManager 把当前的记忆内容作为快照注入系统提示。之后整个会话期间系统提示保持不变 - 中途写入的记忆只更新磁盘文件不刷新系统提示。这样做的好处是保持前缀缓存有效。如果每次记忆更新都刷新系统提示KV cache 就会失效每次请求都要重新计算前面所有 token 的 KV 对。冻结快照让前缀缓存命中率大大提高。这是一个典型的读写分离思路读路径会话开始时的快照注入和写路径中途更新磁盘文件完全解耦。代价是 Agent 在一个会话内对记忆的修改需要等到下一个会话才能被读取。对于大多数使用场景来说这个延迟是可以接受的。Skill 系统tools/memory_tool.py负责双存储的管理Skill 文件存放在~/.hermes/skills/目录下是标准的 Markdown 文件。Skill 的创建和改进流程Agent 完成一个复杂任务后自动识别是否包含可复用的模式如果有生成 Markdown 格式的 Skill 文件包含触发条件、执行步骤、注意事项使用 Skill 时如果发现问题过时、报错立即 patch 更新agent/prompt_builder.py中的SKILLS_GUIDANCE提供了 Skill 创建和更新的指导规则。PromptBuilder还实现了两级缓存LRU 磁盘快照来加速 Skill 索引的读取。会话搜索hermes_state.py中的SessionDB基于 SQLite FTS5 实现跨所有会话消息的全文搜索。搜索流程是FTS5 召回相关片段 → LLM 总结 → 注入当前上下文。prompt_builder.py中的SESSION_SEARCH_GUIDANCE指导 Agent 何时以及如何使用会话搜索。从数据流向看完整的记忆召回链路是用户提问 → Agent 判断是否需要历史信息 → 调用session_searchFTS5 召回 → LLM 总结召回结果 → 结合 MEMORY.md/USER.md 的快照 → 形成完整的记忆上下文。这是一个多级检索的设计不同类型的记忆走不同的通道。记忆与学习闭环图图 3记忆与学习闭环 — 五阶段循环 三层记忆架构 多级检索链路你在项目中用过类似的记忆持久化方案吗欢迎在评论区聊聊。上下文管理可插拔压缩引擎ContextEngine 抽象架构agent/context_engine.py定义了抽象基类ContextEngineagent/context_compressor.py提供了默认实现ContextCompressor。可插拔设计意味着你可以实现自己的上下文管理策略比如基于 RAG 的检索增强、基于重要性评分的选择性保留等。ContextEngine的接口设计很简洁核心就是接收当前对话历史和 token 预算返回压缩后的上下文。为什么要把上下文管理做成可插拔因为不同使用场景对上下文的处理策略差异很大。编程场景需要保留完整的代码变更历史对话场景需要保留情感上下文数据分析场景需要保留中间结果。一个通用的压缩策略很难同时满足这些需求。压缩策略详解ContextCompressor的压缩策略很讲究参数默认值作用threshold_percent0.75上下文使用率超过 75% 时触发压缩protect_first_n3保护前 3 条消息通常是 system prompt 用户初始请求protect_last_n6保护后 6 条消息最近的对话上下文压缩的具体流程保护头部和尾部前 N 条和后 M 条消息不动中间部分用辅助模型总结不是简单截断而是让另一个 LLM 生成结构化摘要总结模板包含已解决的问题、待处理的事项、活跃任务工具输出裁剪对工具返回的长文本做前置过滤减少总结的 token 消耗按比例分配 token 预算中间部分的每段对话按比例分配总结的 token 预算另外trajectory_compressor.py提供了轨迹压缩能力主要用于科研场景的批量轨迹生成。PromptBuilder 的安全扫描agent/prompt_builder.py还有一个容易被忽略的功能_scan_context_content()检测注入攻击。上下文文件.hermes.md、AGENTS.md、CLAUDE.md、.cursorrules的优先级是.hermes.md AGENTS.md CLAUDE.md .cursorrules。安全扫描会检查这些文件中是否包含恶意指令防止 prompt injection。子 Agent 委托机制tools/delegate_tool.py实现了子 Agent 委托机制允许主 Agent 生成独立的子 Agent 实例来并行处理任务。隔离设计子 Agent 的隔离做得比较彻底无父历史子 Agent 看不到父 Agent 的对话历史独立终端会话子 Agent 有自己的终端环境工具限制DELEGATE_BLOCKED_TOOLS列表禁止子 Agent 使用特定工具被禁止的工具包括递归委托防止子 Agent 再生孙 Agent、用户交互类工具子 Agent 不应该直接和用户对话、记忆写入工具防止子 Agent 污染主 Agent 的记忆。并行与深度控制# 子 Agent 关键配置MAX_DEPTH 1 # 默认扁平最多可配到 3MAX_CONCURRENT 3 # 最多 3 个并行子 Agent并行执行通过ThreadPoolExecutor实现。多个子任务可以同时运行。深度控制有两层含义委托深度_delegate_depth跟踪委托链的长度默认MAX_DEPTH1意味着子 Agent 不能再委托角色模式leaf叶节点只能执行或orchestrator编排者可以再次委托run_agent.py中的_active_children管理所有活跃的子 Agent 实例。子 Agent 委托架构图图 4子 Agent 委托架构 — 父子隔离、并行执行、深度控制说实话子 Agent 并发最多 3 个这个限制社区里有人吐槽过。对于复杂的并行场景3 个子 Agent 确实不够用。但从架构安全的角度看限制并发数可以避免资源爆炸 - 每个 Agent 都有自己的终端会话和上下文3 个就已经意味着 3 倍的资源消耗。多平台网关架构gateway/run.py实现了一个统一的消息网关单一进程处理所有平台消息。支持的平台网关支持 17 个平台Telegram、Discord、Slack、WhatsApp、Signal、Email、SMS、Home Assistant、Mattermost、Matrix、DingTalk钉钉、Feishu飞书、WeChat微信、WeCom企业微信、QQ、BlueBubbles、Webhook。Agent 缓存策略网关用 LRU 缓存 空闲 TTL 淘汰来管理 Agent 实例缓存容量128 个 Agent 实例空闲淘汰1 小时无活动自动清理这个设计是为了平衡内存使用和响应速度。Agent 实例占用内存不小需要维护对话历史、工具状态等但每次创建新实例开销也大。LRU TTL 是一个合理的折中。网关与 Agent 循环的协作网关收到消息后会从缓存中查找或创建对应的 Agent 实例然后把消息交给 Agent 的主循环处理。Agent 的响应再通过网关发回给对应平台。这意味着同一个 Agent 可以同时服务多个平台 - 你可以在 Telegram 上开始一个对话然后在 Discord 上继续。不同平台的消息格式差异比如 Telegram 的 Markdown V2、Discord 的 Embed、Slack 的 Block Kit在网关层统一处理Agent 核心不需要关心这些细节。v0.9.0代号 “the everywhere release”还加入了 TermuxAndroid和 iMessage 支持进一步扩展了平台覆盖。状态持久化SQLite FTS5hermes_state.py中的SessionDB是整个系统的状态层。技术选型SQLite WAL 模式支持多读者 单写者适合网关多平台并发场景FTS5 全文搜索跨所有会话消息的快速文本搜索Schema 版本控制当前 v8自动迁移写竞争处理SQLite 在高并发写入时容易出现锁竞争。SessionDB 的处理方式是随机抖动重试15 次重试每次等待 20-150ms 的随机时间。这个随机抖动可以避免多个写请求同时重试导致的护航效应convoy effect。会话管理get_compression_tip()方法沿压缩-续链前进追踪会话的完整历史。会话标题管理支持自动生成和唯一性约束族系命名如 “title #2”、“title #3”。所有数据存储在本地~/.hermes/目录没有云端同步。搬家的时候拷贝目录就行。这种本地优先的设计在隐私敏感场景下是个加分项 - 你的对话历史和 Agent 记忆不会上传到任何云服务。从选型上看SQLite 在这里是一个恰到好处的选择。PostgreSQL 太重了需要单独的数据库服务纯文件存储又缺乏查询能力。SQLite FTS5 提供了全文搜索、事务支持、WAL 并发同时保持单文件部署的简洁性。对于 Agent 的状态管理场景来说这是一个平衡得很好的方案。总结翻完 Hermes Agent 的代码库几个架构层面的判断做得好的地方闭环学习是原生能力不是事后加的补丁。从PromptBuilder的MEMORY_GUIDANCE到MemoryManager的双文件架构再到SessionDB的 FTS5 搜索整套学习闭环在架构层面是贯通的工具自注册 Toolset 组合的设计很灵活新接入平台只需定义差异部分上下文压缩的可插拔架构给未来的优化留下了空间迭代预算 中断机制体现了对 Agent 实际运行问题的深入理解需要关注的局限子 Agent 并发上限 3 个复杂并行场景受限项目迭代节奏很快 - 不到 3 周发布了 4 个大版本稳定性需要观察Windows 原生不支持必须通过 WSL2关于抄袭的争议中国团队指控架构级抄袭目前还没有最终结论从架构设计上看Hermes Agent 最大的贡献是把 Mitchell Hashimoto 提出的Harness Engineering五大组件指令层、约束层、反馈层、记忆层、编排层做成了产品级的内建能力。这在 Agent 框架领域是比较少见的。如果你在做 Agent 相关的架构设计Hermes Agent 的闭环学习和上下文管理部分值得细看。开源生态里能做到这个完成度的 Agent 框架目前确实不多。学AI大模型的正确顺序千万不要搞错了2026年AI风口已来各行各业的AI渗透肉眼可见超多公司要么转型做AI相关产品要么高薪挖AI技术人才机遇直接摆在眼前有往AI方向发展或者本身有后端编程基础的朋友直接冲AI大模型应用开发转岗超合适就算暂时不打算转岗了解大模型、RAG、Prompt、Agent这些热门概念能上手做简单项目也绝对是求职加分王给大家整理了超全最新的AI大模型应用开发学习清单和资料手把手帮你快速入门学习路线:✅大模型基础认知—大模型核心原理、发展历程、主流模型GPT、文心一言等特点解析✅核心技术模块—RAG检索增强生成、Prompt工程实战、Agent智能体开发逻辑✅开发基础能力—Python进阶、API接口调用、大模型开发框架LangChain等实操✅应用场景开发—智能问答系统、企业知识库、AIGC内容生成工具、行业定制化大模型应用✅项目落地流程—需求拆解、技术选型、模型调优、测试上线、运维迭代✅面试求职冲刺—岗位JD解析、简历AI项目包装、高频面试题汇总、模拟面经以上6大模块看似清晰好上手实则每个部分都有扎实的核心内容需要吃透我把大模型的学习全流程已经整理好了抓住AI时代风口轻松解锁职业新可能希望大家都能把握机遇实现薪资/职业跃迁这份完整版的大模型 AI 学习资料已经上传CSDN朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】