openclaw-cortex-memory 0.1.0-Alpha.2 → 0.1.0-Alpha.20

package/README.md

@@ -1,85 +1,114 @@
 # OpenClaw Cortex Memory
 
-OpenClaw 长期记忆插件，提供跨会话检索、事件存储、规则反思、增量同步与运行诊断能力。  
-可作为 OpenClaw 的 memory slot 直接接入，支持从历史会话持续沉淀可复用记忆。
+OpenClaw 长期记忆插件 - 专为 OpenClaw AI 助手设计的智能记忆系统
 
-## 功能特性
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node.js: 22+](https://img.shields.io/badge/Node.js-22+-green.svg)](https://nodejs.org/)
+[![OpenClaw: Plugin](https://img.shields.io/badge/OpenClaw-Plugin-orange.svg)](https://github.com/openclaw)
 
-| 特性 | 说明 |
-|------|------|
-| 语义检索 | `search_memory` 支持 query + top_k |
-| 事件存储 | `store_event` 将摘要写入归档 |
-| 上下文注入 | `get_hot_context` / `get_auto_context` |
-| 增量同步 | `sync_memory` 按状态文件增量导入 |
-| 规则演进 | `reflect_memory` 更新 `CORTEX_RULES.md` |
-| 运行诊断 | `diagnostics` 检查本地存储状态 |
+面向 OpenClaw 的长期记忆插件，集成多路检索、事件归档、图谱关系、向量化与反衰减排序，支持历史增量导入、规则反思和可观测诊断，帮助 Agent 在跨会话中持续积累并稳定调用高价值记忆。
+
+---
+
+## ✨ 特性
+
+### 🔍 语义检索
+- **多路召回**: 关键词/BM25 + 向量召回统一融合重排
+- **智能排序**: 支持长度归一化防止长文本天然占优
+- **反衰减机制**: 命中频次反衰减，避免高价值老记忆被过度遗忘
+
+### 📝 事件存储
+- **分层记忆**: 原始会话、结构化事件、抽象规则拆分存储
+- **全文分块向量化**: Active 与 Archive 统一按 `chunk_size/chunk_overlap` 做全文分块向量化
+- **增量同步**: 按状态文件增量导入，避免全量重复扫描
+
+### 🕸️ 图谱关系
+- **实体关系层**: 基于归档事件中的 `entities` / `relations` 字段动态构图
+- **图谱治理**: 写入前按 `schema/graph.schema.yaml` 做规范化与关系规则校验
+- **关系查询**: 支撑 `query_graph` 的实体共现与关系查询
+
+### ⚙️ 规则演进
+- **自动反思**: `reflect_memory` 自动将事件转化为规则
+- **规则去重**: 对规则写入做签名判重，减少重复沉淀
+- **可复用规则**: 存储于 `CORTEX_RULES.md` 供后续任务复用
 
-## 安装
+### 🔧 运维诊断
+- **系统诊断**: `diagnostics` 检查本地存储状态与 API 连通性
+- **向量回填**: `backfill_embeddings` 支持 incremental / vector_only / full 三种模式重建向量层
+- **可观测性**: 通过状态文件快速定位数据目录、同步与反思异常
+
+---
+
+## 🚀 快速开始
 
 ### 前置要求
 
 - Node.js 22+
 - OpenAI API Key（或其他兼容 API）
 
-### 安装步骤
+### 安装
 
-快速安装（推荐，npm 发布版）：
+**快速安装（推荐）:**
 
 ```bash
 cd ~/openclaw
-pnpm openclaw plugins install openclaw-cortex-memory@alpha
-pnpm openclaw plugins enable openclaw-cortex-memory
-pnpm openclaw gateway restart
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
 ```
 
-后续更新：
+**npm 安装方式:**
 
 ```bash
 cd ~/openclaw
-pnpm openclaw plugins install openclaw-cortex-memory@alpha
-pnpm openclaw gateway restart
+openclaw plugins install openclaw-cortex-memory@alpha
+openclaw plugins enable openclaw-cortex-memory
 ```
-
-安装前如果 `openclaw.json` 已经提前写了 `allow/slots/entries` 指向本插件，先临时移除，安装后再加回，避免安装前校验报 `plugin not found`。
-
-### 本地打包安装（源码模式）
+**本地包安装方式（当 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.20.tgz
 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 install /tmp/cortex.tgz
+openclaw plugins enable openclaw-cortex-memory
+rm -f /tmp/cortex.tgz
 ```
 
-### 本地开发模式（无安装记录）
+**本地开发模式:**
 
 ```bash
 cd ~/.openclaw/extensions
 git clone https://github.com/deki18/openclaw-cortex-memory.git
 cd openclaw-cortex-memory
-npm install
+npm install && npm run build
 ```
 
-`npm install` 会自动执行 TypeScript 构建并生成 `dist/`，但这种方式默认不写 OpenClaw 安装记录。
-
-## 配置
+### 配置
 
 在 `openclaw.json` 中添加：
 
 ```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",
@@ -106,68 +135,33 @@ npm install
 }
 ```
 
-### 配置项说明
-
-| 配置项 | 必填 | 说明 |
-|--------|------|------|
-| `embedding.provider` | 是 | 建议使用 `api`（统一第三方接口模式） |
-| `embedding.model` | 是 | 嵌入模型名称 |
-| `embedding.dimensions` | 否 | 向量维度，需与模型匹配 |
-| `embedding.apiKey` | 是 | Embedding API Key（建议 `${EMBEDDING_API_KEY}`） |
-| `embedding.baseURL` | 是 | Embedding API 端点 |
-| `llm.provider` | 是 | 建议使用 `api` |
-| `llm.model` | 是 | LLM 模型名称 |
-| `llm.apiKey` | 是 | LLM API Key（建议 `${LLM_API_KEY}`） |
-| `llm.baseURL` | 是 | LLM API 端点 |
-| `reranker.provider` | 否 | 建议使用 `api` |
-| `reranker.model` | 是 | Reranker 模型名称 |
-| `reranker.apiKey` | 是 | Reranker API Key（建议 `${RERANKER_API_KEY}`） |
-| `reranker.baseURL` | 是 | Reranker API 端点 |
-| `engineMode` | 否 | 固定 `ts` |
-| `dbPath` | 否 | 数据目录，默认 `<plugin-dir>/data/memory` |
-| `autoSync` | 否 | 会话结束时自动同步历史记录，默认 `true` |
-| `autoReflect` | 否 | 自动触发记忆反思，默认 `false` |
-
 ### 启动
 
 ```bash
-pnpm openclaw config validate
-pnpm openclaw gateway restart
+openclaw config validate
+openclaw gateway restart
 ```
 
-### 主 Agent 注入说明
-
-首次接入后，建议把下面这段发给主 Agent，确保其按记忆工作流执行：
-
-```text
-你已接入 Cortex Memory。请遵循以下规则：
-1) 当用户询问历史对话、偏好、项目上下文时，先调用 search_memory 再回答。
-2) 需要当前会话热上下文时调用 get_hot_context。
-3) 需要自动召回相关记忆时调用 get_auto_context。
-4) 在一件重要事情结束并形成明确结果后，再调用 store_event 记录（不要在过程进行中频繁记录）。
-5) 需要实体关联关系时调用 query_graph。
-6) 当任务经历“失败→调整→最终成功”时，优先用 store_event 记录失败原因与成功方案，再调用 reflect_memory 沉淀可复用规则。
-7) 需要导入历史会话时调用 sync_memory。
-8) 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时，优先调用 diagnostics。
-9) 同一任务内不要反复调用 store_event 或 reflect_memory；仅在关键节点或任务收尾时触发一次。
-10) 不要臆造历史事实；无法确认时必须先检索。
-```
+---
 
-## 可用工具
+## 🛠️ 可用工具
 
 | 工具 | 说明 |
 |------|------|
-| `search_memory` | 语义搜索记忆库，支持 top_k 参数 |
+| `search_memory` | 语义搜索记忆库，支持 query + 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 命令
+---
+
+## 💻 CLI 命令
 
 CLI 命令需在插件目录运行：
 
@@ -180,7 +174,9 @@ npx cortex-memory uninstall --keep-data  # 卸载但保留数据
 npx cortex-memory help                # 查看命令帮助
 ```
 
