05 · 记忆与召回 · AI 编程教程中文版

Hermes 的 memory（长期记忆）不是无限日志，而是精选长期事实。它的目标是让新 session 一开始就知道关键偏好、环境事实和项目约定，同时把历史细节留给 session_search（会话检索）按需调用。理解这一点比记任何命令都重要——把 memory 当日志写，结果就是 agent 在错误信息上越用越固执。

官方资料：Persistent Memory、Memory Providers、Sessions、Honcho。

先给结论：MEMORY.md（项目记忆）和 USER.md（用户偏好）是短、稳、可验证的长期事实；session_search 是历史会话检索（FTS5 全文索引）；外部 memory provider 是进阶扩展，不是新手必选项——基础三件套用好，多数任务已经够。

官方机制补充

Hermes 的 memory 工具只有三个动作：add、replace、remove。没有 read 动作——因为 memory 会在 session 启动时直接注入 system prompt（系统提示），agent 在当前上下文里已经能看到启动快照，不需要主动读。这是和"无限日志型记忆"的根本区别。

replace 和 remove 使用 old_text 的短唯一子串匹配，不要求复制完整条目。如果子串命中多条，工具会要求更具体的匹配。这个设计适合小容量、高密度 memory，但也要求条目不要写得太相似——否则 replace 时找不到唯一匹配，操作会失败。

add      -> 新增一条长期事实
replace  -> 用唯一子串定位旧条目并替换
remove   -> 用唯一子串定位旧条目并删除
read     -> 不存在，启动时已注入

系统还会拒绝 exact duplicate entries（完全重复条目），并在写入前扫描 prompt injection（提示注入：恶意文本伪装成系统指令）、credential exfiltration（凭据外泄：偷偷把 token / 密码塞进 memory）、SSH backdoor（SSH 后门：写入未授权登录入口）、invisible Unicode（不可见 Unicode：用零宽字符隐藏恶意内容）等模式。原因很直接：memory 会进入 system prompt（系统提示），所以它本身就是长期注入面——任何写进去的内容下次启动都会被模型当成权威指令读。

三层记忆机制总览

Hermes 的记忆并不是单一系统，而是三层各管不同时间尺度，叠在一起才构成"自我改进闭环"的记忆支柱：

flowchart LR
    subgraph S1["启动注入<br/>每次启动 system prompt 自带"]
        M1["MEMORY.md<br/>项目长期事实<br/>~2200 chars"]
        M2["USER.md<br/>用户偏好画像<br/>~1375 chars"]
    end
    subgraph S2["当前会话<br/>本轮对话上下文"]
        S3["session 上下文<br/>本次对话的滚动窗口"]
    end
    subgraph S3box["按需检索<br/>需要时再查"]
        SS["session_search<br/>FTS5 全文索引<br/>历史所有 session"]
        EXT["External Providers<br/>Honcho / Mem0 等<br/>语义 / 用户建模"]
    end
    M1 --> S3
    M2 --> S3
    SS -.LLM 摘要.-> S3
    EXT -.插件式.-> S3

三层使用规则：每次启动都该带 → 内置 memory；本次任务用 → 当前对话；历史回查 → session_search；复杂用户建模 → 外部 provider。

两类长期事实

内置记忆在：

~/.hermes/memories/
├── MEMORY.md
└── USER.md

MEMORY.md

Agent 需要记住的环境和工作事实，例如项目约定、工具坑、已验证修复结论。

USER.md

用户画像，例如沟通偏好、常用技术栈、明确偏好和反复纠正过的要求。

默认容量按官方当前 memory 配置文档（截至本文核验日：MEMORY.md 2200 chars、USER.md 1375 chars）。容量小是有意设计——为了让记忆保持高密度，而不是把聊天历史变成永久 prompt。容量小才是优势：每次启动这两个文件全文都进系统提示，越短模型越能精准记住。

官方配置键在 ~/.hermes/config.yaml 的 memory 段：

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375

不要为了“多记一点”盲目把限制调大。限制越大，长期 prompt 的噪音和注入面也越大。

冻结快照

两者会在 session 启动时注入 system prompt。当前 session 中新增或修改的记忆会写盘，但不会刷新当前 system prompt；新 session 才能看到。

这个机制的判断：

当前任务马上需要：直接在当前对话说。
以后每次都该知道：写入 memory。
只是可能要回查：留给 session_search。

不要因为“刚保存的记忆没立刻生效”就重复写入。

保存标准

适合保存：

