@t0ken.ai/memoryx-openclaw-plugin 1.0.3 → 1.0.6

package/README.md

@@ -1,35 +1,128 @@
 # MemoryX OpenClaw Plugin
 
-Real-time memory capture and recall plugin for OpenClaw.
+Official MemoryX plugin for OpenClaw. Enables long-term memory for agents by recalling context before execution and saving conversations after each run.
 
 ## Features
 
-- **Conversation Buffer**: Automatically buffers conversations with token counting
+- **Recall**: `before_agent_start` → semantic search for relevant memories
+- **Add**: `message_received` + `assistant_response` → buffer and flush to MemoryX API
 - **Auto Registration**: Agents auto-register with machine fingerprint
-- **Memory Recall**: Semantic search for relevant memories
-- **Configurable API**: Custom API base URL support
+- **Conversation Buffer**: Smart buffering with token counting and round-based flushing
 
-## Installation
+## Install
+
+### Option A — NPM (Recommended)
+
+```bash
+openclaw plugins install @t0ken.ai/memoryx-openclaw-plugin
+openclaw gateway restart
+```
+
+Make sure it's enabled in `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "@t0ken.ai/memoryx-openclaw-plugin": { "enabled": true }
+    }
+  }
+}
+```
+
+### Option B — GitHub
 
 ```bash
