给 Hermes Agent 装上「外挂系统」：记忆系统与 Skill 系统的深度改造

一套完整的 AI Agent 记忆管理 + Skill 自进化 + 自动化维护的实践记录。不改 Hermes 核心代码，通过外挂插件让 Agent 越用越聪明。

TL;DR

Part 1: 记忆系统

1.1 问题：Agent 的「金鱼记忆」

Hermes Agent 原生有三层记忆：MEMORY.md（系统提示词注入）、memory tool（memories/MEMORY.md）、session_search（SQLite 对话历史）。看起来够用，实际跑起来有三个致命问题：

1.2 我们的改造：5 层记忆体系

┌─────────────────────────────────────────────────────────────┐
│  Layer 1: 系统提示词 MEMORY/USER                              │
│  永远加载，2200 字符上限，存最关键的事实                       │
│  文件：~/.hermes/MEMORY.md + ~/.hermes/memories/MEMORY.md     │
├─────────────────────────────────────────────────────────────┤
│  Layer 2: fact_store（全息结构化记忆）                        │
│  向量嵌入 + 实体关系 + 信任评分                               │
│  支持语义搜索、实体探查、组合推理                              │
├─────────────────────────────────────────────────────────────┤
│  Layer 3: session_search（FTS5 对话历史）                    │
│  全文搜索过去的对话，支持 discovery/scroll/read/browse 四种模式│
├─────────────────────────────────────────────────────────────┤
│  Layer 4: compound-system（反思 + 知识库）                    │
│  任务后自动反思，写入 solutions/，带 track/level 三级管理     │
├─────────────────────────────────────────────────────────────┤
│  Layer 5: Skill 系统（可复用技能）                            │
│  从成功模式自动提炼，按需加载，防膨胀                         │
└─────────────────────────────────────────────────────────────┘

1.3 compound-system：让 Agent 学会反思

这是整个记忆系统的核心。每次完成一个非平凡任务，Agent 会自动执行反思流程：

任务完成
    ↓
compound.sh reflect → 判断是否需要反思
    ↓ 需要反思
reflect.sh → 调用 LLM 分析，输出结构化 JSON
    ↓
write-solution.sh → 写入 solutions/ 目录
    ↓
下次遇到类似问题 → compound.sh search → 命中历史方案

关键设计决策：

实际效果：

$ bash compound.sh search "ruff format"
[INFO] Found 3 solution(s) for: ruff format

[1] "ruff format 欠账导致 CI 失败"
    File: solutions/bug/ticketpilot-ruff-format-debt-2026-06-21.md
    Track: bug, Level: session

[2] "子代理拆分模块后必须检查 ruff"
    File: solutions/session/ruff-subagent-lesson.md
    Track: session, Level: session

1.4 reflect.sh：LLM 驱动的结构化反思

最初 reflect.sh 只返回裸 JSON，LLM 经常只回显输入而不做分析。经过多轮迭代：

最终 pipeline：

# 一键反思+存档
bash ~/.hermes/skills/compound-system/scripts/reflect.sh \
    "修复了 QQ Bot 心跳回环" "success" "low" "" \
  | bash ~/.hermes/skills/compound-system/scripts/write-solution.sh

1.5 记忆维护自动化

手动维护不可持续。我们建了一套自动化维护链：

衰减机制原理：

# memory-decay.py 核心逻辑
# 信任评分按指数衰减，30 天半衰期
new_trust = old_trust * (0.5 ** (days_elapsed / 30))
# 低于阈值 → 自动归档到 .archive/

去重机制：

# memory-dedup.py 核心逻辑
# FTS5 全文搜索 + SequenceMatcher 相似度
# 相似度 > 0.85 → 合并，保留更新的版本

1.6 MEMORY.md 的三层文件陷阱

这是调试中最坑的一个发现——系统里有三个不同的 MEMORY.md：

memory tool 的 add/replace/remove 操作的是 memories/MEMORY.md，不是注入到系统提示词的那个。当 tool 报告 "at X/2200 chars" 时，需要手动编辑 memories/MEMORY.md 来清理。

