Hermes 架构全解
191.8 万行 Python · 4,772 个文件 · 单系统深潜 · 不做任何对比
这一篇只讲 Hermes 一个系统。不和任何其他项目对比，只回答：这个系统是怎么造出来的？
从 22 个聊天平台的消息入口，到全息记忆的向量运算，逐层拆开每一个可插拔子系统 —— 包括常驻网关进程、多身份路由、凭据池故障转移、定时任务、以及那套让它自称「自我改进」的技能演化机制。
阅读门槛：不需要人工智能背景。所有概念在首次出现时都会解释。如果你完全没接触过大语言模型，建议先读《合刊》那一篇的第 1 章（零基础前置知识），大约 20 分钟，之后再回来。
0 · 项目全景与代码地图
0.1 这个软件是什么
项目自己的定位写在 README 第一句：
「The self-improving AI agent built by Nous Research. It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.」
译：由 Nous Research 打造的自我改进型 AI 智能体。它是唯一内置学习闭环的智能体 —— 它从经验中创建技能、在使用中改进它们、提醒自己持久化知识、搜索自己过往的对话，并跨会话地建立一个对你越来越深入的认知模型。你可以把它跑在一台每月 5 美元的虚拟服务器上、跑在 GPU 集群上、或者跑在闲置时几乎零成本的无服务器基础设施上。它不绑定在你的笔记本上 —— 你可以从 Telegram 和它对话，而它在一台云端虚拟机上干活。
把这段话拆开，它声明了四个核心主张，而这四个主张各自对应了架构里的一大块：
| 主张 | 对应的架构 | 哪一章 |
|---|---|---|
| 不绑定你的笔记本 从 Telegram 对话，在云端干活 | 常驻网关进程 + 22 个平台适配器 | 第 1 章 |
| 用任何你想用的模型 切换不改代码、不锁定 | 供应商适配层 + 凭据池 | 第 11 章 |
| 跨会话建立对你的认知 | 记忆提供者抽象 + 8 种后端 | 第 8 章 |
| 内置学习闭环 从经验创建技能并改进 | 技能系统（81 个技能，近 9,000 行管理代码） | 第 13 章 |
| 属性 | 值 |
|---|---|
| 开发方 | Nous Research |
| 编程语言 | Python 3.11 |
| 包管理 | uv —— 一个用 Rust 写的、比 pip 快很多的 Python 包管理器 |
| 许可证 | MIT（最宽松的开源许可证之一） |
| 发布 | 2026 年 2 月 25 日。8 周后在代码托管平台 GitHub 上获得约 9.9 万收藏，6 月突破 17.5 万 |
| 代码规模 | 4,772 个 Python 文件，191.8 万行 |
0.2 目录地图
括号里是文件数，能直观看出体量分布：
0.3 从这张地图能读出的三件事
第一：外围远大于核心，而且外围就是产品本身
| 核心（智能体逻辑） | 外围（集成与扩展） |
|---|---|
conversation_loop.py 主循环model_tools.py 工具分发context_engine.py 引擎抽象 —— 490 行memory_provider.py 记忆抽象
|
plugins/ 351 个文件hermes_cli/ 299 个文件ui-tui/ 475 个文件skills/ 484 个文件gateway/ 99 个文件
|
注意 context_engine.py 只有 490 行，而它旁边的 context_compressor.py 有 419 KB。前者是接口（规定「一个上下文引擎必须提供哪些功能」），后者是内置的一个实现。
这个比例关系贯穿全系统：抽象层薄，实现层厚，而且实现层可以整个换掉。
第二：有一层叫「网关」，而且它是最大的模块
gateway/run.py 单文件 1.55 MB —— 是整个项目最大的文件。
这一层解决的是一个很具体的问题：一个长期在线的智能体，怎么被 22 个不同的聊天软件以统一的方式触达。
它带来的能力是：你在电脑上用 Slack 和智能体聊到一半，出门换成手机上的 Telegram 继续聊，对话上下文完全连续。对智能体来说这始终是同一场会话，只是消息的进出口换了。
第三：几乎每个关键决策点都是一个抽象基类
「抽象基类」（Abstract Base Class，缩写 ABC）是 Python 里的一种「插座标准」：它规定「任何想接进来的东西必须提供哪几个功能」，但不规定这些功能怎么实现。
| 抽象基类 | 规定了什么 | 已有的实现 |
|---|---|---|
ContextEngine | 上下文怎么管理 | 内置压缩器 + 第三方引擎 |
MemoryProvider | 长期记忆怎么存取 | 8 种（内置全息记忆 + 7 种外部服务） |
BasePlatformAdapter | 一个聊天平台怎么接入 | 22 种 |
Environment | 工具在哪里执行 | 7 种（本机 / Docker / 云沙箱 / SSH…） |
| Provider Adapter | 一个模型服务怎么调用 | Anthropic / OpenAI / Gemini / Bedrock / Vertex / Azure / Codex / Ollama… |
这是 Hermes 最核心的架构立场：把每一个「可能有多种做法」的决策点，都定义成接口交出去。
代价是显而易见的：接口必须照顾所有实现的最低公分母，拿不到任何单一实现的深度优化。
收益也是显而易见的：1,000 多位贡献者可以并行地往这些插座上接东西，而不需要碰核心代码。
0.4 一条消息的完整旅程
0.5 全文章节索引
| 章 | 标题 | 核心内容 |
|---|---|---|
| 1 | 网关层 | 常驻进程、22 平台适配器抽象、能力声明式设计、投递账本、重启守卫 |
| 2 | 身份与会话路由 | Profile 多身份、四级路由、SOUL.md 人格文件、跨平台会话连续性 |
| 3 | 主循环 | ★ 预算驱动的循环、宽限调用、中途插话、每轮 prologue |
| 4 | 工具系统 | TOOLSETS 投放策略、中心分发、参数强制矫正层、错误净化 |
| 5 | 审批与安全红线 | ★ 12 条硬红线、命令位置锚定、引号遮蔽、反混淆、路径归一化 |
| 6 | 执行环境 | 7 种可插拔环境、本机默认无沙箱的审计发现 |
| 7 | 上下文引擎 | ★ 抽象基类、select 与 compress 双动词、缓存契约 |
| 8 | 记忆系统 | ★ HRR 全息记忆、SQLite + FTS5、信任分衰减、8 种可插拔后端 |
| 9 | 插件系统 | 3 个发现来源、可叠加能力与互斥策略的区分 |
| 10 | 委派与看板 | 子智能体、实时干预（插话/中止/暂停）、看板协作、心跳 |
| 11 | 供应商适配 | 十余种后端、凭据池故障转移、按供应商重打缓存断点 |
| 12 | 定时任务 | 自主触发、失败连击提醒、事故记录、注入防护 |
| 13 | 技能系统 | 81 个技能、渐进式披露、使用记录、自我改进闭环 |
Hermes Architecture, in Full
1.918 million lines of Python · 4,772 files · a single-system deep dive · no comparisons
This piece is about one system only: Hermes. It does not compare it to any other project. It answers one question: how was this system built?
From the message entry points of 22 chat platforms down to the vector math of holographic memory, it takes apart every pluggable subsystem layer by layer — the always-on gateway process, multi-identity routing, credential pool failover, scheduled tasks (cron), and the skill-evolution mechanism that lets the project call itself “self-improving.”
Who this is for: no AI background required. Every concept is explained the first time it appears. If you have never touched a large language model, read Chapter 1 of the Companion volume first (the from-zero primer); it takes about 20 minutes. Then come back.
0 · The Project at a Glance, and a Map of the Code
0.1 What This Software Is
The project states its own positioning in the first sentence of its README:
“The self-improving AI agent built by Nous Research. It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.”
In plain terms: an AI agent from Nous Research that improves itself. It claims to be the only agent with a built-in learning loop — it turns experience into skills, refines them as it uses them, reminds itself to write knowledge down, searches its own past conversations, and builds an ever-deeper model of who you are across sessions. You can run it on a $5-a-month virtual server, on a GPU cluster, or on serverless infrastructure that costs almost nothing while idle. It is not tied to your laptop — you can talk to it from Telegram while it does the work on a cloud VM.
Unpack that paragraph and it makes four core claims, and each claim maps onto a major block of the architecture:
| Claim | Architecture behind it | Chapter |
|---|---|---|
| Not tied to your laptop Talk from Telegram, work in the cloud | Always-on gateway process + 22 platform adapters | Chapter 1 |
| Use any model you want Switch without code changes, no lock-in | Provider adapter layer + credential pool | Chapter 11 |
| Builds a model of you across sessions | Memory provider abstraction + 8 backends | Chapter 8 |
| Built-in learning loop Creates skills from experience and improves them | Skill system (81 skills, nearly 9,000 lines of management code) | Chapter 13 |
| Attribute | Value |
|---|---|
| Developer | Nous Research |
| Language | Python 3.11 |
| Package manager | uv — a Python package manager written in Rust, much faster than pip |
| License | MIT (one of the most permissive open-source licenses) |
| Release | February 25, 2026. About 99,000 stars on GitHub, the code hosting platform, within 8 weeks; past 175,000 in June |
| Code size | 4,772 Python files, 1.918 million lines |
0.2 Directory Map
File counts are in parentheses, so you can see at a glance where the bulk lives:
0.3 Three Things You Can Read Off This Map
First: the periphery is far bigger than the core, and the periphery is the product
| Core (agent logic) | Periphery (integrations and extensions) |
|---|---|
conversation_loop.py main loopmodel_tools.py tool dispatchcontext_engine.py engine abstraction — 490 linesmemory_provider.py memory abstraction
|
plugins/ 351 fileshermes_cli/ 299 filesui-tui/ 475 filesskills/ 484 filesgateway/ 99 files
|
Notice that context_engine.py is only 490 lines, while context_compressor.py right next to it is 419 KB. The former is the interface (it specifies “what a context engine must be able to do”); the latter is one built-in implementation.
That ratio runs through the whole system: thin abstraction layer, thick implementation layer, and the implementation layer can be swapped out wholesale.
Second: there is a layer called the “gateway,” and it is the largest module
gateway/run.py is a single 1.55 MB file — the largest file in the entire project.
This layer solves one very specific problem: how does a long-running agent get reached by 22 different chat apps in a uniform way?
What it buys you: you can be halfway through a conversation with the agent on Slack at your desk, walk out the door, switch to Telegram on your phone, and pick up right where you left off, with the conversation context fully intact. To the agent, it has been the same session all along; only the message inlet and outlet changed.
Third: almost every key decision point is an abstract base class
An “abstract base class” (ABC) is Python's version of a wall-socket standard: it specifies “anything that wants to plug in must provide these functions,” but says nothing about how they are implemented.
| Abstract base class | What it specifies | Existing implementations |
|---|---|---|
ContextEngine | How context is managed | Built-in compressor + third-party engines |
MemoryProvider | How long-term memory is stored and retrieved | 8 (built-in holographic memory + 7 external services) |
BasePlatformAdapter | How a chat platform plugs in | 22 |
Environment | Where tools execute | 7 (local / Docker / cloud sandbox / SSH…) |
| Provider Adapter | How a model service is called | Anthropic / OpenAI / Gemini / Bedrock / Vertex / Azure / Codex / Ollama… |
This is the single most central architectural stance of Hermes: every decision point that “could be done more than one way” is defined as an interface and handed out.
The cost is obvious: the interface has to serve the lowest common denominator of all implementations, and gets none of the deep optimizations any single implementation could offer.
The payoff is equally obvious: more than 1,000 contributors can plug things into these sockets in parallel without touching the core code.
0.4 The Full Journey of One Message
0.5 Chapter Index
| Ch. | Title | What's in it |
|---|---|---|
| 1 | Gateway Layer | Always-on process, 22-platform adapter abstraction, declarative capabilities, delivery ledger, restart guard |
| 2 | Identity and Session Routing | Profile multi-identity, four-level routing, SOUL.md persona files, cross-platform session continuity |
| 3 | Main Loop | ★ Budget-driven loop, grace calls, mid-turn interjection, per-turn prologue |
| 4 | Tool System | TOOLSETS exposure policy, central dispatch, argument coercion layer, error sanitization |
| 5 | Approval and Safety Red Lines | ★ 12 hard red lines, command-position anchoring, quote masking, de-obfuscation, path normalization |
| 6 | Execution Environments | 7 pluggable environments, and the audit finding that local runs unsandboxed by default |
| 7 | Context Engine | ★ Abstract base class, the two verbs select and compress, the cache contract |
| 8 | Memory System | ★ HRR holographic memory, SQLite + FTS5, trust-score decay, 8 pluggable backends |
| 9 | Plugin System | 3 discovery sources, the distinction between stackable capabilities and mutually exclusive policies |
| 10 | Delegation and Kanban | Subagents, live intervention (interject/abort/pause), kanban collaboration, heartbeats |
| 11 | Provider Adapters | A dozen-plus backends, credential pool failover, per-provider cache breakpoints |
| 12 | Scheduled Tasks | Autonomous triggering, failure-streak alerts, incident records, injection protection |
| 13 | Skill System | 81 skills, progressive disclosure, usage records, the self-improvement loop |