技术笔记
Memora 群忆开发记录
可审计、可审批、可撤销的 QQ 群长期记忆系统——提炼/嵌入/重排链路、SQLite+FAISS 双路检索、候选审批与记忆组隔离的关键取舍。
关联作品：Memora 群忆
一款 AstrBot 的 QQ 群长期记忆插件：从群聊提炼长期事实，具备来源证据、置信度、状态与不可变版本历史，高风险候选需管理员审批，并按记忆组严格隔离。
技术栈：Python（AstrBot Star 插件）、SQLite（主存储 + FTS5）、FAISS（向量检索）、可插拔 Provider（提炼/Embedding/Reranker）。
仓库：github.com/YamaArashiHZ/astrbot_plugin_memora · 版本：v1.0.0（2026-07-30）
背景与动机
群机器人最常见的痛点是“不记得”。每次对话都从零开始，群里聊过的事实、达成的共识、成员的偏好，要么丢在上下文窗口里，要么被记成不可信的闲聊。
Memora 的目标是把“记忆”做成可信的数据资产：通过提炼（而不是简单存聊天记录）把散落在消息里的长期事实结构化，再用证据、置信度、状态和版本历史保证可审计，用管理员审批保证高风险事实可控，用记忆组隔离保证多群之间不互相污染。
技术选型
| 决策点 | 选择 | 理由 |
|---|---|---|
| 事实存储 | SQLite | 事务与迁移成熟、单文件易备份；同时提供 FTS5 全文检索 |
| 向量检索 | FAISS | 语义检索，配合 Embedding 召回“意思相近但用词不同”的事实 |
| 兜底方案 | FTS5 ↔ FAISS 互为降级 | 任一不可用自动切换，聊天不受影响 |
| 提炼链路 | 独立提炼 Provider | 与聊天模型隔离，避免提炼污染对话上下文 |
| 增强链路 | Embedding / Reranker Provider（可选） | 提升召回与排序质量，未配置时回退 FTS |
| 配置与管理 | Plugin Page WebUI | 记忆组、Provider、索引、审计统一面板，无需手改配置文件 |
架构核心
- 记忆组隔离：一个记忆组可包含多个群，在组内共享事实；所有查询、索引、注入与工具调用严格按组隔离，不存在全局搜索捷径。
- 事实即数据资产：每条事实带来源证据（来源消息）、置信度、状态，并维护不可变版本历史——改一条事实会生成新版本而不是覆盖。
- 候选审批链路：高风险、冲突、低置信及敏感候选不会直接写入，而是进入待审批队列，由管理员在 Plugin Page 决策。
- 采集边界明确：Bot 回复、语音正文、文件正文、图片二进制一律不采集；语音与视频只保留占位标签。
关键取舍
- 明文保留 30 天后脱敏：规范化正文在 SQLite 中明文保留（默认 30 天），到期清除正文与可识别段信息，仅保留不可逆哈希与最小证据摘要。这是“可审计”与“保护隐私”之间取的平衡。
- FAISS 不是备份源：向量索引可从 SQLite 完全重建，因此备份以 SQLite 为准，FAISS 只是可重建的派生缓存。
- 切换 Embedding 触发全量重建：向量维度随模型变化，切换 Provider 或模型必然重建索引，属预期成本。
- Provider 故障不回退：提炼 Provider 故障不会降级到聊天模型执行提炼，避免把不可信内容当作长期记忆。
- 权限边界：QQ 群管理员不等于 Dashboard 管理员；
admins_id仅用作群事实管理员证据与告警接收者候选。
降级与一致性
围绕“聊天不中断”设计了一套降级矩阵：提炼 Provider 未配置时消息照常入库（任务挂起等待恢复）；FAISS 不可用回退 FTS5，FTS5 不可用回退 FAISS，二者都不可用时只放弃动态事实注入、正常聊天继续。数据库迁移由插件启动时自动执行，迁移失败会进入诊断模式（只开管理 API，不采集消费消息）。
数据一览
- 首个发布版本：v1.0.0（2026-07-30）
- 兼容：AstrBot
>=4.26.8,<5、NapCat + OneBot 11、Python 3.11+ - 许可：AGPLv3
本文档由项目会话记录与 git 历史自动整理生成，用于个人网站技术笔记栏目。