@evermind-ai/openclaw-plugin 1.1.0

package/README.zh.md

@@ -0,0 +1,400 @@
+# EverMemOS ContextEngine OpenClaw 插件
+
+通过 [EverMemOS](https://github.com/EverMind-AI/EverMemOS) 为 **OpenClaw 3.8+** 提供全生命周期记忆管理。
+
+> **专为 OpenClaw 3.8+ ContextEngine API 构建** - 利用最新的 ContextEngine 生命周期钩子实现智能记忆管理。
+
+---
+
+## 功能特性
+
+- **Bootstrap**: 插件加载时后端健康检查
+- **Assemble**: 每次 agent 轮次前的查询感知上下文检索
+- **AfterTurn**: 每轮结束后及时提取记忆（而非仅会话结束时）
+- **Compact**: 参与会话压缩以优化上下文窗口
+- **边界检测**: 通过 EverMemOS 的边界检测算法智能提取记忆
+
+---
+
+## 快速开始
+
+### 前置要求
+
+| 要求 | 版本 | 说明 |
+|-------------|---------|-------|
+| **Node.js** | 18+ | 运行插件 |
+| **Python** | 3.10+ | 运行 EverMemOS 后端 |
+| **Docker** | 20.10+ | 基础设施服务 |
+| **OpenClaw** | 3.8+ | 支持 ContextEngine |
+
+---
+
+## 步骤 1: 安装 EverMemOS 后端
+
+### 克隆并设置
+
+```bash
+# 克隆 EverMemOS 仓库
+git clone https://github.com/EverMind-AI/EverMemOS.git
+cd EverMemOS
+
+# 启动 Docker 服务（MongoDB、Elasticsearch、Milvus、Redis）
+docker compose up -d
+
+# 安装 uv 包管理器
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# 安装 Python 依赖
+uv sync
+
+# 配置 API 密钥
+cp env.template .env
+# 编辑 .env 并设置你的 LLM_API_KEY 和 VECTORIZE_API_KEY
+
+# 启动后端服务（默认: http://localhost:1995）
+uv run python src/run.py
+```
+
+### 验证后端
+
+```bash
+curl http://localhost:1995/health
+# 预期响应: {"status": "healthy", ...}
+```
+
+> **详细 EverMemOS 安装指南**，请参阅 [官方安装文档](https://github.com/EverMind-AI/EverMemOS/blob/main/docs/installation/SETUP.md)
+
+---
+
+## 步骤 2: 安装插件
+
+### 选项 A: 本地开发（推荐）
+
+```bash
+# 克隆此仓库
+git clone https://github.com/EverMind-AI/evermemos-openclaw-plugin.git
+cd evermemos-openclaw-plugin
+
+# 安装依赖
+npm install
+```
+
+### 选项 B: 通过 npm
+
+```bash
+npm install @evermind-ai/openclaw-plugin
+```
+
+---
+
+## 步骤 3: 配置 OpenClaw
+
+编辑 `~/.openclaw/openclaw.json`：
+
+### 3.1 添加插件路径
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": [
+        "/path/to/openclaw/extensions/feishu",
+        "/path/to/openclaw/extensions/memory-openviking",
+        "/Users/admin/EverMind/evermemos-openclaw-plugin"  // 添加此行
+      ]
+    }
+  }
+}
+```
+
+### 3.2 启用插件
+
+```json
+{
+  "plugins": {
+    "allow": [
+      "memory-openviking",
+      "feishu",
+      "mem9",
+      "evermemos-openclaw-plugin"  // 添加此行
+    ]
+  }
+}
+```
+
+### 3.3 设置 ContextEngine 插槽（OpenClaw 3.8+）
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "none",
+      "contextEngine": "evermemos-openclaw-plugin"  // 使用 EverMemOS ContextEngine
+    }
+  }
+}
+```
+
+### 3.4 添加插件配置
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "evermemos-openclaw-plugin": {
+        "enabled": true,
+        "config": {
+          "baseUrl": "http://localhost:1995",
+          "userId": "evermemos-user",
+          "groupId": "evermemos-group",
+          "topK": 5,
+          "memoryTypes": ["episodic_memory", "profile", "agent_skill", "agent_case"],
+          "retrieveMethod": "hybrid"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 步骤 4: 重启 OpenClaw
+
+```bash
+openclaw gateway restart
+```
+
+---
+
+## 步骤 5: 验证安装
+
+检查 OpenClaw 日志中的插件加载信息：
+
+```
+[evermemos] Registering EverMemOS ContextEngine plugin
+[evermemos] bootstrap: session=xxx, key=xxx
+[evermemos] bootstrap: backend healthy, status=ok
+```
+
+---
+
+## 测试
+
+### 测试记忆存储
+
+向 agent 发送消息：
+```
+记住：我最喜欢的颜色是蓝色
+```
+
+### 测试记忆检索
+
+稍后询问：
+```
+我最喜欢什么颜色？
+```
+
+Agent 应该能够从 EverMemOS 中回忆起该信息。
+
+---
+
+## 配置说明
+
+| 参数 | 类型 | 默认值 | 说明 |
+|-----------|------|---------|-------------|
+| `baseUrl` | string | `http://localhost:1995` | EverMemOS 服务地址 |
+| `userId` | string | `evermemos-user` | 用户身份，用于记忆归属 |
+| `groupId` | string | `evermemos-group` | 组 ID，用于共享记忆 |
+| `topK` | integer | `5` | 最多检索的记忆条目数 |
+| `memoryTypes` | string[] | 见下方 | 搜索的记忆类型 |
+| `retrieveMethod` | string | `hybrid` | 检索策略 |
+
+### 记忆类型
+
+| 值 | 说明 |
+|-------|-------------|
+| `episodic_memory` | 过往对话片段 |
+| `profile` | 用户档案和偏好 |
+| `agent_case` | 相似历史案例 |
+| `agent_skill` | Agent 技能知识 |
+
+### 检索策略
+
+| 值 | 说明 |
+|-------|-------------|
+| `keyword` | 全文关键词搜索 |
+| `vector` | 语义向量搜索 |
+| `hybrid` | 关键词 + 向量融合 |
+| `rrf` | 倒序排名融合 |
+| `agentic` | Agent 驱动的自适应检索 |
+
+---
+
+## 架构
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         OpenClaw 核心                           │
+│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────────┐ │
+│  │   消息流    │  │  会话管理    │  │   Token 预算管理        │ │
+│  │             │  │              │  │   (压缩)                │ │
+│  └──────┬──────┘  └──────┬───────┘  └──────────┬──────────────┘ │
+└─────────┼────────────────┼─────────────────────┼────────────────┘
+          │                │                     │
+          ▼                ▼                     ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    EverMemOS ContextEngine                      │
+│  ┌─────────┐  ┌─────────┐  ┌──────────┐  ┌──────────────────┐   │
+│  │bootstrap│  │  ingest │  │afterTurn │  │     assemble     │   │
+│  └────┬────┘  └────┬────┘  └────┬─────┘  └────────┬─────────┘   │
+└───────┼─────────────┼─────────────┼─────────────────┼─────────────┘
+        │             │             │                 │
+        ▼             ▼             ▼                 ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      EverMemOS 后端                             │
+│                    http://localhost:1995                        │
+│                                                                 │
+│  • 边界检测  • 记忆提取  • 向量搜索    • 档案构建               │
+│  • 聚类      • 预测                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## OpenClaw 3.8+ ContextEngine API
+
+本插件利用 OpenClaw 3.8 的 **ContextEngine API** 实现精细的生命周期控制：
+
+| 生命周期钩子 | 调用时机 | 插件行为 |
+|----------------|-------------|------------------|
+| `bootstrap()` | 会话开始 | 健康检查，初始化状态 |
+| `assemble()` | 每次 agent 轮次前 | 检索相关记忆，注入上下文 |
+| `afterTurn()` | 每次 agent 轮次后 | 保存新消息到 EverMemOS |
+| `compact()` | 超出 token 预算时 | 评估压缩需求 |
+| `dispose()` | 会话结束时 | 清理会话状态 |
+
+### 与传统记忆插件的差异
+
+| 传统记忆钩子 | ContextEngine API |
+|--------------------|-------------------|
+| 简单存储/检索 | 全生命周期管理 |
+| 自动时机 | 可控时机 |
+| 有限的上下文控制 | 查询感知组装 |
+
+---
+
+## 生命周期流程
+
+```
+┌──────────────┐
+│  bootstrap() │ → 健康检查，初始化会话状态
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐     ┌──────────────────┐
+│  assemble()   │ ── │ 记忆搜索         │ → 注入上下文作为系统消息
+│  (每轮)       │     │ GET /memories/   │
+└──────┬───────┘     │ search           │
+       │             └──────────────────┘
+       ▼
+┌──────────────────┐
+│  [Agent 轮次]    │
+└──────┬───────────┘
+       │
+       ▼
+┌──────────────┐     ┌──────────────────┐
+│ afterTurn()   │ ── │ 保存记忆         │ → POST /memories
+│  (每轮)       │     │ 边界检测         │
+└──────┬───────┘     └──────────────────┘
+       │
+       ▼
+┌──────────────┐
+│  compact()   │ → 评估是否需要压缩
+└──────────────┘
+```
+
+---
+
+## 故障排查
+
+### 插件未加载
+
+**症状**: 插件未出现在 OpenClaw 日志中
+
+**解决方案**:
+1. 检查 `plugins.allow` 是否包含 `"evermemos-openclaw-plugin"`
+2. 确认 `plugins.load.paths` 包含正确的插件目录
+3. 检查 `plugins.entries.evermemos-openclaw-plugin.enabled` 是否为 `true`
+
+### 后端连接失败
+
+**症状**: `bootstrap: backend unhealthy` 或超时错误
+
+**解决方案**:
+1. 验证 EverMemOS 后端是否运行: `curl http://localhost:1995/health`
+2. 检查 `baseUrl` 配置是否与后端 URL 匹配
+3. 检查防火墙/网络设置
+
+### 记忆未被保存
+
+**症状**: 后端日志中没有记忆提取记录
+
+**解决方案**:
+1. 验证 `plugins.slots.contextEngine` 设置为 `"evermemos-openclaw-plugin"`
+2. 发送更多消息 - EverMemOS 使用边界检测，需要足够的上下文
+3. 检查后端日志中的 `[Boundary Detection]` 消息
+
+### 记忆未被检索
+
+**症状**: Agent 无法回忆之前的信息
+
+**解决方案**:
+1. 验证记忆已被提取（检查后端日志中的 "Successfully extracted MemCell"）
+2. 检查查询长度是否 ≥ 3 个字符
+3. 增大 `topK` 值以检索更多记忆
+4. 尝试不同的 `retrieveMethod`（如 `hybrid` 或 `agentic`）
+
+### 向量服务错误
+
+**症状**: `VllmVectorizeService API error: 502`
+
+**解决方案**: 这是正常现象 - EverMemOS 会自动回退到备用嵌入服务。记忆提取继续正常工作。
+
+---
+
+## 项目结构
+
+```
+├── index.js                  # ContextEngine 工厂及主入口
+├── package.json
+├── openclaw.plugin.json      # 插件元数据 (kind: context-engine)
+├── README.md                 # 英文文档
+├── README.zh.md              # 中文文档
+└── src/
+    ├── config.js             # 配置解析
+    ├── memory-api.js         # EverMemOS REST API 客户端
+    ├── formatter.js          # 记忆响应解析与格式化
+    ├── message-utils.js      # 消息收集与格式转换
+    ├── http-client.js        # HTTP 客户端（超时与重试）
+    ├── types.js              # JSDoc 类型定义
+    ├── assembler.js          # 查询感知上下文组装
+    ├── lifecycle.js          # 轮次级提取钩子
+    ├── compaction.js         # 压缩评估逻辑
+    ├── subagent.js           # 子代理生命周期跟踪
+    └── context-engine.js     # 核心 ContextEngine 实现
+```
+
+---
+
+## 相关链接
+
+- [EverMemOS](https://github.com/EverMind-AI/EverMemOS) - 后端记忆系统
+- [OpenClaw](https://github.com/openclaw-org/openclaw) - Agent 框架
+- [English Documentation](README.md) - 英文文档
+
+---
+
+## 许可证
+
+Apache-2.0