-## 数据存储
+---
+
+## 📁 数据存储结构
 
 | 路径 | 说明 |
 |------|------|
@@ -188,17 +184,46 @@ 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` | 图谱写入审计日志 |
+
+---
+
+## 📋 核心特点
+
+- **分层记忆**: 把"原始会话、结构化事件、抽象规则"拆分存储，便于分别检索与治理
+- **图谱派生**: 实体关系来自事件层的 `entities` / `relations`，查询时动态生成图结构
+- **会话结束写入**: message hook 默认仅缓存，会在 `session_end` 后批量抽取并落盘
+- **严格导入门禁**: 历史导入内容必须经 LLM 提取判定后才写入事件层与图谱层
+- **三阶段去重**: SimHash 预过滤 → MinHash 精比对 → 向量余弦相似度
+- **自动演进**: 可结合 `autoSync`、`autoReflect` 持续把会话经验转化为长期可复用记忆
 
-## 注意事项
+---
 
-1. **API Key 安全**：使用环境变量 `${OPENAI_API_KEY}` 而非硬编码
-2. **向量维度**：必须与嵌入模型匹配，如 `text-embedding-3-large` 为 3072
-3. **重排序**：可选配置 `reranker` 以提升检索精度
-4. **单栈运行**：当前版本为纯 TS，无 Python 运行时依赖
+## ⚠️ 注意事项
 
-## 许可证
+1. **API Key 安全**: 使用 `${EMBEDDING_API_KEY}`、`${LLM_API_KEY}`、`${RERANKER_API_KEY}` 等环境变量而非硬编码
+2. **向量维度**: 必须与嵌入模型匹配，如 `text-embedding-3-large` 为 3072
+3. **重排序**: 可选配置 `reranker` 以提升检索精度
+4. **外部传输**: 检索与反思会调用你配置的 embedding/llm/reranker endpoint，请使用可信服务并最小化密钥权限
+5. **会话数据**: 启用 `autoSync` 时会读取 OpenClaw 会话文件并写入本地记忆目录，生产环境建议先小范围验证
+
+---
+
+## � 致谢
+
+感谢 [memory-lancedb-pro](https://github.com/CortexReach/memory-lancedb-pro) 项目作者，本插件的核心想法借鉴了该项目。
+
+---
+
+## �📄 许可证
 
 MIT License
+
+发布签名见 [SIGNATURE.md](SIGNATURE.md)

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,36 +36,54 @@ metadata:
 
 ### 安装
 
-快速安装（推荐，npm 发布版）：
+命令前缀说明：
+- 若你是全局安装 OpenClaw，请直接使用 `openclaw ...`
+- 若你使用源码安装的 OpenClaw ，请使用 `pnpm openclaw ...`
+
+快速安装（推荐，显式来源）：
 
 ```bash
 cd ~/openclaw
