@evermind-ai/openclaw-plugin 1.1.0

package/README.md

@@ -0,0 +1,400 @@
+# EverMemOS ContextEngine Plugin for OpenClaw
+
+Full-lifecycle memory management for **OpenClaw 3.8+** via [EverMemOS](https://github.com/EverMind-AI/EverMemOS).
+
+> **Built for OpenClaw 3.8+ ContextEngine API** - Leverages the latest ContextEngine lifecycle hooks for intelligent memory management.
+
+---
+
+## Features
+
+- **Bootstrap**: Backend health check on plugin load
+- **Assemble**: Query-aware context retrieval before each agent turn
+- **AfterTurn**: Timely memory extraction after each turn (not just session end)
+- **Compact**: Session compaction participation for context window optimization
+- **Boundary Detection**: Smart memory extraction via EverMemOS's boundary detection algorithm
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| **Node.js** | 18+ | For the plugin |
+| **Python** | 3.10+ | For EverMemOS backend |
+| **Docker** | 20.10+ | For infrastructure services |
+| **OpenClaw** | 3.8+ | With ContextEngine support |
+
+---
+
+## Step 1: Install EverMemOS Backend
+
+### Clone and Setup
+
+```bash
+# Clone EverMemOS repository
+git clone https://github.com/EverMind-AI/EverMemOS.git
+cd EverMemOS
+
+# Start Docker services (MongoDB, Elasticsearch, Milvus, Redis)
+docker compose up -d
+
+# Install uv package manager
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Install Python dependencies
+uv sync
+
+# Configure API keys
+cp env.template .env
+# Edit .env and set your LLM_API_KEY and VECTORIZE_API_KEY
+
+# Start the backend server (default: http://localhost:1995)
+uv run python src/run.py
+```
+
+### Verify Backend
+
+```bash
+curl http://localhost:1995/health
+# Expected response: {"status": "healthy", ...}
+```
+
+> **For detailed EverMemOS setup**, see the [Official Setup Guide](https://github.com/EverMind-AI/EverMemOS/blob/main/docs/installation/SETUP.md)
+
+---
+
+## Step 2: Install the Plugin
+
+### Option A: Local Development (Recommended)
+
+```bash
+# Clone this repository
+git clone https://github.com/EverMind-AI/evermemos-openclaw-plugin.git
+cd evermemos-openclaw-plugin
+
+# Install dependencies
+npm install
+```
+
+### Option B: Via npm
+
+```bash
+npm install @evermind-ai/openclaw-plugin
+```
+
+---
+
+## Step 3: Configure OpenClaw
+
+Edit `~/.openclaw/openclaw.json`:
+
+### 3.1 Add Plugin Path
+
+```json
+{
+  "plugins": {
+    "load": {
+      "paths": [
+        "/path/to/openclaw/extensions/feishu",
+        "/path/to/openclaw/extensions/memory-openviking",
+        "/Users/admin/EverMind/evermemos-openclaw-plugin"  // Add this line
+      ]
+    }
+  }
+}
+```
+
+### 3.2 Enable the Plugin
+
+```json
+{
+  "plugins": {
+    "allow": [
+      "memory-openviking",
+      "feishu",
+      "mem9",
+      "evermemos-openclaw-plugin"  // Add this line
+    ]
+  }
+}
+```
+
+### 3.3 Set ContextEngine Slot (OpenClaw 3.8+)
+
+```json
+{
+  "plugins": {
+    "slots": {
+      "memory": "none",
+      "contextEngine": "evermemos-openclaw-plugin"  // Use EverMemOS ContextEngine
+    }
+  }
+}
+```
+
+### 3.4 Add Plugin Configuration
+
+```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"
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Step 4: Restart OpenClaw
+
+```bash
+openclaw gateway restart
+```
+
+---
+
+## Step 5: Verify Installation
+
+Check the OpenClaw logs for successful plugin loading:
+
+```
+[evermemos] Registering EverMemOS ContextEngine plugin
+[evermemos] bootstrap: session=xxx, key=xxx
+[evermemos] bootstrap: backend healthy, status=ok
+```
+
+---
+
+## Testing
+
+### Test Memory Storage
+
+Send a message to your agent:
+```
+记住：我最喜欢的颜色是蓝色
+```
+
+### Test Memory Retrieval
+
+Later in the conversation, ask:
+```
+我最喜欢什么颜色？
+```
+
+The agent should recall the information from EverMemOS.
+
+---
+
+## Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `baseUrl` | string | `http://localhost:1995` | EverMemOS server URL |
+| `userId` | string | `evermemos-user` | User identity for memory ownership |
+| `groupId` | string | `evermemos-group` | Group ID for shared memory |
+| `topK` | integer | `5` | Max memory entries to retrieve |
+| `memoryTypes` | string[] | See below | Memory types to search |
+| `retrieveMethod` | string | `hybrid` | Retrieval strategy |
+
+### Memory Types
+
+| Value | Description |
+|-------|-------------|
+| `episodic_memory` | Past conversation episodes |
+| `profile` | User profile and preferences |
+| `agent_case` | Similar historical cases |
+| `agent_skill` | Agent skill knowledge |
+
+### Retrieval Strategies
+
+| Value | Description |
+|-------|-------------|
+| `keyword` | Full-text keyword search |
+| `vector` | Semantic vector search |
+| `hybrid` | Keyword + vector fusion |
+| `rrf` | Reciprocal Rank Fusion |
+| `agentic` | Agent-driven adaptive retrieval |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         OpenClaw Core                            │
+│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────────────┐ │
+│  │   Message   │  │    Session   │  │   Token Budget Mgmt     │ │
+│  │    Flow     │  │  Management  │  │   (Compaction)          │ │
+│  └──────┬──────┘  └──────┬───────┘  └──────────┬──────────────┘ │
+└─────────┼────────────────┼─────────────────────┼────────────────┘
+          │                │                     │
+          ▼                ▼                     ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    EverMemOS ContextEngine                       │
+│  ┌─────────┐  ┌─────────┐  ┌──────────┐  ┌──────────────────┐   │
+│  │bootstrap│  │ ingest  │  │afterTurn │  │     assemble     │   │
+│  └────┬────┘  └────┬────┘  └────┬─────┘  └────────┬─────────┘   │
+└───────┼─────────────┼─────────────┼─────────────────┼─────────────┘
+        │             │             │                 │
+        ▼             ▼             ▼                 ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      EverMemOS Backend                           │
+│                    http://localhost:1995                         │
+│                                                                 │
+│  • Boundary Detection  • Memory Extraction  • Vector Search    │
+│  • Profile Building    • Clustering         • Foresight        │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## OpenClaw 3.8+ ContextEngine API
+
+This plugin leverages OpenClaw 3.8's **ContextEngine API** for fine-grained lifecycle control:
+
+| Lifecycle Hook | When Called | What Plugin Does |
+|----------------|-------------|------------------|
+| `bootstrap()` | Session starts | Health check, initialize state |
+| `assemble()` | Before each agent turn | Retrieve relevant memories, inject as context |
+| `afterTurn()` | After each agent turn | Save new messages to EverMemOS |
+| `compact()` | When token budget exceeded | Evaluate compaction needs |
+| `dispose()` | Session ends | Clean up session state |
+
+### Difference from Legacy Memory Plugins
+
+| Legacy Memory Hook | ContextEngine API |
+|--------------------|-------------------|
+| Simple storage/retrieval | Full lifecycle management |
+| Automatic timing | Controlled timing |
+| Limited context control | Query-aware assembly |
+
+---
+
+## Lifecycle Flow
+
+```
+┌──────────────┐
+│  bootstrap() │ → Health check, initialize session state
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐     ┌──────────────────┐
+│  assemble()   │ ── │ Memory Search    │ → Inject context as system message
+│  (each turn)  │     │ GET /memories/   │
+└──────┬───────┘     │ search           │
+       │             └──────────────────┘
+       ▼
+┌──────────────────┐
+│  [Agent Turn]    │
+└──────┬───────────┘
+       │
+       ▼
+┌──────────────┐     ┌──────────────────┐
+│ afterTurn()   │ ── │ Save Memories    │ → POST /memories
+│  (each turn)  │     │ Boundary Detect  │
+└──────┬───────┘     └──────────────────┘
+       │
+       ▼
+┌──────────────┐
+│  compact()   │ → Evaluate if compaction needed
+└──────────────┘
+```
+
+---
+
+## Troubleshooting
+
+### Plugin not loading
+
+**Symptom**: Plugin not showing in OpenClaw logs
+
+**Solution**:
+1. Check `plugins.allow` contains `"evermemos-openclaw-plugin"`
+2. Verify `plugins.load.paths` contains the correct plugin directory
+3. Check `plugins.entries.evermemos-openclaw-plugin.enabled` is `true`
+
+### Backend connection failed
+
+**Symptom**: `bootstrap: backend unhealthy` or timeout errors
+
+**Solution**:
+1. Verify EverMemOS backend is running: `curl http://localhost:1995/health`
+2. Check `baseUrl` configuration matches backend URL
+3. Check firewall/network settings
+
+### Memories not being saved
+
+**Symptom**: No memory extraction in backend logs
+
+**Solution**:
+1. Verify `plugins.slots.contextEngine` is set to `"evermemos-openclaw-plugin"`
+2. Send more messages - EverMemOS uses boundary detection and needs sufficient context
+3. Check backend logs for `[Boundary Detection]` messages
+
+### Memories not being retrieved
+
+**Symptom**: Agent doesn't recall previous information
+
+**Solution**:
+1. Verify memories were extracted (check backend logs for "Successfully extracted MemCell")
+2. Check query length is ≥ 3 characters
+3. Increase `topK` value to retrieve more memories
+4. Try different `retrieveMethod` (e.g., `hybrid` or `agentic`)
+
+### Vector service errors
+
+**Symptom**: `VllmVectorizeService API error: 502`
+
+**Solution**: This is normal - EverMemOS automatically falls back to alternative embedding services. Memory extraction continues working.
+
+---
+
+## Project Structure
+
+```
+├── index.js                  # ContextEngine factory & main entry
+├── package.json
+├── openclaw.plugin.json      # Plugin metadata (kind: context-engine)
+├── README.md                 # English documentation
+├── README.zh.md              # Chinese documentation
+└── src/
+    ├── config.js             # Configuration parsing
+    ├── memory-api.js         # EverMemOS REST API client
+    ├── formatter.js          # Memory response parsing & formatting
+    ├── message-utils.js      # Message collection & format conversion
+    ├── http-client.js        # HTTP client with timeout & retry
+    ├── types.js              # JSDoc type definitions
+    ├── assembler.js          # Query-aware context assembly
+    ├── lifecycle.js          # Turn-level ingestion hooks
+    ├── compaction.js         # Compaction evaluation logic
+    ├── subagent.js           # Subagent lifecycle tracking
+    └── context-engine.js     # Core ContextEngine implementation
+```
+
+---
+
+## Links
+
+- [EverMemOS](https://github.com/EverMind-AI/EverMemOS) - Backend memory system
+- [OpenClaw](https://github.com/openclaw-org/openclaw) - Agent framework
+- [中文文档](README.zh.md) - Chinese documentation
+
+---
+
+## License
+
+Apache-2.0