1.7 实战数据

Part 2: Skill 系统

2.1 问题：Skill 膨胀

Hermes Agent 的 Skill 机制本质上是把 SKILL.md 内容注入到 system prompt。一个 300 行的 skill 每次对话都全量注入，不管你用不用。

2.2 改造 1：Hub + 专注 Skill 分层

核心原则：一个大 skill 不如多个小 skill。

改造后的架构：

Hub Skill（索引层，<100 行）
  context-engineering-hub
  快速参考 + 按需加载子 skill
      ↓ 按需加载
专注 Skill（功能层，每个 <200 行）
  project-context        文件结构、模板
  skill-evolver          从成功模式生成 skill
  context-validation     验证改进效果
  self-evolution-system  完整闭环架构
      ↓
工具 Skill（支撑层）
  memory-orchestrator    统一记忆编排
  resilient-web-search   搜索 API fallback

实际案例：context-engineering 的拆分

2.3 改造 2：质量门

每个 skill 创建/更新时必须过质量门：

三段式陷阱示例：

- **psycopg_pool 事务回滚**：`with` 块退出时自动回滚 → 写操作用 `autocommit=True`
- **ruff format 欠账**：CI 会跑 `ruff format --check` → 提交前先 `ruff format .`

2.4 改造 3：防膨胀机制

2.5 改造 4：Smart Skill 注入

Hermes 原生每次对话加载所有 enabled skill 的描述。我们的优化：

# config.yaml
skills:
  disabled:
    # Lark 系列（25 个）— QQ 聊天用不到
    - lark-approval
    - lark-apps
    - lark-attendance
    # ... 共 25 个
    
    # 其他不需要的
    - yuanbao
    - honcho
    - hermes-memory-setup
    # ... 共 6 个

2.6 resilient-web-search：搜索容错

Tavily API 经常 432（配额耗尽）。我们建了一条 fallback 链：

web_search（Tavily）
    ↓ 失败
web_search_plus（auto 路由）
    ↓ 失败
web_search_plus（指定 provider 轮询）
    ↓ 失败
返回错误 + 已尝试列表

这个 skill 被所有搜索相关的 cron job 引用，确保即使一个 API 挂了也不会空手回来。

2.7 Skill 优化实战数据

Part 3: 自动化系统

3.1 Cron Job 时间表（UTC+8）

3.2 会话级自动化

会话启动
    ↓
fact_store(action='search') → 查已有知识
    ↓
开始任务
    ↓
任务完成
    ↓
compound.sh reflect → 反思
    ↓
session-end.sh → 压缩 + 归档 + 更新统计

3.3 解耦原则

所有改造都不修改 Hermes 核心代码。 这是最重要的设计决策：

为什么解耦？

1. Hermes 更新时不会冲突
2. 可以独立测试和迭代
3. 可以分享给其他用户
4. 维护成本低——不需要跟踪上游变更

Part 4: 设计哲学

4.1 从研究到实践

我们的所有决策都有研究支撑：

4.2 核心洞察

1. 减少 token ≠ 减少理解：结构化压缩可以同时实现两者
2. 渐进披露 > 全量加载：只在需要时加载详细内容
3. 闭环验证是关键：每次改进都要验证效果，不盲目优化
4. 自动化是必须的：手动维护不可持续
5. 解耦是原则：不依赖特定工具的内部实现

4.3 仍在迭代的方向

总结

给 Hermes Agent 加外挂系统的核心思路：不改核心，用插件机制扩展能力。

• 记忆系统让 Agent 不再失忆——踩过的坑会记住，做过的决策会保留
• Skill 系统让知识有组织——按需加载、质量控制、自动淘汰
• 自动化让系统自运转——会话级/日/周三层维护，无需人工干预

所有代码都在 ~/.hermes/skills/ 下，纯外挂，不碰 Hermes 核心。

写于 2026-06-21，基于 Hermes Agent + compound-system + memory-orchestrator 的实践