记忆系统

Moltbot 与普通 AI 聊天工具的核心区别之一在于持久记忆。

常见的 ChatGPT、Claude 网页版，每次新对话都是空白状态。你昨天提到的偏好，今天就不复存在了。Moltbot 将与你相关的信息持久化到本地文件中，每次对话都会加载这些上下文。

随着使用时间增长，它会越来越了解你。这带来的体验差异非常显著。

两个核心文件

USER.md — 对你的认知

~/.moltbot/USER.md 记录了 Moltbot 对你的了解。

每次对话中，Moltbot 判断有值得记录的信息时，会自动追加到这个文件中。例如你提到「我在北京工作」，这条信息就会被写入。

文件内容大致如下：

## 基本信息
- 坐标北京
- 程序员，主要写 TypeScript
- 喜欢美式咖啡

## 工作习惯
- 早上9点到公司，喜欢先花20分钟看邮件
- 代码规范偏好 ESLint + Prettier

## 偏好
- 不喜欢太啰嗦的回复
- 代码示例尽量用 TypeScript 而不是 JavaScript

这个文件会随着你与 Moltbot 的互动持续增长。

你可以直接编辑它。如果 Moltbot 记录有误，或者你想预先提供一些信息，直接修改即可。下次对话时会读取最新内容。

SOUL.md — Bot 的性格

~/.moltbot/SOUL.md 控制 Moltbot 的人格和回复风格。

默认是较为通用的助手风格，你可以根据需要调整。

例如，希望回复更简洁：

## 性格
- 回复简洁，不废话
- 技术问题直接给代码，不需要解释原理除非被问到
- 用中文回复

或者希望更有个性：

## 性格
- 说话带点幽默感
- 偶尔吐槽
- 像一个比较毒舌但很靠谱的朋友

修改后保存即生效，无需重启。

memory 目录 — 长期记忆

除了 USER.md 和 SOUL.md，还有 ~/.moltbot/memory/ 目录用于存储更细粒度的长期记忆。

~/.moltbot/memory/
├── preferences.md      # 偏好
├── contacts.md         # 联系人
├── projects/           # 项目相关
│   ├── project-a.md
│   └── project-b.md
└── daily/              # 每日记录
    ├── 2026-01-27.md
    └── ...

Moltbot 会根据当前话题按需读取这些文件。例如聊到某个项目时，会查找 projects/ 目录下的对应文件。

你也可以手动在此目录下创建文件。例如提前编写一份项目说明，Moltbot 在涉及该项目的对话中就能获取到上下文。

主动记忆

直接用自然语言告诉 Moltbot 即可：

记住：我们组的周会是每周三下午2点

记住：生产环境数据库用的 PostgreSQL 16，端口 5432

记住：老板不喜欢在周五下午开会

它会将这些信息持久化存储。

查看已记录的信息：

你都记住了哪些关于我的信息？

删除某条记忆：

忘掉你记的关于咖啡偏好的事

记忆压缩和刷新

随着对话历史不断增长，Moltbot 提供了 compaction（压缩） 机制，自动将冗长的对话历史提炼为要点。

压缩过程中，有价值的信息会被写入 memory 文件。此行为可通过配置控制：

agents:
  defaults:
    compaction:
      memoryFlush: true  # 压缩时把重要信息写入 memory 文件

默认开启。

压缩后，旧的对话细节不再保留在上下文中，但关键信息已被存入 memory。因此不会出现明显的「失忆」现象。

向量搜索

当 memory 中的文件越来越多时，Moltbot 不可能每次对话都加载全部内容（Token 消耗会过大）。它需要一种方式快速定位与当前话题最相关的记忆。

这就是向量搜索的作用。

Moltbot 默认启用向量搜索，将 memory 中的内容转为向量存储在 SQLite 数据库中（使用 sqlite-vec 扩展）。每次对话时，根据当前话题检索最相关的记忆片段。

向量搜索提供者会自动选择：

• 如果本地具备计算条件，使用本地计算
• 配置了 OpenAI API Key 时，可使用 OpenAI embedding
• 配置了 Gemini API Key 时，可使用 Gemini embedding

通常无需手动配置，Moltbot 会自动选择可用的方案。

底层的 SQLite 数据库位于 ~/.moltbot/ 目录下，可以用 SQLite 工具查看，但一般不需要手动操作。

记忆成本

记忆越多，每次对话消耗的 Token 越多。

USER.md 的内容每次对话都会完整加载。如果该文件变得很长（例如数千行），Token 成本会明显上升。

建议定期审查 USER.md，清理过时或不重要的信息。例如几个月前某个临时项目的细节，大概率已不需要。

memory 目录的文件影响较小，因为有向量搜索机制，只会加载相关部分。

备份

记忆文件均位于 ~/.moltbot/ 目录下，是普通文本文件。

备份方式：

cp -r ~/.moltbot/ ~/moltbot-backup-$(date +%Y%m%d)

迁移到新电脑时，将整个 .moltbot 目录复制过去即可。Moltbot 的记忆随之迁移。

隐私提醒

记忆文件以明文存储。任何能读取你 home 目录的程序都可以访问这些内容。

如果让 Moltbot 记住了敏感信息（如服务器密码），需要意识到这些信息以明文形式存储在磁盘上。

不建议让 Moltbot 记住密码、API Key 等敏感凭证。这类信息应通过环境变量或专门的密钥管理工具处理。

更多安全相关内容参见安全配置。