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

package/README.md

@@ -1,204 +1,164 @@
-# OpenClaw Cortex Memory
-
-OpenClaw 长期记忆插件，提供跨会话检索、事件存储、规则反思、增量同步与运行诊断能力。  
-可作为 OpenClaw 的 memory slot 直接接入，支持从历史会话持续沉淀可复用记忆。
-
-## 功能特性
-
-| 特性 | 说明 |
-|------|------|
-| 语义检索 | `search_memory` 支持 query + top_k |
-| 事件存储 | `store_event` 将摘要写入归档 |
-| 上下文注入 | `get_hot_context` / `get_auto_context` |
-| 增量同步 | `sync_memory` 按状态文件增量导入 |
-| 规则演进 | `reflect_memory` 更新 `CORTEX_RULES.md` |
-| 运行诊断 | `diagnostics` 检查本地存储状态 |
-
-## 安装
-
-### 前置要求
-
-- 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
-```
-
-后续更新：
-
-```bash
-cd ~/openclaw
-pnpm openclaw plugins install openclaw-cortex-memory@alpha
-pnpm openclaw gateway restart
-```
-
-安装前如果 `openclaw.json` 已经提前写了 `allow/slots/entries` 指向本插件，先临时移除，安装后再加回，避免安装前校验报 `plugin not found`。
-
-### 本地打包安装（源码模式）
-
-```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
-```
-
-### 本地开发模式（无安装记录）
-
-```bash
-cd ~/.openclaw/extensions
-git clone https://github.com/deki18/openclaw-cortex-memory.git
-cd openclaw-cortex-memory
-npm install
-```
-
-`npm install` 会自动执行 TypeScript 构建并生成 `dist/`，但这种方式默认不写 OpenClaw 安装记录。
-
-## 配置
-
-在 `openclaw.json` 中添加：
-
-```json
-{
-  "plugins": {
-    "slots": { "memory": "openclaw-cortex-memory" },
-    "entries": {
-      "openclaw-cortex-memory": {
-        "enabled": true,
-        "config": {
-          "engineMode": "ts",
-          "dbPath": "<optional-memory-dir>",
-          "autoSync": true,
-          "autoReflect": true,
-          "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"
-          }
-        }
-      }
-    }
-  }
-}
-```
-
-### 配置项说明
-
-| 配置项 | 必填 | 说明 |
-|--------|------|------|
-| `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
-```
-
-### 主 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>/.sync_state.json` | 同步增量状态 |
-| `<dbPath>/.session_end_state.json` | session_end 幂等状态 |
-| `<dbPath>/.rule_store_state.json` | 规则去重状态 |
-
-## 注意事项
-
-1. **API Key 安全**：使用环境变量 `${OPENAI_API_KEY}` 而非硬编码
-2. **向量维度**：必须与嵌入模型匹配，如 `text-embedding-3-large` 为 3072
-3. **重排序**：可选配置 `reranker` 以提升检索精度
-4. **单栈运行**：当前版本为纯 TS，无 Python 运行时依赖
-
-## 许可证
-
+# 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 的长期记忆插件，集成多路检索、事件归档、图谱关系、向量化与反衰减排序，支持历史增量导入、规则反思和可观测诊断，帮助 Agent 在跨会话中持续积累并稳定调用高价值记忆。
+
+---
+
+## 核心能力
+
+### 1) 语义检索
+- 多路召回：`keyword / BM25 / vector / graph` 混合检索
+- 排序融合：加权打分 + RRF + 可选 reranker
+- 结果融合：可选 `readFusion`，支持权威融合返回
+- 时序建模：`memoryDecay` + 命中反衰减（anti-decay）
+
+### 2) 事件存储
+- 分层写入：`active`（会话）与 `archive`（结构化事件）
+- 摘要优先：归档记录保留 `summary` 与 `source_text`
+- 向量分块：支持 summary/evidence 双通道向量记录
+- 增量同步：按状态文件增量导入历史会话
+
+### 3) 图谱关系
+- 图谱独立层：`graph/memory.jsonl` 独立于 archive 文本层
+- 关系追溯：每条关系可追溯 `source_event_id`
+- 关系查询：`query_graph` 支持方向、关系类型、路径搜索
+- 质量门禁：`graphQualityMode` 支持 `off/warn/strict`
+
+### 4) 规则演进
+- 反思沉淀：`reflect_memory` 将事件抽象为规则
+- 去重治理：规则与事件均有去重控制，避免污染
+- 规则复用：规则写入 `CORTEX_RULES.md` 供后续任务复用
+
+### 5) 运维诊断
+- `diagnostics`：模型连通、层级状态、字段对齐检查
+- `backfill_embeddings`：支持 `incremental / vector_only / full`
+- 完整状态文件：便于快速定位同步、回填、质量问题
+
+---
+
+## 已注册工具（与当前代码一致）
+
+- `search_memory`
+- `store_event`
+- `query_graph`
+- `get_hot_context`
+- `get_auto_context`
+- `reflect_memory`
+- `sync_memory`
+- `backfill_embeddings`
+- `delete_memory`
+- `diagnostics`
+
+### 工具参数速览
+
+| 工具 | 关键参数 |
+|------|------|
+| `search_memory` | `query`, `top_k` |
+| `store_event` | `summary`, `entities`, `entity_types`, `outcome`, `relations` |
+| `query_graph` | `entity`, `rel`, `dir`, `path_to`, `max_depth` |
+| `get_hot_context` | `limit` |
+| `get_auto_context` | `include_hot` |
+| `backfill_embeddings` | `layer`, `batch_size`, `max_retries`, `retry_failed_only`, `rebuild_mode` |
+| `delete_memory` | `memory_id` |
+
+---
+
+## 快速开始
+
+### 安装
+
+```bash
+cd ~/openclaw
+openclaw plugins install clawhub:openclaw-cortex-memory
+openclaw plugins enable openclaw-cortex-memory
+openclaw gateway restart
+```
+
+### 最小配置（推荐先跑起来）
+
+```json
+{
+  "plugins": {
+    "allow": ["openclaw-cortex-memory"],
+    "slots": { "memory": "openclaw-cortex-memory" },
+    "entries": {
+      "openclaw-cortex-memory": {
+        "enabled": true,
+        "config": {
+          "autoSync": true,
+          "autoReflect": false,
+          "graphQualityMode": "warn",
+          "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"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+<details>
+<summary>高级配置（默认已内置，不懂可以不改）</summary>
+
+- `readFusion`：融合候选数、通道权重、通道 TopK、最小 lexical/semantic 命中、长度归一
+- `memoryDecay`：最小衰减地板、默认半衰期、事件类型半衰期、anti-decay 参数
+- `vectorChunking`：分块大小、重叠、evidence 最大分块数
+- `writePolicy`：archive/active 质量阈值与文本长度限制
+- `readTuning`：打分权重、RRF 参数、recency 分桶、auto-context 轻量检索
+
+</details>
+
+---
+
+## 数据目录
+
+- `<dbPath>/MEMORY.md`
+- `<dbPath>/CORTEX_RULES.md`
+- `<dbPath>/sessions/active/sessions.jsonl`
+- `<dbPath>/sessions/archive/sessions.jsonl`
+- `<dbPath>/graph/memory.jsonl`
+- `<dbPath>/graph/mutation_log.jsonl`
+- `<dbPath>/vector/lancedb`
+- `<dbPath>/vector/lancedb_events.jsonl`
+- `<dbPath>/.sync_state.json`
+- `<dbPath>/.session_end_state.json`
+- `<dbPath>/.rule_store_state.json`
+- `<dbPath>/.dedup_index.json`
+- `<dbPath>/.read_hit_stats.json`
+
+---
+
+## 常用命令
+
+```bash
+npm run typecheck
+npm run test:graph-quality
+npm run test:graph-quality-zh
+```
+
+---
+
 MIT License