amrita_plugin_memory 0.4.1__tar.gz → 0.6.0__tar.gz

{amrita_plugin_memory-0.4.1/amrita_plugin_memory.egg-info → amrita_plugin_memory-0.6.0}/PKG-INFO

@@ -1,17 +1,17 @@
 Metadata-Version: 2.4
 Name: amrita_plugin_memory
-Version: 0.4.1
+Version: 0.6.0
 Summary: Amrita长期记忆插件
 Requires-Python: <3.14,>=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp>=3.13.3
 Requires-Dist: aiologic>=0.16.0
-Requires-Dist: amrita-core>=0.8.5
-Requires-Dist: amrita>=1.3
+Requires-Dist: amrita-core<2.0.0,>=1.0.0
+Requires-Dist: amrita>=1.10
 Requires-Dist: chromadb>=1.5.8
 Requires-Dist: click>=8.1
-Requires-Dist: nonebot-plugin-amrita>=0.3.0
+Requires-Dist: nonebot-plugin-amrita>=0.4.0
 Requires-Dist: nonebot-plugin-apscheduler>=0.5.0
 Requires-Dist: nonebot-plugin-localstore>=0.7.4
 Requires-Dist: nonebot-plugin-orm[default]>=0.8.2
@@ -165,7 +165,7 @@ L3 在代码中沿用历史标识符 `subconscious` / `rethinking`（避免破
 | `subconscious_*` 工具             | 巩固循环工具   | —                                                |
 | 用户聊天 → `cancel_and_reschedule` | 任务负激活     | 专注任务时 DMN 被抑制                            |
 | 静默期触发 `_run`                 | 空闲时活跃     | DMN 在无任务时活跃                               |
-| 去重 / 压缩 / `MemoryLimiter`      | 记忆巩固       | 海马 → 皮层的系统巩固                            |
+| 去重 / 压缩 / `ContextCompactor`   | 记忆巩固       | 海马 → 皮层的系统巩固                            |
 | 画像构建（`*_profile`）            | 自传体记忆     | DMN 负责自我参照加工                             |
 | 主动消息（`send_to_user`）         | 心智游移       | 走神产生与自我相关的念头                         |
 | 每轮数万 tokens                    | 静息高能耗     | DMN 占脑能耗约 20%                               |
@@ -254,6 +254,7 @@ LLM 读当前 memo → 融合新事实 → 输出新全文 → 服务端校验
 
 每条记忆带 `user_id` / `scope` / `tags` / `importance` / `created_at`。
 `importance` 分 `low` / `medium` / `high`，可在检索时作为过滤条件。
+检索时额外回填 `decay_score`（时间退化得分），不参与过滤。
 
 ### 检索
 
@@ -267,6 +268,32 @@ LLM 读当前 memo → 融合新事实 → 输出新全文 → 服务端校验
 > 距离是原始度量而非归一化相似度：`l2` 空间下其取值范围取决于向量是否归一化，
 > 因此不要跨模型比较绝对值，只用于同一查询内的相对排序。
 
+### 时间记忆退化（软衰减 + 分层清理）
+
+记忆不是永久等权 —— 越旧权重越低，超龄则逐级退化直至清理。分两段实现：
+
+**软衰减（检索期）**：`query_notes` 先多取 `overfetch` 倍候选，再按
+
+$$\text{score} = \frac{1}{1 + d} \times \max\left(0.5^{\,\text{age} / \text{half-life}},\ \text{floor}\right)$$
+
+重排后截回 `top_k`。半衰期随 `importance` 放大：`low` 为 `half_life_days`，
+`medium` 为 `1+boost` 倍，`high` 为 `1+2·boost` 倍。得分回填到元数据的
+`decay_score` 字段，便于排查。这一步**只重排、不删数据**。
+
+**硬分层（清理期）**：每条记忆按 `importance` 有一条寿命阈值 ——
+`low` = `short_term_days`、`high` = `long_term_days`、`medium` 取两者几何中值。
+后台任务按 `sweep_interval_hours` 扫描，超龄先 `high → medium → low` 逐级降级，
+降到 `low` 仍超龄才删除。降级只改 `importance`，不重新嵌入。
+
+| 动作     | 触发条件           | 效果                |
+| -------- | ------------------ | ------------------- |
+| `keep`   | `age ≤ 当前层阈值` | 不动                |
+| `demote` | 超龄且非 `low`     | `importance` 降一级 |
+| `purge`  | 超龄且已是 `low`   | 删除该条            |
+
+`created_at` 缺失或不可解析时按 `keep` 处理，避免误删。
+软衰减与分层清理都受 `[decay].enabled` 总开关控制。
+
 ---
 
 ## L3 离线巩固循环（DMN）
