openclaw-cortex-memory 0.1.0-Alpha.8 → 0.1.0

package/README.md

@@ -1,299 +1,347 @@
-# OpenClaw Cortex Memory
-
-面向 OpenClaw 的长期记忆插件，集成多路检索、事件归档、图谱关系、向量化与反衰减排序，支持历史增量导入、规则反思和可观测诊断，帮助 Agent 在跨会话中持续积累并稳定调用高价值记忆。  
-
-发布签名见 [SIGNATURE.md]
-
-## 功能特性
-
-| 特性 | 说明 |
-|------|------|
-| 语义检索 | `search_memory` 支持 query + top_k |
-| 事件存储 | `store_event` 将摘要写入归档 |
-| 上下文注入 | `get_hot_context` / `get_auto_context` |
-| 增量同步 | `sync_memory` 按状态文件增量导入 |
-| 规则演进 | `reflect_memory` 更新 `CORTEX_RULES.md` |
-| 运行诊断 | `diagnostics` 检查本地存储状态 |
-
-## 记忆库组成与特点
-
-### 组成结构
-
-| 层级 | 核心文件/数据 | 作用 |
-|------|---------------|------|
-| 会话记忆层 | `sessions/active/sessions.jsonl` | 存储最近会话消息，支撑实时检索与上下文注入 |
-| 事件归档层 | `sessions/archive/sessions.jsonl` | 存储已沉淀事件（摘要、实体、结果），用于长期回顾 |
-| 实体关系层 | 基于归档事件中的 `entities` / `relations` 字段动态构图 | 支撑 `query_graph` 的实体共现与关系查询（派生图谱，不单独落盘） |
-| 向量检索层 | `vector/lancedb`（可用时）或 `vector/lancedb_events.jsonl`（回退） | 存储事件向量，用于语义检索与向量去重 |
-| 规则知识层 | `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` 后批量抽取并落盘
-- 增量导入：通过状态文件只处理新增会话内容，避免全量重复扫描
-- 幂等去重：对 session_end 事件和规则写入做签名判重，减少重复沉淀
-- 三阶段去重：SimHash 预过滤 → MinHash 精比对 → 向量余弦相似度
-- 自动演进：可结合 `autoSync`、`autoReflect` 持续把会话经验转化为长期可复用记忆
-- 可观测可诊断：通过 `diagnostics` 与状态文件快速定位数据目录、同步与反思异常
-
-## 安装
-
-### 前置要求
-
-- Node.js 22+
-- OpenAI API Key（或其他兼容 API）
-
-### 安装步骤
-
-快速安装（推荐，显式来源）：
-
-```bash
-cd ~/openclaw
-pnpm openclaw plugins install clawhub:openclaw-cortex-memory
-pnpm openclaw plugins enable openclaw-cortex-memory
-```
-
-npm 安装方式：
-
-```bash
-cd ~/openclaw
-pnpm openclaw plugins install openclaw-cortex-memory@alpha
-pnpm openclaw plugins enable openclaw-cortex-memory
-```
-
-第三种安装方式（当 ClawHub/npm 解析受网络影响时）：
-
-```bash
-curl -L -o /tmp/cortex.tgz https://registry.npmjs.org/openclaw-cortex-memory/-/openclaw-cortex-memory-0.1.0-Alpha.8.tgz
-cd ~/openclaw
-pnpm openclaw plugins install /tmp/cortex.tgz
-pnpm openclaw plugins enable openclaw-cortex-memory
-rm -f /tmp/cortex.tgz
-```
-
-后续更新：
-
-```bash
-cd ~/openclaw
-pnpm openclaw plugins uninstall openclaw-cortex-memory
-pnpm openclaw plugins install clawhub:openclaw-cortex-memory
-pnpm openclaw plugins enable openclaw-cortex-memory
-```
-
-说明：
-- 推荐显式安装来源，减少 ClawHub-first 时代的来源歧义。
-- 使用 `plugins install` 的安装记录方式，避免 `loaded without install/load-path provenance`。
-- 保持 `plugins.allow` 显式包含 `openclaw-cortex-memory`，避免运行时把插件判定为未绑定信任源。
-- 若 `plugins install openclaw-cortex-memory` 在 ClawHub 解析阶段失败，可使用上述 tgz 方式直接安装。
-
-
-### 本地开发模式（无安装记录）
-
-```bash
-cd ~/.openclaw/extensions
-git clone https://github.com/deki18/openclaw-cortex-memory.git
-cd openclaw-cortex-memory
-npm install
-```
-
-`npm install` 不会自动构建 `dist/`，源码模式请显式执行 `npm run build`，且这种方式默认不写 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": false,
-          "autoReflectIntervalMinutes": 30,
-          "readFusion": {
-            "enabled": true,
-            "maxCandidates": 10,
-            "authoritative": true
-          },
-          "memoryDecay": {
-            "enabled": true,
-            "minFloor": 0.15,
-            "defaultHalfLifeDays": 90,
-            "halfLifeByEventType": {
-              "issue": 30,
-              "fix": 30,
-              "action_item": 30,
-              "decision": 120,
-              "preference": 240,
-              "constraint": 240,
-              "requirement": 240
-            },
-            "antiDecay": {
-              "enabled": true,
-              "maxBoost": 1.6,
-              "hitWeight": 0.08,
-              "recentWindowDays": 30
-            }
-          },
-          "embedding": {
-            "provider": "api",
-            "model": "text-embedding-3-large",
-            "apiKey": "${EMBEDDING_API_KEY}",
-            "baseURL": "https://your-embedding-endpoint/v1",
-            "dimensions": 3072
-          },
-          "llm": {
-            "provider": "api",
-            "model": "gpt-4",
-            "apiKey": "${LLM_API_KEY}",
-            "baseURL": "https://your-llm-endpoint/v1"
-          },
-          "reranker": {
-            "provider": "api",
-            "model": "BAAI/bge-reranker-v2-m3",
-            "apiKey": "${RERANKER_API_KEY}",
-            "baseURL": "https://your-reranker-endpoint/v1/rerank"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### 关键功能开关（建议显式配置）
-
-- `readFusion.enabled`：开启多路召回后 LLM 融合
-- `readFusion.authoritative`：开启后仅返回融合后的权威记忆包
-- `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` |
-| `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` |
-| `autoReflectIntervalMinutes` | 否 | 自动反思扫描间隔（分钟），默认 `30`，最小 `5` |
-| `readFusion.enabled` | 否 | 启用重排后 LLM 融合，默认 `true` |
-| `readFusion.maxCandidates` | 否 | 融合候选上限，默认 `10` |
-| `readFusion.authoritative` | 否 | 仅返回融合权威记忆包，默认 `true` |
-| `memoryDecay.enabled` | 否 | 启用按 `event_type` 的半衰期衰减，默认 `true` |
-| `memoryDecay.minFloor` | 否 | 衰减系数下限（0~1），默认 `0.15` |
-| `memoryDecay.defaultHalfLifeDays` | 否 | 未配置类型的默认半衰期（天），默认 `90` |
-| `memoryDecay.halfLifeByEventType` | 否 | 各 `event_type` 半衰期覆盖配置（天） |
-| `memoryDecay.antiDecay.enabled` | 否 | 启用命中频次反衰减，默认 `true` |
-| `memoryDecay.antiDecay.maxBoost` | 否 | 反衰减最大增益（>=1），默认 `1.6` |
-| `memoryDecay.antiDecay.hitWeight` | 否 | 命中次数增益系数，默认 `0.08` |
-| `memoryDecay.antiDecay.recentWindowDays` | 否 | 命中新鲜度窗口（天），默认 `30` |
-
-### 启动
-
-```bash
-pnpm openclaw config validate
-pnpm 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 参数 |
-| `store_event` | 存储事件，可包含实体和关系 |
-| `query_graph` | 查询实体关系图谱，支持关系过滤、方向过滤与路径查询 |
-| `get_hot_context` | 获取热上下文（CORTEX_RULES.md + 近期会话） |
-| `get_auto_context` | 自动检索相关记忆 + 热上下文 |
-| `reflect_memory` | 触发记忆反思，将事件转化为规则 |
-| `sync_memory` | 同步 OpenClaw 历史会话（增量） |
-| `delete_memory` | 删除指定记忆 |
-| `diagnostics` | 系统诊断 |
-
-## CLI 命令
-
-CLI 命令需在插件目录运行：
-
-```bash
-npx cortex-memory status              # 查看插件状态
-npx cortex-memory enable              # 启用插件
-npx cortex-memory disable             # 禁用插件（回退到内置记忆）
-npx cortex-memory uninstall           # 卸载插件
-npx cortex-memory uninstall --keep-data  # 卸载但保留数据
-npx cortex-memory help                # 查看命令帮助
-```
-
-## 数据存储
-
-| 路径 | 说明 |
-|------|------|
-| `<dbPath>/MEMORY.md` | 记忆说明 |
-| `<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 安全**：使用 `${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 会话文件并写入本地记忆目录，生产环境建议先小范围验证
-6. **单栈运行**：当前版本为纯 TS，无 Python 运行时依赖
-7. **历史导入来源**：`sync_memory` 会同时导入 `<openclaw_base>/agents/main/sessions/*.jsonl` 与 `<openclaw_base>/workspace/memory/*.md`
-8. **重复导入防护**：每日总结 `.md` 会按文件内容哈希标记在 `.sync_state.json`，未变化文件不会重复导入
-
-## 许可证
-
-MIT License
+# OpenClaw Cortex Memory
+
+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)
+
+面向 OpenClaw 的长期记忆插件，集成多路检索、事件归档、图谱关系、向量化与反衰减排序，支持历史增量导入、规则反思和可观测诊断，可以将会话中零碎的记忆去噪整理、分层存储，支持对话中自动搜索回忆，吸收了LLM wiki的概念，帮助 Agent 在跨会话中持续积累并稳定调用高价值记忆。
+
+---
+
+## 核心能力
+
+### 1) 语义检索
+- 多路召回：`keyword / BM25 / vector / graph` 混合检索
+- 排序融合：加权打分 + RRF + 可选 reranker
+- 结果融合：可选 `readFusion`，支持权威融合返回
+- 调试输出：`search_memory` 返回 `timing_ms` 与 `debug`，可定位检索链路耗时、召回策略与 fusion 模式
+- 检索控制：`fusion_mode` 可按次关闭/强制 fusion，`track_hits: false` 可用于诊断或评测，避免污染 anti-decay 命中统计
+- 通道明细：`search_memory` 保留兼容字段 `semantic_results` / `keyword_results`，同时返回 `channel_results` 区分 `archive/graph/rules/vector/keyword` 等全局通道
+- 图谱边界：`search_memory` 不把 Wiki markdown 当作候选记忆；图谱命中可返回 `wiki_ref` / `wiki_refs` / `evidence_ids` 作为展示和追溯链接，事实来源仍以 `graph/memory.jsonl` 为准
+- 时序建模：`memoryDecay` + 命中反衰减（anti-decay）
+
+### 2) 事件存储
+- 分层写入：`active`（会话）与 `archive`（结构化事件）
+- 摘要优先：归档记录保留 `summary` 与 `source_text`
+- 向量分块：支持 summary/evidence 双通道向量记录
+- 增量同步：按状态文件增量导入历史会话
+
+### 3) 图谱关系
+- 图谱独立层：`graph/memory.jsonl` 独立于 archive 文本层
+- 关系追溯：每条关系可追溯 `source_event_id`
+- 关系查询：`query_graph` 支持方向、关系类型、路径搜索
+- 冲突治理：单值事实冲突进入队列，支持人工 `accept/reject` 闭环
+- 可视化导出：`export_graph_view` 输出状态化图谱快照（含来源证据）
+- 质量门禁：全局 `graphQualityMode` 支持 `off/warn/strict`；历史导入可用 `syncPolicy.graphQualityMode` 单独收紧
+
+### 4) 规则演进
+- 反思沉淀：`reflect_memory` 将事件抽象为规则
+- 去重治理：规则与事件均有去重控制，避免污染
+- 规则复用：规则写入 `CORTEX_RULES.md` 供后续任务复用
+
+### 5) 运维诊断
+- `cortex_diagnostics`：模型连通、层级状态、字段对齐检查
+- `backfill_embeddings`：支持 `incremental / vector_only / full`
+- `lint_memory_wiki`：Wiki/图谱一致性、证据完整性与知识页质量巡检
+- 完整状态文件：便于快速定位同步、回填、质量问题
+
+---
+
+## 已注册工具（与当前代码一致）
+
+- `search_memory`
+- `store_event`
+- `query_graph`
+- `export_graph_view`
+- `lint_memory_wiki`
+- `list_graph_conflicts`
+- `resolve_graph_conflict`
+- `get_hot_context`
+- `get_auto_context`
+- `reflect_memory`
+- `sync_memory`
+- `backfill_embeddings`
+- `delete_memory`
+- `cortex_diagnostics`（推荐）
+
+### 工具参数速览
+
+| 工具 | 关键参数 |
+|------|------|
+| `search_memory` | `query`, `top_k`, `fusion_mode`, `track_hits` |
+| `store_event` | `summary`, `entities`, `entity_types`, `outcome`, `relations` |
+| `query_graph` | `entity`, `rel`, `dir`, `path_to`, `max_depth` |
+| `export_graph_view` | `write_snapshot` |
+| `lint_memory_wiki` | 无 |
+| `list_graph_conflicts` | `status`, `limit` |
+| `resolve_graph_conflict` | `conflict_id`, `action`, `note` |
+| `get_hot_context` | `limit` |
+| `get_auto_context` | `include_hot` |
+| `reflect_memory` | 无 |
+| `sync_memory` | 无 |
+| `backfill_embeddings` | `layer`, `batch_size`, `max_retries`, `retry_failed_only`, `rebuild_mode` |
+| `cortex_diagnostics` | 无 |
+| `delete_memory` | `memory_id` |
+
+---
+
+## Agent 使用手册（系统提示词）
+
+> 可直接粘贴到 Agent 的系统提示词中使用
+
+**Cortex Memory 记忆插件使用规则（核心规则，不允许删除）**
+
+你已接入 Cortex Memory。必须遵循以下规则：
+
+1. 禁止臆造历史事实；凡涉及历史对话、用户偏好、项目既有决策，先检索再回答。  
+2. 单个任务内避免频繁写入：`store_event` / `reflect_memory` 应按里程碑触发（通常每个完整任务 0-2 次）。  
+3. 用户询问历史信息、偏好、项目上下文时：先调用 `search_memory`，再回答，触发词如“上次、之前、你记得、上个月、去年、上个星期、昨天、前天、我记得、你查一下”等。  
+4. 需要当前会话热上下文时：调用 `get_hot_context`。  
+5. 需要自动召回相关记忆时：调用 `get_auto_context`。  
+6. 需要实体关系、依赖链路或路径关系时：调用 `query_graph`。  
+7. 仅在“重要事项已结束且结论明确”后调用 `store_event` 记录结果；结论未定时先不写入。  
+8. 当任务经历“失败 -> 调整 -> 成功”时：先用 `store_event` 记录失败原因与成功方案，再调用 `reflect_memory` 沉淀可复用规则。  
+9. 需要导入历史会话时：调用 `sync_memory`。  
+10. 当 `cortex_diagnostics` 显示 active/archive 有未向量化记录，或迁移后需重建向量层时：调用 `backfill_embeddings`（按需选择 `incremental` / `vector_only` / `full`）。  
+11. 出现配置校验失败、记忆读写异常、检索结果异常或数据目录问题时：优先调用 `cortex_diagnostics`。  
+12. 仅在用户明确要求删除记忆，且已确认 `memory_id` 时，才调用 `delete_memory`；禁止在未确认情况下自动删除。  
+13. 工具调用失败时：读操作可重试一次；写操作（如 `store_event` / `reflect_memory` / `delete_memory` / `resolve_graph_conflict`）重试前先确认是否已成功落库，避免重复写入。  
+14. 调用任意 Cortex Memory 工具前，先确认当前运行环境可见该工具；若工具不可见，必须立即报告“当前 lane 不可用”，不得虚构执行结果。  
+15. `sync_memory` 与 `backfill_embeddings` 属于关键路径任务：执行前后应避免并发重复触发；若已有同任务进行中，复用当前结果或等待完成。  
+16. 当用户明确请求 Cortex Memory 任务（如 `sync_memory` / `search_memory` / `store_event`）时，禁止切换到无关流程（如心跳巡检、日报、闲聊任务）；若被系统任务打断，先完成用户请求再处理后台任务。  
+17. 当 `query_graph` 返回 `conflict_hint` 时，不得静默覆盖冲突事实；应先调用 `list_graph_conflicts`，并与用户确认后再 `resolve_graph_conflict`。  
+18. 需要解释图谱状态分布或排查投影异常时，优先调用 `export_graph_view` 与 `lint_memory_wiki`。  
+19. 记忆检索结果与模型推断必须分开表述：可明确标注“来自记忆检索/图谱”与“基于当前信息的推断”。  
+20. 涉及隐私或用户明确要求“不要记忆”的内容，禁止调用 `store_event` / `reflect_memory` 写入长期记忆。  
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+cd ~/openclaw
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
+```
+
+如果 `clawhub:` 安装出现 `fetch failed`，可改用 npm 包本地安装（推荐兜底）：
+
+```bash
+npm pack openclaw-cortex-memory@0.1.0
+openclaw plugins install ./openclaw-cortex-memory-0.1.0.tgz
+openclaw plugins enable openclaw-cortex-memory
+rm ./openclaw-cortex-memory-0.1.0.tgz
+```
+
+完成安装后，请先按下方"最小配置"示例配置 `openclaw.json`，确认配置无误后再启动 gateway。
+
+### 更新
+
+```bash
+rm -r ~/.openclaw/extensions/openclaw-cortex-memory
+npm pack openclaw-cortex-memory@0.1.0
+openclaw plugins install ./openclaw-cortex-memory-0.1.0.tgz
+openclaw plugins enable openclaw-cortex-memory
+rm ./openclaw-cortex-memory-0.1.0.tgz
+openclaw plugins list  --enabled
+openclaw gateway restart
+```
+
+### 卸载
+
+```bash
+cd ~/openclaw
+openclaw plugins disable openclaw-cortex-memory
+openclaw plugins uninstall openclaw-cortex-memory
+```
+
+如需卸载插件但保留记忆数据：
+
+```bash
+cd ~/openclaw
+openclaw plugins disable openclaw-cortex-memory
+openclaw plugins uninstall openclaw-cortex-memory --keep-data
+```
+
+### 最小配置（推荐先跑起来）
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-cortex-memory"],
+    "slots": { "memory": "none" },
+    "entries": {
+      "memory-core": {
+        "enabled": false
+      },
+      "memory-lancedb": {
+        "enabled": false
+      },
+      "openclaw-cortex-memory": {
+        "enabled": true,
+        "config": {
+          "autoSync": true,
+          "autoReflect": false,
+          "graphQualityMode": "warn",
+          "readFusion": {
+            "enabled": true,
+            "authoritative": true
+          },
+          "memoryDecay": {
+            "enabled": true,
+            "antiDecay": {
+              "enabled": true
+            }
+          },
+          "embedding": {
+            "provider": "api",
+            "model": "text-embedding-3-small",
+            "apiKey": "${EMBEDDING_API_KEY}",
+            "baseURL": "https://your-embedding-endpoint/v1",
+            "dimensions": 1536
+          },
+          "llm": {
+            "provider": "api",
+            "model": "gpt-4",
+            "apiKey": "${LLM_API_KEY}",
+            "baseURL": "https://your-llm-endpoint/v1"
+          },
+          "reranker": {
+            "provider": "api",
+            "model": "BAAI/bge-reranker-v2-m3",
+            "apiKey": "${RERANKER_API_KEY}",
+            "baseURL": "https://your-reranker-endpoint/v1/rerank"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+独占模式注意事项：
+
+- `plugins.slots.memory` 不要设置为 `openclaw-cortex-memory`
+- 建议将 `memory-core` 与 `memory-lancedb` 显式禁用（如上示例），避免多记忆后端并存冲突
+
+## 外部端点与凭证声明（审查说明）
+
+本插件是本地长期记忆系统，但以下能力依赖用户自配置的外部模型端点：
+
+- `embedding`：向量化（`/embeddings`）
+- `llm`：写入门控、规则反思、读融合（`/chat/completions`）
+- `reranker`：候选重排序（`/rerank`）
+
+对应凭证要求：
+
+- 环境变量（可选）：`EMBEDDING_API_KEY`、`LLM_API_KEY`、`RERANKER_API_KEY`
+- 插件配置（常用）：`embedding.apiKey`、`llm.apiKey`、`reranker.apiKey`
+- 端点配置：`embedding.baseURL`、`llm.baseURL`、`reranker.baseURL`
+
+### 网络发送的数据边界
+
+- 会发送：用于模型推理的文本片段（如 query、候选摘要、转写片段、待向量化文本）
+- 不会主动发送：本地配置文件原文、系统环境变量全集、插件状态文件全集
+- 凭证使用方式：仅作为 `Authorization: Bearer` 请求头调用你配置的端点
+
+### 风险与建议
+
+- 你应只配置可信模型网关，密钥权限最小化（建议专用 key）
+- 生产环境建议启用网关审计与请求日志脱敏
+- 如不希望联网推理，不要配置外部端点/密钥（相关能力将降级或跳过）
+
+<details>
+<summary>高级配置（默认已内置，不懂可以不改）</summary>
+
+- `readFusion`：融合候选数、通道权重、通道 TopK、最小 lexical/semantic 命中、长度归一
+- `memoryDecay`：最小衰减地板、默认半衰期、事件类型半衰期、anti-decay 参数
+- `vectorChunking`：分块大小、重叠、evidence 最大分块数
+- `writePolicy`：archive/active 质量阈值与文本长度限制
+- `syncPolicy`：历史导入来源与导入期图谱质量门禁
+- `readTuning`：打分权重、RRF 参数、recency 分桶、auto-context 轻量检索
+
+`search_memory` 支持按次覆盖读取行为：
+
+```json
+{
+  "query": "上次我们怎么处理记忆搜索延迟？",
+  "top_k": 5,
+  "fusion_mode": "candidates",
+  "track_hits": false
+}
+```
+
+- `fusion_mode: "auto"`：默认值，遵循 `readFusion.authoritative`
+- `fusion_mode: "authoritative"`：返回融合后的权威结果
+- `fusion_mode: "candidates"`：返回融合结果 + 候选明细，适合调试
+- `fusion_mode: "off"`：关闭 LLM fusion，适合低延迟或诊断
+- `track_hits: false`：不更新 anti-decay 命中统计，适合评测/排查
+
+`search_memory` 的 JSONL fallback 向量层会缓存文档、向量 norm 与 source-memory 分组；当 query embedding 可用时，会先按 cosine 预选 topN，再进入 BM25/RRF 混合排序，避免大库下把所有 fallback vector chunk 放进后续排序。中文 n-gram 用于召回扩展，但 BM25 文档 token 保留重复项以维持 term frequency 区分度。
+
+`get_auto_context` 使用最近会话消息构造自动查询，并默认走无外部模型调用的 auto 检索路径；显式 `search_memory` 仍使用完整检索链路。消息 hook 仍有短保护窗口，但同一 session 的 on-message 自动检索会做 in-flight 去重，避免超时后后台搜索堆积。
+
+</details>
+
+---
+
+## 数据目录
+
+默认情况下（未配置 `dbPath`），数据目录为 OpenClaw workspace 下：
+
+- Linux/macOS: `~/.openclaw/workspace/memory/openclaw-cortex-memory`
+- Windows: `%USERPROFILE%\\.openclaw\\workspace\\memory\\openclaw-cortex-memory`
+
+如果当前进程无法识别 OpenClaw 基础目录（例如离线脚本直接运行且无相关环境变量），会回退到项目目录：
+
+- `<projectRoot>/data/memory`
+
+如果在插件配置里设置了 `dbPath`，则以下文件都会写到你指定的 `dbPath` 下：
+
+- `<memoryRoot>/CORTEX_RULES.md`
+- `<memoryRoot>/sessions/active/sessions.jsonl`
+- `<memoryRoot>/sessions/archive/sessions.jsonl`
+- `<memoryRoot>/graph/memory.jsonl`
+- `<memoryRoot>/graph/memory.md`
+- `<memoryRoot>/graph/mutation_log.jsonl`
+- `<memoryRoot>/graph/mutation_log.md`
+- `<memoryRoot>/graph/conflict_queue.jsonl`
+- `<memoryRoot>/graph/superseded_relations.jsonl`
+- `<memoryRoot>/wiki/index.md`
+- `<memoryRoot>/wiki/log.md`
+- `<memoryRoot>/wiki/entities/*.md`
+- `<memoryRoot>/wiki/topics/*.md`
+- `<memoryRoot>/wiki/timelines/*.md`
+- `<memoryRoot>/wiki/graph/view.json`
+- `<memoryRoot>/wiki/graph/timeline.jsonl`
+- `<memoryRoot>/wiki/graph/network.mmd`
+- `<memoryRoot>/wiki/graph/network.md`
+- `<memoryRoot>/wiki/.projection_index.json`
+- `<memoryRoot>/wiki/.rebuild_queue.jsonl`
+- `<memoryRoot>/vector/lancedb`
+- `<memoryRoot>/vector/lancedb_events.jsonl`
+- `<memoryRoot>/.sync_state.json`
+- `<memoryRoot>/.session_end_state.json`
+- `<memoryRoot>/.rule_store_state.json`
+- `<memoryRoot>/.dedup_index.json`
+- `<memoryRoot>/.read_hit_stats.json`
+
+Wiki 是图谱关系的物化投影，不是独立记忆库。Wiki 投影会为实体页生成 `Current Conclusion`、`Recent Changes`、`High Confidence Facts`、`Evidence Excerpts` 等知识页结构；为主题页生成状态分组；为时间线页生成 `Event Flow`，并在 archive 事件存在时带上 `cause/process/result`。`lint_memory_wiki` 会检查这些结构是否缺失、是否仍停留在旧式泛化 Summary、以及图谱证据是否不足。
+
+---
+
+## 常用命令
+
+```bash
+npm run typecheck
+npm run test:graph-quality
+npm run test:graph-quality-zh
+```
+
+---
+
+MIT License