第20篇：持久记忆——AI 的长期记忆

第20篇：持久记忆——AI 的长期记忆

你有没有遇到过这种情况：跟 AI 聊完一个项目，第二天打开新会话，它什么都不记得了，你得从头再解释一遍？Hermes Agent 的“持久记忆”功能，就像给 AI 配了一个随身笔记本——它会把重要的事情记下来，下次见面时自动翻出来看，不用你反复叮嘱。

---

第1步：了解记忆存在哪

Hermes 的记忆由两个文件组成，都存放在 ~/.hermes/memories/ 目录下：

文件	用途	字数上限
MEMORY.md	AI 的个人笔记（环境信息、项目约定、踩坑经验）	2,200 字符
USER.md	你的用户画像（偏好、沟通风格、期望）	1,375 字符

这两个文件会在每次会话开始时，被“快照”注入到系统提示词里，AI 一睁眼就能看到。

第2步：认识记忆的显示格式

会话开始后，AI 的提示词里会有一块固定的记忆区域，长这样：

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
§
This machine runs Ubuntu 22.04, has Docker and Podman installed

注意两点：

• 每条记忆用 § 符号分隔，支持多行内容
• 头部会显示已用百分比和字符数，让 AI 知道还剩多少空间

第3步：AI 如何管理记忆

AI 通过 memory 工具来操作记忆，只有三个动作：

• add — 添加新记忆
• patch — 替换某条记忆内部的一小段，其余内容保留（old_text 是那一段，content 是它的替换内容）
• remove — 删除不再需要的记忆（用 old_text 做子串匹配）

不需要 read 动作，因为记忆已经自动注入到提示词里了。

子串匹配小技巧：patch 或删除时，只需提供能唯一定位某条记忆的短片段即可。比如记忆里有“User prefers dark mode in all editors”，你可以这样替换：

memory(action="patch", target="memory",
       old_text="dark mode",
       content="User prefers light mode in VS Code, dark mode in terminal")

如果片段匹配到多条记忆，工具会报错，要求你提供更精确的匹配。如果 old_text 一条都没匹配上，同样会失败，并在 closest_entries 里列出最接近的几条，方便你换个片段重试。

注意 patch 只替换 old_text 命中的那一小段，条目其余内容原样保留；想整条重写就改用 add 新增后 remove 旧条目。

每次工具调用都必须带一个顶层 target："memory" 表示 AI 笔记，"user" 表示用户画像。批量操作里所有动作共用这一个 target：

{"target": "user", "operations": [{"action": "add", "content": "User prefers metric units"}]}

缺少 target、target 为 null，或某个操作里的 target 与顶层不一致，都会在写入或暂存审核之前直接报错。改好 payload 再重试；要同时更新两个存储，请分两次调用。

第4步：分清两个记忆目标

• memory（AI 的个人笔记）：记环境事实、项目约定、工具坑、成功经验等
• user（用户画像）：记你的偏好、沟通风格、期望

第5步：注意两个重要规则

1. 一个 Hermes 目录只能跑一个 agent：别让两个 agent 共用同一个 home 目录，否则记忆会互相污染。需要多 agent 时，给每个 agent 单独建 profile；如果它们确实需要共享记忆，那就改用外部记忆提供者。
2. 记忆满了不会自动压缩：当写入超出字符限制时，工具会报错而不是静默丢弃。报错信息会告诉你超了多少字符，并明确要求 AI 用一次 operations 批量操作来腾空间：在同一次调用里删掉或缩短（patch）过时条目，腾出足够的字符数，同时把新条目加进去——上限只在批量操作的最终结果上检查一次。AI 会照这个提示重试。注意 patch 也受这个限制：把一条记忆改得更长同样可能撑爆，所以新内容得压缩一下，或者顺手删掉别的条目。

另外，记忆是会话开始时冻结的快照，会话中途的修改会立即存盘，但要到下次会话才会出现在提示词里。工具响应中看到的始终是实时状态。

第6步：记得给会话划个界

整套记忆机制其实是围绕“会话结束”这个时刻设计的：MEMORY.md 和 USER.md 把要点带到下一次会话，session_search 则在旧上下文消失后补上细节。而在同一个会话内部，这些机制基本没机会上场——重要的东西都还在当前上下文里，AI 很少去翻历史会话，更多只是压缩记忆条目。

这在消息平台上尤其明显（Telegram、Discord 等），因为那边的聊天被设计成一个持续不断的会话，能扛过重启、网关崩溃甚至机器重启。晚上关机并不会结束会话，下一条消息会接着上次的地方继续。如果你一直不重置，一个聊天可能连续跑好几周：方便是方便，但会越来越贵（压缩反复在越来越长的历史上跑），而且“遗忘 → 从记忆里回想 → 搜索历史会话”这个学习闭环几乎没机会触发。再加上前面说的冻结快照，新写入的记忆对当前会话也是不可见的。