-npm install @t0ken.ai/memoryx-openclaw-plugin
+openclaw plugins install github:t0ken-ai/MemoryX#plugins/memoryx-realtime-plugin
+openclaw gateway restart
+```
+
+### Option C — Local path
+
+Copy this folder into an OpenClaw plugin path (e.g. `~/.openclaw/extensions/`) or use `plugins.load.paths` to point at it.
+
+Example `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "memoryx-openclaw-plugin": { "enabled": true }
+    },
+    "load": { "paths": ["/path/to/memoryx-openclaw-plugin"] }
+  }
+}
 ```
 
+Restart the gateway after config changes.
+
 ## Configuration
 
+### Plugin Config
+
+In `plugins.entries.memoryx-openclaw-plugin.config`:
+
 ```json
 {
   "apiBaseUrl": "https://t0ken.ai/api"
 }
 ```
 
-## Usage
+For self-hosted MemoryX:
+
+```json
+{
+  "apiBaseUrl": "http://192.168.31.65:8000/api"
+}
+```
+
+### Environment Variables
+
+The plugin stores credentials locally in `~/.t0ken/memoryx.sqlite`.
+
+## How it Works
+
+### Recall (`before_agent_start`)
+
+- Builds a `/v1/memories/search` request using the current prompt
+- Injects relevant memories via `prependContext`:
+  ```
+  [相关记忆]
+  - [preference] User prefers dark mode
+  - [fact] User's timezone is UTC+8
+  [End of memories]
+  ```
+
+### Add (`message_received` + `assistant_response`)
+
+- Buffers messages with precise token counting (tiktoken)
+- Flushes to `/v1/conversations/flush` when:
+  - 2 conversation rounds completed (user + assistant = 1 round)
+  - 30 minutes timeout
+- Server extracts entities, facts, and preferences automatically
+
+### Auto Registration
+
+On first run, the plugin:
+1. Generates a machine fingerprint
+2. Calls `/agents/auto-register` to get API key
+3. Stores credentials locally for future sessions
+
+## Memory Categories
+
+Memories are categorized by the server:
+- **preference**: User preferences and settings
+- **fact**: Factual information about the user
+- **plan**: Future plans and goals
+- **experience**: Past experiences
+- **opinion**: User opinions and views
+
+## Notes
 
-The plugin automatically:
-1. Captures user and assistant messages
-2. Buffers conversations until threshold (2 rounds)
-3. Flushes to MemoryX API for memory extraction
-4. Recalls relevant memories before agent starts
+- Conversation buffer uses `cl100k_base` encoding (GPT-4 compatible)
+- Maximum 8000 tokens per message
+- Minimum 2 characters per message
+- Short messages like "ok", "thanks" are skipped
 
 ## License
 

package/dist/index.d.ts

@@ -93,10 +93,13 @@ declare class MemoryXPlugin {
         };
     };
 }
-export declare function onMessage(message: string, context: Record<string, any>): Promise<{
-    context: Record<string, any>;
-}>;
-export declare function onResponse(response: string, context: Record<string, any>): string;
-export declare function register(api: any, pluginConfig?: PluginConfig): void;
+declare const _default: {
+    id: string;
+    name: string;
+    version: string;
+    description: string;
+    register(api: any, pluginConfig?: PluginConfig): void;
+};
+export default _default;
 export { MemoryXPlugin, ConversationBuffer };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAWH,UAAU,YAAY;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAUD,UAAU,OAAO;IACb,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACrB;AAED,UAAU,YAAY;IAClB,QAAQ,EAAE,KAAK,CAAC;QACZ,EAAE,EAAE,MAAM,CAAC;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;KACjB,CAAC,CAAC;IACH,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,cAAM,kBAAkB;IACpB,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,QAAQ,CAAc;IAC9B,OAAO,CAAC,cAAc,CAAc;IACpC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,cAAc,CAAsB;IAC5C,OAAO,CAAC,OAAO,CAAW;IAE1B,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAK;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAQ;;IAO/C,OAAO,CAAC,UAAU;IAIlB,OAAO,CAAC,WAAW;IAInB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IA6BlD,WAAW,IAAI,OAAO;IAiBtB,KAAK,IAAI;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE;IAkB/E,UAAU,IAAI;QAAE,eAAe,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,EAAE,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAO3F,SAAS,IAAI;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAA;KAAE;CAOpF;AAED,cAAM,aAAa;IACf,OAAO,CAAC,MAAM,CAMZ;IAEF,OAAO,CAAC,MAAM,CAAgD;IAC9D,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,YAAY,CAA6B;gBAErC,YAAY,CAAC,EAAE,YAAY;IAQvC,OAAO,KAAK,OAAO,GAElB;YAEa,IAAI;YAWJ,UAAU;IAgBxB,OAAO,CAAC,UAAU;YAQJ,YAAY;YAgCZ,qBAAqB;IAkBnC,OAAO,CAAC,eAAe;YAQT,iBAAiB;IAqClB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAyB1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IAoD/D,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAKtC,SAAS,IAAI;QAChB,WAAW,EAAE,OAAO,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;QACnB,YAAY,EAAE;YAAE,YAAY,EAAE,MAAM,CAAC;YAAC,UAAU,EAAE,MAAM,CAAA;SAAE,CAAA;KAC7D;CAOJ;;;;;;kBAUiB,GAAG,iBAAiB,YAAY,GAAG,IAAI;;AANzD,wBAwEE;AAEF,OAAO,EAAE,aAAa,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/index.js

@@ -320,64 +320,65 @@ class MemoryXPlugin {
     }
 }
 let plugin;
-export async function onMessage(message, context) {
-    if (message && plugin) {
-        await plugin.onMessage("user", message);
-    }
-    return { context };
-}
-export function onResponse(response, context) {
-    return response;
-}
-export function register(api, pluginConfig) {
-    api.logger.info("[MemoryX] Plugin registering (Phase 1 - Cloud with Buffer)...");
-    if (pluginConfig?.apiBaseUrl) {
-        api.logger.info(`[MemoryX] Using custom API base URL: ${pluginConfig.apiBaseUrl}`);
-    }
-    plugin = new MemoryXPlugin(pluginConfig);
-    api.on("message_received", async (event, ctx) => {
-        const { content, from, timestamp } = event;
-        if (content && plugin) {
-            await plugin.onMessage("user", content);
+export default {
+    id: "@t0ken.ai/memoryx-openclaw-plugin",
+    name: "MemoryX Real-time Plugin",
+    version: "1.0.6",
+    description: "Real-time memory capture and recall for OpenClaw",
+    register(api, pluginConfig) {
+        api.logger.info("[MemoryX] Plugin registering...");
+        if (pluginConfig?.apiBaseUrl) {
+            api.logger.info(`[MemoryX] API Base: \`${pluginConfig.apiBaseUrl}\``);
         }
