openclaw-cortex-memory 0.1.0-Alpha.1 → 0.1.0-Alpha.11

package/README.md

@@ -1,7 +1,8 @@
 # OpenClaw Cortex Memory
 
-OpenClaw 长期记忆插件，提供跨会话检索、事件存储、规则反思、增量同步与运行诊断能力。  
-可作为 OpenClaw 的 memory slot 直接接入，支持从历史会话持续沉淀可复用记忆。
+面向 OpenClaw 的长期记忆插件，集成多路检索、事件归档、图谱关系、向量化与反衰减排序，支持历史增量导入、规则反思和可观测诊断，帮助 Agent 在跨会话中持续积累并稳定调用高价值记忆。  
+
+发布签名见 [SIGNATURE.md]
 
 ## 功能特性
 
@@ -9,11 +10,42 @@ OpenClaw 长期记忆插件，提供跨会话检索、事件存储、规则反
 |------|------|
 | 语义检索 | `search_memory` 支持 query + top_k |
 | 事件存储 | `store_event` 将摘要写入归档 |
+| 全文分块向量化 | Active 与 Archive 统一按 `chunk_size/chunk_overlap` 做全文分块向量化 |
 | 上下文注入 | `get_hot_context` / `get_auto_context` |
-| 增量同步 | `sync_memory` 按状态文件增量导入 |
+| 增量同步 | `sync_memory` 按状态文件增量导入，并统一走 LLM 提取后写入事件/图谱 |
+| 向量回填重建 | `backfill_embeddings` 支持 incremental / vector_only / full 三种模式 |
 | 规则演进 | `reflect_memory` 更新 `CORTEX_RULES.md` |
 | 运行诊断 | `diagnostics` 检查本地存储状态 |
 
+## 记忆库组成与特点
+
+### 组成结构
+
+| 层级 | 核心文件/数据 | 作用 |
+|------|---------------|------|
+| 会话记忆层 | `sessions/active/sessions.jsonl` | 存储最近会话消息，支撑实时检索与上下文注入 |
+| 事件归档层 | `sessions/archive/sessions.jsonl` | 存储已沉淀事件（摘要、实体、结果），用于长期回顾 |
+| 实体关系层 | 基于归档事件中的 `entities` / `relations` 字段动态构图 | 支撑 `query_graph` 的实体共现与关系查询（派生图谱，不单独落盘） |
+| 向量检索层 | `vector/lancedb`（可用时）或 `vector/lancedb_events.jsonl`（回退） | 存储 active/archive 全文分块向量（含 `source_memory_id` 与 chunk 元信息），用于语义检索与同源融合 |
+| 规则知识层 | `CORTEX_RULES.md` | 存储由反思生成的可复用规则，供后续任务复用 |
+| 运行状态层 | `.sync_state.json` / `.session_end_state.json` / `.rule_store_state.json` / `.dedup_index.json` / `graph/mutation_log.jsonl` | 记录增量同步、session_end 幂等、规则去重、三阶段去重索引、图谱变更审计日志 |
+| 说明与入口层 | `MEMORY.md` | 记忆库说明与使用约定入口 |
+
+### 核心特点
+
+- 分层记忆：把“原始会话、结构化事件、抽象规则”拆分存储，便于分别检索与治理
+- 图谱派生：实体关系来自事件层的 `entities` / `relations`，查询时动态生成图结构
+- 图谱治理：写入前按 `schema/graph.schema.yaml` 做 event/relation 规范化与关系规则校验
+- 会话结束写入：message hook 默认仅缓存，会在 `session_end` 后批量抽取并落盘
+- 严格导入门禁：历史导入内容必须经 LLM 提取判定后才写入事件层与图谱层
+- 增量导入：通过状态文件只处理新增会话内容，避免全量重复扫描
+- 幂等去重：对 session_end 事件和规则写入做签名判重，减少重复沉淀
+- 三阶段去重：SimHash 预过滤 → MinHash 精比对 → 向量余弦相似度
+- 全文分块向量化：active/archive 两层统一使用可配置 chunk 策略（默认 `600/100`，语义断句优先）
+- 混合检索：关键词/BM25 + 向量召回统一融合重排，并支持长度归一化防止长文本天然占优
+- 自动演进：可结合 `autoSync`、`autoReflect` 持续把会话经验转化为长期可复用记忆
+- 可观测可诊断：通过 `diagnostics` 与状态文件快速定位数据目录、同步与反思异常
+
 ## 安装
 
 ### 前置要求
