@t0ken.ai/memoryx-openclaw-plugin 1.1.15 → 1.1.17

package/README.md

@@ -4,11 +4,44 @@ Official MemoryX plugin for OpenClaw. Enables long-term memory for agents by rec
 
 ## Features
 
-- **Recall**: `before_agent_start` → semantic search for relevant memories
-- **Add**: `message_received` + `assistant_response` → buffer and flush to MemoryX API
+- **Auto Recall**: `before_agent_start` → semantic search for relevant memories
+- **Auto Capture**: `message_received` + `assistant_response` → buffer and flush to MemoryX API
+- **Function Calling**: LLM can actively search, list, and delete memories
 - **Auto Registration**: Agents auto-register with machine fingerprint
 - **Conversation Buffer**: Smart buffering with token counting and round-based flushing
 
+## Function Calling Tools
+
+The plugin registers three tools that LLM can call during conversations:
+
+| Tool | Description | When to Use |
+|------|-------------|-------------|
+| `memoryx_recall` | Search through long-term memories | User asks "do you remember X?" or needs context |
+| `memoryx_store` | Save important information to memory | User says "remember this" or you identify important info |
+| `memoryx_list` | List all stored memories | User asks "what do you remember about me?" |
+| `memoryx_forget` | Delete a specific memory | User asks to forget/remove something |
+
+### memoryx_store Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `content` | string | Yes | The information to remember (e.g., "User prefers dark mode") |
+| `category` | enum | No | `preference`, `fact`, `plan`, `experience`, `opinion`, `other` |
+
+### Example Usage
+
+**User**: "What do you remember about my preferences?"
+**LLM**: *calls `memoryx_list`* → Returns list of stored memories
+
+**User**: "Did I ever mention my favorite color?"
+**LLM**: *calls `memoryx_recall` with query="favorite color"* → Searches and returns relevant memories
+
+**User**: "Please forget about my old address"
+**LLM**: *calls `memoryx_forget` with memory_id* → Deletes the memory
+
+**User**: "Remember that my favorite color is blue"
+**LLM**: *calls `memoryx_store` with content="User's favorite color is blue" category="preference"* → Stores the memory
+
 ## Install
 
 ```bash

package/dist/index.d.ts

@@ -81,6 +81,14 @@ declare class MemoryXPlugin {
     onMessage(role: string, content: string): Promise<boolean>;
     recall(query: string, limit?: number): Promise<RecallResult>;
     endConversation(): Promise<void>;
+    forget(memoryId: string): Promise<boolean>;
+    store(content: string, category?: string): Promise<{
+        success: boolean;
+        task_id?: string;
+        duplicate?: boolean;
+        existing?: string;
+    }>;
+    list(limit?: number): Promise<any[]>;
     getStatus(): Promise<{
         initialized: boolean;
         hasApiKey: boolean;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAqDH,UAAU,YAAY;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACvB;AAiBD,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,eAAe,EAAE,KAAK,CAAC;QACnB,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;AA0JD,cAAM,mBAAmB;IACrB,OAAO,CAAC,qBAAqB,CAAc;IAC3C,OAAO,CAAC,qBAAqB,CAAyC;IACtE,OAAO,CAAC,cAAc,CAAsB;IAE5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAK;IACrC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;;IAM7C,OAAO,CAAC,UAAU;IAIlB,iBAAiB,IAAI,MAAM;IAIrB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAiB3D,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBrC,oBAAoB,IAAI,IAAI;IAMtB,SAAS,IAAI,OAAO,CAAC;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,cAAc,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAQ/F;AAED,cAAM,aAAa;IACf,OAAO,CAAC,MAAM,CAMZ;IAEF,OAAO,CAAC,mBAAmB,CAAkD;IAC7E,OAAO,CAAC,UAAU,CAAa;IAC/B,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAQ;IAC5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAK;IACrC,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,WAAW,CAAkB;gBAEzB,YAAY,CAAC,EAAE,YAAY;IAQvC,IAAI,IAAI,IAAI;IAmBZ,OAAO,KAAK,OAAO,GAElB;YAEa,UAAU;YAWV,UAAU;YAIV,YAAY;IA+B1B,OAAO,CAAC,qBAAqB;IAa7B,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,mBAAmB;YAMb,gBAAgB;IAiEjB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA2B1D,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAU,GAAG,OAAO,CAAC,YAAY,CAAC;IA6D/D,eAAe,IAAI,OAAO,CAAC,IAAI,CAAC;IAKhC,SAAS,IAAI,OAAO,CAAC;QAC9B,WAAW,EAAE,OAAO,CAAC;QACrB,SAAS,EAAE,OAAO,CAAC;QACnB,kBAAkB,EAAE;YAAE,YAAY,EAAE,MAAM,CAAC;YAAC,cAAc,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KACvF,CAAC;CAQL;;;;;;kBAUiB,GAAG,iBAAiB,YAAY,GAAG,IAAI;;AANzD,wBA6EE;AAEF,OAAO,EAAE,aAAa,EAAE,mBAAmB,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -491,6 +491,99 @@ class MemoryXPlugin {
         this.conversationManager.startNewConversation();
         log("Conversation ended, starting new conversation");
     }
+    async forget(memoryId) {
+        this.init();
+        if (!this.config.apiKey) {
+            log("Forget failed: no API key");
+            return false;
+        }
+        try {
+            const response = await fetch(`${this.apiBase}/v1/memories/${memoryId}`, {
+                method: "DELETE",
+                headers: {
+                    "X-API-Key": this.config.apiKey
+                }
+            });
+            if (response.ok) {
+                log(`Forgot memory ${memoryId}`);
+                return true;
+            }
+            log(`Forget failed: ${response.status}`);
+            return false;
+        }
+        catch (e) {
+            log(`Forget failed: ${e}`);
+            return false;
+        }
+    }
+    async store(content, category = "other") {
+        this.init();
+        if (!this.config.apiKey) {
+            log("Store failed: no API key");
+            return { success: false };
+        }
+        try {
+            const response = await fetch(`${this.apiBase}/v1/memories`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-API-Key": this.config.apiKey
+                },
+                body: JSON.stringify({
+                    content,
+                    project_id: this.config.projectId,
+                    metadata: { category, source: "function_call" }
+                })
+            });
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}));
+                log(`Store failed: ${response.status} ${JSON.stringify(errorData)}`);
+                return { success: false };
+            }
+            const data = await response.json();
+            log(`Stored memory, task_id: ${data.task_id}`);
+            return { success: true, task_id: data.task_id };
+        }
+        catch (e) {
+            log(`Store failed: ${e}`);
+            return { success: false };
+        }
+    }
+    async list(limit = 10) {
+        this.init();
+        if (!this.config.apiKey) {
+            log("List failed: no API key");
+            return [];
+        }
+        try {
+            const response = await fetch(`${this.apiBase}/v1/memories/search`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-API-Key": this.config.apiKey
+                },
+                body: JSON.stringify({
+                    query: "*",
+                    project_id: this.config.projectId,
+                    limit
+                })
+            });
+            if (!response.ok) {
+                log(`List failed: ${response.status}`);
+                return [];
+            }
+            const data = await response.json();
+            return (data.data || []).map((m) => ({
+                id: m.id,
+                content: m.memory || m.content,
+                category: m.category || "other"
+            }));
+        }
+        catch (e) {
+            log(`List failed: ${e}`);
+            return [];
+        }
+    }
     async getStatus() {
         const status = await this.conversationManager.getStatus();
         return {
@@ -504,7 +597,7 @@ let plugin;
 export default {
     id: "memoryx-openclaw-plugin",
     name: "MemoryX Realtime Plugin",
-    version: "1.2.0",
+    version: "1.1.17",
     description: "Real-time memory capture and recall for OpenClaw",
     register(api, pluginConfig) {
         api.logger.info("[MemoryX] Plugin registering...");
@@ -512,6 +605,233 @@ export default {
             api.logger.info(`[MemoryX] API Base: \`${pluginConfig.apiBaseUrl}\``);
         }
         plugin = new MemoryXPlugin(pluginConfig);
