让 AI 真正记住你：分层记忆系统（Vault / MEMORY.md）完全指南
让 AI 真正记住你：分层记忆系统（Vault / MEMORY.md）完全指南
你有没有过这种体验：同一个 AI 助手，今天教它”我们的后端用 FastAPI”，明天它又问你”你们什么技术栈”。普通聊天机器人的”记忆”是假的——它只是把你当前窗口的上下文塞进来，窗口一关，啥也不剩。
Hermes Agent 不是这样。它有一套跨会话的持久记忆系统，写在磁盘上，下次打开还在。这才是”数字员工”和”套壳聊天机器人”的本质区别：员工会成长，机器人只会失忆。
这一节把记忆系统彻底拆开。
记忆到底存在哪
▲ Hermes 中文桌面版工作台（暗色模式）
所有记忆都在 ~/.hermes/ 目录下，核心是这两个文件（简报 §4e）：
~/.hermes/
├── SOUL.md # 全局身份（slot #1），定义 Agent 是谁
└── memories/
├── MEMORY.md # Agent 的笔记：环境事实 / 约定 / 学到的东西（≤2200 字符）
└── USER.md # 用户画像：偏好 / 风格（≤1375 字符）注意两个硬限制：
MEMORY.md上限 2200 字符USER.md上限 1375 字符
字符，不是 token，也不是行数。这意味着你不能往里堆小说，得写精炼的条目。
⚠️ 这里要纠正一个流传很广的旧说法：早期文档/社区里有人讲”记忆在独立的 decisions/actions 文件夹里”。以当前简报为准，没有这些独立实体文件夹。 项目相关的信息、约定、决策，全部以条目形式存进 MEMORY.md，用 § 符号分隔多行条目。别再去翻什么 decisions/ 目录了，那是错的。
条目式存储：一个文件装下所有上下文
MEMORY.md 不是自由散文，而是用 § 分隔的多行条目缓冲区。结构长这样（可直接抄）：
§ 业务
- 我们在做 B2B SaaS，主产品是面向工厂的排产系统
- 当前最大痛点是多工厂协同排产冲突
§ 技术栈
- 后端 FastAPI + PostgreSQL，前端 React + Vite
- 部署在阿里云 ACK，用 GitHub Actions CI
§ 关键规则
- 永远不要 force push main 分支
- 提交信息用中文，遵循 Conventional Commits
- 数据库迁移必须带 down 脚本
§ 当前项目
- 正在做 v2.3 的看板模块（截止 9 月底）
- 接口契约在 internal-api 仓库的 openapi.yaml
§ 沟通偏好
- 回复直接给结论，少铺垫
- 报错要贴完整 traceback，不要只说"出错了"USER.md 同理，但聚焦”你这个人”：
§ 用户画像
- 全栈工程师，5 年经验，熟悉 Python/TS
- 讨厌 AI 腔和废话，要直接给代码
§ 风格
- 偏好命令行优先的方案
- 关注成本，本地模型能跑就不调 API这种”条目式 + § 分隔”的设计很聪明：它让后台审查程序能精确地 add/replace/remove 单条，而不是整篇重写。
自动记忆循环：三时段的生命周期
记忆不是你手动维护的静态文件，而是一条自动化流水线（简报 §4e）。理解这条流水线，你就理解了 Hermes 为什么”越用越懂你”。
┌─────────────┐ 冻结快照 ┌──────────────────┐
│ 磁盘 MEMORY │ ───────────▶ │ 会话系统提示(前缀 │
│ USER.md │ │ 缓存，本会话只读) │
└─────────────┘ └──────────────────┘
▲ │
│ 立即落盘 │ 会话中
│ ▼
┌─────────────┐ memory 工具 ┌──────────────────┐
│ 后台自我改进 │ ◀─────────── │ 会话进行中 │
│ 审查(会话后) │ add/replace │ add/replace/remove│
└─────────────┘ └──────────────────┘拆成三个时段看：
会话前（Before）：从磁盘加载 MEMORY.md / USER.md，作为系统提示里的冻结快照（frozen snapshot） 注入，并保留前缀缓存（prompt-cache）。这是性能关键——记忆不每次重读计费。
会话中（During）：Agent 通过 memory 工具自主 add / replace / remove，改动立即落盘到磁盘。但当前会话的系统提示不更新。这是为了不产生缓存失效（cache invalidation 会让整段上下文重新计费）。
会话后（After）：后台自我改进审查自动运行（用主模型或廉价模型），重放整段对话，把反复出现的修正、踩过的坑、可复用的工作流，提炼成紧凑的记忆条目或技能。默认 memory.write_approval: false 时自由写入；设为 true 则 staged，等你 /memory approve。不想要这个后台审查？auxiliary.background_review.enabled: false 关掉。
FTS5 跨会话召回：session_search
记下来的东西，怎么在需要时被找到？靠 session_search 工具（简报 §4e）。
它在 state.db（SQLite + FTS5 全文索引）里检索，返回真实消息、无 LLM 摘要、无截断，延迟约 20ms。
这点和很多”记忆系统”不同：别人的实现常常用向量检索 + LLM 总结，结果你拿到的是”大概意思”。Hermes 直接给你原始对话片段——你看到的就是当时真实发生的内容，不是模型二次加工后的失真版本。
# 在会话里直接问 Agent 去翻历史，它会调 session_search
"上次我们讨论数据库连接池爆了，当时怎么解决的？"
# Agent 内部走 FTS5，~20ms 返回真实消息⚠️ 最坑的一点：记忆是”冻结快照”
这是新手必踩的坑，必须单独拎出来说。
前面讲了：会话中通过 memory 工具改了 MEMORY.md，立刻落盘了。但当前会话的系统提示是”冻结快照”，不会中途更新。也就是说——
你在本次对话里纠正了 Agent，本次对话它并不会”突然想起”新记忆；要等到下一会话，冻结快照重新加载，新记忆才生效。
这不是 bug，是性能权衡（避免前缀缓存失效导致全价重读）。但如果你期待”我刚教它的事它马上就用上”，会失望。正确预期是：纠正是给”下次的它”用的。需要当前会话立刻生效，就直接在对话里说，别依赖记忆工具。
写好一份”员工入职手册级”的 Memory.md
把 MEMORY.md 当成你给数字员工的入职手册——一个新同事第一天来，你塞给他一份文档，他就能上手干活。模板直接抄（控制在 2200 字符内）：
§ 你是谁（Agent 定位）
- 你是我的全栈工程搭档，负责排产系统的日常开发、排障、文档
§ 业务
- B2B SaaS，主产品工厂排产系统，核心痛点是多工厂协同冲突
§ 技术栈
- 后端 FastAPI + PostgreSQL + Redis；前端 React + Vite + TypeScript
- 部署阿里云 ACK；CI 用 GitHub Actions；监控 Grafana + Loki
§ 关键规则（红线）
- 禁止 force push main / master
- 数据库迁移必须带可逆 down 脚本
- 生产环境命令先给我看再执行
§ 当前项目
- v2.3 看板模块（9 月底截止），接口契约在 internal-api/openapi.yaml
- 正在排查：排产引擎在 500+ 工单时响应超时
§ 沟通偏好
- 先结论后细节；报错贴完整 traceback
- 给代码优先，解释从简；成本敏感，本地能跑的不调 API填这份模板时记住：字符数有限（2200），写”该记的”而非”能记的”。业务背景、技术栈、红线规则、当前项目、沟通偏好，这五块最值钱。
本节能造出什么数字员工
- 不会重复问蠢问题的搭档：技术栈、红线规则一次写清，每次对话都带着。
- 跨周持续的项目助手：周一说的项目状态，周五它还记得，还能结合
session_search翻出细节。 - 懂你沟通风格的合作者：USER.md 写清偏好，它回消息不再 AI 腔。
记忆是”闭环学习”的第一环。下一节（第 06 章）讲第二环：技能——让 Agent 不只是”记住”，而是”学会怎么做事”。
下篇预告
第 06 章《越用越聪明：自进化技能（Skills）是怎么炼成的》——memory 记住”是什么”，skill 记住”怎么做”。你会学到 SKILL.md 的完整格式、Agent 怎么在干完活后自动写技能、以及那个让效率滚雪球的”复利效应”。
延伸阅读
- 官方文档（记忆系统）：https://hermes-agent.nousresearch.com/docs
- 中文社区：https://hermesagent.org.cn/docs
- 参考调研简报 §4e（记忆结构与自动记忆循环）、§17（记忆相关 gotcha）