@@ -23,29 +55,51 @@ OpenClaw 长期记忆插件，提供跨会话检索、事件存储、规则反
 
 ### 安装步骤
 
-快速安装（推荐）：
+命令前缀说明：
+- 若你是全局安装 OpenClaw，请直接使用 `openclaw ...`
+- 若你使用源码安装的 OpenClaw ，请使用 `pnpm openclaw ...`
+
+快速安装（推荐，显式来源）：
+
+```bash
+cd ~/openclaw
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
+```
+
+npm 安装方式：
+
+```bash
+cd ~/openclaw
+openclaw plugins install openclaw-cortex-memory@alpha
+openclaw plugins enable openclaw-cortex-memory
+```
+
+第三种安装方式（当 ClawHub/npm 解析受网络影响时）：
 
 ```bash
-git clone https://github.com/deki18/openclaw-cortex-memory.git ~/openclaw-cortex-memory-src
-cd ~/openclaw-cortex-memory-src
-npm install && npm run build && npm pack
+curl -L -o /tmp/cortex.tgz https://registry.npmjs.org/openclaw-cortex-memory/-/openclaw-cortex-memory-0.1.0-Alpha.11.tgz
 cd ~/openclaw
-pnpm openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.1.tgz
-pnpm openclaw plugins enable openclaw-cortex-memory
-pnpm openclaw gateway restart
+openclaw plugins install /tmp/cortex.tgz
+openclaw plugins enable openclaw-cortex-memory
+rm -f /tmp/cortex.tgz
 ```
 
-后续更新（同一套流程）：
+后续更新：
 
 ```bash
-cd ~/openclaw-cortex-memory-src
-git pull && npm install && npm run build && npm pack
 cd ~/openclaw
-pnpm openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.1.tgz
-pnpm openclaw gateway restart
+openclaw plugins uninstall openclaw-cortex-memory
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
 ```
 
-安装前如果 `openclaw.json` 已经提前写了 `allow/slots/entries` 指向本插件，先临时移除，安装后再加回，避免安装前校验报 `plugin not found`。
+说明：
+- 推荐显式安装来源，减少 ClawHub-first 时代的来源歧义。
+- 使用 `plugins install` 的安装记录方式，避免 `loaded without install/load-path provenance`。
+- 保持 `plugins.allow` 显式包含 `openclaw-cortex-memory`，避免运行时把插件判定为未绑定信任源。
+- 若 `plugins install openclaw-cortex-memory` 在 ClawHub 解析阶段失败，可使用上述 tgz 方式直接安装。
+
 
 ### 本地开发模式（无安装记录）
 
