Hermes智能体记忆外挂：分层设计、接入与排障

Hermes 这类智能体框架在单轮对话里可以回答得很漂亮，可一旦关掉窗口，它就像失忆了一样。给 Hermes 装上记忆外挂，真正要解决的并不是把模型底座换得更大，而是把用户偏好、历史结论、失败记录和任务状态保存下来，在下次对话时按需取回。适合先动手的人有两类：一类在基于 Hermes 做个人助理或客服问答，另一类在跑重复性任务，却被同一个问题反复卡住。我会按实际落地顺序拆：记忆分层、接入点、存储结构、参数判断、排查链路和边界控制。很多记忆需求不需要一开始就上复杂架构，先抓住一条主线：对话前读取，对话后写入，需要时注入 prompt。

1. Hermes 智能体缺的不是聪明，而是“记住了什么”

1.1 智力型 AI 和实用型 AI 的差距在哪

模型本身的知识来自训练阶段，它知道很多通用知识，但它不知道“你”上一次跟它聊了什么。你可能已经告诉过 Hermes“我这边是电商项目，术语要保留英文”，下次提问时它又默认翻译成中文。不是模型变笨了，而是 conversation history 已经清空，它只能基于当前请求重新理解。

实用型 AI 和演示型 AI 的一个明显分界线就在这里。演示型 AI 只要单轮回答惊艳就够了；实用型 AI 必须能连续承接多轮、多天的任务。用户会默认“你应该记得我说过的话”，这是人对助手的基本期望。所以记忆外挂解决的不是模型智商问题，而是“状态延续”问题。模型负责推理，记忆模块负责告诉模型：这个用户是谁、之前做过什么、现在最在意什么。

1.2 记忆模块在整个智能体架构里的位置

在常见智能体流程里，用户输入不会直接进模型。通常会经过意图识别、提示词组装、工具调用、上下文管理，最后再把模型输出返回给用户。记忆模块最适合插在两个位置：一个是模型调用之前，负责把相关历史信息一起组装进 prompt；另一个是模型调用之后，负责把本次对话中有价值的信息提取出来写入存储。

我一般会画一条最小链路：

用户输入 -> 读取记忆 -> 组装 prompt -> 模型推理 -> 执行动作 -> 更新记忆 -> 返回结果。

记忆模块在这里相当于一个外部数据层。它和模型本身解耦，所以就算以后换底座模型，历史记忆也不需要重做。反过来，如果一开始就把记忆逻辑写死在系统提示词里，后面每次改 prompt 都会牵连到记忆格式，维护成本会快速上升。

1.3 记忆外挂的“外挂”到底指什么

“外挂”在这里不是游戏外挂，而是给智能体挂载的外部扩展模块。它单独负责数据的写入、检索、更新和过期清理，业务代码只需要调用两个函数：读取记忆、保存记忆。这样做的最大好处是：你不需要重新训练模型，也不需要改动 Hermes 的核心调度逻辑，就可以让同一套模型表现出“记得我”的效果。所谓“越用越聪明”，本质上是记忆模块里的用户画像和任务状态越来越完整，检索命中越来越准。

2. 先想清楚记忆系统要具备哪几层，再动手写代码

2.1 会话级记忆：只负责当前上下文

会话级记忆就是当前对话窗口里的历史消息。大多数智能体框架自带的 history 就是这一层。它的生命周期很短，窗口关闭或上下文超长截断后，早期信息就丢了。很多人的误区是，以为把 system prompt 里塞满历史消息就能解决记忆问题。实际上那只是在堆 token，超过窗口长度后照样被截断，而且会让模型分不清哪句是当前指令、哪句是历史背景。

会话级记忆适合保存临时信息，比如用户正在调试的代码、当前页面的 URL、上次工具调用返回的中间结果。不建议把长期偏好放在这一层。

2.2 用户级记忆：跨对话持久化的关键

用户级记忆是记忆外挂的核心。它要保存的是“不依赖某一次对话”的信息，常见的有：

• 用户身份和称呼方式
• 回答风格偏好：喜欢短回答还是长回答，要不要给代码，是否保留英文术语
• 历史结论：上次完成了什么任务，下一步准备做什么
• 对象信息：项目名称、数据库表名、服务器地址等业务上下文

这部分必须落到外部存储。最简单可以用 SQLite 或本地 JSON 文件，按 user_id 分组。用户 ID 要从稳定来源取，比如登录账号、会话生成的唯一 ID。注意不要拿浏览器 UA、临时 token 当用户 ID，否则两次登录之间记忆会断。

