AM
Agent Memory Learn 把 context 和 memory 讲给普通人听
Source Bundle

hermes-agent 证据页

来自 docs/hermes-agent 的原始分析文档与行号。

证据页
回上一页
怎么用这页
  • 左上角是文档名，下面是带行号的原始内容。
  • 学习页里的源码锚点会跳到这里的具体行号。
Docs

原始文档与行号

这些内容直接来自当前仓库的 docs/。

hermes-agent.md
`hermes-agent`
1
# `hermes-agent`
2
3
## 仓库定位
4
5
`hermes-agent` 是完整 agent runtime，不是单一 memory 库。和 `context / memory` 最相关的主干至少有三条：system prompt 组装、session transcript 持久化、长时 memory provider。它们在 `run_agent.py` 里汇合，但实现边界彼此独立。
6
7
## 源码架构树
8
9
```text
10
hermes-agent
11
├─ run_agent.py
12
├─ agent/
13
│ ├─ prompt_builder.py
14
│ ├─ context_engine.py
15
│ ├─ context_compressor.py
16
│ └─ memory_manager.py
17
├─ tools/
18
│ ├─ memory_tool.py
19
│ └─ session_search_tool.py
20
├─ hermes_state.py
21
├─ gateway/
22
│ ├─ session.py
23
│ └─ mirror.py
24
└─ plugins/memory/*
25
```
26
27
## 关键结论摘要
28
29
- 这套实现的 memory 不是单层结构，而是 `prompt_builder`、内建 `MEMORY.md/USER.md`、`session_search`、外部 provider 插件四条并行路径。
30
- context 管理的中心能力是 `ContextCompressor`，它不只摘要消息，还会先瘦身旧 tool 输出，再做摘要替换和 tool call / result 对齐修复。
31
- `session_search` 读的是 `state.db` 里的 session transcript 历史，不是 provider 长期 memory 本体。
32
- 内建 memory 是本地文件型，外部 provider 通过 `MemoryManager` 统一注册、prefetch、sync、tool 路由和生命周期。
33
34
## 专题文档
35
36
- [01-架构与范围](./hermes-agent/01-%E6%9E%B6%E6%9E%84%E4%B8%8E%E8%8C%83%E5%9B%B4.md)
37
- [02-context管理](./hermes-agent/02-context%E7%AE%A1%E7%90%86.md)
38
- [03-memory实现](./hermes-agent/03-memory%E5%AE%9E%E7%8E%B0.md)
39
- [04-存储与状态](./hermes-agent/04-%E5%AD%98%E5%82%A8%E4%B8%8E%E7%8A%B6%E6%80%81.md)
40
- [05-调用链、压缩与边界](./hermes-agent/05-%E8%B0%83%E7%94%A8%E9%93%BE%E3%80%81%E5%8E%8B%E7%BC%A9%E4%B8%8E%E8%BE%B9%E7%95%8C.md)
41
42
## 关键源码索引
43
44
- `run_agent.py:1219-1320`
45
- `run_agent.py:3349-3476`
46
- `run_agent.py:7040-7386`
47
- `run_agent.py:8237-8595`
48
- `agent/prompt_builder.py:144-173`
49
- `agent/prompt_builder.py:893-1006`
50
- `agent/context_compressor.py:188-1094`
51
- `agent/memory_manager.py:57-356`
52
- `tools/memory_tool.py:105-571`
53
- `tools/session_search_tool.py:245-560`
54
- `hermes_state.py:115-1199`
55
56
## 阅读提示
57
58
先看 `02-context管理`，再看 `03-memory实现`。这个仓库里最容易犯的错误，是把 `session_search`、内建文件 memory 和 provider memory 混成一条链。
59
hermes-agent/01-架构与范围.md
`hermes-agent`：架构与范围
1
# `hermes-agent`：架构与范围
2
3
## 1. 三条主干
4
5
`hermes-agent` 与本任务最相关的三条主干是：
6
7
- `prompt_builder + run_agent`：system prompt 与 turn 上下文组装。
8
- `hermes_state + gateway/session`：session transcript 的 SQLite / JSONL 持久化。
9
- `memory_tool + memory_manager + plugins/memory/*`：内建 memory 与外部 provider memory。
10
11
### 源码锚点
12
13
- `run_agent.py:1219-1320`
14
- `agent/prompt_builder.py:144-173`
15
- `hermes_state.py:115-1199`
16
- `gateway/session.py:498-1045`
17
- `agent/memory_manager.py:57-356`
18
19
## 2. 范围边界
20
21
本组文档重点覆盖：
22
23
- `run_agent.py`
24
- `agent/*`
25
- `plugins/memory/*`
26
- `hermes_state.py`
27
- `tools/session_search_tool.py`
28
- `gateway/session.py`
29
30
不把外围 skills、网站资源或无关工具实现当作 memory 主线。
31
32
### 源码锚点
33
34
- `tools/session_search_tool.py:245-560`
35
- `plugins/memory/__init__.py:66-404`
36
37
## 3. 关键边界
38
39
- `session_search` 是历史 transcript 检索，不是 provider memory 本体。
40
- 内建 memory 和外部 provider memory 同时存在，但不是一回事。
41
- context compression 是单独的一条主线，不应简化成“摘要提示词”。
42
43
### 源码锚点
44
45
- `tools/session_search_tool.py:245-560`
46
- `tools/memory_tool.py:105-571`
47
- `agent/context_compressor.py:336-1094`
48
hermes-agent/02-context管理.md
`hermes-agent`：context 管理
1
# `hermes-agent`：context 管理
2
3
## 1. system prompt 组装
4
5
`prompt_builder.py` 负责把身份、memory 指导、session_search 指导、skills、项目上下文文件、环境提示等内容拼进 system prompt；`run_agent.py` 再把这些结果与运行时状态结合起来，形成真正送进模型的 prompt。
6
7
### 源码锚点
8
9
- `agent/prompt_builder.py:144-173`
10
- `agent/prompt_builder.py:893-1006`
11
- `run_agent.py:3349-3476`
12
13
## 2. 项目上下文与临时上下文引用
14
15
项目上下文文件有明确优先级，例如 `.hermes.md/HERMES.md`、`AGENTS.md`、`CLAUDE.md`、`.cursorrules`。`@file/@folder/@git/@diff/@url` 这类引用会在发送前展开，并受 workspace 边界和 token 预算约束。
16
17
### 源码锚点
18
19
- `agent/prompt_builder.py:893-1006`
20
- `agent/context_references.py:41-142`
21
- `agent/context_references.py:236-342`
22
23
## 3. `ContextCompressor`
24
25
`ContextCompressor.compress()` 不是只做摘要。它会先对旧 tool 输出做摘要替换，保护头尾消息，再对中段做结构化 summary；失败时会插入静态 fallback，并修复 tool call / result 对齐。
26
27
### 源码锚点
28
29
- `agent/context_engine.py:32-169`
30
- `agent/context_compressor.py:336-1094`
31
32
## 4. 压缩触发后的上下文重建
33
34
`run_agent._compress_context()` 会先 `flush_memories()`，再通知 provider 的 `on_pre_compress()`，然后压缩消息、重建 system prompt、结束旧 session、创建带 `parent_session_id` 的新 session，并把新的 prompt 写回 `state.db`。
35
36
### 源码锚点
37
38
- `run_agent.py:7040-7263`
39
- `hermes_state.py:403-412`
40
hermes-agent/03-memory实现.md
`hermes-agent`：memory 实现
1
# `hermes-agent`：memory 实现
2
3
## 1. 内建文件型 memory
4
5
内建 memory 由 `tools/memory_tool.py` 实现，真实存储是 `HERMES_HOME/memories/MEMORY.md` 和 `HERMES_HOME/memories/USER.md`。`MemoryStore` 会在 session start 时加载并去重，再把当时内容冻结成 system prompt snapshot。
6
7
### 源码锚点
8
9
- `tools/memory_tool.py:105-198`
10
- `tools/memory_tool.py:359-451`
11
12
## 2. `memory` 工具的写入模型
13
14
内建 `memory` 工具只支持 `add / replace / remove`，用短唯一子串定位条目，并在写入前做 injection / exfil 模式扫描。它更像“精选记忆编辑器”，而不是自动海量归档。
15
16
### 源码锚点
17
18
- `tools/memory_tool.py:222-355`
19
- `tools/memory_tool.py:463-571`
20
21
## 3. `MemoryManager` 与插件体系
22
23
`MemoryManager` 负责统一内建 memory 和外部 provider：注册 provider、追加 provider system prompt、prefetch、sync、tool schema 和生命周期钩子。插件发现机制由 `plugins/memory/__init__.py` 统一完成。
24
25
### 源码锚点
26
27
- `agent/memory_manager.py:57-356`
28
- `plugins/memory/__init__.py:66-404`
29
30
## 4. 代表性 provider
31
32
仓库内同时存在多类 provider，例如：
33
34
- `supermemory`
35
- `mem0`
36
- `honcho`
37
- `hindsight`
38
- `retaindb`
39
- `byterover`
40
- `openviking`
41
- `holographic`
42
43
它们分别提供不同的 recall、profile、conclude、background sync 语义，因此这里的外部 memory 明显是插件并行模型。
44
45
### 源码锚点
46
47
- `plugins/memory/supermemory/__init__.py:1-790`
48
- `plugins/memory/mem0/__init__.py:1-371`
49
- `plugins/memory/honcho/__init__.py:1-1052`
50
- `plugins/memory/hindsight/__init__.py:1-881`
51
- `plugins/memory/retaindb/__init__.py:1-764`
52
- `plugins/memory/byterover/__init__.py:1-381`
53
- `plugins/memory/openviking/__init__.py:1-672`
54
- `plugins/memory/holographic/__init__.py:1-260`
55
hermes-agent/04-存储与状态.md
`hermes-agent`：存储与状态
1
# `hermes-agent`：存储与状态
2
3
## 1. `state.db`
4
5
`hermes_state.py` 定义了 SQLite `state.db` 的 session / message / FTS5 结构，并承担标题、分支、压缩后新 session 等元数据持久化。
6
7
### 源码锚点
8
9
- `hermes_state.py:115-1199`
10
11
## 2. gateway transcript 双写
12
13
`gateway/session.py` 会把消息同时写进 `sessions/<session_id>.jsonl` 和 SQLite；`load_transcript()` 会比较 JSONL 与 DB 哪边消息更多，避免迁移或异常情况下的历史截断。
14
15
### 源码锚点
16
17
- `gateway/session.py:947-1045`
18
- `gateway/mirror.py:1-124`
19
20
## 3. 本地 memory 文件与 provider 配置
21
22
内建 memory 落在 `HERMES_HOME/memories/`；不同 provider 又各自维护配置文件或本地工作目录，例如 `supermemory.json`、`mem0.json`、`honcho.json`、`byterover/`。
23
24
### 源码锚点
25
26
- `tools/memory_tool.py:105-198`
27
- `plugins/memory/supermemory/__init__.py:1-250`
28
- `plugins/memory/mem0/__init__.py:1-120`
29
- `plugins/memory/honcho/__init__.py:1-160`
30
- `plugins/memory/byterover/__init__.py:1-120`
31
32
## 4. `session_search` 的状态来源
33
34
`session_search_tool.py` 直接读取 `state.db` 的 transcript 历史并走 FTS5 检索，再把命中的 session 摘要化返回。因此它的底座是历史数据库，而不是 provider memory backend。
35
36
### 源码锚点
37
38
- `tools/session_search_tool.py:245-560`
39
hermes-agent/05-调用链、压缩与边界.md
`hermes-agent`：调用链、压缩与边界
1
# `hermes-agent`：调用链、压缩与边界
2
3
## 1. 初始化主链
4
5
主调用链的骨架是：
6
7
`run_agent.py` 初始化 `MemoryStore`、`MemoryManager`、`ContextCompressor`，再在 build prompt、prefetch、tool dispatch、turn end 等节点把这些能力串起来。
8
9
### 源码锚点
10
11
- `run_agent.py:1219-1320`
12
- `run_agent.py:8237-8595`
13
- `run_agent.py:11329-11332`
14
15
## 2. 压缩主链
16
17
压缩路径是：
18
19
`flush_memories()` -> provider `on_pre_compress()` -> `ContextCompressor.compress()` -> 重建 system prompt -> 新 session。
20
21
这里真正被改变的不只是消息列表，还包括 prompt snapshot 与 session lineage。
22
23
### 源码锚点
24
25
- `run_agent.py:7040-7263`
26
- `agent/context_compressor.py:336-1094`
27
28
## 3. 历史检索主链
29
30
`session_search` 会排除当前 lineage，对命中的 transcript 片段做截断与总结，再作为可读回忆返回。这条链路与 provider recall 并列存在，而不是 provider recall 的一种实现。
31
32
### 源码锚点
33
34
- `tools/session_search_tool.py:245-560`
35
36
## 4. 关键边界
37
38
- `session_search` 不是 long-term provider memory。
39
- 内建 `MEMORY.md / USER.md` 不是 session transcript。
40
- provider memory 与 prompt builder 并列，不应并入“单一 memory 层”。
41
42
### 源码锚点
43
44
- `tools/session_search_tool.py:245-560`
45
- `tools/memory_tool.py:105-571`
46
- `agent/prompt_builder.py:144-173`
47