-    });
-    api.on("assistant_response", async (event, ctx) => {
-        const { content } = event;
-        if (content && plugin) {
-            await plugin.onMessage("assistant", content);
+        const storedConfig = localStorage.getItem("memoryx_config");
+        if (storedConfig) {
+            api.logger.info(`[MemoryX] Database: ${storedConfig.split('"apiBaseUrl"')[0].match(/"([^"]+)"/)?.[1] || 'unknown'}`);
         }
-    });
-    api.on("before_agent_start", async (event, ctx) => {
-        const { prompt } = event;
-        if (!prompt || prompt.length < 2 || !plugin)
-            return;
-        try {
-            const result = await plugin.recall(prompt, 5);
-            if (result.isLimited) {
-                api.logger.warn(`[MemoryX] ${result.upgradeHint}`);
+        plugin = new MemoryXPlugin(pluginConfig);
+        api.on("message_received", async (event, ctx) => {
+            const { content, from, timestamp } = event;
+            if (content && plugin) {
+                await plugin.onMessage("user", content);
+            }
+        });
+        api.on("assistant_response", async (event, ctx) => {
+            const { content } = event;
+            if (content && plugin) {
+                await plugin.onMessage("assistant", content);
+            }
+        });
+        api.on("before_agent_start", async (event, ctx) => {
+            const { prompt } = event;
+            if (!prompt || prompt.length < 2 || !plugin)
+                return;
+            try {
+                const result = await plugin.recall(prompt, 5);
+                if (result.isLimited) {
+                    api.logger.warn(`[MemoryX] ${result.upgradeHint}`);
+                    return {
+                        prependContext: `[系统提示] ${result.upgradeHint}\n`
+                    };
+                }
+                if (result.memories.length === 0)
+                    return;
+                const memories = result.memories
+                    .map(m => `- [${m.category}] ${m.content}`)
+                    .join("\n");
+                api.logger.info(`[MemoryX] Recalled ${result.memories.length} memories from cloud`);
                 return {
-                    prependContext: `[系统提示] ${result.upgradeHint}\n`
+                    prependContext: `[相关记忆]\n${memories}\n[End of memories]\n`
                 };
             }
-            if (result.memories.length === 0)
-                return;
-            const memories = result.memories
-                .map(m => `- [${m.category}] ${m.content}`)
-                .join("\n");
-            api.logger.info(`[MemoryX] Recalled ${result.memories.length} memories from cloud`);
-            return {
-                prependContext: `[相关记忆]\n${memories}\n[End of memories]\n`
-            };
-        }
-        catch (error) {
-            api.logger.warn(`[MemoryX] Recall failed: ${error}`);
-        }
-    });
-    api.on("conversation_end", async (event, ctx) => {
-        if (plugin) {
-            await plugin.endConversation();
-        }
-    });
-    api.logger.info("[MemoryX] Plugin registered successfully");
-}
+            catch (error) {
+                api.logger.warn(`[MemoryX] Recall failed: ${error}`);
+            }
+        });
+        api.on("conversation_end", async (event, ctx) => {
+            if (plugin) {
+                await plugin.endConversation();
+            }
+        });
+        api.logger.info("[MemoryX] Plugin registered successfully");
+    }
+};
 export { MemoryXPlugin, ConversationBuffer };

package/openclaw.plugin.json

@@ -1,16 +1,18 @@
 {
   "id": "@t0ken.ai/memoryx-openclaw-plugin",
   "name": "MemoryX Real-time Plugin",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "description": "Real-time memory capture and recall for OpenClaw",
-  "entry": "./dist/index.js",
   "kind": "memory",
+  "main": "./dist/index.js",
   "configSchema": {
     "type": "object",
     "properties": {
       "apiBaseUrl": {
-        "type": "string"
+        "type": "string",
+        "description": "MemoryX API base URL (default: https://t0ken.ai/api)"
       }
-    }
+    },
+    "additionalProperties": false
   }
 }

package/package.json

@@ -1,18 +1,18 @@
 {
   "name": "@t0ken.ai/memoryx-openclaw-plugin",
-  "version": "1.0.3",
+  "version": "1.0.6",
   "description": "MemoryX real-time memory capture and recall plugin for OpenClaw",
   "type": "module",
-  "main": "dist/index.js",
-  "types": "dist/index.d.ts",
+  "author": "MemoryX Team",
+  "license": "MIT",
+  "main": "./dist/index.js",
   "files": [
     "dist",
     "openclaw.plugin.json",
     "README.md"
   ],
   "scripts": {
-    "build": "tsc",
-    "prepare": "npm run build"
+    "build": "tsc"
   },
   "keywords": [
     "openclaw",
@@ -20,17 +20,13 @@
     "memory",
     "plugin"
   ],
-  "author": "MemoryX Team",
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/t0ken-ai/MemoryX.git",
     "directory": "plugins/memoryx-realtime-plugin"
   },
   "openclaw": {
-    "extensions": [
-      "./dist/index.js"
-    ]
+    "extensions": ["./dist/index.js"]
   },
   "devDependencies": {
     "@types/node": "^20.0.0",