@evermind-ai/openclaw-plugin 1.1.0 → 1.3.0

package/README.md

@@ -1,152 +1,115 @@
-# EverMemOS ContextEngine Plugin for OpenClaw
+# EverOS OpenClaw Plugin
 
-Full-lifecycle memory management for **OpenClaw 3.8+** via [EverMemOS](https://github.com/EverMind-AI/EverMemOS).
+Persistent memory for **OpenClaw** through normal conversation.
 
-> **Built for OpenClaw 3.8+ ContextEngine API** - Leverages the latest ContextEngine lifecycle hooks for intelligent memory management.
+This plugin keeps the current OpenClaw `context-engine` architecture and connects it to a self-hosted EverOS backend powered by [EverMemOS](https://github.com/EverMind-AI/EverMemOS).
 
----
+## What it does
 
-## Features
+- Recalls relevant memory before each reply through `assemble()`
+- Saves new conversation content after each turn through `afterTurn()`
+- Works through normal natural-language chat
+- Does not require manual `memory_store` or `memory_search` tool calls
 
-- **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
+Important:
 
----
+- This is a `context-engine` plugin
+- This is not a `memory` slot plugin like official `mem9`
+- To avoid conflicts, installation sets `plugins.slots.memory = "none"`
 
-## Quick Start
+## 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
+Recommended install:
 
 ```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
+npx --yes --package @evermind-ai/openclaw-plugin everos-install
+```
 
-# Install uv package manager
-curl -LsSf https://astral.sh/uv/install.sh | sh
+The installer:
 
-# Install Python dependencies
-uv sync
+- reuses `~/.openclaw/openclaw.json` if it already exists
+- adds the plugin path to `plugins.load.paths`
+- adds `@evermind-ai/openclaw-plugin` to `plugins.allow`
+- sets `plugins.slots.contextEngine = "@evermind-ai/openclaw-plugin"`
+- sets `plugins.slots.memory = "none"`
+- creates or updates the plugin entry with sane defaults
 
-# Configure API keys
-cp env.template .env
-# Edit .env and set your LLM_API_KEY and VECTORIZE_API_KEY
+After install:
 
-# Start the backend server (default: http://localhost:1995)
-uv run python src/run.py
+```bash
+openclaw gateway restart
 ```
 
-### Verify Backend
+Then verify with natural language:
 
-```bash
-curl http://localhost:1995/health
-# Expected response: {"status": "healthy", ...}
+```text
+Remember: I like espresso.
+What coffee do I like?
 ```
 
-> **For detailed EverMemOS setup**, see the [Official Setup Guide](https://github.com/EverMind-AI/EverMemOS/blob/main/docs/installation/SETUP.md)
+## Backend
 
----
+Default backend URL:
 
-## Step 2: Install the Plugin
+```text
+http://localhost:1995
+```
 
-### Option A: Local Development (Recommended)
+Health check:
 
 ```bash
-# Clone this repository
-git clone https://github.com/EverMind-AI/evermemos-openclaw-plugin.git
-cd evermemos-openclaw-plugin
-
-# Install dependencies
-npm install
+curl http://localhost:1995/health
 ```
 
-### Option B: Via npm
+If you have not started the EverOS backend yet:
 
 ```bash
-npm install @evermind-ai/openclaw-plugin
+git clone https://github.com/EverMind-AI/EverMemOS.git
+cd EverMemOS
+docker compose up -d
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv sync
+cp env.template .env
+# edit .env
+uv run python src/run.py
 ```
 
----
+## How natural-language memory works
 
-## Step 3: Configure OpenClaw
+Runtime flow:
 
-Edit `~/.openclaw/openclaw.json`:
+1. The user sends a normal message.
+2. `assemble()` searches the EverOS backend for relevant memory.
+3. Matching memory is injected as context.
+4. OpenClaw replies normally.
+5. `afterTurn()` saves the new turn back to the EverOS backend.
 
-### 3.1 Add Plugin Path
+This means the user experience is:
 
-```json
-{
-  "plugins": {
-    "load": {
-      "paths": [
-        "/path/to/openclaw/extensions/feishu",
-        "/path/to/openclaw/extensions/memory-openviking",
-        "/Users/admin/EverMind/evermemos-openclaw-plugin"  // Add this line
-      ]
-    }
-  }
-}
-```
+- "Remember: I prefer dark mode"
+- later: "What UI style do I prefer?"
 
-### 3.2 Enable the Plugin
+without any explicit memory tool usage.
 
-```json
-{
-  "plugins": {
-    "allow": [
-      "memory-openviking",
-      "feishu",
-      "mem9",
-      "evermemos-openclaw-plugin"  // Add this line
-    ]
-  }
-}
-```
+## OpenClaw config
 
-### 3.3 Set ContextEngine Slot (OpenClaw 3.8+)
+Expected config shape:
 
 ```json
 {
   "plugins": {
+    "allow": ["@evermind-ai/openclaw-plugin"],
     "slots": {
       "memory": "none",
-      "contextEngine": "evermemos-openclaw-plugin"  // Use EverMemOS ContextEngine
-    }
-  }
-}
-```
-
-### 3.4 Add Plugin Configuration
-
-```json
-{
-  "plugins": {
+      "contextEngine": "@evermind-ai/openclaw-plugin"
+    },
     "entries": {
-      "evermemos-openclaw-plugin": {
+      "@evermind-ai/openclaw-plugin": {
         "enabled": true,
         "config": {
           "baseUrl": "http://localhost:1995",
-          "userId": "evermemos-user",
-          "groupId": "evermemos-group",
+          "userId": "everos-user",
+          "groupId": "everos-group",
           "topK": 5,
           "memoryTypes": ["episodic_memory", "profile", "agent_skill", "agent_case"],
           "retrieveMethod": "hybrid"
@@ -157,243 +120,50 @@ Edit `~/.openclaw/openclaw.json`:
 }
 ```
 
----
-
-## 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
+| Field | Default | Description |
+| --- | --- | --- |
+| `baseUrl` | `http://localhost:1995` | EverOS backend URL |
+| `userId` | `everos-user` | Memory owner identity |
+| `groupId` | `everos-group` | Shared memory namespace |
+| `topK` | `5` | Max retrieved entries |
+| `memoryTypes` | `["episodic_memory", "profile", "agent_skill", "agent_case"]` | Memory types to search |
+| `retrieveMethod` | `hybrid` | Retrieval mode |
 
-| Value | Description |
-|-------|-------------|
-| `keyword` | Full-text keyword search |
-| `vector` | Semantic vector search |
-| `hybrid` | Keyword + vector fusion |
-| `rrf` | Reciprocal Rank Fusion |
-| `agentic` | Agent-driven adaptive retrieval |
+## Manual install
 
----
-
-## 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        │
-└─────────────────────────────────────────────────────────────────┘
+```bash
+npm install -g @evermind-ai/openclaw-plugin
+everos-install
 ```
 
----
-
-## 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
+Or from a local checkout:
 
+```bash
+git clone https://github.com/EverMind-AI/evermemos-openclaw-plugin.git
+cd evermemos-openclaw-plugin
+npm install
+node ./bin/install.js
 ```
-┌──────────────┐
-│  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
-
----
+| Problem | Fix |
+| --- | --- |
+| Plugin not loading | Check `plugins.allow`, `plugins.load.paths`, and `plugins.slots.contextEngine` |
+| Backend connection failed | Verify `baseUrl` and run `curl <baseUrl>/health` |
+| Memory not recalled | Check backend data and try a more specific query |
+| Memory not saved | Verify the EverOS backend write API is healthy |
+| Conflict with another memory plugin | Ensure `plugins.slots.memory = "none"` |
+
+## Related files
+
+- `index.js`: ContextEngine registration and lifecycle hooks
+- `bin/install.js`: installer and config bootstrap
+- `src/memory-api.js`: EverOS backend REST client
+- `src/message-utils.js`: message normalization and turn collection
+- `openclaw.plugin.json`: plugin metadata and config schema
 
 ## License