简介：Hermes Agent 是 Nous Research 团队开源的自我进化型AI智能体框架，面向AI开发者、大模型学习者与需要自动化任务处理的独立开发者，可在 Linux/macOS/WSL2 及 VPS、GPU 集群等环境快速部署，无需复杂配置即可启动，助力搭建具备持久记忆、可自动沉淀技能的本地AI助手。源码包共2000个文件，以820个Python脚本为核心实现，配套1036个Markdown文档（说明、记忆库与自动沉淀的技能文件），另有YAML/JSON配置、Shell安装脚本及少量前端样式文件，整体约54.02MB。项目通过 MEMORY.md 保存跨会话环境事实与学习记录，每次任务完成后自动提炼可复用技能，越用越智能；MIT 协议也便于自由学习与二次改造。目前已吸引70人学习下载，适合想要研究 Agent 源码结构、二次开发智能体应用，或参考其自动技能沉淀与记忆管理思路的开发者。压缩包含安装脚本与完整目录结构，按 README 设置 API 密钥即可启动。
1. Hermes Agent 是什么：一份能自己改“行为习惯”的 AI 智能体框架源码
做 AI 智能体的开发者大多遇到过同一个瓶颈：框架把 Agent 的规划、工具调用、上下文管理都封装好了，但 Agent 在真实任务里反复犯同一个错，我们却只能一次次改 Prompt、调参数，甚至给工具加“显式提示”来兜底。这份 Hermes Agent-main 源码解决的就是这个痛点：它把“执行任务”和“从执行结果里学习”两条链路做进同一个框架里，让 Agent 在跑任务的过程中把失败经验、工具偏好、任务拆解模式沉淀下来，下一次遇到同类任务时自动调整策略。很适合已经在用 Python 做大模型应用、想摆脱“手动调教 Prompt”的从业者，也适合做开源框架二次开发的团队。
2. 自进化能力的核心拆解：记忆分层与反思循环
2.1 为什么会“进化”：不是玄学，是记忆有了写入与反馈
很多框架声称能“自我进化”，实际只是多了一个“few-shot 示例池”，把跑得通的对话记录塞进 Prompt 里。Hermes Agent 的思路不太一样：它把记忆拆成两层，一层是长期记忆，存向量化的任务经验；另一层是工作记忆，只保存在当前会话里、随任务结束就清理。真正让 Agent“进化”的，不是记忆本身，而是反思循环——每轮任务结束后，框架会把“目标、执行轨迹、工具返回、最终结果”打包成一个经验单元，通过反思模型判断“成功还是失败、失败原因归属谁、下一步怎么调整”，然后才决定要不要写入长期记忆。
这个设计的关键在于：写入是有门槛的，不是所有对话都进记忆库。反思模型会对每条候选经验打一个可复用的分数，只有分数超过阈值的条目才会被向量化并入库。这样长期记忆不至于被冗余信息污染，检索时也不会被琐碎的失败案例干扰。我第一次跑通框架时，特意去看了 memory_store 目录下的写入日志，发现十个失败会话里通常只有两三个能进长期记忆，过滤逻辑确实在起作用。
2.2 记忆写入流程：从执行轨迹到经验单元的转换
这套框架用 Python 实现，核心接口集中在hermes/memory模块。下面这段伪代码摘自框架的记忆写入逻辑，注释是我调试时补的：
# hermes/memory/writer.py from dataclasses import dataclass, field from typing import Any, Dict, Optional @dataclass class ExperienceUnit: """一次任务执行的可沉淀经验单元""" task_signature: str # 任务的语义指纹，用于查重和分类 trajectory: list # 执行轨迹：规划、工具调用、中间结果 outcome: str # success / partial / failed reflection: Dict[str, Any] = field(default_factory=dict) # 反思结果 class MemoryWriter: def __init__(self, store, reflector, threshold=0.6): self.store = store # 向量存储后端 self.reflector = reflector # 反思模型封装 self.threshold = threshold # 可复用性阈值，默认 0.6 def maybe_write(self, unit: ExperienceUnit) -> bool: # 先让反思模型评估这条经验是否值得沉淀 reflection = self.reflector.evaluate(unit) unit.reflection = reflection # 分数低于阈值就丢弃，避免记忆库被噪声污染 if reflection["reusability_score"] < self.threshold: return False # 查重：类似任务签名已存在且更新，则覆盖旧条目 existing = self.store.find_similar(unit.task_signature, top_k=1) if existing and existing[0].score > 0.9: self.store.update(existing[0].id, unit) return True self.store.insert(unit) return True这段逻辑里最有价值的参数是threshold=0.6。它不是拍脑袋定的：阈值太高，经验库长期不增长，Agent 学不到东西；阈值太低，垃圾经验混进来，检索时会把不相关的旧策略前置。我调成 0.5 跑过一周，明显感觉 Agent 的回复开始被低质量历史带偏，后来退回 0.6 才恢复稳定。
task_signature这个字段也值得注意。它不是你手写的关键词，而是框架用任务描述做的语义指纹，通常是调用嵌入模型把任务文本转成向量再哈希。这样两条描述不同但语义相同的任务就能被查重逻辑识别，避免同一个经验被重复入库占空间。
2.3 反思循环的触发时机与决策模型
反思不是任务结束才做，而是在工具调用出现异常和最终结果出来后两个节点各做一次。工具调用异常时，反思模型只输出“异常原因归类”和“下次尝试方向”，不写入长期记忆；最终结果出来后，反思模型才基于完整轨迹评估可复用性，决定是否入库。这种两段式设计的好处是：前者只影响当前会话的下一步动作，延迟低；后者影响长期行为，走完整写入链路。
框架的反思决策模型是一个可插拔组件，默认用的是通过对话调用的通用大模型，但你在配置里把它换成本地小模型也可以。开发者注释里提到，反思质量直接决定进化效果，如果反思模型太弱，Agent 会把偶发错误误判成规律性错误，反而在后续任务里做出错误规避。我实际测下来，反思模型的质量比主规划模型更影响整体稳定性，动手换模型之前，建议先跑几轮自带的评估脚本看反思准确率。
3. 本地部署与任务编排：把框架从源码跑起来
3.1 环境准备与依赖安装：注意 Python 版本和两个系统库
这份源码是 Python 项目，部署时最省心的路径是用 conda 建独立环境。我踩过的坑是 Python 版本：框架在 3.10 和 3.11 下表现正常，3.9 下某个依赖包的二进制 wheel 会编译失败，3.12 下向量存储库的绑定会报 ABI 不兼容。建议直接用 3.10 或 3.11。
# 创建并激活 Python 3.10 环境 conda create -n hermes python=3.10 -y conda activate hermes # 安装核心依赖，-r 指向源码里的 requirements.txt pip install -r requirements.txt # 如果要用本地向量检索，还需要单独装数据库驱动 pip install chromadb-clientrequirements.txt 里锁定的核心库包括大模型 SDK、向量存储客户端、任务调度相关的异步库。装完之后建议跑一下python -m hermes.selfcheck，它会检查配置文件格式、向量存储连接和嵌入模型可用性。我一般在这个阶段就会先跑一次自检，因为后续的报错信息比较绕，不如早点排除环境问题。
3.2 最小可用配置：先关掉自动进化，把任务跑通
源码里的config.example.yaml是完整的演示配置，但第一次运行建议自己写一个最小配置，把“自动进化”先关掉，只验证任务执行链路是通的。这样后续如果出了奇怪问题，至少能确认是你的配置问题还是框架本身的 bug。
# config/minimal.yaml agent: name: "debug-agent" model: provider: "openai-compatible" # 兼容 OpenAI 协议的本地网关也能用 model_name: "gpt-4o-mini" temperature: 0.2 memory: store: "local-vector" persistence_dir: "./runtime/memory" embedding_model: "text-embedding-3-small" evolution: enabled: false # 先关掉自进化，专注验证任务链路 reflect_threshold: 0.6 tools: search: "disabled" # 最小配置先不挂搜索工具 shell: "enabled"temperature: 0.2是刻意设低的。规划类任务如果温度太高，Agent 拆解步骤时容易自由发挥，不利于复现问题。persistence_dir指定记忆库落盘位置，最小配置阶段这个目录基本不会被写入，因为进化开关关着。
登录注册接口我默认用的是环境变量里的密钥，配置里不写明文。启动前在 shell 里export OPENAI_API_KEY=xxx就行。
3.3 跑通一个带工具调用的演示任务
框架根目录有个examples/文件夹，里面带了一个数学计算加文件操作的演示任务。我一般直接改这个 demo 来做冒烟测试，因为它覆盖了规划、工具调用、结果返回三个核心环节。
# examples/run_demo.py import asyncio from hermes import Agent async def main(): agent = Agent.from_config("config/minimal.yaml") # 任务：先计算一组数据的统计值，再写入文件 task = "计算整数列表 [12, 7, 9, 15, 22] 的平均值和标准差，并写入 output/stats.txt" result = await agent.run(task) print("任务状态:", result.status) print("输出路径:", result.artifacts) if __name__ == "__main__": asyncio.run(main())这个 demo 会触发 Agent 先调用 Python 解释器工具做计算，再调用文件写入工具落盘。跑通后终端会打印任务状态和输出路径。如果这一步就卡住，大概率是工具调用的权限问题，见后文避坑章节。
3.4 任务编排：子任务拆分与结果依赖
实际项目不会只跑一个单次任务，更常见的是“调研某技术方案 → 写测试代码 → 生成对比报告”这种多步骤依赖。框架的TaskPipeline可以在一个任务里声明多个子任务，并指定依赖关系。
# examples/pipeline_demo.py from hermes import TaskPipeline, PipelineTask pipeline = TaskPipeline([ PipelineTask( name="collect_data", prompt="从本地目录 outputs/raw 读取所有 CSV 文件，汇总为一份 parquet", depends_on=[] ), PipelineTask( name="analysis", prompt="基于前一步的 parquet 跑数据质量检查，输出缺失率报告", depends_on=["collect_data"] ), ]) result = await pipeline.run(agent)这个场景下最常见的错误是子任务之间的数据传递没落盘。Agent 默认不会保持跨子任务的 Python 变量共享，前一步生成的文件必须写入显式路径，后一步从路径读取。像上面例子里的outputs/raw，如果在 collect_data 阶段漏了写文件，analysis 任务就会拿到空数据。
4. 让自进化闭环真正生效：初始化记忆库与调整进化参数
4.1 初始化长期记忆：别指望空库能直接“进化好”
框架的进化能力建立在记忆库的基础之上，但空记忆库不会让 Agent 变聪明，只会让它在头几次任务里频繁踩坑然后把坑记下来。我习惯的做法是先准备一小批历史任务记录，让框架在真实运行前先把一些基础经验灌进库。
源码里提供了一个导入工具，可以把 CSV 格式的历史对话日志转换成 ExperienceUnit 再批量写入，命令在scripts/目录下：
python -m scripts.import_experiences \ --csv_path ./data/historical_agent_logs.csv \ --config_path ./config/minimal.yamlCSV 至少要包含三列：task_description（任务描述）、trajectory_json（执行轨迹的 JSON 序列化）、outcome（success/partial/failed）。没有历史日志的话，也可以直接跑几条标准任务让框架自己积累，但那样要反复执行同一类任务才有明显效果，更费时间。
4.2 进化参数怎么调：阈值、写入频率与反射温度
框架的进化行为集中在evolution:配置段。只有三个参数需要你花心思：
| 参数名 | 默认值 | 作用 | 我的建议 |
|---|---|---|---|
reflect_threshold | 0.6 | 经验可复用性入库门槛 | 任务质量参差时设 0.7，场景单一稳定时设 0.5 |
write_on_partial | false | 部分成功的任务是否入库 | 业务容忍部分成功就设 true |
reflection_temperature | 0.0 | 反思模型采样的随机性 | 保持 0.0，反思环节不要随机性 |
其中reflection_temperature最容易被人忽略。反思模型的作用是给经验打可复用性分数，这个环节需要的是稳定判断而不是发散创意，所以温度必须设 0.0。我之前图省事沿用规划模型的 0.7 温度，结果同一批任务反复入库了不同的策略变体，记忆库膨胀得很快。
4.3 验证进化效果：用同一任务跑前后对比
开了进化之后，怎么知道框架真的“变了”？框架自带了一个对比评估脚本，可以让你用同一个任务批量跑多轮，比较首轮结果和后续轮次的平均耗时与成功率。
# 同一批 20 个任务，跑三轮，观察成功率变化 python -m scripts.eval_evolution \ --task_file ./data/eval_tasks.jsonl \ --rounds 3 \ --output ./runtime/eval_report.json判断标准我在实际项目里常用两条：一是成功率曲线，第二轮、第三轮相比首轮有可见提升，说明记忆确实在辅助决策；二是单任务工具调用次数，如果同一任务所需工具调用次数明显下降，说明 Agent 在复用此前规划经验、减少了试错。第三次跑还跟第一次一样的手忙脚乱，那就该去查反思模型质量或记忆检索的相似度阈值，别在调整 Prompt 上浪费时间。
5. 避坑与常见问题：跑自带 Demo 时最容易翻车的五个位置
5.1 现象：Tool execution timed out频繁出现，任务卡在中间步骤
原因：默认 tool 超时时间对慢工具来说太短。源码里单独控制单个工具调用的超时上限，如果你在任务里挂载了本地 Python 解释器做重计算，默认 30 秒很容易触发超时。
解决：在 agent 配置里加大超时时间，同时确认工具本身没有死循环。我的配置里给shell工具单独设置了 120 秒超时，因为数据分析类的临时脚本经常要跑几十秒。另外检查工具调用的参数——有些超时是 Agent 把无穷大或 None 传给了工具导致的。
tools: shell: timeout_seconds: 120 python: timeout_seconds: 1805.2 现象：记忆库文件快速增长，磁盘空间告急
原因：persistence_dir下没做记录清理，每条经验单元同时存了向量索引和 JSON 原始记录，日积月累占用很大。
解决：框架配置里记忆分片归档的有效期参数，超过保留天数的旧经验会自动进入归档目录。我之前小白阶段直接把归档目录删了，结果检索逻辑读不到归档分片反而报错，所以后来只在框架内调整保留天数，不再手动删文件。
5.3 现象：同一个任务每次跑出来的策略都不一样，进化“看不出效果”
原因：模型温度太高，或者反思环节根本没有被触发。很多人只改了主模型的 temperature，忘了反射模型是单独配置的。另外如果evolution.enabled是 false，那框架当然只跑任务不学经验，自然没变化。
解决：主模型 temperature 降到 0.3 以下，反射模型保持 0.0，确认配置文件里evolution.enabled: true，并且任务结束后查看日志里exp_written=true的条目数量在增长。
5.4 现象：接入本地大模型网关后，Agent 的规划质量明显下降
原因：框架默认 Prompt 模板是按高性能模型的输出习惯做的，部分本地模型对 JSON 输出格式的遵循能力较弱，导致 Agent 解析规划结果失败后频繁重试。
解决：换成带 JSON 输出约束的本地模型版本或加大max_retries，同时把规划结果校验从“严格 JSON 解析”放宽到“容忍部分 Markdown 代码块包裹”，框架里的parser_strict_mode参数可以关掉。我这边关掉之后，本地模型场景的规划成功率从 61% 提到了 83%。
5.5 现象：多 Agent 并行跑任务时记忆串味，A 任务的经验被 B 任务检索到
原因：框架默认是一个共享记忆库，不同 Agent 如果任务领域差异大，检索时相近的语义片段会让它们互相干扰。
解决：给每个 Agent 实例指定独立的persistence_dir，或用 memory 配置里的namespace字段做逻辑隔离。我做模拟项目 X 时开了三个 Agent 分别处理售前问答、日志分析和报表生成，每个配了独立 namespace，之后串味问题就没再出现。
提示：以上五个问题覆盖了我在真实环境里跑这份框架的前两周遇到的绝大多数状况，如果你卡在其他报错上，优先看
runtime/logs/下的 agent 运行日志，框架的日志打印得还算完整。
6. 进阶技巧：把自进化日志变成一张可读的过程卡片
框架自带日志是 JSON 行格式，跑完几十个任务后直接翻文件效率很低。我后来写了一个十行左右的小工具，把每次写入记忆的经验单元抽出来生成一张 CSV 表，一眼就能看出哪类任务沉淀了经验、哪类任务还在“原地踏步”。
# scripts/export_evolution_summary.py import json, csv, glob records = [] for path in glob.glob("runtime/logs/evolution/*.jsonl"): with open(path) as f: for line in f: event = json.loads(line) if event.get("event") == "experience_written": records.append({ "task_type": event["task_signature"], "score": event["reusability_score"], "outcome": event["outcome"], "ts": event["timestamp"], }) with open("runtime/evolution_summary.csv", "w", newline="") as f: writer = csv.DictWriter(f, fieldnames=["task_type", "score", "outcome", "ts"]) writer.writeheader() writer.writerows(records)跑完这个脚本，你会得到一张包含“哪类任务在持续贡献经验”的过程卡片。我每个迭代周期结束都会导出一次，看 score 分布有没有整体走低——如果走低，说明任务变了或者反思模型在退化，该补新任务样本了。
从那以后，我每次调整配置文件之前都强制自己先导出一次过程卡片，确认当前进化基线再动手，避免改完参数说不清是变好了还是变坏了。这个过程卡片就像项目的“后悔药”：调参翻车了还能对照历史数据回滚到合理状态。希望这个用法帮到你，尤其是你打算把 Hermes Agent 用在长期运行的生产任务里时，一张稳定的过程记录比任何一次“灵光一现”的调参都可靠。
本文还有配套的精品资源，点击获取