+        api.registerTool({
+            name: "memoryx_recall",
+            label: "MemoryX Recall",
+            description: "Search through long-term memories. Use when you need context about user preferences, past decisions, or previously discussed topics.",
+            parameters: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "Search query to find relevant memories"
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Maximum number of results to return (default: 5)"
+                    }
+                },
+                required: ["query"]
+            },
+            async execute(_toolCallId, params) {
+                const { query, limit = 5 } = params;
+                if (!plugin) {
+                    return {
+                        content: [{ type: "text", text: "MemoryX plugin not initialized." }],
+                        details: { error: "not_initialized" }
+                    };
+                }
+                try {
+                    const result = await plugin.recall(query, limit);
+                    if (result.isLimited) {
+                        return {
+                            content: [{ type: "text", text: result.upgradeHint || "Quota exceeded" }],
+                            details: { error: "quota_exceeded", hint: result.upgradeHint }
+                        };
+                    }
+                    if (result.memories.length === 0 && result.relatedMemories.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No relevant memories found." }],
+                            details: { count: 0 }
+                        };
+                    }
+                    const lines = [];
+                    const total = result.memories.length + result.relatedMemories.length;
+                    if (result.memories.length > 0) {
+                        lines.push(`Found ${result.memories.length} direct memories:`);
+                        result.memories.forEach((m, i) => {
+                            lines.push(`${i + 1}. [${m.category}] ${m.content} (${Math.round(m.score * 100)}%)`);
+                        });
+                    }
+                    if (result.relatedMemories.length > 0) {
+                        if (lines.length > 0)
+                            lines.push("");
+                        lines.push(`Found ${result.relatedMemories.length} related memories:`);
+                        result.relatedMemories.forEach((m, i) => {
+                            lines.push(`${i + 1}. [${m.category}] ${m.content}`);
+                        });
+                    }
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                        details: {
+                            count: total,
+                            direct_count: result.memories.length,
+                            related_count: result.relatedMemories.length,
+                            remaining_quota: result.remainingQuota
+                        }
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [{ type: "text", text: `Memory search failed: ${error.message}` }],
+                        details: { error: error.message }
+                    };
+                }
+            }
+        }, { name: "memoryx_recall" });
+        api.registerTool({
+            name: "memoryx_forget",
+            label: "MemoryX Forget",
+            description: "Delete specific memories. Use when user explicitly asks to forget or remove something from memory.",
+            parameters: {
+                type: "object",
+                properties: {
+                    memory_id: {
+                        type: "string",
+                        description: "The ID of the memory to delete"
+                    }
+                },
+                required: ["memory_id"]
+            },
+            async execute(_toolCallId, params) {
+                const { memory_id } = params;
+                if (!plugin) {
+                    return {
+                        content: [{ type: "text", text: "MemoryX plugin not initialized." }],
+                        details: { error: "not_initialized" }
+                    };
+                }
+                try {
+                    const success = await plugin.forget(memory_id);
+                    if (success) {
+                        return {
+                            content: [{ type: "text", text: `Memory ${memory_id} has been forgotten.` }],
+                            details: { action: "deleted", id: memory_id }
+                        };
+                    }
+                    else {
+                        return {
+                            content: [{ type: "text", text: `Memory ${memory_id} not found or could not be deleted.` }],
+                            details: { action: "failed", id: memory_id }
+                        };
+                    }
+                }
+                catch (error) {
+                    return {
+                        content: [{ type: "text", text: `Failed to forget memory: ${error.message}` }],
+                        details: { error: error.message }
+                    };
+                }
+            }
+        }, { name: "memoryx_forget" });
+        api.registerTool({
+            name: "memoryx_store",
+            label: "MemoryX Store",
+            description: "Save important information to long-term memory. Use when user explicitly asks to remember something, or when you identify important user preferences, facts, or decisions that should be persisted.",
+            parameters: {
+                type: "object",
+                properties: {
+                    content: {
+                        type: "string",
+                        description: "The information to remember. Should be a clear, concise statement. Examples: 'User prefers dark mode in all applications', 'User birthday is January 15th', 'User works as a software engineer at Acme Corp'"
+                    },
+                    category: {
+                        type: "string",
+                        enum: ["preference", "fact", "plan", "experience", "opinion", "other"],
+                        description: "Category of the memory: preference (user likes/dislikes), fact (objective info), plan (future goals), experience (past events), opinion (user's views), other"
+                    }
+                },
+                required: ["content"]
+            },
+            async execute(_toolCallId, params) {
+                const { content, category = "other" } = params;
+                if (!plugin) {
+                    return {
+                        content: [{ type: "text", text: "MemoryX plugin not initialized." }],
+                        details: { error: "not_initialized" }
+                    };
+                }
+                if (!content || content.trim().length < 5) {
+                    return {
+                        content: [{ type: "text", text: "Content too short. Please provide more meaningful information to remember." }],
+                        details: { error: "content_too_short" }
+                    };
+                }
+                try {
+                    const result = await plugin.store(content.trim(), category);
+                    if (result.success) {
+                        return {
+                            content: [{ type: "text", text: `Stored: "${content.slice(0, 100)}${content.length > 100 ? '...' : ''}"` }],
+                            details: { action: "stored", task_id: result.task_id }
+                        };
+                    }
+                    else if (result.duplicate) {
+                        return {
+                            content: [{ type: "text", text: `Similar memory already exists: "${result.existing}"` }],
+                            details: { action: "duplicate" }
+                        };
+                    }
+                    else {
+                        return {
+                            content: [{ type: "text", text: "Failed to store memory. Please try again." }],
+                            details: { error: "store_failed" }
+                        };
+                    }
+                }
+                catch (error) {
+                    return {
+                        content: [{ type: "text", text: `Failed to store memory: ${error.message}` }],
+                        details: { error: error.message }
+                    };
+                }
+            }
+        }, { name: "memoryx_store" });
+        api.registerTool({
+            name: "memoryx_list",
+            label: "MemoryX List",
+            description: "List all stored memories. Use when user asks what you remember about them.",
+            parameters: {
+                type: "object",
+                properties: {
+                    limit: {
+                        type: "number",
+                        description: "Maximum number of memories to list (default: 10)"
+                    }
+                }
+            },
+            async execute(_toolCallId, params) {
+                const { limit = 10 } = params;
+                if (!plugin) {
+                    return {
+                        content: [{ type: "text", text: "MemoryX plugin not initialized." }],
+                        details: { error: "not_initialized" }
+                    };
+                }
+                try {
+                    const memories = await plugin.list(limit);
+                    if (memories.length === 0) {
+                        return {
+                            content: [{ type: "text", text: "No memories stored yet." }],
+                            details: { count: 0 }
+                        };
+                    }
+                    const lines = [`Here are the ${memories.length} most recent memories:`];
+                    memories.forEach((m, i) => {
+                        lines.push(`${i + 1}. [${m.category || 'general'}] ${m.content || m.memory}`);
+                    });
+                    return {
+                        content: [{ type: "text", text: lines.join("\n") }],
+                        details: { count: memories.length }
+                    };
+                }
+                catch (error) {
+                    return {
+                        content: [{ type: "text", text: `Failed to list memories: ${error.message}` }],
+                        details: { error: error.message }
+                    };
+                }
+            }
+        }, { name: "memoryx_list" });
         api.on("message_received", async (event, ctx) => {
             const { content } = event;
             if (content && plugin) {

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "memoryx-openclaw-plugin",
   "name": "MemoryX Real-time Plugin",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "Real-time memory capture and recall for OpenClaw",
   "kind": "memory",
   "main": "./dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t0ken.ai/memoryx-openclaw-plugin",
-  "version": "1.1.15",
+  "version": "1.1.17",
   "description": "MemoryX real-time memory capture and recall plugin for OpenClaw",
   "type": "module",
   "author": "MemoryX Team",