2.3 任务级记忆：让批量任务不重复犯错

如果你用 Hermes 跑的是批量任务，比如批量改写文档、批量审核文本、自动化测试流程，那还需要任务级记忆。任务级记忆记录的是“这次任务做到哪了、哪条失败、失败原因、是否重试、输出命名规则”。

这类记忆不需要很高的智能检索，反而更像状态表。我一般会用一张任务表保存：task_id、item_id、status、error_message、retry_count、started_at、finished_at。每处理完一条，立即更新状态。这样即使中间崩溃，重启后也能从上次失败点继续，而不是从头跑一遍。

2.4 三层记忆的协作关系

三层记忆不是互相替代，而是互相补充。会话级记忆提供当前上下文，用户级记忆提供长期画像，任务级记忆提供执行进度。协作方式可以理解为：对话开始时，优先加载用户级记忆；对话过程中，会话级记忆实时更新；每轮结束后，把值得沉淀的信息回写到用户级或任务级存储。

用一个表来看比较清楚：

先把这个分层想清楚，再写代码就不会乱。很多人一上来就接向量数据库，结果连最基本的历史偏好都没存住，这就是层级没分明白。

3. 给 Hermes 加记忆外挂的落地步骤

3.1 第一步：确定接入点，先写一个记忆钩子

给 Hermes 加记忆，不需要一开始就侵入核心调度。先找出消息处理入口，在模型调用前加“读取记忆”，在回复返回前加“保存记忆”。下面是一个示例伪代码，具体函数名以你用的 Hermes 版本为准：

def handle_message(user_id: str, user_input: str): # 模型调用前：读取与该用户相关的记忆 memories = memory_store.retrieve(user_id, user_input) # 组装 prompt：把记忆作为参考信息注入 prompt = build_prompt(user_input, memories) # 模型正常推理 reply = agent.chat(prompt) # 模型调用后：把值得记住的信息写入存储 memory_store.save(user_id, user_input, reply) return reply

这段逻辑看起来很简单，但它把记忆链路完整串起来了。最关键的一点是“读取”和“保存”都放在同一个入口里，避免某些分支漏掉。如果你有工具调用、RPA 步骤，也要在同一个流程里更新记忆，否则下次还是会丢状态。

3.2 第二步：设计记忆条目和存储结构

记忆条目需要包含足够的元信息，否则后面检索不到，也清不掉。一个比较稳妥的 JSON 结构长这样：

{ "user_id": "user_001", "updated_at": "2025-01-01T12:00:00Z", "items": [ { "id": "memo_001", "type": "preference", "content": "用户希望回答控制在300字以内", "created_at": "2025-01-01T10:00:00Z", "last_access_at": "2025-01-01T12:00:00Z", "source": "chat" } ] }

type 字段建议不要乱写，固定几个枚举：preference、project_info、conclusion、state、error_record。后面做检索和清理时，按 type 过滤会比全文扫描方便很多。数据量不大时，一个 JSON 文件或者 SQLite 表就够了；数据量大了再考虑向量库。

存储结构定好后，要尽早确认记忆目录的位置。用 Docker 部署 Hermes 时，需要把记忆目录挂载到宿主机，否则容器重建后记忆会丢失；在 Windows 本地跑时，要注意 JSON 文件路径里的反斜杠和 UTF-8 编码，中文内容写进文件后变成乱码，后面检索基本就废了。

3.3 第三步：查询时把记忆注入上下文

记忆不是把所有历史都塞回给模型，而是按当前输入筛选出最相关的几条。检索方式可以分阶段：

1. 先按关键词和 type 过滤，把明显无关的记忆去掉。
2. 再用向量相似度排序，取 top_k 条。
3. 最后按更新时间做轻微衰减，避免旧记忆占用太多权重。

注入时注意位置。我习惯把记忆放在系统提示和用户问题之间，并加一行说明：

以下是该用户的历史记忆摘要，如果与当前问题无关，请忽略： - 用户偏好：回答尽量控制在300字以内 - 之前结论：上周完成了订单查询接口联调 - 当前任务：正在整理 Hermes 部署文档 请根据用户当前问题做出回答：

这样模型既能看到背景，又不会被历史信息带偏。注入的内容要控制长度，建议限制在 1000 到 2000 字符以内，具体看模型上下文窗口和任务复杂度。

3.4 第四步：用最小链路跑通验证

第一次测试不要直接上生产数据。我一般会准备三组固定输入：

