Hermes Agent 记忆系统全景图

1 系统架构总览 v

核心原则：内置 Provider 和外部 Provider 共享同一套 MemoryProvider 接口，MemoryManager 统一编排。内置永远激活；外部同一时刻只允许一个。

2 Builtin MemoryStore — memories/MEMORY.md & USER.md v

存储路径HERMES_HOME/memories/MEMORY.md 和 USER.md

持久化Markdown，条目间用 § 分隔；原子写入（tempfile + os.fsync + atomic_replace）

容量上限MEMORY.md → 2200 chars；USER.md → 1375 chars

文件锁fcntl (Unix) / msvcrt (Win) 独占锁，防并发写入

读写触发机制

会话启动 -> AIAgent.__init__() 实例化 MemoryStore -> load_from_disk() 读取文件并冻结快照 -> System Prompt 组装 -> format_for_system_prompt() 注入快照

会话中途写入 -> memory_tool(action=add|replace|remove) -> _scan_memory_content() 扫描注入/外泄特征 -> 立即持久化到磁盘 -> System Prompt 快照不变（保护 prefix cache）

快照模式核心逻辑

      memory_entries — 实时内存状态（可变）

      _system_prompt_snapshot — 冻结快照（load_from_disk 时固定）

      写入时：只更新 memory_entries + 持久化磁盘

      不修改 _system_prompt_snapshot → System Prompt 全程稳定

安全扫描（每次写入前）

      _MEMORY_THREAT_PATTERNS 在写入时执行扫描，而非注入前临时检查：

      ignore ... instructions — 提示注入检测

      you are now ... — 角色劫持检测

      curl ... $KEY/$TOKEN/$SECRET — 数据外泄检测

      authorized_keys — SSH 后门检测

      $HOME/.hermes/.env — 凭证读取检测

内容规范

      应写入：用户偏好、环境常量、项目约定、工具习惯、稳定事实

      不写入：任务进度、PR号、commit SHA、已完成的工作、7天内过时的信息

      格式：陈述句，非指令句

            'Project uses pytest with xdist' OK — 'Run tests with pytest -n 4' BAD

3 Session DB — state.db（FTS5 全文检索） v

存储路径HERMES_HOME/state.db（SQLite WAL 模式）

容量无上限；FTS5 全文索引跨所有 session 消息

FTS5Trigram tokenizer（CJK 字符原生支持）

读写触发机制

每轮对话结束 -> append_message(role, content) -> 写入 messages 表（WAL 并发安全）

上下文压缩 -> 新 session_id 创建，parent_session_id 指向旧 session -> 链式追溯不丢失历史

session_search 工具调用 -> FTS5 全文检索（trigram） -> 返回匹配 session 的摘要

数据库 Schema

      sessions — session 元数据（source, parent_session_id 链）

      messages — 完整对话历史（role, content）

      messages_fts — FTS5 虚拟表，trigram tokenizer（CJK 原生支持）

      schema_version — 版本追踪

      state — 全局键值状态

4 Skills — 技能知识库（可复用工作流） v

