Hermes Agent 源码级研究报告

研究时间: 2026-05-01
研究对象: nousresearch/hermes-agent v0.11.0
本地副本: /Users/maple/maple/references/hermes-agent/
研究方法: 源码逐模块阅读 + GitHub 元数据分析
目标: 判断哪些机制值得并入 Vyane/Meridian，哪些只适合作参考

---

一、项目概况

维度	数据
语言 / 协议	Python / MIT
版本	v0.11.0 (2026-04-23)
规模	~4,140 .py 文件、~1,324,000 行代码
Stars / Forks	126,407 / 18,916
活跃度	10 个版本 / 6 周，v0.11.0 含 1,556 commits、761 merged PRs
定位	全功能单体 AI 个人助手框架（CLI + 21 平台网关 + Skill 生态）

三个入口点:

• hermes → CLI TUI（主交互界面）
• hermes-agent → 纯 agent loop（供 gateway/batch 后端调用）
• hermes-acp → Agent Client Protocol 服务端（编辑器集成）

核心模块层次:

hermes_cli/ (35K 行)  ← 命令分发、配置、认证、setup
  ↓
run_agent.py (9.4K 行) ← 主循环：消息→LLM→工具→响应
  ↓
agent/ (14K 行)         ← 核心智能层：memory、compression、pricing、routing
  ↓
tools/ (38K 行, 171 文件) ← 工具实现：browser、code、file、mcp、delegate...
  ↓
gateway/ (34K 行)       ← 多平台适配：Telegram/Discord/Slack/WhatsApp/Signal/飞书/钉钉...

---

二、Memory Provider 系统

2.1 架构设计

抽象接口: agent/memory_provider.py — MemoryProvider ABC

必须实现	作用
name	标识符（“builtin”/“honcho”/“holographic”）
is_available()	可用性检查（禁止网络调用）
initialize(session_id, **kwargs)	Session 级初始化
get_tool_schemas()	返回 OpenAI function-calling schema
handle_tool_call(tool_name, args)	路由工具调用

可选钩子	触发时机
system_prompt_block()	构建系统 prompt 时注入静态内容
prefetch(query)	API 调用前，返回召回的上下文
queue_prefetch(query)	后台预取下一轮上下文
sync_turn(user, assistant)	每轮结束异步写入
on_turn_start(turn_number)	每轮开始的节拍信号
on_session_end(messages)	Session 结束时 flush
on_pre_compress(messages)	压缩前提取洞察，注入压缩摘要
on_memory_write(action, target, content)	镜像内置 memory 写操作
on_delegation(task, result)	观察子 agent 完成结果
shutdown()	清理退出

Manager 层: agent/memory_manager.py — 强制 1 builtin + 最多 1 external provider，统一编排全生命周期。

2.2 具体实现

Provider	存储	检索方式	特色
Builtin	~/.hermes/memories/MEMORY.md + USER.md	全量注入 system prompt（无搜索）	冻结快照机制
Honcho	云端语义存储	语义搜索 + 辩证推理 + Peer Cards	跨 session 用户建模
Holographic	SQLite + HRR 向量	BM25 + Jaccard + 全息向量余弦相似度	HRR 代数检索（bind/unbind/bundle）
Supermemory	云端	混合语义搜索	自动捕获 + 实体提取

2.3 冻结快照机制（核心亮点）

实现位置: tools/memory_tool.py:105-135

Session 开始
  → load_from_disk() 读取 MEMORY.md + USER.md
  → 立即生成 _system_prompt_snapshot（Dict[str, str]）
  → 此后整个 session 期间:
      - system prompt 注入的 memory 内容永远是这个快照
      - 工具调用读写的是磁盘上的实时数据
      - 两者解耦，保护 Anthropic 的 prefix cache（5分钟 TTL）
  → 下次 session 开始时重新快照

为什么重要: System prompt 保持不变 → prompt cache 命中率最大化 → 大幅降低 token 成本和延迟。这是 Hermes 做出的一个精妙权衡——牺牲 session 内 memory 实时性，换取 cache 性能。

2.4 注入安全扫描

实现位置: tools/memory_tool.py:60-97

所有写入 memory 的内容经过两层检查：

1. 11 条正则威胁模式: prompt injection (“ignore previous instructions”)、role hijack (“you are now”)、secret exfiltration (curl/wget + API key 变量)、SSH backdoor、hermes .env 读取
2. 10 个不可见 Unicode 字符检测: zero-width space/joiner、BOM、direction override 等

在 add() 和 replace() 时拦截，remove() 不扫描。被拦截时返回明确错误：“Blocked: content matches threat pattern ‘prompt_injection’”。