-pnpm openclaw plugins install openclaw-cortex-memory@alpha
-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
-pnpm openclaw plugins install openclaw-cortex-memory@alpha
-pnpm openclaw gateway restart
+openclaw plugins install openclaw-cortex-memory@alpha
+openclaw plugins enable openclaw-cortex-memory
+openclaw gateway restart
 ```
 
-安装前如果 `openclaw.json` 已经提前写了 `allow/slots/entries` 指向本插件，先临时移除，安装后再加回，避免安装前校验报 `plugin not found`。
+第三种安装方式（当 ClawHub/npm 解析受网络影响时）：
 
-### 本地打包安装（源码模式）
+```bash
+cd ~/openclaw
+curl -L -o /tmp/cortex.tgz https://registry.npmjs.org/openclaw-cortex-memory/-/openclaw-cortex-memory-0.1.0-Alpha.20.tgz
+openclaw plugins install /tmp/cortex.tgz
+openclaw plugins enable openclaw-cortex-memory
+rm -f /tmp/cortex.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
-pnpm openclaw plugins install ~/openclaw-cortex-memory-src/openclaw-cortex-memory-0.1.0-Alpha.1.tgz
-pnpm openclaw gateway restart
+rm -rf ~/.openclaw/extensions/openclaw-cortex-memory
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
+openclaw gateway restart
 ```
 
+说明：
+- 推荐显式安装来源，减少 ClawHub-first 时代的来源歧义。
+- 使用 `plugins install` 的安装记录方式，避免 `loaded without install/load-path provenance`。
+- 保持 `plugins.allow` 显式包含 `openclaw-cortex-memory`，避免运行时把插件判定为未绑定信任源。
+- 若 `plugins install openclaw-cortex-memory` 在 ClawHub 解析阶段失败，可使用上述 tgz 方式直接安装。
+
 ### 本地开发模式（无安装记录）
 
 ```bash