• 第一轮：让 Hermes 记住一个偏好，比如“我只需要最终结论，不要分析过程”。
• 第二轮：模拟新开会话，问一个需要该偏好的问题。
• 第三轮：修改偏好，再确认系统有没有更新旧记忆。

跑完后直接看三件事：第一轮的偏好是否被写入，第二轮输出是否体现该偏好，第三轮更新后旧记忆有没有被覆盖或标记过期。能跑通这三步，记忆外挂的最小闭环就算成立了。

3.5 从单条对话扩展到批量任务

批量任务和单条对话的差异主要在于状态管理。如果一次要处理 100 条输入，不能只靠对话记忆，因为中间可能崩溃、超时、并发冲突。建议加一个任务列表，每条记录包含：

• item_id：当前处理到哪一条
• status：待处理、处理中、成功、失败、跳过
• error_message：失败原因
• retry_count：已经重试几次

伪代码思路大概是：

for item in task_list: select * from task_state where item_id = current if status in ('success', 'skip'): continue try: reply = agent.chat(build_prompt(item, memory)) save_output(reply) update_state(item_id, status='success') except Exception as e: update_state(item_id, status='failed', error=str(e))

这样既能断点续跑，也能统计失败率。不要一上来就开高并发，先把单条跑通，再按 2、4、8 逐步往上加。

4. 关键参数和效果判断标准

4.1 记忆有没有生效，先看这四个现象

很多人在调试记忆时只看模型有没有报错。报错少了，但记忆不一定生效。我会按下面四个现象逐个确认：

• 重新开会话后，模型能不能说出用户上次提到的偏好。
• 同一个问题问两次，如果历史已经有结论，模型是否会引用而不是重新回答。
• 修改偏好后，模型是否按新偏好走，而不是继续沿用过时的旧偏好。
• 批量任务重启后，能否从上次失败点继续，而不是从头开始。

如果这四个现象都没出现，记忆链路大概率有问题。如果只有部分出现，说明写入、检索、注入之间的某个环节没对齐。

4.2 常用参数和参考范围

参数设置会直接影响记忆效果。下面是我在实际调试中会留意的几项，范围仅供参考，需要按你的模型和数据量调整：

参数之间会互相影响。top_k 调大后，响应时间会变长，噪声也变多；similarity_threshold 调高后，命中率会下降。我建议一次只调一个参数，每次对照 20 条真实对话来看效果，不要同时改好几个。

4.3 资源占用和响应速度怎么判断

记忆模块不是免费的。加记忆后，响应时间通常会增加，原因主要有三个：读取存储、向量检索或 embedding 调用、注入后让模型读更多 token。

如果只是本地 JSON 文件加关键词过滤，每次增加的开销很小。如果接向量库和 embedding，就要关注单次检索耗时。一个可以接受的判断标准是：加了记忆后，单次响应时间比不加时增加不超过 20%-30%。超过这个范围，先看是不是检索太慢，再看是不是注入内容太多。如果用的是云端 embedding 接口，网络耗时和限流也要算进去。

4.4 冷启动问题：没有历史记忆怎么办

新用户或新任务没有历史记忆时，记忆模块不能报错，也不能给模型塞空数据。建议做降级处理：没有检索到记忆就只传一个空标识，让模型按普通对话处理；同时把第一轮对话中提取到的信息写入记忆，作为后续的冷启动数据。

冷启动阶段不要急着让模型“背熟”用户，第一轮多收集事实，少做推断。比如用户说“我是做 Java 开发的”，这算事实；用户说“我觉得 Spring 挺好”，这只能算观点，不应该直接写死成长期偏好。

5. 常见问题排查链路：不是所有“记不住”都是记忆模块的问题

5.1 先确认现象卡在哪个环节

“模型记不住”听起来是一个问题，实际可能发生在三个不同环节：

• 写入环节：对话后根本没有保存成功。
• 检索环节：保存进去了，但查询时没取出来。
• 注入环节：取出来了，但没放进 prompt，或者放了但被系统指令覆盖。

排查顺序建议按这个链路走。第一步打开日志，确认每一轮处理有没有执行 memory_store.save 和 memory_store.retrieve。如果 save 没执行，检查代码路径和异常捕获；如果 save 执行但 retrieve 结果为空，检查 user_id 是否一致；如果 retrieve 有结果但模型输出没有体现，检查 prompt 组装顺序和指令冲突。

5.2 用户 ID 和会话 ID 混用是最高频问题

很多次“记忆不生效”的根因，是写入时用的 user_id 和读取时用的不是同一个。比如写入用账号 ID，读取用了一次会话临时生成的 session ID；或者第一次登录用的 ID 大小写不同。排查时先在日志里把 user_id、session_id、请求时间打出来，确认两次请求使用的是同一个稳定 ID。

