为AstrBot赋予真正的记忆能力：让AI不仅能记住，还能主动思考、自主进化
模拟人类认知结构，让AI拥有真正的"思维层次"：
- 灵魂层（Soul）：4维情感能量槽，动态调整AI行为参数
- 潜意识层（DeepMind）：后台自动处理记忆检索、整理和巩固
- 主意识层（LLM）：通过4个专用工具主动管理核心记忆
赋予AI主动的记忆能力，不再被动等待：
- angel_remember - 永久铭记重要信息（主动记忆，永不遗忘）
- angel_recall - 统一回忆核心记忆与相关笔记
- angel_note_read - 按短 ID 分页读取笔记正文（深度阅读能力）
- angel_note_create - 自主整理并归档学习笔记（自主学习能力）
三层独立能力，按配置自动组合：
| 层级 | 能力 | 说明 |
|---|---|---|
| BM25 | Tantivy + CJK 1~2-gram | 始终可用，强关键词检索 |
| 嵌入向量 | 语义相似度 | 可选，仅增强记忆向量检索 |
| 重排 | rerank_provider | 可选，独立于嵌入，BM25 候选也能重排 |
检索策略自动选择：
- 无向量、无重排 → BM25 直出
- 有向量、无重排 → 向量 + BM25 通过 RRF 融合
- 有重排 → 候选重排（无论是否有向量）
向量带来的额外提升通常较小，重排效果提升明显。推荐优先配置 rerank_provider。
- 睡眠巩固：定期清理弱记忆，强化重要内容
- 中央索引维护：睡眠维护管线自动执行记忆索引维护与每日 JSON 备份；笔记索引由文件监控维护，可按版本全量重建
通过4维能量槽实现情感化AI行为：
- RecallDepth（回忆深度）：控制RAG检索数量
- ImpressionDepth（印象深度）：控制记忆生成数量
- ExpressionDesire（表达欲望）：控制LLM输出长度
- Creativity（创造力）：控制LLM温度参数
能量值通过橡皮筋算法（Tanh）映射到具体参数，旧记忆状态通过共鸣机制影响当前决策。
- 支持格式：Markdown / 纯文本（
.md/.txt），按段落切片并写入独立note_chunks.db - 切片检索：Tantivy CJK bigram 多级搜索，优先严格 2-gram AND，不足时降级为 1+2-gram OR
- 可选二阶段重排：支持上游 rerank_provider，在可用时提升检索排序质量
- 主动学习优先：通过笔记工具主动整理与归档知识，而非被动RAG注入
- 短条目优化：推荐100字以内的结构化条目，避免长文档污染上下文
同一只粉毛天使的五个能力化身，合在一起就是一个完整的灵魂：
| 插件 | 能力 |
|---|---|
| 天使之心 | 智能群聊/私聊交互，懂分寸、知进退 |
| 天使之眼 | 聊天记录查询，随时翻旧账 |
| 天使之笑 | 表情包管理，看见好看的就想收进库存 |
| 天使之魂 | AI 记忆与认知，越用越懂你 |
| 天使的画笔 | 说话出图、发图改图 |
必须安装前置插件：astrbot_plugin_angel_heart
Angel Heart 提供增强的聊天记录管理能力，是记忆系统的必要依赖。
-
安装Angel Heart插件
# 在AstrBot的plugins目录中安装 cd plugins git clone https://github.com/kawayiYokami/astrbot_plugin_angel_heart.git
-
安装Angel Memory插件
git clone https://github.com/kawayiYokami/astrbot_plugin_angel_memory.git
-
安装依赖
cd astrbot_plugin_angel_memory pip install -r requirements.txt -
重启AstrBot
# 插件将自动初始化
通过AstrBot配置界面设置以下参数：
| 配置项 | 默认值 | 说明 |
|---|---|---|
provider_id |
"" | 记忆整理LLM提供商ID（建议有思考能力的模型） |
retrieval.embedding_provider_id |
"" | 嵌入模型提供商ID（可选，实测提升有限） |
retrieval.rerank_provider_id |
"" | 重排提供商ID（推荐，效果提升明显） |
conversation_scope_map |
"{}" | 记忆分类映射（先按人格名匹配，再按会话ID匹配，未命中为public） |
memory_behavior.min_message_length |
5 | 触发记忆处理的最小消息长度 |
memory_behavior.sleep_interval |
3600 | 记忆巩固间隔（秒） |
enable_soul_system.* |
- | 灵魂系统各维度的默认值 |
conversation_scope_map 示例：
{
"女友": "恋爱",
"aiocqhttp:group:12345": "家人"
}匹配顺序：先当前人格名（Persona名），后会话ID（unified_msg_origin）。
插件内置了基于 AstrBot Plugin Pages 的管理面板，无需额外启动服务。
- 进入 AstrBot WebUI（默认
http://localhost:6185） - 点击左侧「插件管理」
- 点击「天使之魂」插件卡片进入详情页
- 点击「memory-dashboard」页面入口
| 页面 | 说明 |
|---|---|
| 📌 总览 | 系统状态、提供商信息、记忆/标签/笔记统计 |
| 🧾 记忆浏览 | 分页浏览、按 scope/关键词过滤、查看详情、删除 |
| 👤 用户画像 | 列出所有已识别用户，按属性分组展示画像记忆 |
| 🔖 Tags 调试 | 输入文本查看命中标签和对应记忆，浏览全局标签列表 |
| 🧭 向量检索 | 对 memory_index 执行向量查询 |
| 🗂️ 笔记索引 | 分页浏览笔记注册表，关键词搜索走切片检索并展示摘要/分数/行号 |
| 📝 笔记读取 | 按 note_short_id + offset/limit 读取笔记正文 |
| 🔄 导入导出 | 导出中央记忆 JSON 快照 / 从 JSON 导入 |
| 🛠️ 维护状态 | 查看 maintenance_state.json、下载备份文件 |
- 导出：进入「导入导出」页面，点击「生成并下载快照」
- 导入：选择 1 个 JSON 文件后，点击「执行导入」
- 支持的快照格式：顶层包含
records、global_tags、memory_tag_rel - 去重规则：已存在的记忆按
id跳过，不会覆盖旧记录
AI可以通过以下工具主动管理记忆：
1. 铭记重要信息
当用户明确表达重要偏好时，AI会调用：
angel_remember(
judgment="用户偏好猫胜过狗",
reasoning="用户明确提到更喜欢猫的性格",
tags=["用户偏好", "宠物"],
strength=80,
memory_type="knowledge"
)
2. 回忆核心记忆
AI可主动反思核心原则：
angel_recall(
limit=5,
query="用户偏好" # 可选的检索关键词
)
→ 返回相关记忆，并在可用时附带相关笔记摘要
3. 展开笔记内容
查看完整笔记上下文：
angel_note_read(
note_short_id=12,
offset=1, # 可选，默认1
limit=200 # 可选，默认200
)
→ 返回分页正文、实际起止行、总行数与 has_more 提示
4. 整理学习笔记
将学到的知识系统整理并归档：
angel_note_create(
title="Python异步编程",
content="# Python异步编程\n\n## 协程基础\n..."
)
→ 生成一篇 Markdown 笔记并永久存档，自动纳入知识库索引
知识库不是RAG系统！它是 AI 主动整理与回顾的笔记知识源。
千万不要把知识库当作RAG系统使用！
以下做法会严重污染上下文，导致AI理解能力下降：
- ❌ 存放长篇 Markdown/TXT 文档（如整本书、完整论文）
- ❌ 存放大段落的技术文档（超过100字的连续文本）
- ❌ 期待系统自动检索并注入到对话中
- ❌ 把知识库当作"背景知识"让AI被动吸收
为什么长文档RAG是错误的？
用做菜来比喻：
想象你要做一道"宫保鸡丁"：
- ❌ 长文档RAG：给你一整本《中华烹饪大全》，里面有川菜、粤菜、鲁菜...你得翻遍整本书找宫保鸡丁的做法，还可能找到"宫保虾仁"、"鱼香肉丝"等干扰信息
- ✅ 短条目知识库：给你一张"宫保鸡丁食谱卡"，100字写清配料和步骤，拿来就用
具体问题：
- 上下文污染：就像做菜时灶台上堆满了不相关的食材，找不到需要的那瓶酱油
- 信息噪音：检索到的长文档里，只有10%是你需要的，90%是"我知道番茄炒蛋、红烧肉的做法"等无用信息
- 检索失准：搜"宫保鸡丁"，可能给你返回整个"川菜章节"，里面有20道菜，你还得自己筛选
- Token浪费：就像用一个大冰箱存一颗白菜，99%的空间都被浪费了
知识库应该存放结构化的短条目（100字以内），作为 AI 主动回顾的笔记知识源。
推荐的文件组织结构
raw/
├── 美食食谱/
│ ├── 家常菜.md
│ │ # 每条不超过100字，就像食谱卡片
│ │ ## 番茄炒蛋
│ │ 材料: 番茄2个、鸡蛋3个、盐、糖。步骤: 蛋液加盐打散炒熟盛出→番茄切块炒软加糖→倒入鸡蛋翻炒
│ │
│ │ ## 蒜蓉西兰花
│ │ 西兰花焯水1分钟→蒜末爆香→倒入西兰花快炒→加盐出锅。保持翠绿脆嫩的秘诀: 焯水后过冷水
│ │
│ └── 川菜.md
│ ## 宫保鸡丁
│ 鸡胸肉丁腌制→花生米炸香→鸡丁炒至变色→加干辣椒花椒爆香→倒入宫保汁收汁→加花生米
│ 关键: 宫保汁=酱油2勺+醋1勺+糖1勺+淀粉水
│
├── 穿搭技巧/
│ └── 基础搭配.md
│ ## 冬季保暖公式
│ 内层贴身打底衫+中层羊毛衫/卫衣+外层大衣/羽绒服。颜色: 上浅下深显高。避免: 全身黑膨胀
│
│ ## 腿粗怎么穿裤子
│ 选择: 直筒裤、阔腿裤、烟管裤。避免: 紧身裤、哈伦裤。长度: 盖住脚踝显瘦
│
└── 生活妙招/
└── 收纳技巧.md
## 衣柜整理法则
当季衣服放中间→换季衣服放上层→过季衣服收纳箱。T恤竖着卷起来存放，既省空间又方便找
## 冰箱保鲜顺序
熟食上层、生食下层。蔬菜独立保鲜盒。肉类冷冻前分小份。避免: 剩菜超过3天
为什么这样组织效果好？
继续用做菜比喻：
- 精确检索：你说"我要做宫保鸡丁"，系统直接给你那张食谱卡，而不是整本烹饪书
- 即用即懂：100字就像一张便签纸，扫一眼就记住了，不用翻阅厚重的说明书
- 上下文清爽：灶台上只放当前菜的食材，而不是把冰箱搬过来
- 主动学习：想学新菜时通过笔记工具主动整理"红烧肉的做法"，而不是被动接收"你可能需要知道500道菜"
- 结构化记忆：就像把调料按"咸/甜/辣"分格，衣服按"春夏秋冬"分区，拿取方便
生活化类比总结：
- 长文档RAG = 带着整个衣柜出门，找一件T恤都费劲
- 短条目知识库 = 整理好的胶囊衣橱，每件都是精选，随时搭配
最佳实践
- ✅ 每条知识控制在100字以内
- ✅ 使用Markdown的二级标题（##）分隔条目
- ✅ 文件夹名即分类标签（如"Python快速参考"）
- ✅ 一个主题一个文件，避免大杂烩
- ✅ 定期精简，删除过时或冗余内容
索引同步
- 添加/修改/删除 Markdown/TXT 文件后，文件监控会自动同步切片索引；架构版本变化时会触发全量重建。
用户消息
↓
【潜意识层 - DeepMind】
├─ 观察：消息预处理 + 实体提取
├─ 回忆：三层检索（BM25 → RRF向量融合 → 重排）
│ ├─ 记忆轨道：已内化的知识
│ └─ 笔记轨道：知识库短条目
├─ 灵魂共鸣：旧记忆状态影响当前决策
└─ 注入：记忆+笔记+灵魂状态 → LLM
↓
【主意识层 - LLM】
├─ 思考：结合上下文生成回复
└─ 工具调用：主动管理核心记忆
↓
【反馈与进化】
├─ 小模型分析：识别有用记忆和新认知
├─ 记忆强化：增强有用记忆的强度
├─ 记忆生成：创建新的理解
├─ 记忆合并：抽象化相似记忆
└─ 睡眠巩固：定期清理和优化
- 记住用户偏好和历史对话
- 学习用户的沟通风格
- 提供个性化建议
- 在交流与学习中主动整理笔记
- 从知识库短条目中快速学习
- 自主沉淀多源知识形成笔记
- 存储精简的命令速查卡片
- 快速检索关键语法和配置
- 避免长文档污染上下文
- AI在对话中不断进化
- 自主积累领域知识
- 形成稳定的认知体系
retrieval:
# 记忆嵌入向量（可选，实测提升有限；笔记检索不走向量）
embedding_provider_id: ""
enable_local_embedding: false
# 重排（推荐，效果提升明显，独立于嵌入）
rerank_provider_id: "" # 留空则自动尝试复用 provider_id推荐配置优先级：
- 最小配置：只需
provider_id，BM25 检索已足够好用 - 推荐升级：添加
rerank_provider_id，效果提升明显 - 可选增强：添加
embedding_provider_id，语义检索补充
睡眠维护管线自动执行，无需额外配置：
- 记忆向量库同步：睡眠前维护阶段执行
- 每日JSON备份：每天1次，最多保留3份
频率由 sleep_interval 控制（默认3600秒）。
enable_soul_system:
enabled: true
recall_depth_mid: 7 # 回忆深度（1-20）
impression_depth_mid: 3 # 记住倾向（1-10）
expression_desire_mid: 0.5 # 表达欲望（0.0-1.0）
creativity_mid: 0.7 # 创造力（0.0-1.0）note_assistant:
enable_recall: true # 在增强检索中检索笔记
enable_create: true # 注册 angel_note_create 工具
top_k: 3 # 注入笔记数量上限（候选固定为7倍）
memory_behavior:
short_term_memory_capacity: 1 # 短期记忆容量倍数
sleep_interval: 3600 # 巩固间隔（秒）Q: 插件启动失败？
- 检查是否已安装
astrbot_plugin_angel_heart - 查看日志确认具体错误信息
Q: 检索效果不好？
- 推荐配置
rerank_provider_id - 检查知识库条目是否过长（建议100字以内）
Q: 记忆系统不工作？
- 确认
provider_id已正确配置 - 检查消息长度是否达到
min_message_length
Q: 灵魂系统参数异常？
- 检查能量值是否超出软限制（-20到+20）
- 验证配置中的mid值设置
查看插件日志了解详细运行情况：
- 初始化状态
- 记忆检索过程
- 灵魂状态变化
- 工具调用记录
欢迎提交Issue和Pull Request！
# 克隆项目
git clone https://github.com/kawayiYokami/astrbot_plugin_angel_memory.git
cd astrbot_plugin_angel_memory
# 安装依赖
pip install -r requirements.txt
# 代码格式化
ruff format .详见AGENTS.md开发文档。
本项目采用 GNU General Public License v3.0。
感谢所有贡献者和用户的支持！
赋予AI真正的记忆与认知 - Angel Memory 🧠✨