feat(memory): 引入群聊记忆作用域（personal/group/conversation）及可见性模型

CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## v0.3.0 (2026-05-03)
+
+### 新增
+- **群聊记忆作用域**：引入三层记忆作用域模型（`personal` / `group` / `conversation`），解决群聊场景下记忆归属问题
+  - `personal`：用户个人记忆，按 `user_id` 隔离
+  - `group`：群组共享记忆，按 `session_id` 隔离，群内所有成员可见
+  - `conversation`：当前会话临时记忆，仅当前会话内召回
+- **可见性模型**：`private`（仅记忆所有者可见）/ `group`（同群组内多人共享），多所有者记忆自动设为 `group` 可见
+- **新元数据字段**：`memory_scope`、`owner_user_id`、`owner_user_ids`、`owner_session_id`、`visibility`、`speaker_id`、`subject`、`entities`、`topics`、`memory_content`
+- **作用域感知召回**：群聊中自动合并 personal + group + conversation 三层记忆，私聊召回 personal，并可使用 conversation 保存当前私聊会话上下文
+- **重建式升级**：运行时不再对旧 metadata 做兼容兜底；从旧版本升级后需执行 `/memory rebuild` 补齐 v0.3 作用域字段
+- **记忆注入格式化**：按作用域分组展示，区分 personal/group/conversation 三类记忆
+- **记忆提取增强**：LLM 提取 prompt 新增会话作用域信息、`scope`/`subject`/`subjects`/`entities`/`topics` 字段，支持群聊下多人记忆归属标注
+- **Sender 追踪**：请求快照中记录 `sender_id`，对话历史按发送者标注
+- **检索优化超时配置**：新增 `optimize_recall_query_timeout`，限制检索优化模型调用最长等待时间
+- **列表扫描上限配置**：新增 `max_memory_list_scan`，限制群聊可见记忆列表的扫描量
+
+### 变更
+- `/memory list` 群聊中展示当前用户可见的所有记忆（含群组共享）
+- 记忆内容格式化改用结构化 `memory:` 标签行，仅写入 domain、memory、recall_when、entities、topics 等语义检索字段
+- 可见性值改为 `MemoryVisibility` 常量，减少裸字符串重复使用
+
 ## v0.2.2 (2026-04-03)
 
 ### 修复

README.md

@@ -1,23 +1,27 @@
 # AstrBot 简单长期记忆插件
 
-为 AstrBot 提供简易的长期记忆能力，基于内置知识库实现用户偏好、历史交互和重要事实的记忆存储与召回。
+为 AstrBot 提供长期记忆能力，基于内置知识库实现用户偏好、历史交互和重要事实的记忆存储与召回。
 
 ## 功能特性
 
 - **自动记忆提取**：每隔 N 轮对话自动调用 LLM 从对话中提取值得记忆的信息
 - **记忆注入**：在每次 LLM 请求前，自动召回相关记忆并注入到对话上下文
 - **用户隔离**：通过 `user_id` 实现用户级记忆隔离，互不干扰
-- **全局/会话记忆**：支持跨会话的全局记忆模式和仅当前会话的记忆模式
+- **群聊记忆作用域**：支持群聊场景下的记忆归属区分（个人记忆 vs 群共享记忆）
 - **LLM 工具**：提供 `memory_recall`、`memory_store`、`memory_forget` 工具供 AI 主动操作
 - **用户命令**：通过 `/memory` 指令组管理记忆
-- **知识库管理**：记忆直接存储在 AstrBot 内置知识库中，可在知识库管理界面直接查看、检索、删除记忆，无需额外 WebUI
+- **知识库管理**：记忆直接存储在 AstrBot 内置知识库中，可在知识库管理界面直接查看、检索、删除记忆
 
 ## 安装
 
-1. 在 AstrBot 插件市场安装本插件
-2. 在知识库管理中创建一个用于存储记忆的知识库（需配置嵌入模型）
-3. 在插件设置中配置：
-   - **记忆知识库**：选择创建的知识库
+**方式一**：AstrBot 插件市场搜索「简单长期记忆」安装（待上架）。
+
+**方式二**：插件界面右下角加号 → 从链接安装，输入：
+```
+https://github.com/piexian/astrbot_plugin_simple_long_memory
+```
+
+安装后，在知识库管理中创建一个用于存储记忆的知识库（需配置嵌入模型），然后在插件设置中选该知识库。
 
 ## 配置说明
 
