nanoMuse AI Agent 记忆系统深度解析:SOUL.md 等四个记忆文件,让你的 Agent 真正记住你

原创2026-10-16 06:38:132,293 阅读

nanoMuse AI Agent 记忆系统深度解析:SOUL.md 等四个记忆文件,让你的 Agent 真正记住你

🤖 nanoMuse 是一个开源的个人 AI Agent,可运行在 Android、iPhone、Windows、macOS、Linux 和浏览器上,同一个账号、同一个对话跨设备同步。它最大的特色之一就是记忆系统:关闭 App 后它继续工作,下一次打开还记得你是谁、喜欢什么、正在忙什么。本文带你完整看懂 nanoMuse AI Agent 记忆系统的四个核心 Markdown 文件与背后的长期记忆机制。

nanoMuse 记忆系统跨设备同步架构示意图

图中可以看到,Web 端的 Agent 能回答 "what did I ask you?"——答案就来自记忆。下面逐层拆解。

一、记忆系统全景:四个文件 + 一套 SQLite 长期记忆

nanoMuse 把 Agent 的"人格与记忆"拆成了几个可以直接打开、编辑的纯文本文件,全部存放在设备沙箱的 minis-global/memory/ 目录(Agent 在自己的 shell 里对应 /var/minis/memory/ 路径)。文件清单定义在 SystemFiles.kt 中:

文件 作用 谁在写 可否编辑
SOUL.md 人格:名字、价值观、说话风格 模板起步,Agent 会随时间自我微调 ✅
USER.md Agent 关于你的工作笔记 Agent 边聊边补,你也可改 ✅
GLOBAL.md 跨会话的持久记忆 + 导入的外部记忆 Agent + 你的导入 ✅
HEARTBEAT.md 例程与目标检查的运行状态(心跳) 系统自动渲染 ❌ 只读

再加上一套 SQLite 长期记忆(remember / recall / forget 工具),构成"文件层 + 数据库层"的双轨记忆。

二、SOUL.md:Agent 的人格文件

SOUL.md 是 Agent 的"灵魂":它在每次对话中试图遵循的价值观与习惯、它的名字、它回答问题的风格。

它的格式是 YAML front matter + Markdown 正文:

  • front matter 里保存 name、icon、style、lang 等字段,直接驱动聊天界面的头像、署名;
  • 正文会作为系统提示词的第一层注入(实现见 SoulStore.kt)。

首次对话时,Agent 会问"我该怎么称呼你",而你自己为它起的名字会直接写进 SOUL.md,界面上的名字、消息署名、输入框提示会立刻更新(详见 v0.1.2 发布说明)。之后它还可能自我微调这份人格——每次修改都会告诉你。

三、USER.md:它写下的"关于你"

USER.md 是 Agent 的工作笔记:你的名字、希望被如何称呼、时区、正在忙的项目、各种偏好。

  • 每次对话开始时读取。文件有内容时,会以 ## About the user (USER.md) 段落拼进系统提示词,见 SystemFiles.kt 的 UserFile;
  • Agent 自己维护:系统提示词明确告诉它——学到新的持久信息就用 shell 更新 /var/minis/memory/USER.md,并且用一句话通知你;
  • 红线:永远不要把密码等秘密写进去;
  • 你随时可改:你写的就是它要遵循的。

四、GLOBAL.md:跨会话的长期记忆

GLOBAL.md 存放"值得记住的事":Agent 用我自己的话写下的持久笔记,以及从其他助手导入的内容。首次对话时保存的称呼就存在这里的 ## About the user 一节。

📥 一键"导入记忆":换 Agent 不丢上下文

这是很实用的功能:把别的助手(ChatGPT、Claude 等)已经记住的你"搬过来"。

  1. 在"系统文件 → 导入记忆"页复制内置提示词,发给另一个助手,让它把关于你的信息整理成要点列表;
  2. 把回答粘贴回 nanoMuse,点"追加到记忆";
  3. 内容会以 ### 日期 · 来自 的格式追加到 GLOBAL.md 末尾的 ## Imported 节(中英文标题都能识别)。

实现见 NanoMuseSystemFiles.swift。官方提醒:粘贴前先自查,去掉密码、卡号等不想留在纯文本里的内容。

五、HEARTBEAT.md:Agent 的"心跳"

HEARTBEAT.md 是只读文件,由系统从"目标 → 例程"自动渲染:什么例程会自己跑、几点跑、上次运行成不成功,一目了然。想修改,请去例程设置页改源数据,而不是改文件。它让"App 关掉后 Agent 还在工作"这件事变得可见、可查。

六、第二层:SQLite 长期记忆与自动整理

除了四个文件,Agent 还有一套结构化的长期记忆,存小粒度的事实("喜欢靠窗座位""时区 UTC+8"),保存在 SQLite 中,核心实现是 memory/store.py。

  • 记:remember 工具保存一条短事实,支持 replaces 参数——事实变了(搬家、换工作)就更新旧条目,而不是记两条;
  • 找:检索用"稀有词加权"打分(出现在越少记忆里的词权重越高),中文字符按双字组合匹配,天然支持多语言;配置了 embedding 服务后还会融合语义排序;
  • 忘:forget 可按 id 或关键词删除,且所有删除都会记日志、可恢复;
  • 整理:后台的"记忆整理"会请模型提议合并重复项、丢弃一次性信息,但模型只提议、代码做决定——它不许编造事实、不许删你亲手写的内容、每轮最多清理两成(见 consolidate.py)。每一步改动都带"改前文本"的日志,可以一键撤销。

nanoMuse App 界面截图:Soul 与记忆设置、技能与记忆目录跨设备同步

七、如何管理这些记忆

  • 手机 App:设置 → 系统文件,五个文件全部可浏览;除 HEARTBEAT.md 外都支持编辑、复制、分享;
  • 网页控制台:提供 GET /api/memory(列出)、DELETE /api/memory/{id}(删除)、POST /api/memory/tidy(整理,支持 dry_run 预演)、GET /api/memory/changes 与恢复接口(见 api.py);
  • 备份:minis-global/memory/ 整个目录会进入备份包,迁移设备或换账号时可以带回来。

八、给新手的 3 条使用建议

  1. ✍️ 把 USER.md 当作"说明书":刚安装时花 1 分钟写下你的称呼、时区、工作方向,Agent 的每次回答都会更贴切;
  2. 🚫 别存秘密:四个文件都是明文,密码、支付信息永远不该进记忆;
  3. 🔁 换助手时用"导入记忆":一条提示词就能把旧助手的上下文迁移过来,从 GLOBAL.md 继续积累。

结语

nanoMuse 用"可读、可编辑、可撤销"的纯文本文件,把 AI Agent 的记忆从黑盒变成了明盒:SOUL.md 定义它是谁,USER.md 记录你是谁,GLOBAL.md 沉淀共同记忆,HEARTBEAT.md 展示它的节律——再配上可审计的 SQLite 长期记忆,"记得你"就不再是一句宣传语,而是一份你可以打开检查的档案。

关键路径速查

登录后查看全文
nanoMuse