@@ -82,15 +100,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",
@@ -117,6 +146,14 @@ npm install
 }
 ```
 
+关键功能开关（建议显式配置）：
+
+- `readFusion.enabled`：开启多路召回后的 LLM 融合
+- `readFusion.authoritative`：仅返回融合后的权威记忆包
+- `memoryDecay.enabled`：开启按事件类型的半衰期衰减
+- `memoryDecay.antiDecay.enabled`：开启命中频次反衰减
+- `autoReflect`：建议验证稳定后再开启（默认 false）
+
 ### 启动
 
 ```bash
@@ -126,7 +163,7 @@ openclaw gateway restart
 
 ### 主Agent注入说明
 
-首次接入后，建议把下面这段发给主 Agent，确保它会主动使用记忆工具：
+首次接入后，建议把下面这段发给主 Agent，确保其按统一记忆工作流调用工具：
 
 ```text
 你已接入 Cortex Memory。请遵循以下规则：
@@ -137,9 +174,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) 不要臆造历史事实；无法确认时必须先检索。
 ```
 
 ## 可用工具
@@ -168,12 +206,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
 
@@ -199,7 +241,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
 
@@ -212,7 +267,7 @@ openclaw gateway restart
 
 ### diagnostics
 
-运行本地系统诊断，检查数据目录与基础状态。
+运行本地系统诊断，检查数据目录、分层状态与 embedding/LLM/reranker 连通性。
 
 ## 配置选项
 
@@ -220,7 +275,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`（推荐） |
@@ -235,6 +289,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 | 启用命中频次反衰减 |
 
 ## 数据文件
 
@@ -244,9 +303,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` | 图谱变更审计日志 |
 
 ## 错误处理
 
@@ -265,4 +329,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

@@ -1,4 +1,3 @@
-import type { EngineMode } from "./src/engine/types";
 interface EmbeddingConfig {
     provider: string;
     model: string;
@@ -6,6 +5,8 @@ interface EmbeddingConfig {
     baseURL?: string;
     baseUrl?: string;
     dimensions?: number;
+    timeoutMs?: number;
+    maxRetries?: number;
 }
 interface LLMConfig {
     provider: string;
@@ -23,15 +24,56 @@ interface RerankerConfig {
 }
 interface CortexMemoryConfig {
     enabled?: boolean;
+    fallbackToBuiltin?: boolean;
     embedding: EmbeddingConfig;
     llm: LLMConfig;
     reranker: RerankerConfig;
     dbPath?: string;
     autoSync?: boolean;
+    llmRequiredForWrite?: boolean;
     autoReflect?: boolean;
-    fallbackToBuiltin?: boolean;
-    apiUrl?: string;
-    engineMode?: EngineMode;
+    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;
+        };
+    };
 }
 interface ToolContext {
     agentId: string;
@@ -44,11 +86,6 @@ interface ToolResult {
     error?: string;
     errorCode?: string;
 }
-interface BuiltinMemory {
-    search: (query: string, limit?: number) => Promise<unknown[]>;
-    store: (content: string, metadata?: Record<string, unknown>) => Promise<string>;
-    delete: (id: string) => Promise<boolean>;
-}
 interface Logger {
     debug: (message: string, ...args: unknown[]) => void;
     info: (message: string, ...args: unknown[]) => void;
@@ -64,10 +101,7 @@ interface OpenClawPluginApi {
             args?: Record<string, unknown>;
             context: ToolContext;
         }) => Promise<ToolResult>;
-        handler?: (params: {
-            args?: Record<string, unknown>;
-            context: ToolContext;
-        }) => Promise<ToolResult>;
+        handler?: (...params: unknown[]) => Promise<ToolResult>;
     }): void;
     unregisterTool?(name: string): void;
     registerHook(hook: {
@@ -80,13 +114,16 @@ interface OpenClawPluginApi {
     off?(event: string, handler: (payload: unknown, context: ToolContext) => Promise<void> | void): void;
     unregisterHook?(event: string): void;
     getLogger?(): Logger;
-    getBuiltinMemory?(): BuiltinMemory;
+    getBuiltinMemory?(): {
+        search: (query: string, topK?: number) => Promise<unknown[]>;
+        store: (text: string, metadata?: Record<string, unknown>) => Promise<string>;
+        delete: (id: string) => Promise<boolean>;
+    } | null;
 }
 export declare function enable(): Promise<void>;
 export declare function disable(): Promise<void>;
 export declare function getStatus(): {
     enabled: boolean;
-    serviceRunning: boolean;
 };
 export declare function unregister(): Promise<void>;
 export declare function register(pluginApi: OpenClawPluginApi, userConfig?: Partial<CortexMemoryConfig>): void;