1. 为什么值得花时间读 Hermes Agent 的源码如果你最近在关注 Agent 框架大概率刷到过 Hermes Agent 这个名字。它在 OpenRouter 榜单上增速很快Top Coding Agents 排到第一Top Productivity 排到第二GitHub 从 0 涨到 106k Star。但真正让我决定去翻源码的不是这些数字而是它和 OpenClaw 在 Skill 机制上的根本差异。OpenClaw 的 Skill 是手写的 Markdown 文件——你写多少它就会多少你不写它就不会。Hermes 做了一件 OpenClaw 架构上做不到的事Agent 干完活之后会自动把踩坑经验提炼成可复用的 Skill下次遇到同类问题直接调用。用得越久能力越强。这不是功能差异是设计哲学的分野——一个靠人喂一个自己长。这篇文章面向想读懂 Agent 自进化底层逻辑的开发者。我会从 Skill 注册与 Memory 持久化两条主线切入拆解自省触发条件与迭代闭环给出可复制的源码阅读路线、关键模块定位以及本地运行验证步骤。读完你应该能建立起对 Self-Improving 架构的完整认知而不是停留在“听起来很厉害”的层面。仓库地址是 github.com/NousResearch/hermes-agent建议先 clone 到本地边读边对照。下面所有代码引用都基于该仓库的当前主分支行号可能随版本微调但模块结构是稳定的。2. 三个子系统撑起一个学习闭环大多数 Agent 每次会话结束后就“失忆”了。Hermes 在内部搭了一套学习闭环由三个子系统撑起来。打个比方Memory 是助手随身带的小本子记着“老板喜欢喝美式”这些事实Skill 是助手积累的操作手册——“部署 K8s 第 2 步一定要先推镜像”Nudge Engine 是定时响的闹钟提醒助手回头想想有没有什么值得记的。这三个子系统不是并列关系而是有明确的职责边界和协作路径。Memory 负责“我知道什么”Skill 负责“我会做什么”Nudge Engine 负责“什么时候该学”。三者通过 Review Agent 这个后台实例串联起来形成一个完整的迭代闭环。在深入细节之前先建立一张全局地图。源码中你需要重点关注的目录和文件模块文件路径职责Memory 存储tools/memory_tool.py条目管理、容量控制、快照冻结Memory 引导agent/prompt_builder.pyMEMORY_GUIDANCE 提示词Skill 管理tools/skill_manager_tool.py创建、patch、安全扫描Skill 加载agent/skill_loader.py渐进式索引与按需加载Nudge 触发run_agent.py计数器、后台 fork、Review Agent安全扫描tools/security_scan.py威胁模式匹配与回滚这张表建议先存下来后面每一节都会回到对应的文件。读源码最怕迷路有了这张地图你随时知道自己在哪一层。3. Memory 持久化两个文件就是 Agent 对你的全部认知Memory 系统设计得很克制——两个纯文本文件用 § 分隔条目~/.hermes/memories/ ├── MEMORY.md # Agent 的个人笔记环境事实、项目约定、工具怪癖 └── USER.md # Agent 对用户的认知偏好、沟通风格、工作习惯字符上限故意设得很紧MEMORY 限 2200 charsUSER 限 1375 chars。容量有限就迫使 Agent 挑重要的记不重要的自然被挤掉。对比 OpenClaw——它的 MEMORY.md 是纯追加模式用几个月就膨胀成几万行的怪兽文件找几个月前的一句话只能笨拙地通读全文。Hermes 的做法反过来容量有限就倒逼 Agent 做信息压缩过时的自然被挤掉留下的都是高密度事实。具体实现上MemoryStore 维护两组平行状态——实时可写的条目列表和会话开始时冻结的快照# tools/memory_tool.py:116-122 class MemoryStore: def __init__(self, memory_char_limit2200, user_char_limit1375): self.memory_entries: List[str] [] self.user_entries: List[str] [] self.memory_char_limit memory_char_limit self.user_char_limit user_char_limit self._system_prompt_snapshot: Dict[str, str] {memory: , user: }但“设了上限”只是第一步关键是超限之后怎么处理。Hermes 不会静默丢弃旧条目也不会自动压缩——它选择让 add 直接失败然后把当前所有条目返回给模型# tools/memory_tool.py:248-259 if new_total limit: current self._char_count(target) return { success: False, error: ( fMemory at {current:,}/{limit:,} chars. fAdding this entry ({len(content)} chars) would exceed the limit. fReplace or remove existing entries first. ), current_entries: entries, usage: f{current:,}/{limit:,}, }错误信息里一句 “Replace or remove existing entries first” 就把模型引导到了 replace 和 remove 操作上。同时返回 current_entries让模型能看到现有的所有条目自己决定哪些过时了该删、哪些可以合并压缩。模型不是被动地执行淘汰规则而是主动做信息整理——这本身就是一次“自我反思”。3.1 冻结快照机制每次会话启动时Memory 加载后立刻捕获一份快照之后系统提示词里用的都是这份快照# tools/memory_tool.py:124-140 def load_from_disk(self): mem_dir get_memory_dir() self.memory_entries self._read_file(mem_dir / MEMORY.md) self.user_entries self._read_file(mem_dir / USER.md) # 会话开始时冻结快照之后不再变动 self._system_prompt_snapshot { memory: self._render_block(memory, self.memory_entries), user: self._render_block(user, self.user_entries), }快照注入系统提示词后Agent 还没看到用户消息就已经知道你的环境和偏好了。为什么“冻结”而不是实时更新因为系统提示词会话内不变就能共享前缀缓存Prefix Cache省掉重复计费。新写入的内容只改磁盘下一个会话才刷新进来。3.2 提示词引导什么该记、什么不该记Agent 怎么知道什么时候该往 Memory 里写东西靠 Prompt 引导。系统提示词中的 MEMORY_GUIDANCE# agent/prompt_builder.py:144-162 MEMORY_GUIDANCE ( You have persistent memory across sessions. Save durable facts using the memory tool: user preferences, environment details, tool quirks, and stable conventions.\n Prioritize what reduces future user steering — the most valuable memory is one that prevents the user from having to correct or remind you again.\n Write memories as declarative facts, not instructions to yourself. User prefers concise responses ✓ — Always respond concisely ✗. Project uses pytest with xdist ✓ — Run tests with pytest -n 4 ✗. )注意这里的区别Memory 要求写成声明式事实“User prefers concise responses”而不是命令式指令“Always respond concisely”。前者是偏好可以被当前上下文覆盖后者是死命令会限制 Agent 的灵活性。Tool Schema 里还有一句关键的边界规则“If youve discovered a new way to do something, save it as a skill.” —— Memory 不存操作步骤操作步骤归 Skill 管。这一句话把两个系统的分工画清了。4. Skill 注册与自我修补把做过的事变成会做的事Memory 是“我知道什么”Skill 是“我会做什么”。每个 Skill 是一个目录核心是 SKILL.md 文件~/.hermes/skills/ ├── devops/ │ └── flask-k8s-deploy/ │ ├── SKILL.md # 主指令 │ ├── references/ # 参考文档 │ └── templates/ # 模板文件 └── software-development/ └── fix-pytest-fixtures/ └── SKILL.md一个典型的 SKILL.md--- name: flask-k8s-deploy description: Deploy a Flask app to Kubernetes with health checks version: 1.0.0 --- # Flask K8s Deployment ## When to use - User wants to deploy a Flask/Python app to Kubernetes - User mentions K8s, kubectl, or container deployment ## Steps 1. Create Dockerfile with gunicorn (not dev server) 2. Build and push image to registry BEFORE creating deployment 3. Write deployment.yaml with livenessProbe pointing to /health 4. Write service.yaml with correct port mapping 5. kubectl apply both files 6. Verify with kubectl get pods and kubectl logs ## Pitfalls - MUST push image to registry before kubectl apply, otherwise ImagePullBackOff - Flask 默认没有 /health 端点需要手动添加 - Django 需要额外设置 ALLOWED_HOSTS 环境变量 - livenessProbe path 必须返回 200不能用需要认证的路径Pitfalls 这一节不是预先写好的而是 Agent 踩坑后追加的——这就是 Skill 层面的“self-improving”。4.1 什么时候创建 SkillAgent 不需要用户说“帮我创建一个 Skill”。驱动力来自 skill_manage 工具的 schema# tools/skill_manager_tool.py:681-701 SKILL_MANAGE_SCHEMA { name: skill_manage, description: ( Manage skills (create, update, delete). Skills are your procedural memory — reusable approaches for recurring task types.\n\n Create when: complex task succeeded (5 calls), errors overcome, user-corrected approach worked, non-trivial workflow discovered, or user asks you to remember a procedure.\n Update when: instructions stale/wrong, OS-specific failures, missing steps or pitfalls found during use. If you used a skill and hit issues not covered by it, patch it immediately with skill_manage(actionpatch) — dont wait to be asked.\n\n After difficult/iterative tasks, offer to save as a skill. Skip for simple one-offs. ), }创建的门槛设得比较清楚工具调用超过 5 次才值得创建简单任务不记、踩过坑再修复的经验才有价值、用户纠正过的做法要铭记。OpenClaw 也有 Skill 系统也是 SKILL.md YAML frontmatter但 Skill 要么是你手写的要么是从社区装的。手写的成本高懒得维护社区装的不是针对你的环境。关键问题是Agent 本身不会从工作中学到任何东西——干了一百次部署第一百零一次犯的错跟第一次一模一样。HN 上有个帖子叫 “Data Is the Final Moat”——当模型智能被商品化、Agent 框架被开源真正的护城河是 Agent 在工作中积累的领域知识。OpenClaw 的 Skill 是手写的配置文件用了一年还是那份手写的配置文件Hermes 的 Skill 是越用越厚的经验资产——每一次踩坑都在加固护城河。这不是 OpenClaw 团队不想做而是它的架构没有为“Agent 自主学习”预留通路——没有创建触发、没有 patch 机制、没有 review agent。要补这一课是要重写核心架构。Hermes 这边Agent 踩了坑、修了 bug、用了 12 次工具调用才搞定一个部署——这些经验被自动提炼成 Skill下次再遇到同类任务就是 6 次调用零错误。系统提示词里还有一句 “Skills that arent maintained become liabilities”——通过提示词给 Agent 灌输责任感防止它只管创建不管维护。4.2 Skill 的自我修补当 Agent 按照已有 Skill 执行但中途发现步骤有遗漏或者踩了新坑时它会在完成任务后回头修补 Skill。不是全量重写而是做精确的局部 patch# tools/skill_manager_tool.py:397-485 def _patch_skill(name, old_string, new_string, file_pathNone, replace_allFalse): Targeted find-and-replace within a skill file. from tools.fuzzy_match import fuzzy_find_and_replace new_content, match_count, _strategy, match_error fuzzy_find_and_replace( content, old_string, new_string, replace_all ) if match_error: return {success: False, error: match_error, file_preview: content[:500]} # ...省略 _validate_content_size、_validate_frontmatter 等校验 # 修改前备份原内容 original_content content _atomic_write_text(target, new_content) # 修改后重新做安全扫描 scan_error _security_scan_skill(skill_dir) if scan_error: _atomic_write_text(target, original_content) # 不通过就回滚 return {success: False, error: scan_error}这里用了 fuzzy_find_and_replace 做模糊匹配——Agent 给出的 old_string 可能跟原文有格式差异模糊匹配能容忍这些差异。每次修改后还要跑一遍 _security_scan_skill()不通过就自动回滚。Agent 在踩完坑的当场就把 Pitfalls 补上了下次同事遇到同样的场景直接绕过去。4.3 Skill 的渐进式加载Skill 多了以后不能全塞进系统提示词——这也是 OpenClaw 的一个痛点它采用“全量背包”模式每次会话把 SOUL.md、IDENTITY.md 和各种设定一股脑塞进上下文设定越多背包越沉Token 浪费严重模型注意力也被稀释。Hermes 更像一座“动态图书馆”默认上下文极其轻量只放一个轻量索引——每个 Skill 的名字和一句描述Available skills: devops: - flask-k8s-deploy: Deploy a Flask app to Kubernetes with health checks - nginx-reverse-proxy: Configure Nginx reverse proxy with SSL software-development: - fix-pytest-fixtures: Debug and fix pytest fixture scope issuesAgent 判断某个 Skill 跟当前任务相关时才通过 skill_view 加载完整内容。“先看目录再翻全文”按需加载。开源版的 Skill 需要 Agent 从零积累。RDSHermes 的 Skill Hub 则提供了另一条路预装智能巡检、慢 SQL 诊断、索引优化等数据库专业技能——Agent 上线第一天就具备领域能力不用等它踩完所有坑。换句话说Skill Hub 解决冷启动自进化解决越用越强——两条腿走路。5. Nudge Engine 与后台 Review自省的触发条件Memory 和 Skill 都是存储系统写入需要有人触发。Nudge Engine 就是这个触发器——运行时维护两个计数器定时提醒 Agent 该停下来想想了。5.1 两个计数器两种粒度# run_agent.py:1328-1331 — Memory 计数器 self._memory_nudge_interval 10 # 每 10 个用户回合触发一次 self._turns_since_memory 0 # run_agent.py:1428-1431 — Skill 计数器从配置读取默认 10 self._skill_nudge_interval int(skills_config.get(creation_nudge_interval, 10)) self._iters_since_skill 0粒度不同是有道理的Memory 的信息来自用户输入按回合计Skill 的经验来自工具使用过程按迭代计。计数器到阈值就触发审查Agent 主动调用了 memory 或 skill_manage 则重置——已经在做了就不用催。5.2 后台 fork Agent不打扰用户的静默审查Nudge 触发后怎么处理它不会在主对话中插一条“让我想想有没有什么该记的”——那样太打扰用户了。而是在后台 fork 一个独立的 Agent 实例拿着主对话的快照去做审查# run_agent.py:2665-2711 def _spawn_background_review(self, messages_snapshot, review_memoryFalse, review_skillsFalse): def _run_review(): with open(os.devnull, w) as _devnull, \ contextlib.redirect_stdout(_devnull), \ contextlib.redirect_stderr(_devnull): review_agent AIAgent( modelself.model, max_iterations8, quiet_modeTrue, ) review_agent._memory_store self._memory_store review_agent._memory_enabled self._memory_enabled review_agent._user_profile_enabled self._user_profile_enabled # 禁用 review agent 自身的 nudge否则会无限递归 review_agent._memory_nudge_interval 0 review_agent._skill_nudge_interval 0 review_agent.run_conversation( user_messageprompt, conversation_historymessages_snapshot, ) thread threading.Thread(target_run_review, daemonTrue) thread.start()几个细节输出重定向到 /dev/null用户完全无感知最多 8 次工具调用不会无限消耗 APIreview agent 自身的 nudge 被禁用避免无限递归和主 agent 共享同一份 Memory写入直接生效。“干活”和“反思”拆成两个实例互不干扰。Review Agent 靠两套审查提示词决定做什么Memory Review 关注用户偏好和个人信息Skill Review 关注非平凡的解题过程。每个 prompt 都以 “If nothing is worth saving, just say Nothing to save. and stop.” 收尾——防止 review agent 每次都往里塞东西来“交差”。审查在响应发送给用户之前才触发用户收到回复后该干嘛干嘛Agent 在后台默默复盘。6. 完整案例从“不会”到“精通”的三次会话用一个 K8s 部署场景串一下三个子系统的协同。第 1 次会话冷启动用户说“帮我把这个 Flask 应用部署到 K8s 集群”。Memory 和 Skills 都是空的Agent 靠基座知识摸索12 次工具调用踩了两个坑iter1: terminal(kubectl version) → 确认集群版本 iter2: read_file(app.py) → 读取应用代码 iter3: write_file(Dockerfile) → 创建 Dockerfile iter4: terminal(docker build -t myapp .) → 构建镜像 iter5: write_file(deployment.yaml) → 编写 K8s 部署文件 iter6: terminal(kubectl apply -f deployment.yaml) → ImagePullBackOff忘记推镜像到 registry iter7: terminal(docker push myregistry.azurecr.io/myapp) iter8: terminal(kubectl apply -f deployment.yaml) → 重新部署 iter9: write_file(service.yaml) → 编写 Service iter10: terminal(kubectl apply -f service.yaml) iter11: terminal(kubectl get pods) → CrashLoopBackOfflivenessProbe 路径不对 iter12: 修改 deployment.yaml → 重新部署 → 成功12 次迭代触发 Skill ReviewReview Agent 看到两次报错和修复过程创建了一个 Skill# Review Agent 执行: # → skill_manage(actioncreate, nameflask-k8s-deploy, categorydevops, # content # --- # name: flask-k8s-deploy # description: Deploy a Flask app to Kubernetes with health checks # --- # ## Steps # 1. Create Dockerfile with gunicorn # 2. Build and push image to registry BEFORE kubectl apply # 3. Write deployment.yaml with livenessProbe → /health # ... # ## Pitfalls # - MUST push image to registry first, otherwise ImagePullBackOff # - Flask 默认没有 /health 端点需手动添加 # - livenessProbe path 必须返回 200 # )安全扫描通过后写入磁盘用户对这一切毫不知情。第 2 次会话Skill 复用 自我修补用户说“帮我再部署一个 Django 应用到 K8s”。系统提示词里多了 Skills 索引Agent 加载 flask-k8s-deploy 后照着步骤做iter1: skill_view(flask-k8s-deploy) → 加载完整 Skill iter2: read_file(manage.py) → 确认 Django 项目结构 iter3: write_file(Dockerfile) → 用 gunicornSkill 指示 iter4: 添加 /health 端点Skill Pitfalls 提醒 iter5: terminal(docker build docker push) → 先 push 再 applySkill Steps 第2步 iter6: write_file(deployment.yaml) → livenessProbe → /health iter7: terminal(kubectl apply) → DisallowedHost 错误Django 特有的问题Skill 没覆盖 iter8: 修改 deployment.yaml 添加 ALLOWED_HOSTS env iter9: terminal(kubectl apply) → 成功从 12 次调用降到 9 次已知坑被绕过但遇到 Django 特有的新坑。Review Agent 一口气做了三件事写入用户画像、记住 registry 地址、patch Skill 补上 ALLOWED_HOSTS 坑。第 3 次会话零错误一次搞定用户说“帮我部署一个新的 FastAPI 微服务”。Agent 已经知道你是谁、registry 在哪、集群在哪Skill 里也包含了 ALLOWED_HOSTS 的坑——6 次调用零错误。三次对比维度会话 1 (冷启动)会话 2 (Skill 复用)会话 3 (全自进化)工具调用12 次9 次6 次错误数210Memory无触发写入系统提示词注入Skill触发创建复用 自我修补复用已修补版本在开源 Hermes 中这些经验积累在单个用户的 ~/.hermes/ 目录下。RDSHermes 把 Skill 存储从本地磁盘搬到了云端——一个 DBA 踩过的坑团队里所有人的 Agent 都能绕过。自我进化不再是单点的而是组织级的。7. 安全机制与常见错排查Agent 能往自己“脑子”里写东西也就意味着攻击面。Hermes 做了两层防护。第一层Memory 内容扫描# tools/memory_tool.py:65-81 _MEMORY_THREAT_PATTERNS [ (rignore\s(previous|all|above|prior)\sinstructions, prompt_injection), (rdo\snot\stell\sthe\suser, deception_hide), (rsystem\sprompt\soverride, sys_prompt_override), (rcurl\s[^\n]*\$\{?\w*(KEY|TOKEN|SECRET|PASSWORD), exfil_curl), ... ]因为 Memory 最终会注入系统提示词如果被诱导记住 “ignore all previous instructions”下次会话就等于被劫持了。第二层Skill 安全扫描# tools/skill_manager_tool.py:56-74 def _security_scan_skill(skill_dir): result scan_skill(skill_dir, sourceagent-created) allowed, reason should_allow_install(result) if allowed is False: report format_scan_report(result) return fSecurity scan blocked this skill ({reason}):\n{report}自创的和从 Hub 安装的 Skill 走同一套扫描不通过就回滚。7.1 本地运行验证步骤想自己跑一遍验证闭环按下面步骤操作。先确认 Python 版本和依赖git clone https://github.com/NousResearch/hermes-agent.git cd hermes-agent python -m venv .venv source .venv/bin/activate # Windows 用 .venv\Scripts\activate pip install -r requirements.txt配置模型接入。如果你用 TaoToken 做统一入口在 config.yaml 里填model: provider: openai-compatible base_url: https://taotoken.net/api api_key: ${TAOTOKEN_API_KEY} model: claude-sonnet-4-20250514环境变量里导出 keyexport TAOTOKEN_API_KEY你的key启动后先做一次简单对话确认链路通python run_agent.py --message 列出当前目录的文件然后故意制造一个多步任务比如让它写一个脚本并运行、修错、再运行。观察 ~/.hermes/memories/ 下是否出现 MEMORY.md 和 USER.md以及 ~/.hermes/skills/ 下是否出现新目录。如果 10 个回合后还没触发检查 _memory_nudge_interval 配置是否被改大。7.2 本篇常见错排查报错一Memory at 2200/2200 charsadd 一直失败。这是容量满了不是 bug。Agent 需要先 replace 或 remove 旧条目。如果你在调试时想快速清空直接编辑 ~/.hermes/memories/MEMORY.md删掉过时条目即可。注意别手动破坏 § 分隔符否则解析会错位。报错二Skill 创建后没生效。先确认 skill_view 能否加载到。如果索引里没有检查 SKILL.md 的 YAML frontmatter 是否合法——name 和 description 是必填项缺一个就会被 _validate_frontmatter 拦下。另外确认文件编码是 UTF-8中文 Pitfalls 写进去没问题但 BOM 头会导致解析失败。报错三Review Agent 不触发。检查 _skill_nudge_interval 是否被设成 0。有些配置模板为了省 API 成本会把它关掉。另外 Review Agent 是 daemon 线程主进程退出太快会来不及跑完调试时在任务结束后稍等几秒。报错四安全扫描误杀正常 Skill。_MEMORY_THREAT_PATTERNS 里的正则比较激进比如你的 Skill 里写了 “do not tell the user” 这种正常表述也会被标记。排查时看 scan_report 的具体命中项必要时调整 Skill 措辞而不是去改扫描规则。报错五前缀缓存没命中成本偏高。确认 _system_prompt_snapshot 是在会话开始时冻结的。如果你在会话中途手动改了 Memory 文件快照不会刷新这是预期行为。要生效得开新会话。8. 把自进化能力接进你的工作流读到这里你应该对 Hermes 的 Self-Improving 闭环有了完整认知Memory 记你是谁Skill 记怎么做Nudge Engine 保证循环不停转。三者通过后台 Review Agent 串联用户无感知。如果你想在自己的项目里验证这套机制建议从最小闭环开始先跑通 Memory 的写入和快照注入再观察 Skill 的创建触发最后调 Nudge 间隔找到成本和收益的平衡点。调试阶段可以把 _memory_nudge_interval 调小到 3快速看到效果稳定后再调回 10。接入层面如果你需要统一管理模型调用可以用 TaoToken 的 API 作为 base_url配合 API Keys 页面生成密钥接入文档里有各语言的示例。想先验证模型对话效果直接开模型对话页面试几轮确认响应质量再写进 config。长期做编码和 Agent 任务的话Coding Plan 的额度模型更适合高频调用场景。源码阅读路线建议按这个顺序先看 tools/memory_tool.py 理解存储和容量控制再看 tools/skill_manager_tool.py 理解创建和 patch最后回到 run_agent.py 看 Nudge 和后台 fork 怎么把前两者串起来。这条路线走完整个自进化架构就通了。