@@ -56,7 +110,7 @@ cd openclaw-cortex-memory
 npm install
 ```
 
-`npm install` 会自动执行 TypeScript 构建并生成 `dist/`，但这种方式默认不写 OpenClaw 安装记录。
+`npm install` 不会自动构建 `dist/`，源码模式请显式执行 `npm run build`，且这种方式默认不写 OpenClaw 安装记录。
 
 ## 配置
 
@@ -65,15 +119,26 @@ npm install
 ```json
 {
   "plugins": {
+    "allow": ["openclaw-cortex-memory"],
     "slots": { "memory": "openclaw-cortex-memory" },
     "entries": {
       "openclaw-cortex-memory": {
         "enabled": true,
         "config": {
           "engineMode": "ts",
-          "dbPath": "<optional-memory-dir>",
           "autoSync": true,
-          "autoReflect": true,
+          "autoReflect": false,
+          "autoReflectIntervalMinutes": 30,
+          "readFusion": {
+            "enabled": true,
+            "authoritative": true
+          },
+          "memoryDecay": {
+            "enabled": true,
+            "antiDecay": {
+              "enabled": true
+            }
+          },
           "embedding": {
             "provider": "api",
             "model": "text-embedding-3-large",
@@ -100,13 +165,23 @@ npm install
 }
 ```
 
+### 关键功能开关（建议显式配置）
+
+- `readFusion.enabled`：开启多路召回后 LLM 融合
+- `readFusion.authoritative`：开启后仅返回融合后的权威记忆包
+- `readFusion.channelWeights/channelTopK`：控制各召回通道权重与配额
+- `readFusion.lengthNorm`：长度归一化参数，抑制超长文本得分偏置
+- `vectorChunking.chunkSize/chunkOverlap`：全文分块向量化参数（默认 `600/100`）
+- `memoryDecay.enabled`：开启按 `event_type` 半衰期衰减
+- `memoryDecay.antiDecay.enabled`：开启命中频次反衰减，避免高价值老记忆被过度衰减
+- `autoReflect`：建议在验证稳定后再开启；默认 `false`
+
 ### 配置项说明
 
 | 配置项 | 必填 | 说明 |
 |--------|------|------|
 | `embedding.provider` | 是 | 建议使用 `api`（统一第三方接口模式） |
 | `embedding.model` | 是 | 嵌入模型名称 |
-| `embedding.dimensions` | 否 | 向量维度，需与模型匹配 |
 | `embedding.apiKey` | 是 | Embedding API Key（建议 `${EMBEDDING_API_KEY}`） |
 | `embedding.baseURL` | 是 | Embedding API 端点 |
 | `llm.provider` | 是 | 建议使用 `api` |
@@ -121,6 +196,11 @@ npm install
 | `dbPath` | 否 | 数据目录，默认 `<plugin-dir>/data/memory` |
 | `autoSync` | 否 | 会话结束时自动同步历史记录，默认 `true` |
 | `autoReflect` | 否 | 自动触发记忆反思，默认 `false` |
+| `autoReflectIntervalMinutes` | 否 | 自动反思扫描间隔（分钟），默认 `30`，最小 `5` |
+| `readFusion.enabled` | 否 | 启用重排后 LLM 融合，默认 `true` |
+| `readFusion.authoritative` | 否 | 仅返回融合权威记忆包，默认 `true` |
+| `memoryDecay.enabled` | 否 | 启用按 `event_type` 的半衰期衰减，默认 `true` |
+| `memoryDecay.antiDecay.enabled` | 否 | 启用命中频次反衰减，默认 `true` |
 
 ### 启动
 
@@ -142,9 +222,10 @@ openclaw gateway restart
 5) 需要实体关联关系时调用 query_graph。
 6) 当任务经历“失败→调整→最终成功”时，优先用 store_event 记录失败原因与成功方案，再调用 reflect_memory 沉淀可复用规则。
 7) 需要导入历史会话时调用 sync_memory。
-8) 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时，优先调用 diagnostics。
-9) 同一任务内不要反复调用 store_event 或 reflect_memory；仅在关键节点或任务收尾时触发一次。
-10) 不要臆造历史事实；无法确认时必须先检索。
+8) 当 diagnostics 显示 active/archive 存在未向量化记录，或迁移后需要重建向量层时，调用 backfill_embeddings（按需选择 incremental/vector_only/full）。
+9) 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时，优先调用 diagnostics。
+10) 同一任务内不要反复调用 store_event 或 reflect_memory；仅在关键节点或任务收尾时触发一次。
+11) 不要臆造历史事实；无法确认时必须先检索。
 ```
 
 ## 可用工具
@@ -153,13 +234,14 @@ openclaw gateway restart
 |------|------|
 | `search_memory` | 语义搜索记忆库，支持 top_k 参数 |
 | `store_event` | 存储事件，可包含实体和关系 |
-| `query_graph` | 查询实体关系图谱 |
+| `query_graph` | 查询实体关系图谱，支持关系过滤、方向过滤与路径查询 |
 | `get_hot_context` | 获取热上下文（CORTEX_RULES.md + 近期会话） |
 | `get_auto_context` | 自动检索相关记忆 + 热上下文 |
 | `reflect_memory` | 触发记忆反思，将事件转化为规则 |
-| `sync_memory` | 同步 OpenClaw 历史会话（增量） |
+| `sync_memory` | 同步 OpenClaw 历史会话（增量），并通过 LLM 判定后写入事件/图谱 |
+| `backfill_embeddings` | 向量回填/重建（支持 `incremental`、`vector_only`、`full`） |
 | `delete_memory` | 删除指定记忆 |
-| `diagnostics` | 系统诊断 |
+| `diagnostics` | 系统诊断（含 embedding/LLM/reranker 连通性检查） |
 
 ## CLI 命令
 
@@ -182,16 +264,24 @@ npx cortex-memory help                # 查看命令帮助
 | `<dbPath>/CORTEX_RULES.md` | 规则文件 |
 | `<dbPath>/sessions/active/sessions.jsonl` | 活跃会话 |
 | `<dbPath>/sessions/archive/sessions.jsonl` | 归档事件 |
+| `<dbPath>/vector/lancedb` | LanceDB 向量表（可用时） |
+| `<dbPath>/vector/lancedb_events.jsonl` | 向量回退存储（LanceDB不可用时） |
 | `<dbPath>/.sync_state.json` | 同步增量状态 |
 | `<dbPath>/.session_end_state.json` | session_end 幂等状态 |
 | `<dbPath>/.rule_store_state.json` | 规则去重状态 |
+| `<dbPath>/.dedup_index.json` | 三阶段去重索引 |
+| `<dbPath>/.read_hit_stats.json` | 检索命中频次统计（用于反衰减增益） |
+| `<dbPath>/graph/mutation_log.jsonl` | 图谱写入审计日志（canonical_id/source_event_id/actor/timestamp） |
 
 ## 注意事项
 
-1. **API Key 安全**：使用环境变量 `${OPENAI_API_KEY}` 而非硬编码
+1. **API Key 安全**：使用 `${EMBEDDING_API_KEY}`、`${LLM_API_KEY}`、`${RERANKER_API_KEY}` 等环境变量而非硬编码
 2. **向量维度**：必须与嵌入模型匹配，如 `text-embedding-3-large` 为 3072
 3. **重排序**：可选配置 `reranker` 以提升检索精度
-4. **单栈运行**：当前版本为纯 TS，无 Python 运行时依赖
+4. **外部传输**：检索与反思会调用你配置的 embedding/llm/reranker endpoint，请使用可信服务并最小化密钥权限
+5. **会话数据**：启用 `autoSync` 时会读取 OpenClaw 会话文件并写入本地记忆目录，生产环境建议先小范围验证
+6. **历史导入来源**：`sync_memory` 会同时导入 `<openclaw_base>/agents/main/sessions/*.jsonl` 与 `<openclaw_base>/workspace/memory/*.md`
+7. **重复导入防护**：每日总结 `.md` 会按文件内容哈希标记在 `.sync_state.json`，未变化文件不会重复导入
 
 ## 许可证
 

package/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cortex-memory
-description: 长期记忆系统（纯 TypeScript）。Use when user asks about past conversations, preferences, project history, or needs to remember information across sessions.
+description: 长期记忆系统（纯 TypeScript）。适用于历史对话回溯、偏好记忆、项目上下文延续与跨会话信息复用场景。
 homepage: https://github.com/deki18/openclaw-cortex-memory
 metadata:
   {
@@ -8,27 +8,27 @@ metadata:
       "emoji": "🧠",
       "os": ["darwin", "linux", "win32"],
       "requires": {
-        "env": ["OPENAI_API_KEY"]
+        "env": ["EMBEDDING_API_KEY", "LLM_API_KEY", "RERANKER_API_KEY"]
       },
-      "primaryEnv": "OPENAI_API_KEY"
+      "primaryEnv": "EMBEDDING_API_KEY"
     }
   }
 ---
 
-# Cortex Memory - 长期记忆系统
+# Cortex Memory · 长期记忆系统
 
-为 OpenClaw Agent 提供持久化记忆能力，当前为纯 TypeScript 单栈实现。
+为 OpenClaw Agent 提供稳定的跨会话记忆能力。
 
 ## 使用场景
 
-**USE when:**
+**建议使用场景（USE when）:**
 - 用户询问过去的对话内容或决策
 - 需要记住用户偏好、项目信息
 - 跨会话保持上下文
 - 查询实体关系（人物、项目、技术）
 - 存储重要事件或里程碑
 
-**DON'T use when:**
+**不建议使用场景（DON'T use when）:**
 - 仅需当前会话的临时信息
 - 查询实时数据（天气、新闻等）
 
@@ -36,30 +36,65 @@ metadata:
 
 ### 安装
 
-快速安装（推荐）：
+命令前缀说明：
+- 若你是全局安装 OpenClaw，请直接使用 `openclaw ...`
+- 若你使用源码安装的 OpenClaw ，请使用 `pnpm openclaw ...`
+
+快速安装（推荐，显式来源）：
 
 ```bash
-git clone https://github.com/deki18/openclaw-cortex-memory.git ~/openclaw-cortex-memory-src
-cd ~/openclaw-cortex-memory-src
-npm install && npm run build && npm pack
 cd ~/openclaw
-pnpm openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.1.tgz
-pnpm openclaw plugins enable openclaw-cortex-memory
-pnpm openclaw gateway restart
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
+openclaw gateway restart
 ```
 
-### 后续更新
+npm 安装方式：
 
 ```bash
-cd ~/openclaw-cortex-memory-src
-git pull && npm install && npm run build && npm pack
+cd ~/openclaw
+openclaw plugins install openclaw-cortex-memory@alpha
+openclaw plugins enable openclaw-cortex-memory
+openclaw gateway restart
+```
 
+第三种安装方式（当 ClawHub/npm 解析受网络影响时）：
+
+```bash
+curl -L -o /tmp/cortex.tgz https://registry.npmjs.org/openclaw-cortex-memory/-/openclaw-cortex-memory-0.1.0-Alpha.11.tgz
+cd ~/openclaw
+openclaw plugins install /tmp/cortex.tgz
+openclaw plugins enable openclaw-cortex-memory
+openclaw gateway restart
+rm -f /tmp/cortex.tgz
+```
+
+### 后续更新
+
+```bash
 cd ~/openclaw
-pnpm openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.1.tgz
-pnpm openclaw gateway restart
+openclaw plugins uninstall openclaw-cortex-memory
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
+openclaw gateway restart
 ```
 
-安装前如果 `openclaw.json` 已经提前写了 `allow/slots/entries` 指向本插件，先临时移除，安装后再加回，避免安装前校验报 `plugin not found`。
+说明：
+- 推荐显式安装来源，减少 ClawHub-first 时代的来源歧义。
+- 使用 `plugins install` 的安装记录方式，避免 `loaded without install/load-path provenance`。
+- 保持 `plugins.allow` 显式包含 `openclaw-cortex-memory`，避免运行时把插件判定为未绑定信任源。
+- 若 `plugins install openclaw-cortex-memory` 在 ClawHub 解析阶段失败，可使用上述 tgz 方式直接安装。
+
+### 本地打包安装（源码模式）
+
+```bash
+git clone https://github.com/deki18/openclaw-cortex-memory.git ~/openclaw-cortex-memory-src
+cd ~/openclaw-cortex-memory-src
+npm install && npm run build && npm pack
+cd ~/openclaw
+openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.11.tgz
+openclaw gateway restart
+```
 
 ### 本地开发模式（无安装记录）
 
@@ -77,15 +112,26 @@ npm install
 ```json
 {
   "plugins": {
+    "allow": ["openclaw-cortex-memory"],
     "slots": { "memory": "openclaw-cortex-memory" },
     "entries": {
       "openclaw-cortex-memory": {
         "enabled": true,
         "config": {
           "engineMode": "ts",
-          "dbPath": "<optional-memory-dir>",
           "autoSync": true,
-          "autoReflect": true,
+          "autoReflect": false,
+          "autoReflectIntervalMinutes": 30,
+          "readFusion": {
+            "enabled": true,
+            "authoritative": true
+          },
+          "memoryDecay": {
+            "enabled": true,
+            "antiDecay": {
+              "enabled": true
+            }
+          },
           "embedding": {
             "provider": "api",
             "model": "text-embedding-3-large",
@@ -112,6 +158,14 @@ npm install
 }
 ```
 
+关键功能开关（建议显式配置）：
+
+- `readFusion.enabled`：开启多路召回后的 LLM 融合
+- `readFusion.authoritative`：仅返回融合后的权威记忆包
+- `memoryDecay.enabled`：开启按事件类型的半衰期衰减
+- `memoryDecay.antiDecay.enabled`：开启命中频次反衰减
+- `autoReflect`：建议验证稳定后再开启（默认 false）
+
 ### 启动
 
 ```bash
@@ -121,7 +175,7 @@ openclaw gateway restart
 
 ### 主Agent注入说明
 
-首次接入后，建议把下面这段发给主 Agent，确保它会主动使用记忆工具：
+首次接入后，建议把下面这段发给主 Agent，确保其按统一记忆工作流调用工具：
 
 ```text
 你已接入 Cortex Memory。请遵循以下规则：
@@ -132,9 +186,10 @@ openclaw gateway restart
 5) 需要实体关联关系时调用 query_graph。
 6) 当任务经历“失败→调整→最终成功”时，优先用 store_event 记录失败原因与成功方案，再调用 reflect_memory 沉淀可复用规则。
 7) 需要导入历史会话时调用 sync_memory。
-8) 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时，优先调用 diagnostics。
-9) 同一任务内不要反复调用 store_event 或 reflect_memory；仅在关键节点或任务收尾时触发一次。
-10) 不要臆造历史事实；无法确认时必须先检索。
+8) 当 diagnostics 显示 active/archive 存在未向量化记录，或迁移后需要重建向量层时，调用 backfill_embeddings（按需选择 incremental/vector_only/full）。
+9) 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时，优先调用 diagnostics。
+10) 同一任务内不要反复调用 store_event 或 reflect_memory；仅在关键节点或任务收尾时触发一次。
+11) 不要臆造历史事实；无法确认时必须先检索。
 ```
 
 ## 可用工具
@@ -163,12 +218,16 @@ openclaw gateway restart
 
 ### query_graph
 
-查询归档事件中的实体共现关系。
+查询归档事件中的实体关系（relations 优先，共现关系回退）。
 
 **参数：**
 | 参数 | 类型 | 必需 | 说明 |
 |------|------|------|------|
 | entity | string | 是 | 实体名称 |
+| rel | string | 否 | 关系类型过滤（如 `depends_on`） |
+| dir | string | 否 | 方向过滤：`incoming` / `outgoing` / `both` |
+| path_to | string | 否 | 查询从 `entity` 到目标实体的路径 |
+| max_depth | number | 否 | 路径最大深度（2~4） |
 
 ### get_hot_context
 
@@ -194,7 +253,20 @@ openclaw gateway restart
 
 ### sync_memory
 
-增量同步会话记录到本地记忆（无参数）。
+增量同步会话记录，且必须经 LLM 提取判定后才写入事件/图谱记忆（无参数）。
+
+### backfill_embeddings
+
+按层回填或重建向量，支持全文分块向量重建。
+
+**参数：**
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| layer | string | 否 | `active` / `archive` / `all` |
+| batch_size | number | 否 | 每批处理数量 |
+| max_retries | number | 否 | 失败重试上限 |
+| retry_failed_only | boolean | 否 | 仅处理失败记录 |
+| rebuild_mode | string | 否 | `incremental` / `vector_only` / `full` |
 
 ### delete_memory
 
@@ -207,7 +279,7 @@ openclaw gateway restart
 
 ### diagnostics
 
-运行本地系统诊断，检查数据目录与基础状态。
+运行本地系统诊断，检查数据目录、分层状态与 embedding/LLM/reranker 连通性。
 
 ## 配置选项
 
@@ -215,7 +287,6 @@ openclaw gateway restart
 |------|------|--------|------|
 | embedding.provider | 是 | - | `api`（推荐） |
 | embedding.model | 是 | - | Embedding 模型名称 |
-| embedding.dimensions | 否 | 3072 | 向量维度 |
 | embedding.apiKey | 是 | ${EMBEDDING_API_KEY} | Embedding API Key |
 | embedding.baseURL | 是 | - | Embedding API 端点 |
 | llm.provider | 是 | - | `api`（推荐） |
@@ -230,6 +301,11 @@ openclaw gateway restart
 | engineMode | 否 | `ts` | 固定为 TS 引擎 |
 | autoSync | 否 | true | 会话结束自动同步 |
 | autoReflect | 否 | false | 自动触发反思 |
+| autoReflectIntervalMinutes | 否 | 30 | 自动反思扫描间隔（分钟） |
+| readFusion.enabled | 否 | true | 启用检索重排后的 LLM 融合 |
+| readFusion.authoritative | 否 | true | 仅返回融合权威记忆包 |
+| memoryDecay.enabled | 否 | true | 启用按事件类型半衰期衰减 |
+| memoryDecay.antiDecay.enabled | 否 | true | 启用命中频次反衰减 |
 
 ## 数据文件
 
@@ -239,9 +315,14 @@ openclaw gateway restart
 | `<dbPath>/CORTEX_RULES.md` | 规则文件 |
 | `<dbPath>/sessions/active/sessions.jsonl` | 活跃会话记忆 |
 | `<dbPath>/sessions/archive/sessions.jsonl` | 归档事件 |
+| `<dbPath>/vector/lancedb` | LanceDB 向量表（可用时） |
+| `<dbPath>/vector/lancedb_events.jsonl` | 向量回退存储（LanceDB 不可用时） |
 | `<dbPath>/.sync_state.json` | 同步增量状态 |
 | `<dbPath>/.session_end_state.json` | session_end 幂等状态 |
 | `<dbPath>/.rule_store_state.json` | 规则去重状态 |
+| `<dbPath>/.dedup_index.json` | 三阶段去重索引 |
+| `<dbPath>/.read_hit_stats.json` | 检索命中频次统计（反衰减） |
+| `<dbPath>/graph/mutation_log.jsonl` | 图谱变更审计日志 |
 
 ## 错误处理
 
@@ -260,4 +341,4 @@ openclaw gateway restart
 ## 依赖
 
 - Node.js >= 22
-- OPENAI_API_KEY（或兼容 API 配置）
+- EMBEDDING_API_KEY、LLM_API_KEY、RERANKER_API_KEY（或兼容 API 配置）

package/dist/index.d.ts

@@ -6,6 +6,8 @@ interface EmbeddingConfig {
     baseURL?: string;
     baseUrl?: string;
     dimensions?: number;
+    timeoutMs?: number;
+    maxRetries?: number;
 }
 interface LLMConfig {
     provider: string;
@@ -28,7 +30,50 @@ interface CortexMemoryConfig {
     reranker: RerankerConfig;
     dbPath?: string;
     autoSync?: boolean;
+    llmRequiredForWrite?: boolean;
     autoReflect?: boolean;
+    autoReflectIntervalMinutes?: number;
+    readFusion?: {
+        enabled?: boolean;
+        maxCandidates?: number;
+        authoritative?: boolean;
+        channelWeights?: {
+            rules?: number;
+            archive?: number;
+            vector?: number;
+            graph?: number;
+        };
+        channelTopK?: {
+            rules?: number;
+            archive?: number;
+            vector?: number;
+            graph?: number;
+        };
+        minLexicalHits?: number;
+        minSemanticHits?: number;
+        lengthNorm?: {
+            enabled?: boolean;
+            pivotChars?: number;
+            strength?: number;
+            minFactor?: number;
+        };
+    };
+    vectorChunking?: {
+        chunkSize?: number;
+        chunkOverlap?: number;
+    };
+    memoryDecay?: {
+        enabled?: boolean;
+        minFloor?: number;
+        defaultHalfLifeDays?: number;
+        halfLifeByEventType?: Record<string, number>;
+        antiDecay?: {
+            enabled?: boolean;
+            maxBoost?: number;
+            hitWeight?: number;
+            recentWindowDays?: number;
+        };
+    };
     fallbackToBuiltin?: boolean;
     apiUrl?: string;
     engineMode?: EngineMode;
@@ -60,10 +105,11 @@ interface OpenClawPluginApi {
         name: string;
         description: string;
         parameters: Record<string, unknown>;
-        execute: (params: {
-            args: Record<string, unknown>;
+        execute?: (params: {
+            args?: Record<string, unknown>;
             context: ToolContext;
         }) => Promise<ToolResult>;
+        handler?: (...params: unknown[]) => Promise<ToolResult>;
     }): void;
     unregisterTool?(name: string): void;
     registerHook(hook: {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../index.ts"],"names":[],"mappings":"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"}