用户明确偏好。
稳定环境事实。
项目长期规则。
反复出现的工具问题。
已验证过的修复结论。

不适合保存：

一次性任务细节。
大段日志或代码。
临时文件路径。
可以从项目文档直接读到的内容。
未验证的猜测。

错误记忆比缺少记忆更危险。它会持续影响后续 session，并让 agent 变得“有依据地错”。

session_search

session_search 是历史会话检索，不是 curated memory。

适合问：

之前怎么修过类似问题。
某个长期任务上次停在哪里。
用户曾经纠正过什么。
某个项目以前跑过哪些命令。

Hermes 把 CLI 和 messaging sessions 写入 SQLite，并用 FTS5 全文检索，再由模型总结相关片段。

官方实现里历史会话存储在 ~/.hermes/state.db。这意味着 session_search 更像“查历史记录再摘要”，而 memory 更像“每轮启动都默认携带的长期事实”。前者容量大但按需触发，后者容量小但每次都会进入上下文。

简单判断：

每次都该知道 -> memory
偶尔需要回查 -> session_search
当前临时上下文 -> 当前对话
项目长期规则 -> AGENTS.md / CLAUDE.md / .hermes.md

外部 provider

Hermes 支持多个外部 memory provider（记忆插件，按官方 Memory Providers 页当前列表为准）：Honcho（AI 原生用户建模）、OpenViking、Mem0（流行的 AI 记忆服务）、Hindsight、Holographic、RetainDB、ByteRover、Supermemory 等——多数是 AI-native（AI 原生）记忆服务，提供语义搜索、用户建模、知识图谱等能力。

外部 provider 适合更复杂的长期用户建模、语义搜索、知识图谱或自动事实抽取，但不要一开始就接。先把内置 memory 用好，再判断是否需要外部 provider——多数场景内置 MEMORY.md + USER.md + session_search 已经够。

hermes memory setup    # 选 provider + 配凭据
hermes memory status   # 查当前激活的 provider 和数据量

它们和内置 memory 并行工作，不替代 MEMORY.md / USER.md——内置层是"启动快照"，外部 provider 是"按需查询的语义检索层"。Honcho 提供官方推荐的 dialectic（辩证式）多代理用户建模，用 LLM 持续修正用户画像，是 Nous Research 自己重点推的能力。

记忆治理

推荐规则：

事实必须可验证
偏好必须来自用户明确表达
临时信息不入库
低密度内容先合并再保存
超过 80% 容量就主动压缩
发现错误立即 replace 或 remove
外部内容先提炼再入库

好的 memory 会让 Hermes 越用越贴合；坏的 memory 会让它越来越固执。

何时合并而不是新增

官方建议 memory 超过 80% 容量时先合并。实践中可以用这组规则判断：

情况	动作
同一项目有多条环境事实	合并成一条项目画像
用户偏好互相冲突	replace 成最新明确偏好
一次性任务已经结束	remove，不要留长期记忆
同一工具坑反复出现	合并为“症状 + 原因 + 修复”
条目来自外部网页或 issue	先提炼事实，再决定是否 add

memory 的目标不是完整，而是稳定。能从项目文档、命令、Git 历史或官方文档重新读到的信息，不应该优先占用 memory。

安全边界

记忆会直接进入 system prompt，所以它是长期注入面——任何写进 memory 的内容会在每次启动时被模型当成"权威指令"读取。这意味着两条铁律：

来源审查：外部网页、issue、聊天记录、PR 评论里的原文不要直接保存成 memory。先判断来源可信度，再提炼成经过验证的事实——攻击者可以在 GitHub issue 留下 prompt injection 文本，等你不慎复制进 memory 就长期生效。
不保存凭据：API key、token、密码、私钥路径、SSH backdoor、可用于攻击的连接信息一律不入 memory。需要凭据时走 ~/.hermes/.env 或操作系统级凭据系统（macOS Keychain / 1Password CLI 等）。Hermes 启动时会扫描 memory 内容里的 prompt injection、凭据外泄、SSH backdoor、不可见 Unicode 等模式并拒写——但你也别故意去试它的下限。

官方资料

Persistent Memory（MEMORY.md / USER.md / 容量 / 注入机制）
Memory Providers（外部 provider 完整列表）
Honcho（AI-native dialectic 用户建模）
Sessions（session_search 来源）
Context Files（项目级 AGENTS.md / CLAUDE.md / .hermes.md / 全局 SOUL.md）

05 · 记忆与召回