@@ -31,11 +35,12 @@
 | extraction_min_content_length | 对话总长度低于此值时跳过提取 | `150` |
 | global_memory | 全局记忆模式（跨会话召回） | `true` |
 | max_memories_per_inject | 每次 LLM 请求注入的最大记忆条数 | `5` |
-| memory_domains | 记忆分类域 | `["user_profile", "preferences", "facts", "events", "context"]` |
+| max_memory_list_scan | 记忆列表扫描上限 | `200` |
 | memory_ttl_days | 记忆生命周期（天） | `30` |
 | install_skill | 安装 AI 记忆指南 Skill | `false` |
 | use_reranker | 记忆召回时启用重排序（需知识库已配置重排序模型） | `true` |
 | optimize_recall_query | 启用检索优化（LLM 提炼关键词） | `false` |
+| optimize_recall_query_timeout | 检索优化超时（秒） | `10` |
 
 ## 使用方法
 
@@ -56,7 +61,21 @@
 - `forget`：普通用户可删除自己的记忆，管理员可删除任意记忆
 - `--all`：管理员可查看/搜索/统计/清空所有用户的记忆
 - `--user <用户ID>`：管理员可删除/清空指定用户的记忆（`--all` 与 `--user` 不可同时使用）
-- 无标志时行为不变，仅操作当前用户数据
+
+### 群聊场景
+
+群聊中记忆按归属分为三种，机器人自动判断无需手动设置：
+
+| 作用域 | 说明 | 日常例子 |
+|--------|------|----------|
+| `personal` | 个人记忆，仅自己可见 | "我比较喜欢喝拿铁"、"下周要出差" |
+| `group` | 群共享记忆，群友都可见 | "群里约了每周五打游戏"、"这个群的固定梗" |
+| `conversation` | 当前会话临时上下文 | "刚才说的那个 bug 还没修完" |
+
+私聊默认召回 `personal` 记忆，并可使用 `conversation` 记录当前私聊会话上下文。
+
+> 从旧版本升级到 v0.3 后，请执行 `/memory rebuild`。运行时召回和列表只认新 metadata 结构；旧格式记录需要通过重建补齐 `memory_scope`、owner、visibility 等字段后才会进入新作用域模型。
+> 重建只处理当前知识库 `kb_id` 下的记忆记录，避免误迁移其它知识库或无法可靠归属的数据。
 
 ### 记忆重建与迁移
 

_conf_schema.json

@@ -52,11 +52,12 @@
     "default": 5,
     "hint": "LLM请求时注入的最大记忆条数"
   },
-  "memory_domains": {
-    "description": "记忆域配置",
-    "type": "list",
-    "default": ["user_profile", "preferences", "facts", "events", "context"],
-    "hint": "记忆分类域，用于组织不同类型的记忆"
+  "max_memory_list_scan": {
+    "description": "记忆列表扫描上限",
+    "type": "int",
+    "default": 200,
+    "hint": "限制 /memory list 为计算当前用户可见记忆而扫描的最大记录数。实际扫描量会按当前页码和每页数量推导，并不会超过此上限",
+    "slider": {"min": 20, "max": 2000, "step": 20}
   },
   "memory_ttl_days": {
     "description": "记忆生命周期(天)",
@@ -81,5 +82,12 @@
     "type": "bool",
     "default": false,
     "hint": "开启后在每次记忆召回前调用记忆提取模型提炼检索关键词，提高召回准确率。每次对话都会调用，建议配置响应速度快的轻量模型"
+  },
+  "optimize_recall_query_timeout": {
+    "description": "检索优化超时(秒)",
+    "type": "int",
+    "default": 10,
+    "hint": "限制检索优化模型调用的最长等待时间。超时后将跳过优化并使用原始检索内容，避免阻塞对话响应",
+    "slider": {"min": 1, "max": 20, "step": 1}
   }
 }