Mnemosyne 是一个为 AstrBot 设计的长期记忆管理插件，基于 RAG (检索增强生成) 技术和 Milvus 向量数据库实现。该插件能够自动总结对话内容，将其转换为向量存储，并在后续对话中智能检索相关记忆，使 AI 具备真正的长期记忆能力。
|
|
| 组件 | 说明 |
|---|---|
| 向量数据库 | 基于 Milvus / Milvus Lite 进行向量存储与检索，支持多种索引类型 |
| Embedding 服务 | 集成 AstrBot 的 Embedding Provider，自动获取文本向量表示 |
| LLM 总结 | 使用配置的 LLM Provider 进行对话内容总结，生成结构化记忆 |
| 上下文管理 | 维护对话历史与记忆注入，支持多种注入策略（用户提示/系统提示） |
| Web 管理面板 | 基于 FastAPI 的管理界面，提供记忆查询、统计、监控功能 |
- 自动总结机制：根据配置的对话轮数阈值自动触发总结
- 时间触发总结：支持基于时间阈值的定期总结（可选）
- 人格过滤：支持按人格配置过滤记忆检索结果
- 会话过滤：支持按会话隔离记忆，或禁用以实现全局记忆共享
- 多集合支持：可为不同场景创建独立的记忆集合
/memory init [--force] 初始化/迁移记忆系统（管理员，首次安装必须） /memory list 查看所有记忆集合 /memory list_records [collection] [limit] 列出指定集合的记忆记录 /memory get_session_id 获取当前会话 ID /memory remember [content] 手动写入一条长期记忆 /memory reset [confirm] 清除当前会话记忆 /memory delete_record [id] [session] [confirm] 删除指定会话中的单条记忆（管理员） /memory delete_session_memory [id] [confirm] 删除指定会话记忆（管理员） /memory drop_collection [name] [confirm] 删除整个集合（管理员） 重要命令说明：
/memory init- 首次安装后必须执行，用于创建正确维度的集合/memory init --force- 强制重新初始化，用于维度迁移（会保留数据）
| 配置项 | 说明 | 默认值 |
|---|---|---|
num_pairs | 触发总结的对话轮数阈值 | 5 |
top_k | 检索返回的记忆数量 | 3 |
collection_name | Milvus 集合名称 | default |
db_name | Milvus 数据库名称（多库隔离） | default |
memory_injection_method | 记忆注入方式 | user_prompt |
memory_injection_position | 记忆注入位置（prepend/append） | prepend |
use_personality_filtering | 是否启用人格过滤 | true |
use_session_filtering | 是否启用会话过滤。如果禁用，所有会话将共享记忆 | true |
platform_blacklist | 平台黑名单（命中平台将跳过记忆查询和写入） | [] |
max_prompt_chars_for_embedding | 向量化前最大输入字符数（超长自动截断） | 4000 |
enable_explicit_memory_capture | 开启后支持“记住/remember”显式触发即时记忆写入 | false |
use_participant_filtering | 按发言用户过滤记忆，缓解群聊串线 | false |
use_lightweight_memory_graph | 启用轻量图谱重排（实体关系 one-hop 扩展） | true |
插件支持灵活的会话记忆管理，通过 use_session_filtering 配置项控制：
- 配置：
use_session_filtering: true - 行为：每个会话拥有独立的记忆空间
- 适用场景：
- 多用户环境，确保用户隐私
- 不同对话主题需要独立上下文
- 避免不同会话间的记忆干扰
- 配置：
use_session_filtering: false - 行为：所有会话共享同一个记忆池
- 适用场景：
- 单用户环境，希望AI记住所有对话历史
- 需要跨会话的知识积累
- 构建全局知识库
注意：无论使用哪种模式，记忆在存储时都会保留原始的 session_id，确保可以随时切换模式而不丢失数据。
- AstrBot v4.0.0+
- Python 3.8+
- Milvus 数据库（可选择 Milvus Lite 或 Standalone）
⚠️ 必须先配置 Embedding Provider
| 1 | 安装依赖 cd data/plugins/astrbot_plugin_mnemosyne uv pip install -r requirements.txt |
| 2 | 配置 Milvus 选择以下方式之一：
|
| 3 | 在 AstrBot WebUI 中必须先配置 Embedding Provider，插件需要使用其向量维度来创建集合。 支持的 Embedding Provider：
|
| 4 | 配置插件 在 AstrBot WebUI 中进行插件配置，设置：
|
| 5 | 初始化记忆系统 启动 AstrBot 后，执行以下命令初始化记忆系统： 这将：
首次安装必须执行此命令！ |
如果您更换了 Embedding Provider 或模型，导致向量维度变化，系统会自动检测并提示您迁移数据：
- 执行
/memory init检查维度 - 如果维度不匹配，系统会提示需要迁移
- 执行
/memory init --force确认迁移
迁移过程：
- ✅ 自动备份文本内容
- ✅ 使用新维度重新生成向量
- ✅ 保留所有历史记忆数据
⚠️ 迁移过程可能需要一些时间，取决于记忆数量
详细的部署指南请参阅：
- 快速启动指南 (QUICKSTART.md) - 5分钟快速部署
- Windows 新手完整教程 (WINDOWS_TUTORIAL.md) - Windows 用户详细教程（新手友好）
- Wiki：如何正确且快速地食用本插件
插件内置了基于 FastAPI 的管理面板，提供以下功能：
- 记忆数据查询与浏览
- 会话统计与分析
- 实时监控与日志查看
- 记忆数据导出
访问地址：http://127.0.0.1:8000（默认端口）
安全配置：
- 支持 API 密钥认证
- 可在配置文件中设置固定密钥
- 未配置时自动生成临时密钥（每次重启变化）
对话消息 → 达到轮数阈值 → LLM 总结 → Embedding 向量化 → Milvus 存储 用户输入 → Embedding 向量化 → Milvus 相似度检索 → 过滤筛选 → 注入上下文 每条记忆记录包含以下字段：
id：唯一标识符text：总结后的文本内容embedding：文本的向量表示session_id：关联的会话 IDpersona_id：关联的人格 IDtimestamp：创建时间戳metadata：扩展元数据
本项目采用自定义许可证，详见 LICENSE 文件。
| 如遇到 Bug 或功能问题，请在 GitHub Issues 中提交问题报告。 | 加入 QQ 群与开发者和用户交流： 群号：953245617 |
欢迎提交 Pull Request 贡献代码或改进文档。