存储路径HERMES_HOME/skills/*.md（用户安装）
HERMES_HOME/optional-skills/（内置包）

容量无上限；每个 skill 独立文件

格式YAML frontmatter + Markdown 正文

读写触发机制

会话启动 -> 扫描 skills/ 目录，解析 frontmatter -> platform 匹配 & 条件过滤 -> skills index 注入 System Prompt

满足触发条件时 -> skill_view(name='xxx') -> 加载完整 SKILL.md 到上下文 -> 按 skill 步骤执行

发现新工作流/错误修复 -> skill_manage(action='create') -> 写入新 skill 目录到 skills/

Skill vs Memory vs session_search 分工

	MemoryStore	Skills	session_search
内容	跨会话稳定事实	可复用工作流/流程	临时任务细节/历史会话
格式	陈述句	步骤+命令+验证	原始对话内容
触发	每轮自动注入	按 skill 条件加载	用户引用/主动召回
生命周期	长期稳定	积累/更新/归档	会话结束仍可查

5 Session Transcripts — sessions/*.jsonl（遗留） v

存储路径HERMES_HOME/sessions/session_<id>.jsonl

状态遗留格式；state.db 是新的标准存储（WAL + FTS5）

用途旧 session 数据的回退兼容；新数据不再写入此处

格式：每行一条 JSON，存储 user/assistant 消息对象。已在代码中标记为 deprecated，state.db 承担全部新负载。

6 .hermes.md — 项目级上下文碎片（分布式） v

存储路径每个项目仓库根目录：.hermes.md 或 HERMES.md

发现方式从 cwd 向上搜索至 git 仓库根；自动扫描，不需配置

注入时机会话启动时，每次组装 System Prompt 时读取（已扫描缓存）

读写触发机制

System Prompt 组装 -> _find_hermes_md(cwd) -> _scan_context_content() 扫描注入 -> 内容注入 volatile tier

安全扫描（与 MEMORY.md 相同的模式）

      _CONTEXT_THREAT_PATTERNS 在文件读取时执行扫描：

      ignore ... instructions — prompt injection

      <div style="...display:none" — hidden div injection

      curl ... $KEY/$TOKEN/$SECRET — 数据外泄检测

7 外部 Memory Provider（可插拔后端） v

接口MemoryProvider（ABC），定义在 agent/memory_provider.py

限制同时只能注册一个外部 Provider（防止工具 schema 膨胀）

注册方式memory.provider in config.yaml

已实现的 Provider

Honchohoncho

Mem0mem0

Hindsighthindsight

SuperMemorysupermemory

RetainDBretaindb

Holographicholographic

ByteRoverbyterover

OpenVikingopenviking

MemoryProvider 核心生命周期

      必须实现：is_available() 就绪检查 · initialize() 连接建表 · get_tool_schemas() 注册工具

      核心操作：system_prompt_block() 静态提示块 · prefetch(query) 每轮前召回 · sync_turn(user, asst) 每轮后持久化

      可选钩子：on_turn_start() · on_session_end() · on_session_switch() · on_pre_compress() · on_memory_write() · on_delegation()

读写触发机制

System Prompt 组装 -> memory_manager.build_system_prompt() -> provider.system_prompt_block()

每轮 LLM 调用前 -> memory_manager.prefetch_all(query) -> provider.prefetch(query) -> build_memory_context_block() 包装 → 注入

每轮对话结束后 -> memory_manager.sync_all(user, asst) -> provider.sync_turn() 异步队列写入

builtin memory 写入时 -> memory_manager.on_memory_write() -> provider.on_memory_write() 同步镜像

8 设计哲学 v

快照而非流式

会话中途写入 → 立即持久化磁盘，但不修改已注入的 System Prompt。保护 prefix cache 全程稳定。

内外解耦，接口先行

内置 + 外部 Provider 共用 MemoryProvider 接口，MemoryManager 统一编排。插件接入无需改核心代码。

安全内嵌，非外挂

内容扫描在写入时执行，不在注入前临时检查。防止多次小写入绕过检测的攻击向量。

错误隔离，Fail-safe

每个 Provider 调用都 try/except 包裹。一个 Provider 故障不导致其他 Provider 或主 agent 崩溃。

Provider 感知生命周期

Provider 不是被动存储，而是有状态的 Observer——知道 turn 开始/结束、context 压缩、session 切换。

记忆 / 技能 / 会话三分

三层机制互补不重叠：MemoryStore 管事实，Skills 管流程，session_search 管历史。各自有明确的容量和触发规则。

9 总览对照表 v

存储实体	路径	记忆类型	写入触发	读取触发	容量
MEMORY.md	`memories/`	跨会话事实（环境/约定/习惯）	memory_tool add	会话启动快照	2200 chars
USER.md	`memories/`	用户画像（偏好/风格）	memory_tool add	会话启动快照	1375 chars
state.db	根目录	会话历史 + FTS5 全文索引	每轮对话结束	session_search 工具	无上限
skills/	根目录	可复用工作流/错误修复	skill_manage create	skill_view / 条件触发	无上限
*sessions/.jsonl**	`sessions/`	早期会话记录（遗留）	已废弃	回退兼容	无上限
.hermes.md	项目仓库根	项目级上下文碎片	用户编辑文件	System Prompt 组装	无上限
External Provider	Provider 自定义	可插拔记忆后端	sync_turn / on_memory_write	prefetch 每轮前召回	Provider 决定

快照而非流式

内外解耦，接口先行

安全内嵌，非外挂

错误隔离，Fail-safe

Provider 感知生命周期

记忆 / 技能 / 会话 三分

记忆 / 技能 / 会话三分