@@ -287,7 +314,7 @@ $$\text{delay} = \min(\text{base} \times \text{multiplier}^{\text{penalty}-1},\
 | 阶段           | 内容                                                       |
 | -------------- | ---------------------------------------------------------- |
 | 状态加载       | 从 `SubconsciousState` 表恢复 `total_runs` / 摘要窗口      |
-| 记忆限幅       | Core `MemoryLimiter` 截断超限消息并生成摘要                |
+| 记忆限幅       | Core `ContextCompactor` 截断超限消息并生成摘要             |
 | ReAct 循环     | Agent 调用 `subconscious_*` 工具执行整理                   |
 | 后处理         | 更新全局 usage、持久化元状态、重置惩罚、调度下次运行       |
 
@@ -304,12 +331,13 @@ $$\text{delay} = \min(\text{base} \times \text{multiplier}^{\text{penalty}-1},\
 
 ```mermaid
 flowchart TD
-    LOAD_STATE --> JINJA2_RENDER --> LIMITING_MEMORY --> BUILD_MESSAGE --> REACT_BLOCK
+    LOAD_STATE --> NORMALIZE_MESSAGES --> COMPACT_HISTORY --> JINJA2_RENDER --> BUILD_MESSAGE --> REACT_BLOCK
 ```
 
 `SubconsciousRunner` 把 ChatObject 当数据容器，注入自定义 `SubconsciousBackend`
 （隔离的工具 + memory 后端）与 Core `ReActAgentStrategy`。
-`LIMITING_MEMORY` 在 Agent Loop 前运行 Core `MemoryLimiter`。
+工作流直接复用 Core 内置的 `REACT_ONLY`，其中的 `COMPACT_HISTORY` 节点在 Agent
+Loop 前运行 Core `ContextCompactor`。压缩排在渲染之前，摘要才能进入本次请求的系统提示词。
 
 ---
 
@@ -400,11 +428,16 @@ flowchart TD
 | `knowledge_search`  | query, top_k?                                 |
 | `knowledge_suggest` | action, title, summary, body, reason          |
 
+知识库的三个只读工具 `knowledge_list` / `knowledge_read` / `knowledge_search`
+需要 LP 权限节点 `memory.knowledge`；`lp.admin` 与 `.env` 里的超级用户始终持有。
+未授权时工具返回错误 JSON，不返回任何知识内容。
+
 ### 巩固循环工具（`rethinking/tools.py`，共 20 个）
 
 记忆与 session/画像工具注册在隔离的 `_SUBCONSCIOUS_TOOLS` 上，不污染全局工具管理器。
-知识库的 `list`/`read`/`search` 双重注册（表层 + 循环均可调用）；
-`create`/`update`/`delete` 仅循环可用，表层通过 `knowledge_suggest` 提交建议。
+知识库的 `list`/`read`/`search` 双重注册：循环侧不受限，表层（对话 LLM）走
+`memory.knowledge` 权限校验；`create`/`update`/`delete` 仅循环可用，
+表层通过 `knowledge_suggest` 提交建议。
 
 | 工具                             | 用途                                   |
 | -------------------------------- | -------------------------------------- |
@@ -473,7 +506,7 @@ flowchart TD
 | ---------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
 | L1 备忘录        | `UserMemo` 表（插件自有 ORM，主键 = uni_id）                 | LLM 维护的常驻用户元信息（≤ `memo_max_chars`）                                                     |
 | 循环元状态       | `SubconsciousState` 表（插件自有 ORM，uid=`amrita_memory`）  | `total_runs`、`last_abstracts`、`pending_messages`、`knowledge_suggestions`                        |
-| Session 摘要缓存 | `LRUCache[int, str]`（最大 128 条）                          | session DB id → LLM 生成的摘要文本，避免重复调用 MemoryLimiter                                     |
+| Session 摘要缓存 | `LRUCache[int, str]`（最大 128 条）                          | session DB id → LLM 生成的摘要文本，避免重复调用 `ContextCompactor`                                     |
 | 惩罚计数器       | 内存（不持久化）                                             | `_penalty_count`：重启后从 0 开始                                                                  |
 | L2 记忆          | ChromaDB `amrita_user_memory`                                | 向量 + documents + metadatas（含嵌入指纹与分区键版本）                                             |
 | 用户画像         | `data/amrita_plugin_memory/user_profile.md`                  | Markdown 文件，`summary---body` 格式，行级增量更新                                                 |
@@ -540,11 +573,22 @@ flowchart TD
 
 ```toml
 # L2 记忆
-short_term_expiry_days = 7
-long_term_expiry_days = 90
 per_session_memory_limit = 50
 memo_max_chars = 1000
 
+# L2 时间记忆退化（软衰减 + 分层清理）
+[decay]
+enabled = true
+short_term_days = 7
+long_term_days = 90
+half_life_days = 30.0
+importance_boost = 1.0
+overfetch = 3
+score_floor = 0.05
+sweep_enabled = true
+sweep_interval_hours = 24
+sweep_batch_limit = 5000
+
 # L3 离线巩固循环
 [subconscious]
 enabled = false
@@ -570,8 +614,16 @@ enable_knowledge = true
 
 | 字段                         | 默认值  | 说明                                        |
 | ---------------------------- | ------- | ------------------------------------------- |
-| `short_term_expiry_days`     | `7`     | ⚠️ **预留字段**，当前未实现自动过期清理     |
-| `long_term_expiry_days`      | `90`    | ⚠️ **预留字段**，当前未实现自动过期清理     |
+| `decay.enabled`              | `true`  | 是否启用时间记忆退化（软衰减 + 分层清理）   |
+| `decay.short_term_days`      | `7`     | `low` 层寿命阈值（天）                      |
+| `decay.long_term_days`       | `90`    | `high` 层寿命阈值（天），`medium` 取几何中值 |
+| `decay.half_life_days`       | `30.0`  | 软衰减基础半衰期（天），`low` 为基准        |
+| `decay.importance_boost`     | `1.0`   | `high` 半衰期为 `1+2·boost` 倍              |
+| `decay.overfetch`            | `3`     | 检索候选放大倍数                            |
+| `decay.score_floor`          | `0.05`  | 衰减因子下限，避免旧记忆权重归零            |
+| `decay.sweep_enabled`        | `true`  | 是否启用分层清理                            |
+| `decay.sweep_interval_hours` | `24`    | 分层清理周期（小时）                        |
+| `decay.sweep_batch_limit`    | `5000`  | 单次清理最多扫描的记忆条数                  |
 | `per_session_memory_limit`   | `50`    | 单个分区（uni_id）的记忆条数上限            |
 | `memo_max_chars`             | `1000`  | L1 备忘录字数硬上限                         |
 | `enabled`                    | `false` | 是否启用离线巩固循环                        |
@@ -649,7 +701,6 @@ amrita_plugin_memory/
     ├── types.py               # TypedDict 定义
     ├── consts.py              # 默认 Prompt 模板 / ensure_prompt_file
     ├── backend.py             # SubconsciousBackend — 隔离的工具 + memory 后端
-    ├── nodes.py               # LIMITING_MEMORY 工作流节点
     ├── runner.py              # SubconsciousRunner — 核心编排器
     ├── hooks.py               # on_precompletion hook / 生命周期管理
     ├── tools.py               # 20 个巩固循环工具 handler

amrita_plugin_memory-0.4.1/PKG-INFO → amrita_plugin_memory-0.6.0/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: amrita_plugin_memory
-Version: 0.4.1
-Summary: Amrita长期记忆插件
-Requires-Python: <3.14,>=3.10
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: aiohttp>=3.13.3
-Requires-Dist: aiologic>=0.16.0
-Requires-Dist: amrita-core>=0.8.5
-Requires-Dist: amrita>=1.3
-Requires-Dist: chromadb>=1.5.8
-Requires-Dist: click>=8.1
-Requires-Dist: nonebot-plugin-amrita>=0.3.0
-Requires-Dist: nonebot-plugin-apscheduler>=0.5.0
-Requires-Dist: nonebot-plugin-localstore>=0.7.4
-Requires-Dist: nonebot-plugin-orm[default]>=0.8.2
-Dynamic: license-file
-
 # amrita_plugin_memory
 
 基于向量数据库的长期记忆插件 — **三层记忆模型**：
@@ -165,7 +146,7 @@ L3 在代码中沿用历史标识符 `subconscious` / `rethinking`（避免破
 | `subconscious_*` 工具             | 巩固循环工具   | —                                                |
 | 用户聊天 → `cancel_and_reschedule` | 任务负激活     | 专注任务时 DMN 被抑制                            |
 | 静默期触发 `_run`                 | 空闲时活跃     | DMN 在无任务时活跃                               |
-| 去重 / 压缩 / `MemoryLimiter`      | 记忆巩固       | 海马 → 皮层的系统巩固                            |
+| 去重 / 压缩 / `ContextCompactor`   | 记忆巩固       | 海马 → 皮层的系统巩固                            |
 | 画像构建（`*_profile`）            | 自传体记忆     | DMN 负责自我参照加工                             |
 | 主动消息（`send_to_user`）         | 心智游移       | 走神产生与自我相关的念头                         |
 | 每轮数万 tokens                    | 静息高能耗     | DMN 占脑能耗约 20%                               |
@@ -254,6 +235,7 @@ LLM 读当前 memo → 融合新事实 → 输出新全文 → 服务端校验
 
 每条记忆带 `user_id` / `scope` / `tags` / `importance` / `created_at`。
 `importance` 分 `low` / `medium` / `high`，可在检索时作为过滤条件。
+检索时额外回填 `decay_score`（时间退化得分），不参与过滤。
 
 ### 检索
 
@@ -267,6 +249,32 @@ LLM 读当前 memo → 融合新事实 → 输出新全文 → 服务端校验
 > 距离是原始度量而非归一化相似度：`l2` 空间下其取值范围取决于向量是否归一化，
 > 因此不要跨模型比较绝对值，只用于同一查询内的相对排序。
 
+### 时间记忆退化（软衰减 + 分层清理）
+
+记忆不是永久等权 —— 越旧权重越低，超龄则逐级退化直至清理。分两段实现：
+
+**软衰减（检索期）**：`query_notes` 先多取 `overfetch` 倍候选，再按
+
+$$\text{score} = \frac{1}{1 + d} \times \max\left(0.5^{\,\text{age} / \text{half-life}},\ \text{floor}\right)$$
+
+重排后截回 `top_k`。半衰期随 `importance` 放大：`low` 为 `half_life_days`，
+`medium` 为 `1+boost` 倍，`high` 为 `1+2·boost` 倍。得分回填到元数据的
+`decay_score` 字段，便于排查。这一步**只重排、不删数据**。
+
+**硬分层（清理期）**：每条记忆按 `importance` 有一条寿命阈值 ——
+`low` = `short_term_days`、`high` = `long_term_days`、`medium` 取两者几何中值。
+后台任务按 `sweep_interval_hours` 扫描，超龄先 `high → medium → low` 逐级降级，
+降到 `low` 仍超龄才删除。降级只改 `importance`，不重新嵌入。
+
+| 动作     | 触发条件           | 效果                |
+| -------- | ------------------ | ------------------- |
+| `keep`   | `age ≤ 当前层阈值` | 不动                |
+| `demote` | 超龄且非 `low`     | `importance` 降一级 |
+| `purge`  | 超龄且已是 `low`   | 删除该条            |
+
+`created_at` 缺失或不可解析时按 `keep` 处理，避免误删。
+软衰减与分层清理都受 `[decay].enabled` 总开关控制。
+
 ---
 
 ## L3 离线巩固循环（DMN）
@@ -287,7 +295,7 @@ $$\text{delay} = \min(\text{base} \times \text{multiplier}^{\text{penalty}-1},\
 | 阶段           | 内容                                                       |
 | -------------- | ---------------------------------------------------------- |
 | 状态加载       | 从 `SubconsciousState` 表恢复 `total_runs` / 摘要窗口      |
-| 记忆限幅       | Core `MemoryLimiter` 截断超限消息并生成摘要                |
+| 记忆限幅       | Core `ContextCompactor` 截断超限消息并生成摘要             |
 | ReAct 循环     | Agent 调用 `subconscious_*` 工具执行整理                   |
 | 后处理         | 更新全局 usage、持久化元状态、重置惩罚、调度下次运行       |
 
@@ -304,12 +312,13 @@ $$\text{delay} = \min(\text{base} \times \text{multiplier}^{\text{penalty}-1},\
 
 ```mermaid
 flowchart TD
-    LOAD_STATE --> JINJA2_RENDER --> LIMITING_MEMORY --> BUILD_MESSAGE --> REACT_BLOCK
+    LOAD_STATE --> NORMALIZE_MESSAGES --> COMPACT_HISTORY --> JINJA2_RENDER --> BUILD_MESSAGE --> REACT_BLOCK
 ```
 
 `SubconsciousRunner` 把 ChatObject 当数据容器，注入自定义 `SubconsciousBackend`
 （隔离的工具 + memory 后端）与 Core `ReActAgentStrategy`。
-`LIMITING_MEMORY` 在 Agent Loop 前运行 Core `MemoryLimiter`。
+工作流直接复用 Core 内置的 `REACT_ONLY`，其中的 `COMPACT_HISTORY` 节点在 Agent
+Loop 前运行 Core `ContextCompactor`。压缩排在渲染之前，摘要才能进入本次请求的系统提示词。
 
 ---
 
@@ -400,11 +409,16 @@ flowchart TD
 | `knowledge_search`  | query, top_k?                                 |
 | `knowledge_suggest` | action, title, summary, body, reason          |
 
+知识库的三个只读工具 `knowledge_list` / `knowledge_read` / `knowledge_search`
+需要 LP 权限节点 `memory.knowledge`；`lp.admin` 与 `.env` 里的超级用户始终持有。
+未授权时工具返回错误 JSON，不返回任何知识内容。
+
 ### 巩固循环工具（`rethinking/tools.py`，共 20 个）
 
 记忆与 session/画像工具注册在隔离的 `_SUBCONSCIOUS_TOOLS` 上，不污染全局工具管理器。
-知识库的 `list`/`read`/`search` 双重注册（表层 + 循环均可调用）；
-`create`/`update`/`delete` 仅循环可用，表层通过 `knowledge_suggest` 提交建议。
+知识库的 `list`/`read`/`search` 双重注册：循环侧不受限，表层（对话 LLM）走
+`memory.knowledge` 权限校验；`create`/`update`/`delete` 仅循环可用，
+表层通过 `knowledge_suggest` 提交建议。
 
 | 工具                             | 用途                                   |
 | -------------------------------- | -------------------------------------- |
@@ -473,7 +487,7 @@ flowchart TD
 | ---------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
 | L1 备忘录        | `UserMemo` 表（插件自有 ORM，主键 = uni_id）                 | LLM 维护的常驻用户元信息（≤ `memo_max_chars`）                                                     |
 | 循环元状态       | `SubconsciousState` 表（插件自有 ORM，uid=`amrita_memory`）  | `total_runs`、`last_abstracts`、`pending_messages`、`knowledge_suggestions`                        |
-| Session 摘要缓存 | `LRUCache[int, str]`（最大 128 条）                          | session DB id → LLM 生成的摘要文本，避免重复调用 MemoryLimiter                                     |
+| Session 摘要缓存 | `LRUCache[int, str]`（最大 128 条）                          | session DB id → LLM 生成的摘要文本，避免重复调用 `ContextCompactor`                                     |
 | 惩罚计数器       | 内存（不持久化）                                             | `_penalty_count`：重启后从 0 开始                                                                  |
 | L2 记忆          | ChromaDB `amrita_user_memory`                                | 向量 + documents + metadatas（含嵌入指纹与分区键版本）                                             |
 | 用户画像         | `data/amrita_plugin_memory/user_profile.md`                  | Markdown 文件，`summary---body` 格式，行级增量更新                                                 |
@@ -540,11 +554,22 @@ flowchart TD
 
 ```toml
 # L2 记忆
-short_term_expiry_days = 7
-long_term_expiry_days = 90
 per_session_memory_limit = 50
 memo_max_chars = 1000
 
+# L2 时间记忆退化（软衰减 + 分层清理）
+[decay]
+enabled = true
+short_term_days = 7
+long_term_days = 90
+half_life_days = 30.0
+importance_boost = 1.0
+overfetch = 3
+score_floor = 0.05
+sweep_enabled = true
+sweep_interval_hours = 24
+sweep_batch_limit = 5000
+
 # L3 离线巩固循环
 [subconscious]
 enabled = false
@@ -570,8 +595,16 @@ enable_knowledge = true
 
 | 字段                         | 默认值  | 说明                                        |
 | ---------------------------- | ------- | ------------------------------------------- |
-| `short_term_expiry_days`     | `7`     | ⚠️ **预留字段**，当前未实现自动过期清理     |
-| `long_term_expiry_days`      | `90`    | ⚠️ **预留字段**，当前未实现自动过期清理     |
+| `decay.enabled`              | `true`  | 是否启用时间记忆退化（软衰减 + 分层清理）   |
+| `decay.short_term_days`      | `7`     | `low` 层寿命阈值（天）                      |
+| `decay.long_term_days`       | `90`    | `high` 层寿命阈值（天），`medium` 取几何中值 |
+| `decay.half_life_days`       | `30.0`  | 软衰减基础半衰期（天），`low` 为基准        |
+| `decay.importance_boost`     | `1.0`   | `high` 半衰期为 `1+2·boost` 倍              |
+| `decay.overfetch`            | `3`     | 检索候选放大倍数                            |
+| `decay.score_floor`          | `0.05`  | 衰减因子下限，避免旧记忆权重归零            |
+| `decay.sweep_enabled`        | `true`  | 是否启用分层清理                            |
+| `decay.sweep_interval_hours` | `24`    | 分层清理周期（小时）                        |
+| `decay.sweep_batch_limit`    | `5000`  | 单次清理最多扫描的记忆条数                  |
 | `per_session_memory_limit`   | `50`    | 单个分区（uni_id）的记忆条数上限            |
 | `memo_max_chars`             | `1000`  | L1 备忘录字数硬上限                         |
 | `enabled`                    | `false` | 是否启用离线巩固循环                        |
@@ -649,7 +682,6 @@ amrita_plugin_memory/
     ├── types.py               # TypedDict 定义
     ├── consts.py              # 默认 Prompt 模板 / ensure_prompt_file
     ├── backend.py             # SubconsciousBackend — 隔离的工具 + memory 后端
-    ├── nodes.py               # LIMITING_MEMORY 工作流节点
     ├── runner.py              # SubconsciousRunner — 核心编排器
     ├── hooks.py               # on_precompletion hook / 生命周期管理
     ├── tools.py               # 20 个巩固循环工具 handler

{amrita_plugin_memory-0.4.1 → amrita_plugin_memory-0.6.0}/amrita_plugin_memory/__init__.py

@@ -15,6 +15,7 @@ from . import (
     memo,
     models,
     rethinking,
+    tasks,
     tools,
     vector,
 )
@@ -38,6 +39,7 @@ __all__ = [
     "memo",
     "models",
     "rethinking",
+    "tasks",
     "tools",
     "vector",
 ]

{amrita_plugin_memory-0.4.1 → amrita_plugin_memory-0.6.0}/amrita_plugin_memory/config.py

@@ -91,14 +91,45 @@ class SubconsciousConfig(BaseModel):
     )
 
 
+class DecayConfig(BaseModel):
+    """时间记忆退化配置：软衰减（检索重排）+ 硬分层（降级 / 清理）。"""
+
+    enabled: bool = Field(default=True, description="是否启用时间记忆退化")
+    short_term_days: int = Field(
+        default=7, ge=1, description="短期记忆保留天数（low 层寿命）"
+    )
+    long_term_days: int = Field(
+        default=90, ge=1, description="长期记忆保留天数（high 层寿命）"
+    )
+    half_life_days: float = Field(
+        default=30.0, ge=1.0, description="软衰减基础半衰期（天），low 为基准"
+    )
+    importance_boost: float = Field(
+        default=1.0,
+        ge=0.0,
+        le=5.0,
+        description="importance 对半衰期的放大系数，high 为 (1+2*boost) 倍",
+    )
+    overfetch: int = Field(
+        default=3, ge=1, le=10, description="软衰减检索的候选放大倍数"
+    )
+    score_floor: float = Field(
+        default=0.05, ge=0.0, le=1.0, description="衰减因子下限，避免旧记忆权重归零"
+    )
+    sweep_enabled: bool = Field(default=True, description="是否启用分层清理")
+    sweep_interval_hours: int = Field(
+        default=24, ge=1, description="分层清理周期（小时）"
+    )
+    sweep_batch_limit: int = Field(
+        default=5000, ge=100, description="单次清理最多扫描的记忆条数"
+    )
+
+
 class ConfigFile(BaseModel):
     """配置文件"""
 
-    short_term_expiry_days: int = Field(
-        default=7, description="短期记忆的过期天数，默认为7天"
-    )
-    long_term_expiry_days: int = Field(
-        default=90, description="长期记忆的过期天数，默认为90天"
+    decay: DecayConfig = Field(
+        default_factory=DecayConfig, description="时间记忆退化配置"
     )
     per_session_memory_limit: int = Field(
         default=100, description="每个会话的记忆数量限制，默认为50条"

amrita_plugin_memory-0.6.0/amrita_plugin_memory/decay.py

@@ -0,0 +1,184 @@
+"""时间记忆退化：软衰减（检索重排）与硬分层（降级 / 清理）。
+
+本模块只放纯逻辑，不碰 I/O，便于单独验证。
+- 软衰减：检索时按 created_at 的年龄压低得分，不删数据。
+- 硬分层：按 importance 决定寿命阈值，超龄先降级、降到 low 再清理。
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from datetime import datetime, timezone
+from typing import Any, Literal
+
+Importance = Literal["low", "medium", "high"]
+
+#: importance 的序，越大寿命越长
+IMPORTANCE_RANK: dict[str, int] = {"low": 0, "medium": 1, "high": 2}
+#: 降级链，走到尽头即清理
+DEMOTE_CHAIN: dict[str, str] = {"high": "medium", "medium": "low"}
+
+_SECONDS_PER_DAY = 86400.0
+
+
+def parse_created_at(value: Any) -> datetime | None:
+    """解析元数据里的 created_at，统一成 aware UTC；不可解析返回 None。"""
+    if isinstance(value, datetime):
+        dt = value
+    elif isinstance(value, str) and value:
+        try:
+            dt = datetime.fromisoformat(value)
+        except ValueError:
+            return None
+    else:
+        return None
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt.astimezone(timezone.utc)
+
+
+def age_days(created_at: datetime, now: datetime) -> float:
+    """年龄（天），未来时间按 0 处理。"""
+    return max((now - created_at).total_seconds() / _SECONDS_PER_DAY, 0.0)
+
+
+def importance_half_life(base_days: float, importance: str, boost: float) -> float:
+    """importance 越高，有效半衰期越长；low 为基准。"""
+    return base_days * (1.0 + boost * IMPORTANCE_RANK.get(importance, 1))
+
+
+def decay_factor(age: float, half_life: float, floor: float) -> float:
+    """指数衰减因子，下限为 floor，避免旧记忆权重归零。"""
+    if half_life <= 0:
+        return 1.0
+    return max(0.5 ** (age / half_life), floor)
+
+
+def similarity_from_distance(distance: float) -> float:
+    """把 Chroma 距离映射到 (0,1]，对 l2 / cosine 都单调。"""
+    try:
+        d = float(distance)
+    except (TypeError, ValueError):
+        d = 0.0
+    return 1.0 / (1.0 + max(d, 0.0))
+
+
+def decay_score(
+    similarity: float,
+    age: float,
+    importance: str,
+    base_half_life: float,
+    boost: float,
+    floor: float,
+) -> float:
+    """相似度 × 时间衰减因子。"""
+    half_life = importance_half_life(base_half_life, importance, boost)
+    return similarity * decay_factor(age, half_life, floor)
+
+
+def tier_days(importance: str, short_days: float, long_days: float) -> float:
+    """该 importance 层的寿命阈值（天）。medium 取 short/long 的几何中值。
+
+    两个配置项写反时按大小重排，保证 low ≤ medium ≤ high 单调，
+    否则 high 会比 medium 先过期。
+    """
+    low_days, high_days = sorted((float(short_days), float(long_days)))
+    if importance == "low":
+        return low_days
+    if importance == "high":
+        return high_days
+    if high_days > low_days:
+        return math.sqrt(low_days * high_days)
+    return low_days
+
+
+def plan_action(
+    metadata: dict, now: datetime, short_days: float, long_days: float
+) -> tuple[str, str | None]:
+    """给出单条记忆的退化动作。
+
+    Returns:
+        (动作, 新 importance)，动作 ∈ {"keep", "demote", "purge"}。
+        仅 demote 会带新的 importance。
+    """
+    created = parse_created_at(metadata.get("created_at"))
+    if created is None:
+        return "keep", None
+    importance = str(metadata.get("importance", "medium"))
+    if importance not in IMPORTANCE_RANK:
+        importance = "medium"
+    if age_days(created, now) <= tier_days(importance, short_days, long_days):
+        return "keep", None
+    nxt = DEMOTE_CHAIN.get(importance)
+    if nxt is None:
+        return "purge", None
+    return "demote", nxt
+
+
+def _inner_list(value: Any, size: int) -> list:
+    """取 QueryResult 里 list-of-list 的内层；兼容 numpy 数组；缺失时补 None。"""
+    if hasattr(value, "tolist"):  # chroma 的 embeddings 可能是 ndarray
+        value = value.tolist()
+    if isinstance(value, list) and value and isinstance(value[0], list):
+        inner = list(value[0])
+    else:
+        inner = []
+    if len(inner) < size:
+        inner.extend([None] * (size - len(inner)))
+    return inner
+
+
+def rerank_query_result(
+    result: Mapping[str, Any],
+    top_k: int,
+    base_half_life: float,
+    boost: float,
+    floor: float,
+    now: datetime | None = None,
+) -> dict[str, Any]:
+    """按衰减得分重排 QueryResult，并截断到 top_k；meta 里回填 decay_score。"""
+    now = now or datetime.now(timezone.utc)
+    ids_nested = result.get("ids")
+    if not ids_nested or not ids_nested[0]:
+        return dict(result)
+    ids = list(ids_nested[0])
+    size = len(ids)
+    metas = _inner_list(result.get("metadatas"), size)
+    dists = _inner_list(result.get("distances"), size)
+
+    scores: list[float] = []
+    for i in range(size):
+        meta = metas[i] if isinstance(metas[i], dict) else {}
+        created = parse_created_at(meta.get("created_at"))
+        age = age_days(created, now) if created else 0.0
+        similarity = similarity_from_distance(dists[i])
+        scores.append(
+            decay_score(
+                similarity,
+                age,
+                str(meta.get("importance", "medium")),
+                base_half_life,
+                boost,
+                floor,
+            )
+        )
+
+    order = sorted(range(size), key=lambda i: scores[i], reverse=True)[:top_k]
+
+    out = dict(result)
+    for key in ("ids", "documents", "metadatas", "distances", "embeddings"):
+        value = result.get(key)
+        if value is None:
+            continue
+        inner = _inner_list(value, size)
+        out[key] = [[inner[i] for i in order]]
+
+    if result.get("metadatas") is not None:
+        reordered = []
+        for i in order:
+            meta = dict(metas[i]) if isinstance(metas[i], dict) else {}
+            meta["decay_score"] = round(scores[i], 4)
+            reordered.append(meta)
+        out["metadatas"] = [reordered]
+    return out

amrita_plugin_memory-0.6.0/amrita_plugin_memory/permissions.py

@@ -0,0 +1,68 @@
+"""知识库读取的权限校验。
+
+会话侧（对话 LLM）可以读全局知识库，但需要 LP 节点 ``memory.knowledge``；
+``lp.admin`` 与 ``.env`` 里的超级用户始终持有该权限。
+潜意识循环内部调用不受此限制。
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from nonebot import get_driver, logger
+
+if TYPE_CHECKING:
+    from nonebot.adapters.onebot.v11 import Event
+
+#: 读取知识库所需的权限节点
+KNOWLEDGE_NODE = "memory.knowledge"
+#: 管理员节点，始终持有 KNOWLEDGE_NODE
+ADMIN_NODE = "lp.admin"
+
+_ENV_ADMINS = get_driver().config.superusers
+
+_lp_warned = False
+
+
+async def _has_node(event: Event, node: str) -> bool:
+    """查询 LP 节点；LP 不可用时按无权限处理。"""
+    global _lp_warned
+    try:
+        from amrita.plugins.perm.API.rules import any_has_permission
+    except Exception:
+        if not _lp_warned:
+            _lp_warned = True
+            logger.warning("[Memory] LitePerm 不可用，知识库读取仅对 .env 超级用户开放")
+        return False
+    try:
+        return bool(await any_has_permission(node)(event))
+    except Exception as e:
+        logger.opt(exception=e, colors=True, raw=True).warning(
+            f"[Memory] 权限节点 {node} 校验失败: {e}"
+        )
+        return False
+
+
+async def can_read_knowledge(event: Event | None) -> bool:
+    """是否允许读取全局知识库：超级用户 / lp.admin / memory.knowledge。"""
+    if event is None:
+        return False
+    if event.get_user_id() in _ENV_ADMINS:
+        return True
+    if await _has_node(event, ADMIN_NODE):
+        return True
+    return await _has_node(event, KNOWLEDGE_NODE)
+
+
+def get_event_from_tool_ctx(ctx: Any) -> Event | None:
+    """从 ToolContext 里取出触发本次调用的原始事件。"""
+    try:
+        from amrita.plugins.chat.runtime import try_get_amrita_ctx
+
+        amrita_ctx = try_get_amrita_ctx(ctx.ctx.chat_object)
+        if amrita_ctx is None:
+            return None
+        return amrita_ctx["event"]
+    except Exception as e:
+        logger.debug(f"[Memory] 取事件失败: {e}")
+        return None