建议：在自然的节点上跑一下 /new——任务做完了、换话题了、新的一天开始了。每个节点都是记忆发挥作用的时候：AI 重新读取更新后的 MEMORY.md/USER.md 快照，从便宜的短上下文起步，真需要历史时再去 session_search。在 CLI 上这基本是自动的（每次调用都是新会话）；在网关上，这个边界就得你自己来划。

第7步：说了“记住”却还是忘？按顺序排查

最常见的抱怨是这样的：你告诉 AI 某个东西放在哪（一个 Obsidian 仓库、一个项目目录、一台服务器），它回答“好的，我记住了”，结果新会话完全不知道你在说什么。按下面的顺序排查，第一条就能解释绝大多数情况：

1. 确认写入真的发生了：记忆只有在模型调用 memory 工具时才会落盘，一句“我已经记到记忆里了”只是文字。直接打开文件看有没有这条：

   cat ~/.hermes/memories/MEMORY.md
   cat ~/.hermes/memories/USER.md

   如果里面没有，说明模型只是嘴上说存了。小模型（大约 30B 参数以下）和工具调用能力弱的模型经常这样。可以明确要求它“用 memory 工具保存仓库路径 /srv/vault”，再确认条目进了文件。如果反复出现，解决办法是换更强的模型来做设置，而不是加更多叮嘱；条目一旦存在，小模型也能正常读到，因为它们会随系统提示词一起送达。
2. 确认写入没有被暂存：开启 write_approval: true 后，交互式 CLI 之外的写入会被挂起等待审核，不会进文件——跑 /memory pending 和 /memory approve all 处理。
3. 确认你读的是同一个 profile 的记忆：记忆是按 profile 隔离的，hermes -p work（或 work chat / work gateway start）读的是 ~/.hermes/profiles/work/memories/，而不是 ~/.hermes/memories/。默认 profile 的 CLI 会话和另一个 profile 上的 Telegram 机器人不共享笔记，hermes profile list 可以看有哪些 profile。
4. 确认记忆是开启的：memory.memory_enabled: false（或把 memory 放进 agent.disabled_toolsets）会直接移除这个工具，模型无论说什么都存不了。
5. 记住快照在会话开始时就被冻结了：当前会话保存的事实对下一个会话可见，对已经在运行的其他会话不可见。写入后开个新会话（/new 或重新调用 CLI）即可。

有两样东西不会让 AI 记住：.env 里的变量（那是凭据和设置，不是记忆），以及随口提到但没要求保存的事实。如果是某个周期性任务每次都要用到的位置，用 skill 往往比记忆条目更合适——它只在相关时加载，也不占用那 2,200 字符的预算。

第8步：内置记忆不够用？试试外部记忆提供者

MEMORY.md 和 USER.md 走的是“精炼、小容量”路线，适合记要点，但装不下大量、长期、需要检索的知识。想要更深、更持久的记忆，Hermes 内置了 2 个外部记忆提供者插件：RetainDB 和 ByteRover。

除此之外，插件目录（plugin catalog）里还有更多选择，比如 Honcho、Hindsight、Supermemory、Mem0、OpenViking 和 Holographic，安装方式统一是：

hermes plugins install <name>

把 <name> 换成上面某个提供者的名字即可。装好之后，记忆就会存到外部服务里，不再受那两个文件的字符上限约束——适合知识量大、需要跨会话长期积累的场景。

关于外部召回的大小：外部提供者默认会返回完整的预取上下文，上限是 hooks.output_spill.max_chars 的 10 倍（至少 100,000 字符）；超过这个上限的召回仍会溢出，避免失控的提供者撑爆上下文窗口。如果你想让当前 profile 把过大的召回换成“头尾预览 + 文件路径”的形式，可以打开 memory.prefetch_spill_enabled: true（默认 false，也就是外部召回保持完整）。这样能减少重复注入的上下文，但排序在中间、相关性最高的部分就不再直接可见了——所以能用提供者自己的召回预算时，优先用它的。这个开关复用 hooks.output_spill 的阈值、预览长度和目录；hooks.output_spill.enabled: false 依然会把它关掉。普通插件钩子默认照常溢出，不受这个开关影响。注意这些设置是在提供者注册时捕获的：改完要重启 Hermes 才生效。

---

总结：持久记忆让 Hermes 成为一个“有记性”的助手。它用两个文件分别记录 AI 的笔记和你的画像，通过 add / patch / remove 三个动作自主管理，并靠字符上限保持内容精炼。内置记忆不够用时，还能通过 hermes plugins install <name> 接入 RetainDB、ByteRover、Honcho、Hindsight、Supermemory、Mem0、OpenViking、Holographic 等外部记忆提供者。下次打开新会话，它依然记得你是谁、在做什么。

下一篇预告：第21篇将介绍 Memory Providers（外部记忆提供者）——当内置记忆不够用时，如何接入外部存储来扩展记忆容量。