nanoMuse AI Agent 记忆系统深度解析:SOUL.md 等四个记忆文件,让你的 Agent 真正记住你
nanoMuse AI Agent 记忆系统深度解析:SOUL.md 等四个记忆文件,让你的 Agent 真正记住你
🤖 nanoMuse 是一个开源的个人 AI Agent,可运行在 Android、iPhone、Windows、macOS、Linux 和浏览器上,同一个账号、同一个对话跨设备同步。它最大的特色之一就是记忆系统:关闭 App 后它继续工作,下一次打开还记得你是谁、喜欢什么、正在忙什么。本文带你完整看懂 nanoMuse AI Agent 记忆系统的四个核心 Markdown 文件与背后的长期记忆机制。
图中可以看到,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 等)已经记住的你"搬过来"。
- 在"系统文件 → 导入记忆"页复制内置提示词,发给另一个助手,让它把关于你的信息整理成要点列表;
- 把回答粘贴回 nanoMuse,点"追加到记忆";
- 内容会以
### 日期 · 来自的格式追加到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)。每一步改动都带"改前文本"的日志,可以一键撤销。
七、如何管理这些记忆
- 手机 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 条使用建议
- ✍️ 把 USER.md 当作"说明书":刚安装时花 1 分钟写下你的称呼、时区、工作方向,Agent 的每次回答都会更贴切;
- 🚫 别存秘密:四个文件都是明文,密码、支付信息永远不该进记忆;
- 🔁 换助手时用"导入记忆":一条提示词就能把旧助手的上下文迁移过来,从
GLOBAL.md继续积累。
结语
nanoMuse 用"可读、可编辑、可撤销"的纯文本文件,把 AI Agent 的记忆从黑盒变成了明盒:SOUL.md 定义它是谁,USER.md 记录你是谁,GLOBAL.md 沉淀共同记忆,HEARTBEAT.md 展示它的节律——再配上可审计的 SQLite 长期记忆,"记得你"就不再是一句宣传语,而是一份你可以打开检查的档案。
关键路径速查
- 记忆存储与检索:nanomuse/memory/store.py
- 记忆自动整理:nanomuse/memory/consolidate.py
- remember / recall / forget 工具:nanomuse/tools/memory_tools.py
- 系统文件(Android):android/src/android/app/src/main/java/io/github/nanomuse/sysfiles/SystemFiles.kt
- 系统文件(iOS):android/src/ios/NanoMuse/NanoMuseSystemFiles.swift
- 记忆 API 与 Web 控制台:nanomuse/server/api.py
- 同步与备份说明:docs/sync.md