2.5 Honcho 的节拍控制

Honcho provider 通过 3 个 cadence 参数控制"memory 多久刷新一次"：

参数	作用	默认
injectionFrequency	“every-turn” 或 “first-turn”	every-turn
contextCadence	两次 context 召回之间最少间隔几轮	1
dialecticCadence	两次辩证推理之间最少间隔几轮	1

实现方式：on_turn_start() 传入 turn_number，prefetch() 和 queue_prefetch() 内部检查间隔是否够。

---

三、Runtime / Session 管理

3.1 Session 存储

存储后端: SQLite WAL 模式（hermes_state.py），位于 ~/.hermes/state.db

-- 核心 schema
sessions (id, source, user_id, model, started_at, ended_at,
          end_reason, parent_session_id, cost 字段...)
messages (session_id, role, content, tool_calls, tool_call_id,
          tool_name, timestamp, token_count, reasoning, reasoning_content)
messages_fts -- FTS5 虚拟表（CJK 三字母索引）

并发安全: WAL 模式允许多读单写，写操作带指数退避 + jitter 重试。

Session 链: 压缩时旧 session 标记 ended_at + end_reason="compression"，新 session 通过 parent_session_id 链接前驱，形成血缘追溯链。

3.2 Context 压缩机制（核心亮点）

实现位置: agent/context_compressor.py

触发条件: 预估 token 数达到模型上下文窗口的 50%（可配置）

5 阶段压缩算法:

阶段	方法	特点
1	Tool Result 裁剪	无 LLM 调用，旧工具结果替换为占位符，保留最近 ~60 条
2	首尾保护	前 3 条 + 后 20 条（或 token 预算内）不压缩
3	LLM 摘要	中间部分通过结构化模板生成摘要
4	Tool Pair 修复	清理孤儿 tool result、补充缺失 result 的 stub
5	Session 分裂	旧 session 结束，新 session 继承摘要 + 保留消息

摘要模板结构（首次压缩）:

## Goal — 用户要完成什么
## Constraints & Preferences — 编码风格、决策偏好
## Progress — Done / In Progress / Blocked
## Key Decisions — 为什么做这个技术选择
## Relevant Files — 读过/改过/创建的文件 + 注释
## Next Steps — 接下来要做什么
## Critical Context — 会丢失的值、错误信息、配置

迭代更新模板: 保留前一次摘要，把 In Progress 移到 Done，追加新进展。

容错: 摘要生成失败 → 600 秒冷却 → 中间消息直接丢弃（数据丢失但防止无限循环）。

3.3 Agent Loop 架构

主循环: run_agent.py:6839+ — run_conversation()

while api_call_count < 90 AND budget.remaining > 0:
    1. 检查用户中断
    2. 构建 API 消息（system prompt + history + ephemeral context）
    3. 注入 memory prefetch + plugin hooks
    4. 应用 Anthropic prompt caching
    5. 调用 API（流式）
    6. 解析响应（text + tool_calls + reasoning）
    7. 执行工具（顺序或并发，最多 8 线程）
    8. 收集结果追加到消息
    9. 检查预算 / 压缩阈值
    10. Flush 到 session DB

线程安全预算: IterationBudget 类在父 agent 和子 agent 间共享，线程安全的 consume() / refund() 操作。

并发工具执行: 无写冲突的工具批量并行（最多 8 线程），通过 _should_parallelize_tool_batch() 判断。

3.4 多平台 Gateway

支持 21 个平台：Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost、飞书、钉钉、Email、HomeAssistant、SMS、QQBot…

统一架构：gateway/run.py（35 万字节）异步事件循环 → 平台适配器 → 统一 session 管理 → run_agent.py 后端。

PII 脱敏: WhatsApp/Signal/Telegram 上的电话号码自动哈希处理。

---

四、Model Routing

4.1 Smart Model Routing

实现位置: agent/smart_model_routing.py（195 行）

路由逻辑极其简单：纯关键词 + 长度判断

• 消息 ≤160 字符、≤28 词、≤1 换行、无代码块/URL、无复杂关键词 → 路由到 cheap model
• 其他一切 → 走主模型

_COMPLEX_KEYWORDS = {"debug", "implement", "refactor", "traceback", 
                     "analyze", "architecture", "design", "review", ...}

评价: 这是 Hermes 最弱的模块之一。纯文本特征判断，无语义理解，误判率高。用户输入"帮我看看这个" 可能触发 cheap model，但实际是复杂任务。

4.2 Provider 抽象层

