hermes-agent 学习页

hermes-agent 是一个把 prompt 组装、会话持久化、context 压缩、内建 memory 和外部 provider memory 并行编排在一起的完整 agent runtime，而不是单一 memory 库。

它最关键的不是某一个 memory provider，而是把 prompt 组装、历史检索、内建记忆和外部 provider 记忆拆成并行链路，再由压缩点把会话切成新 session。

源码事实终端型 Agent Runtime

回横向对照打开证据页

这页怎么读

先看“这一轮模型看到了什么”，建立模型视角。
再看 context 和 memory 两张图，抓主链。
最后看源码锚点和证据页，确认细节。

这一轮模型到底看到了什么

这一段只讲模型真正可见的材料，不把所有底层状态都算进 context。

context 组成图

它把 system prompt、历史检索、压缩和 provider 插件放成并行层，而不是一个统一大 memory。

run_agent

初始化 MemoryStore、MemoryManager 和 ContextCompressor。

prompt_builder

拼出 system prompt。

ContextCompressor

在需要时重写旧消息。

session_search

从 transcript 历史检索可用内容。

MemoryManager

调度 provider 插件。

provider plugins

各自 recall / sync / profile。

模型入口不是“一个记忆层”，而是 prompt_builder 拼出的 system prompt 加上 turn 上下文。
MEMORY.md / USER.md 这类内建 memory 会被加载、去重，并冻结进当前 prompt snapshot。
session_search 只负责从 state.db 里的 transcript 历史检索，不等同于 long-term provider memory。
ContextCompressor 不只是摘要，它还会先替换旧 tool 输出，再做结构化压缩。
压缩时会保留头尾消息，并修复 tool call / result 的对齐关系。
MemoryManager 把外部 provider 统一成可注册、可预取、可同步、可挂钩的插件层。
压缩后的结果不是继续旧会话，而是重建 system prompt 并开启带 parent_session_id 的新 session。

context 是怎么拼起来的

先看组成块，再看顺序。这里最容易帮助普通读者分清“哪些东西会真的进模型”。

system prompt assembly

prompt_builder 把身份、memory 指导、session_search 指导、skills、项目上下文和环境提示拼成 system prompt。

prompt

project context references

.hermes.md/HERMES.md、AGENTS.md、CLAUDE.md、.cursorrules 以及 @file/@folder/@git/@diff/@url 会在发送前展开。

context-references

compression engine

ContextCompressor 负责旧 tool 输出摘要、头尾保护、结构化压缩，以及 tool call / result 对齐修复。

compressor

history retrieval

session_search 基于 state.db 中的 transcript 和 FTS5 检索，把命中的历史摘要回填到当前上下文。

retrieval

session persistence

gateway/session 通过 JSONL + SQLite 双写保存轨迹。

storage

run_agent 先初始化 MemoryStore、MemoryManager 和 ContextCompressor。
prompt_builder 收集身份、memory 指导、session_search 指导、skills、项目上下文和环境提示，生成 system prompt。
运行中再把 prefetch、tool dispatch、turn end 等节点串起来，持续补上下文。
需要压缩时先 flush_memories()，再通知 provider 执行 on_pre_compress()。
ContextCompressor.compress() 处理消息、工具输出和对齐修复后，重建 system prompt。
旧 session 被结束，新的 session 以 parent_session_id 继续写回 state.db。

memory 是怎么形成、保存、再被取回的

不要把记忆想成一个抽象黑盒。这里直接按时间顺序讲“它什么时候生成、存哪、怎么再回来”。

memory 流程时间线

本地 memory、provider memory 和压缩重建会话是三条并行链，在 flush/compact 时合流。

启动读取 memory

先载入 MEMORY.md / USER.md。

生成 system prompt

把内建 memory 冻进当前快照。

运行中检索/写入

持续调 session_search 和 provider。

flush_memories

压缩前先把外部记忆同步出去。

compress + rebuild

重建 prompt 和消息视图。

创建新 session

以 parent_session_id 续接。

启动时 MemoryStore 读取 HERMES_HOME/memories/MEMORY.md 和 USER.md，并做去重。
内建 memory 会在会话开始时冻结成当前 system prompt snapshot。
memory 工具只支持 add / replace / remove，写入前会扫 injection 和 exfil 风险。
MemoryManager 统一注册外部 provider，并附加 provider prompt、prefetch、sync、tool schema 和生命周期钩子。
各 provider 通过插件实现各自的 recall、profile、conclude 和 background sync 语义。
需要刷新时，memory 先同步到 provider，再进入压缩与重建新 session 的循环。

存储分层图

很多误解都来自把 transcript、summary、文件、数据库和向量库混成一层看。

存储分层图

会话库、jsonl 镜像、文件型 memory 和 provider 配置层各司其职。

state.db

核心会话库。

sessions/*.jsonl

轨迹镜像层。

HERMES_HOME/memories/*.md

文件型内建记忆。

provider config

外部 provider 的配置文件或工作目录。

plugins/memory/*

provider 实现层。

state.db：SQLite 主库，承载 session、message、FTS5 和压缩后新 session 等元数据。
sessions/<session_id>.jsonl：gateway 的会话镜像，用于双写、迁移和回放。
HERMES_HOME/memories/：内建文件型 memory 根目录，存放 MEMORY.md 和 USER.md。
supermemory.json / mem0.json / honcho.json / byterover/：外部 provider 的配置文件或本地工作目录。
plugins/memory/*：各 provider 的实现层，封装 recall / sync / profile 能力。
session_search：只读 state.db 的历史 transcript，不直接读 provider backend。