我习惯把用户 ID 单独设置，不跟会话 ID 混在一起。会话 ID 只用于当前对话窗口的上下文，用户 ID 才用于长期记忆。如果当前系统只有会话 ID，就先在会话里加一个匿名映射表，而不是把会话 ID 当用户 ID 用。

5.3 检索到了但命中质量差

如果 retrieve 返回了内容，但模型还是不像“记得”，大概率是检索结果相关性不够。常见原因有三个：相似度阈值设置过低，导致无关记忆混进来；top_k 设置过小，把真正相关的漏掉了；embedding 模型和文本语言不匹配，中文内容用效果差的向量表示，排序自然乱。

可以先从日志里把本次检索到的记忆条目录出来，人工判断前几条是否真的相关。如果不相关，优先调整相似度阈值和 top_k；如果还是不行，再考虑换更合适的 embedding 模型或加关键词过滤前置。

5.4 存储污染：记忆越来越多，反而越来越笨

记忆不是越多越好。一旦存储里积累了互相矛盾、过时、重复的记忆，模型就会混乱。典型的例子是：用户第一次说“回答要简短”，后来修改为“详细一点”，系统把两条都存进去了，模型不知道该听哪条。

建议在写入前做一次冲突检测，同一 type 的旧记忆要么覆盖，要么标注过期。周期性运行清理任务，把 expire_days 之外的临时状态删除，把同一内容重复出现的条目合并。这样才能保证记忆库始终是“越用越准”，而不是“越用越吵”。

6. 边界与后续优化：记忆不是越久越好，也不是越多越好

6.1 什么场景最适合先上记忆

不是所有智能体都需要复杂记忆。如果你只是拿 Hermes 做一次性问答，那直接依赖上下文窗口就够了。真正适合上记忆外挂的场景通常有这些特征：

• 用户会反复回来做相似任务，并且希望你记得上次的设定。
• 任务是多步骤的，中间断了需要恢复。
• 批量处理时，重复失败会让成本快速上升。

个人助理、客服问答、文档处理、自动化测试、运维巡检这类场景，先上用户级和任务级记忆的收益最明显。如果你的场景基本是单轮、无状态、每次都是全新输入，那记忆模块就容易变成负担，反而不如不加。

6.2 建立遗忘机制，比无限存储更重要

长期使用的记忆系统一定要有“忘掉”的能力。模型上下文窗口有限，存储空间也有限，更重要的是旧信息会误导新决策。可以用时间衰减，让很久没访问的记忆权重下降；可以用 LRU 策略，优先淘汰最久没使用的条目；也要允许用户手动删除或修改某条记忆。

不要把所有事都交给模型自己判断。用户明确说“忘掉之前说的部署方式”，系统就应该把对应记忆标记删除，而不是再由模型决定是否保留。这点在做记忆外挂时最容易忽略，也是影响体验的关键。

6.3 数据安全与隐私控制

记忆会保存用户偏好、项目信息、任务状态，这里面的数据保护要提前设计。基本原则是：能本地存储就不要外传，能脱敏就不要存明文，能最小化就不要整段保存。比如用户对话里提到账号密码、密钥一类的信息，写入前就应该过滤掉。

要给用户提供查看和删除记忆的入口。至少提供“清除全部记忆”和“清除单条记忆”两个操作。做接口化部署时，记忆的读取和写入都要加权限控制，不要让其他用户可以查到别人的历史记录。这一条不是锦上添花，而是生产环境的基本要求。

6.4 从单机到生产化的推进顺序

我的建议是不要一上来就搭分布式向量库。先按最小闭环跑通：本地 JSON 或 SQLite，单用户验证。确认写入、检索、注入都正常后，再考虑高并发和长期运行。

生产化时关注四件事：一是存储替换，把 JSON 文件换成带索引的数据库，避免并发写冲突；二是唯一 ID 和审计日志，每条记忆写入和删除都要可追踪；三是检索性能，当单用户记忆超过几百条时再引入向量检索；四是测试覆盖，准备一组固定场景做回归，防止改 prompt 时把记忆链路改坏。

踩过几次之后最大的感受是：很多“记不住”的问题，不是模型不够聪明，而是记忆链路没有闭环。先把写入、读取、注入三步跑通，再谈优化检索和参数。可以先从一条用户记录开始，连续问三次，看模型能不能记住你说过的偏好。能记住，再扩展到批量任务；记不住，就回头查日志，问题多半在前面三步里。