传输协议（v0.11.0 新架构）:

• AnthropicTransport — 原生 Messages API
• ChatCompletionsTransport — OpenAI 兼容
• ResponsesApiTransport — Codex Responses API
• BedrockTransport — AWS Converse API

Hermes Overlay 系统: 在 models.dev 目录之上叠加元数据层，定义每个 provider 的传输协议、认证方式、base URL 等。

4.3 原生特性保留情况

特性	是否保留	实现方式
Anthropic Prompt Caching	是	agent/prompt_caching.py — System+3 策略，4 个 cache_control 断点
Extended Thinking	是	Anthropic adapter 内 budget 映射（xhigh=32K, high=16K…）
Codex Responses API	是	v0.11.0 新增原生传输层
OpenAI tool calling	是	标准 function schema 透传
非 OpenAI provider 的原生特性	部分丢失	聚合器（OpenRouter）走 OpenAI 兼容层，丢失 provider 特有能力

4.4 Credential Pool

实现位置: agent/credential_pool.py（600+ 行）

支持同一 provider 多 API key 轮询，策略包括 fill_first / round_robin / random / least_used。

故障追踪:

• 429 (rate limit) → 1 小时冷却
• 402 (payment/quota) → 24 小时冷却
• 解析 quotaResetDelay 和 Retry-After 获取精确重试时间
• Key 耗尽后自动切换到池中下一个

4.5 Fallback 链

文本任务的 fallback 优先级: OpenRouter → Nous Portal → 自定义端点 → Codex OAuth → 原生 Anthropic → Z.AI/Kimi/MiniMax → None

---

五、CLI Ergonomics

5.1 核心交互特性

特性	实现	评价
Prefix Matching	/m g4 自动展开为 /model，歧义时建议	减少输入量
Smart Input Routing	Agent 运行时按 Enter → steer / queue / interrupt 三种模式	/busy 切换，灵活
Session Resume	/resume name、-c 续上次、交互式 picker	完善
Worktree Isolation	--worktree 隔离 git 分支，退出时自动清理	多 agent 协作必备
Profile System	--profile 独立配置隔离，sticky default	多身份场景
Atomic Config Write	temp file → fsync → os.replace	防中断损坏
Ink TUI（v0.11.0）	React/Ink 重写，sticky composer、streaming、状态栏	最新

5.2 Slash 命令体系

~40+ 内建命令，分类覆盖：

• Session: /new, /clear, /history, /retry, /undo, /compress, /branch, /resume
• 配置: /model, /personality, /yolo, /reasoning, /fast, /voice, /skin
• 工具/Skill: /tools, /skills, /cron, /reload, /reload-mcp, /plugins
• 信息: /help, /usage, /insights, /copy, /paste, /debug

用户可通过 quick_commands 在 config.yaml 中定义自定义命令（exec 或 alias 类型）。

5.3 Skill 系统

格式: YAML frontmatter + Markdown 内容的 SKILL.md 文件

---
name: apple-reminders
description: Manage Apple Reminders via remindctl CLI
platforms: [macos]
prerequisites:
  commands: [remindctl]
---
（Skill 内容：指令、示例、约束）

发现: 递归扫描 ~/.hermes/skills/ + 外部目录，按平台 / 禁用列表过滤。

加载: /skill-name query → 读取 SKILL.md → 注入 agent 消息上下文 → 包含 skill 目录绝对路径 + 配置值。

生态: Skills Hub (agentskills.io) 提供跨 agent 共享标准。

---

六、项目活跃度与问题

6.1 发布节奏

从 v0.2.0 (2026-03-12) 到 v0.11.0 (2026-04-23)，6 周内发布 10 个版本，平均 3-5 天一个版本。v0.11.0 单版本包含 1,556 commits 和 761 merged PRs。

6.2 开放问题

GitHub 显示 7,338 个 open issues（含 PR），其中当前可见的 P1 问题包括：

• 键盘输入冻结、Ctrl+C 无效 (#17959)
• 多轮对话丢失 thinking blocks (#17861)
• Context 压缩后 memory 降级 (#17251)
• Model switch 丢失对话上下文 (#17013)
• Cron jobs.json 并发写竞态 (#18003)

常见问题集中在: cron 可靠性、gateway 竞态、credential pool 边界情况、TUI 渲染、跨平台兼容性。

6.3 技术债务信号

• run_agent.py 单文件 9,439 行（最大单模块），包含了 agent loop、API 调用、工具执行、压缩触发的全部逻辑
• gateway/run.py 350,297 字节（约 1 万行），所有平台的事件循环都在一个文件里
• hermes_cli/main.py 224,931 字节，命令分发 + setup wizard 混在一起
• 测试覆盖率不明确（有 42 个测试目录，但缺少 CI 状态指标）

---

七、对 Vyane/Meridian 的价值评估

7.1 直接可借鉴（值得纳入设计）

1. Memory 冻结快照 + Prefix Cache 保护

机制: Session 开始时对 memory 做一次快照，整个 session 期间 system prompt 不变。工具调用读写磁盘实时数据，但不影响 prompt。

对 Vyane 的价值: Vyane 作为多模型编排平台，Anthropic 的 prompt cache 是关键成本优化点。这个模式可以直接采用。

复杂度: 低。核心逻辑不到 50 行。

2. Context 压缩的结构化模板

机制: Goal / Constraints / Progress(Done+InProgress+Blocked) / Decisions / Files / Next Steps / Critical Context 七段式模板，迭代更新时保留前次摘要。

对 Vyane 的价值: 我们目前的 session-handoff 是手动写 briefing。这个模板可以作为 Vyane 自动 handoff 的基础结构。

复杂度: 低。模板本身是纯文本，可直接适配。

3. Memory 注入安全扫描

机制: 11 条正则（prompt injection / exfiltration / ssh backdoor）+ 不可见 Unicode 检测，在 memory write 时拦截。

对 Vyane 的价值: 任何把外部内容注入 system prompt 的系统都需要这层防护。可直接移植。

复杂度: 极低。单函数 ~40 行。

4. Pluggable Memory Provider 接口

机制: ABC 定义 5 个必须方法 + 8 个可选钩子，Manager 层编排生命周期。

对 Vyane 的价值: Vyane 的 memory 层目前只有 CC 原生的 MEMORY.md。设计一个 provider 接口可以支持未来接入向量数据库、Honcho 等外部系统。

复杂度: 中。接口设计可借鉴，但 Vyane 的多模型架构意味着不同 runtime 的 memory 注入方式不同，需要额外适配层。

5. Tool Pair 完整性修复

机制: 压缩后检查并修复孤儿 tool result（无对应 call）和缺失 result（有 call 无 result），确保 API 不收到畸形消息。

对 Vyane 的价值: 任何做 context 压缩或 session 拼接的系统都会遇到 tool pair 断裂问题。这是必须的卫生措施。

复杂度: 低。

6. Credential Pool 轮询 + 故障冷却

机制: 同 provider 多 key 轮询（round_robin / fill_first / random / least_used），429 → 1h 冷却、402 → 24h 冷却，解析 Retry-After 获取精确重试时间。

对 Vyane 的价值: Vyane 已规划多模型调度，API key pool 是必然需求。Hermes 的实现是目前开源项目中最完善的。

复杂度: 中。核心逻辑 ~300 行，需适配 Vyane 的 key 管理方式。

7.2 设计参考（了解思路，不照搬实现）

1. Skill 系统（SKILL.md frontmatter + 目录上下文注入）

原因: 概念上值得借鉴（Memory 存"知道什么"，Skill 存"怎么做"），但 Vyane 是多 runtime 平台，CC 已有自己的 skill/command 机制，不需要再造一套。

借鉴点: frontmatter 的 platforms / prerequisites 字段设计、skill 目录路径自动注入。

2. Holographic Memory 的 HRR 代数检索

原因: 学术上有趣（全息降维表示、bind/unbind/bundle 操作），但需要 numpy 依赖，且在实际 agent 场景中 BM25 + 语义搜索已经够用。

借鉴点: 混合检索管线的分层设计（FTS5 候选 → Jaccard 重排 → 向量相似度 → 信任加权 → 时间衰减）。

3. Session 血缘追溯（parent_session_id 链）

原因: Vyane 的 session 模型不同（多 runtime 的 AgentRun 而非单进程 session），但"压缩触发 session 分裂 + 链式追溯"的思路值得参考。

4. 多平台 Gateway 架构

原因: Hermes 的 21 平台支持是其核心卖点，但 Vyane/Meridian 的前端策略是"前端给人用，后端 AI native"，不需要 Telegram/Discord adapter 层。

借鉴点: PII 脱敏、平台差异化工具集、Session Context 注入格式。

5. Batch Runner（批量 prompt 并行处理）

原因: 适用于评测/数据生成场景。Vyane 如果做 RL training 或 skill 评测可以参考。

7.3 不适合照搬

机制	原因
Smart Model Routing	纯长度+关键词判断，太粗糙。Vyane 的模型路由是核心差异化（Opus 沟通 + Codex 执行），需要语义级路由
单体架构	1.3M 行单 repo，run_agent.py 9.4K 行单文件混杂所有逻辑。Vyane 应保持模块化
OpenAI 兼容层包装所有 provider	v0.11.0 开始拆分传输层（好的方向），但聚合器模式仍丢失 provider 原生特性
Hermes 的 “Agent = 进程” 模型	每个 agent 是一个 Python 进程，子 agent 通过 RPC 通信。Vyane 的 AgentRun 模型更灵活（可以是 CC CLI session、Codex run、Gemini CLI session）
全量 system prompt 注入 memory	Builtin provider 把所有 memory 条目塞进 system prompt（上限 2.2KB）。对于大量 memory 不可扩展

7.4 与 Vyane 的根本差异

维度	Hermes	Vyane/Meridian
模型策略	单模型 + cheap fallback	多模型编排（不同 runtime 各有所长）
Runtime	纯 Python 进程	CC CLI / Codex / Gemini CLI / 自定义
扩展方式	工具注册 + Skill 文件	Agent 定义 + Role + Channel + Runtime
Memory 层	Provider ABC + 插件	待设计（当前靠 CC 原生 MEMORY.md）
目标用户	终端用户（个人助手）	开发者（AI 工作流平台）

---

八、不确定项

1. 测试覆盖率: 有 42 个测试目录，但未找到 CI badge 或覆盖率报告。代码质量无法从外部评估。
2. Holographic Memory 实际效果: HRR 检索在论文中有理论依据，但在 agent 场景中的 recall 准确率未知。
3. v0.11.0 TUI 稳定性: Ink 重写是全新的，#17959（键盘冻结）是 P1 issue，可能影响日常使用。
4. Skills Hub 生态规模: agentskills.io 的实际 skill 数量和质量未确认。
5. 本地 clone 版本滞后: 本地副本可能停留在 v0.7.0 或更早，v0.8.0-v0.11.0 的源码变化（特别是传输层重构）只能从 release notes 间接了解。

---

九、建议后续工作

短期（可立即执行）

1. 移植 memory 注入安全扫描到 Meridian: ~40 行代码，零依赖，防护价值高
2. 设计 Vyane 的 context 压缩模板: 基于 Hermes 的七段式结构，适配 Vyane 的 AgentRun handoff 场景
3. 更新本地 clone 到 v0.11.0: git pull 获取传输层重构代码，特别是 agent/transports/ 目录

中期（需设计讨论）

4. 设计 Vyane Memory Provider 接口: 参考 Hermes 的 ABC，但需处理多 runtime 差异（CC 的 MEMORY.md vs Codex 的 system prompt vs Gemini 的 context）
5. 评估 Credential Pool 集成: Vyane 的 key 管理需求可能更复杂（多 provider × 多 runtime），但 Hermes 的轮询 + 冷却逻辑是好的起点
6. 冻结快照机制: 在 Vyane 的 session 启动流程中加入 memory snapshot 步骤

长期（观察跟踪）

7. 跟踪 Hermes 的传输层重构: v0.11.0 的 agent/transports/ ABC 是正确方向，后续版本可能进一步完善
8. 观察 Skills Hub 生态: 如果形成规模，跨 agent skill 共享标准对 Vyane 有参考价值
9. 关注 Holographic Memory 的演进: 如果 HRR 检索被验证有效，Vyane 可考虑引入

---

十、关键文件索引

模块	文件路径	行数
Memory Provider ABC	agent/memory_provider.py	~230
Memory Manager	agent/memory_manager.py	~370
Builtin Memory	agent/builtin_memory_provider.py	~95
Memory Tool（含安全扫描）	tools/memory_tool.py	~440
Honcho Provider	plugins/memory/honcho/__init__.py	~714
Holographic Provider	plugins/memory/holographic/__init__.py	~500+
Context Compressor	agent/context_compressor.py	~600
Agent Loop	run_agent.py	~9,440
Smart Model Routing	agent/smart_model_routing.py	~195
Credential Pool	agent/credential_pool.py	~600
Anthropic Adapter	agent/anthropic_adapter.py	~600
Prompt Caching	agent/prompt_caching.py	~73
Usage Pricing	agent/usage_pricing.py	~600
Session DB	hermes_state.py	~1,467
Tool Registry	tools/registry.py	~200+
Skill Commands	agent/skill_commands.py	~300+
CLI Main	hermes_cli/main.py	~5,500+
CLI Interactive	cli.py	~8,620

所有路径相对于 /Users/maple/maple/references/hermes-agent/