@memoryrelay/plugin-memoryrelay-ai 0.5.3 → 0.6.2

package/index.ts

@@ -1,11 +1,19 @@
 /**
  * OpenClaw Memory Plugin - MemoryRelay
+ * Version: 0.6.0 (Enhanced)
  *
  * Long-term memory with vector search using MemoryRelay API.
  * Provides auto-recall and auto-capture via lifecycle hooks.
  *
  * API: https://api.memoryrelay.net
  * Docs: https://memoryrelay.io
+ *
+ * ENHANCEMENTS (v0.6.0):
+ * - Retry logic with exponential backoff (3 attempts)
+ * - Request timeout (30 seconds)
+ * - Environment variable fallback support
+ * - Channel filtering (excludeChannels config)
+ * - Additional CLI commands (stats, delete, export)
  */
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
@@ -16,19 +24,23 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 
 const DEFAULT_API_URL = "https://api.memoryrelay.net";
 const VALID_HEALTH_STATUSES = ["ok", "healthy", "up"];
+const REQUEST_TIMEOUT_MS = 30000; // 30 seconds
+const MAX_RETRIES = 3;
+const INITIAL_RETRY_DELAY_MS = 1000; // 1 second
 
 // ============================================================================
 // Types
 // ============================================================================
 
 interface MemoryRelayConfig {
-  apiKey: string;
-  agentId: string;
+  apiKey?: string; // Optional now (can use env var)
+  agentId?: string; // Optional now (can use env var)
   apiUrl?: string;
   autoCapture?: boolean;
   autoRecall?: boolean;
   recallLimit?: number;
   recallThreshold?: number;
+  excludeChannels?: string[]; // NEW: Channels to skip auto-recall
 }
 
 interface Memory {
@@ -47,8 +59,68 @@ interface SearchResult {
   score: number;
 }
 
+interface Stats {
+  total_memories: number;
+  last_updated?: string;
+}
+
 // ============================================================================
-// MemoryRelay API Client
+// Utility Functions
+// ============================================================================
+
+/**
+ * Sleep for specified milliseconds
+ */
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * Check if error is retryable (network/timeout errors)
+ */
+function isRetryableError(error: unknown): boolean {
+  const errStr = String(error).toLowerCase();
+  return (
+    errStr.includes("timeout") ||
+    errStr.includes("econnrefused") ||
+    errStr.includes("enotfound") ||
+    errStr.includes("network") ||
+    errStr.includes("fetch failed") ||
+    errStr.includes("502") ||
+    errStr.includes("503") ||
+    errStr.includes("504")
+  );
+}
+
+/**
+ * Fetch with timeout
+ */
+async function fetchWithTimeout(
+  url: string,
+  options: RequestInit,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    return response;
+  } catch (err) {
+    clearTimeout(timeout);
+    if ((err as Error).name === "AbortError") {
+      throw new Error("Request timeout");
+    }
+    throw err;
+  }
+}
+
+// ============================================================================
+// MemoryRelay API Client (Enhanced)
 // ============================================================================
 
 class MemoryRelayClient {
@@ -58,32 +130,60 @@ class MemoryRelayClient {
     private readonly apiUrl: string = DEFAULT_API_URL,
   ) {}
 
+  /**
+   * Make HTTP request with retry logic and timeout
+   */
   private async request<T>(
     method: string,
     path: string,
     body?: unknown,
+    retryCount = 0,
   ): Promise<T> {
     const url = `${this.apiUrl}${path}`;
 
-    const response = await fetch(url, {
-      method,
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${this.apiKey}`,
-        "User-Agent": "openclaw-memory-memoryrelay/0.1.0",
-      },
-      body: body ? JSON.stringify(body) : undefined,
-    });
-
-    if (!response.ok) {
-      const errorData = await response.json().catch(() => ({}));
-      throw new Error(
-        `MemoryRelay API error: ${response.status} ${response.statusText}` +
-          (errorData.message ? ` - ${errorData.message}` : ""),
+    try {
+      const response = await fetchWithTimeout(
+        url,
+        {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            "User-Agent": "openclaw-memory-memoryrelay/0.6.0",
+          },
+          body: body ? JSON.stringify(body) : undefined,
+        },
+        REQUEST_TIMEOUT_MS,
       );
-    }
 
-    return response.json();
+      if (!response.ok) {
+        const errorData = await response.json().catch(() => ({}));
+        const error = new Error(
+          `MemoryRelay API error: ${response.status} ${response.statusText}` +
+            (errorData.message ? ` - ${errorData.message}` : ""),
+        );
+
+        // Retry on 5xx errors
+        if (response.status >= 500 && retryCount < MAX_RETRIES) {
+          const delay = INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCount);
+          await sleep(delay);
+          return this.request<T>(method, path, body, retryCount + 1);
+        }
+
+        throw error;
+      }
+
+      return response.json();
+    } catch (err) {
+      // Retry on network errors
+      if (isRetryableError(err) && retryCount < MAX_RETRIES) {
+        const delay = INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCount);
+        await sleep(delay);
+        return this.request<T>(method, path, body, retryCount + 1);
+      }
+
+      throw err;
+    }
   }
 
   async store(content: string, metadata?: Record<string, string>): Promise<Memory> {
@@ -132,8 +232,8 @@ class MemoryRelayClient {
     return this.request<{ status: string }>("GET", "/v1/health");
   }
 
-  async stats(): Promise<{ total_memories: number; last_updated?: string }> {
-    const response = await this.request<{ data: { total_memories: number; last_updated?: string } }>(
+  async stats(): Promise<Stats> {
+    const response = await this.request<{ data: Stats }>(
       "GET",
       `/v1/stats?agent_id=${encodeURIComponent(this.agentId)}`,
     );
@@ -142,6 +242,25 @@ class MemoryRelayClient {
       last_updated: response.data?.last_updated,
     };
   }
+
+  /**
+   * Export all memories as JSON
+   */
+  async export(): Promise<Memory[]> {
+    const allMemories: Memory[] = [];
+    let offset = 0;
+    const limit = 100;
+
+    while (true) {
+      const batch = await this.list(limit, offset);
+      if (batch.length === 0) break;
+      allMemories.push(...batch);
+      offset += limit;
+      if (batch.length < limit) break; // Last page
+    }
+
+    return allMemories;
+  }
 }
 
 // ============================================================================
@@ -171,59 +290,60 @@ function shouldCapture(text: string): boolean {
 
 export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   const cfg = api.pluginConfig as MemoryRelayConfig | undefined;
-  
-  if (!cfg?.apiKey) {
+
+  // NEW: Fall back to environment variables
+  const apiKey = cfg?.apiKey || process.env.MEMORYRELAY_API_KEY;
+  const agentId = cfg?.agentId || process.env.MEMORYRELAY_AGENT_ID || api.agentName;
+
+  if (!apiKey) {
     api.logger.error(
-      "memory-memoryrelay: Missing API key in config.\n\n" +
-      "REQUIRED: Add config after installation:\n\n" +
-      "cat ~/.openclaw/openclaw.json | jq '.plugins.entries.\"plugin-memoryrelay-ai\".config = {\n" +
-      "  \"apiKey\": \"YOUR_API_KEY\",\n" +
-      "  \"agentId\": \"YOUR_AGENT_ID\"\n" +
-      "}' > /tmp/config.json && mv /tmp/config.json ~/.openclaw/openclaw.json\n\n" +
-      "Then restart: openclaw gateway restart\n\n" +
-      "Get your API key from: https://memoryrelay.ai"
+      "memory-memoryrelay: Missing API key in config or MEMORYRELAY_API_KEY env var.\n\n" +
+        "REQUIRED: Add config after installation:\n\n" +
+        'cat ~/.openclaw/openclaw.json | jq \'.plugins.entries."plugin-memoryrelay-ai".config = {\n' +
+        '  "apiKey": "YOUR_API_KEY",\n' +
+        '  "agentId": "YOUR_AGENT_ID"\n' +
+        "}' > /tmp/config.json && mv /tmp/config.json ~/.openclaw/openclaw.json\n\n" +
+        "Or set environment variable:\n" +
+        'export MEMORYRELAY_API_KEY="mem_prod_..."\n\n' +
+        "Then restart: openclaw gateway restart\n\n" +
+        "Get your API key from: https://memoryrelay.ai",
     );
     return;
   }
-  
-  if (!cfg.agentId) {
-    api.logger.error("memory-memoryrelay: Missing agentId in config");
+
+  if (!agentId) {
+    api.logger.error("memory-memoryrelay: Missing agentId in config or MEMORYRELAY_AGENT_ID env var");
     return;
   }
-  
-  const apiUrl = cfg.apiUrl || DEFAULT_API_URL;
-  const client = new MemoryRelayClient(cfg.apiKey, cfg.agentId, apiUrl);
 
-  // Verify connection on startup
+  const apiUrl = cfg?.apiUrl || process.env.MEMORYRELAY_API_URL || DEFAULT_API_URL;
+  const client = new MemoryRelayClient(apiKey, agentId, apiUrl);
+
+  // Verify connection on startup (with timeout)
   try {
     await client.health();
     api.logger.info(`memory-memoryrelay: connected to ${apiUrl}`);
   } catch (err) {
     api.logger.error(`memory-memoryrelay: health check failed: ${String(err)}`);
-    return;
+    // Continue loading plugin even if health check fails (will retry on first use)
   }
 
   // ========================================================================
   // Status Reporting (for openclaw status command)
   // ========================================================================
 
-  // Register gateway RPC method for status probing
-  // This allows OpenClaw's status command to query plugin availability
   api.registerGatewayMethod?.("memory.status", async ({ respond }) => {
     try {
       const health = await client.health();
       let memoryCount = 0;
 
-      // Try to get stats if the endpoint exists
       try {
         const stats = await client.stats();
         memoryCount = stats.total_memories;
       } catch (statsErr) {
-        // Stats endpoint may not exist yet - that's okay, just report 0
         api.logger.debug?.(`memory-memoryrelay: stats endpoint unavailable: ${String(statsErr)}`);
       }
 
-      // Consider API connected if health check succeeds with any recognized status
       const healthStatus = String(health.status).toLowerCase();
       const isConnected = VALID_HEALTH_STATUSES.includes(healthStatus);
 
@@ -233,7 +353,6 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
         endpoint: apiUrl,
         memoryCount: memoryCount,
         agentId: agentId,
-        // OpenClaw checks status.vector.available for memory plugins
         vector: {
           available: true,
           enabled: true,
@@ -246,7 +365,6 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
         error: String(err),
         endpoint: apiUrl,
         agentId: agentId,
-        // Report vector as unavailable when API fails
         vector: {
           available: false,
           enabled: true,
@@ -328,7 +446,7 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
       },
       execute: async (_id, { query, limit = 5 }: { query: string; limit?: number }) => {
         try {
-          const results = await client.search(query, limit, cfg.recallThreshold || 0.3);
+          const results = await client.search(query, limit, cfg?.recallThreshold || 0.3);
 
           if (results.length === 0) {
             return {
@@ -453,7 +571,7 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   );
 
   // ========================================================================
-  // CLI Commands
+  // CLI Commands (Enhanced)
   // ========================================================================
 
   api.registerCli(
@@ -466,24 +584,48 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
         .action(async () => {
           try {
             const health = await client.health();
+            const stats = await client.stats();
             console.log(`Status: ${health.status}`);
             console.log(`Agent ID: ${agentId}`);
             console.log(`API: ${apiUrl}`);
+            console.log(`Total Memories: ${stats.total_memories}`);
+            if (stats.last_updated) {
+              console.log(`Last Updated: ${new Date(stats.last_updated).toLocaleString()}`);
+            }
           } catch (err) {
             console.error(`Connection failed: ${String(err)}`);
           }
         });
 
+      mem
+        .command("stats")
+        .description("Show agent statistics")
+        .action(async () => {
+          try {
+            const stats = await client.stats();
+            console.log(`Total Memories: ${stats.total_memories}`);
+            if (stats.last_updated) {
+              console.log(`Last Updated: ${new Date(stats.last_updated).toLocaleString()}`);
+            }
+          } catch (err) {
+            console.error(`Failed to fetch stats: ${String(err)}`);
+          }
+        });
+
       mem
         .command("list")
         .description("List recent memories")
         .option("--limit <n>", "Max results", "10")
         .action(async (opts) => {
-          const memories = await client.list(parseInt(opts.limit));
-          for (const m of memories) {
-            console.log(`[${m.id.slice(0, 8)}] ${m.content.slice(0, 80)}...`);
+          try {
+            const memories = await client.list(parseInt(opts.limit));
+            for (const m of memories) {
+              console.log(`[${m.id.slice(0, 8)}] ${m.content.slice(0, 80)}...`);
+            }
+            console.log(`\nTotal: ${memories.length} memories`);
+          } catch (err) {
+            console.error(`Failed to list memories: ${String(err)}`);
           }
-          console.log(`\nTotal: ${memories.length} memories`);
         });
 
       mem
@@ -492,9 +634,42 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
         .argument("<query>", "Search query")
         .option("--limit <n>", "Max results", "5")
         .action(async (query, opts) => {
-          const results = await client.search(query, parseInt(opts.limit));
-          for (const r of results) {
-            console.log(`[${r.score.toFixed(2)}] ${r.memory.content.slice(0, 80)}...`);
+          try {
+            const results = await client.search(query, parseInt(opts.limit));
+            for (const r of results) {
+              console.log(`[${r.score.toFixed(2)}] ${r.memory.content.slice(0, 80)}...`);
+            }
+          } catch (err) {
+            console.error(`Search failed: ${String(err)}`);
+          }
+        });
+
+      mem
+        .command("delete")
+        .description("Delete a memory by ID")
+        .argument("<id>", "Memory ID")
+        .action(async (id) => {
+          try {
+            await client.delete(id);
+            console.log(`Memory ${id.slice(0, 8)}... deleted.`);
+          } catch (err) {
+            console.error(`Delete failed: ${String(err)}`);
+          }
+        });
+
+      mem
+        .command("export")
+        .description("Export all memories to JSON file")
+        .option("--output <path>", "Output file path", "memories-export.json")
+        .action(async (opts) => {
+          try {
+            console.log("Exporting memories...");
+            const memories = await client.export();
+            const fs = await import("fs/promises");
+            await fs.writeFile(opts.output, JSON.stringify(memories, null, 2));
+            console.log(`Exported ${memories.length} memories to ${opts.output}`);
+          } catch (err) {
+            console.error(`Export failed: ${String(err)}`);
           }
         });
     },
@@ -506,12 +681,23 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   // ========================================================================
 
   // Auto-recall: inject relevant memories before agent starts
-  if (cfg.autoRecall) {
+  if (cfg?.autoRecall) {
     api.on("before_agent_start", async (event) => {
       if (!event.prompt || event.prompt.length < 10) {
         return;
       }
 
+      // NEW: Check if current channel is excluded
+      if (cfg.excludeChannels && event.channel) {
+        const channelId = String(event.channel);
+        if (cfg.excludeChannels.some((excluded) => channelId.includes(excluded))) {
+          api.logger.debug?.(
+            `memory-memoryrelay: skipping auto-recall for excluded channel: ${channelId}`,
+          );
+          return;
+        }
+      }
+
       try {
         const results = await client.search(
           event.prompt,
@@ -523,9 +709,7 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
           return;
         }
 
-        const memoryContext = results
-          .map((r) => `- ${r.memory.content}`)
-          .join("\n");
+        const memoryContext = results.map((r) => `- ${r.memory.content}`).join("\n");
 
         api.logger.info?.(
           `memory-memoryrelay: injecting ${results.length} memories into context`,
@@ -541,7 +725,7 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   }
 
   // Auto-capture: analyze and store important information after agent ends
-  if (cfg.autoCapture) {
+  if (cfg?.autoCapture) {
     api.on("agent_end", async (event) => {
       if (!event.success || !event.messages || event.messages.length === 0) {
         return;
@@ -596,6 +780,6 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   }
 
   api.logger.info?.(
-    `memory-memoryrelay: plugin loaded (autoRecall: ${cfg.autoRecall}, autoCapture: ${cfg.autoCapture})`,
+    `memory-memoryrelay: plugin loaded (autoRecall: ${cfg?.autoRecall}, autoCapture: ${cfg?.autoCapture})`,
   );
 }

package/openclaw.plugin.json

@@ -3,24 +3,24 @@
   "kind": "memory",
   "name": "MemoryRelay AI",
   "description": "AI memory service using MemoryRelay API (api.memoryrelay.net)",
-  "version": "0.5.3",
+  "version": "0.6.2",
   "uiHints": {
     "apiKey": {
       "label": "MemoryRelay API Key",
       "sensitive": true,
       "placeholder": "mem_prod_...",
-      "help": "API key from memoryrelay.io (or use ${MEMORYRELAY_API_KEY})"
+      "help": "API key from memoryrelay.io (or use ${MEMORYRELAY_API_KEY} env var)"
     },
     "agentId": {
       "label": "Agent ID",
       "placeholder": "iris",
-      "help": "Unique identifier for this agent in MemoryRelay"
+      "help": "Unique identifier for this agent in MemoryRelay (or use ${MEMORYRELAY_AGENT_ID} env var)"
     },
     "apiUrl": {
       "label": "API URL",
       "placeholder": "https://api.memoryrelay.net",
       "advanced": true,
-      "help": "MemoryRelay API endpoint"
+      "help": "MemoryRelay API endpoint (or use ${MEMORYRELAY_API_URL} env var)"
     },
     "autoCapture": {
       "label": "Auto-Capture",
@@ -29,6 +29,11 @@
     "autoRecall": {
       "label": "Auto-Recall",
       "help": "Automatically inject relevant memories into context"
+    },
+    "excludeChannels": {
+      "label": "Exclude Channels",
+      "help": "List of channel IDs to skip auto-recall (e.g., ['whatsapp:group_123', 'telegram:456'])",
+      "advanced": true
     }
   },
   "configSchema": {
@@ -38,12 +43,12 @@
       "apiKey": {
         "type": "string",
         "minLength": 1,
-        "description": "MemoryRelay API key (required, get from https://memoryrelay.ai)"
+        "description": "MemoryRelay API key (optional, can use MEMORYRELAY_API_KEY env var)"
       },
       "agentId": {
         "type": "string",
         "minLength": 1,
-        "description": "Unique agent identifier (required)"
+        "description": "Unique agent identifier (optional, can use MEMORYRELAY_AGENT_ID env var or agent name)"
       },
       "apiUrl": {
         "type": "string",
@@ -59,11 +64,23 @@
       },
       "recallLimit": {
         "type": "number",
-        "default": 5
+        "default": 5,
+        "minimum": 1,
+        "maximum": 20
       },
       "recallThreshold": {
         "type": "number",
-        "default": 0.3
+        "default": 0.3,
+        "minimum": 0,
+        "maximum": 1
+      },
+      "excludeChannels": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "default": [],
+        "description": "List of channel IDs to exclude from auto-recall"
       }
     },
     "required": []

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@memoryrelay/plugin-memoryrelay-ai",
-  "version": "0.5.3",
-  "description": "OpenClaw memory plugin for MemoryRelay API - long-term memory with semantic search",
+  "version": "0.6.2",
+  "description": "OpenClaw memory plugin for MemoryRelay API - long-term memory with semantic search (ENHANCED)",
   "type": "module",
   "main": "index.ts",
   "scripts": {
-    "postinstall": "node -e \"console.log('\\n⚠️  CONFIGURATION REQUIRED\\n\\nAdd config after installation:\\n\\ncat ~/.openclaw/openclaw.json | jq \\'.plugins.entries.\\\"plugin-memoryrelay-ai\\\".config = {\\\"apiKey\\\": \\\"YOUR_KEY\\\", \\\"agentId\\\": \\\"YOUR_AGENT\\\"}\\' > /tmp/config.json && mv /tmp/config.json ~/.openclaw/openclaw.json\\n\\nThen restart: openclaw gateway restart\\n\\nGet your API key from: https://memoryrelay.ai\\n')\""
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "postinstall": "node -e \"console.log('\\n⚠️  CONFIGURATION REQUIRED\\n\\nAdd config after installation:\\n\\ncat ~/.openclaw/openclaw.json | jq \\'.plugins.entries.\\\"plugin-memoryrelay-ai\\\".config = {\\\"apiKey\\\": \\\"YOUR_KEY\\\", \\\"agentId\\\": \\\"YOUR_AGENT\\\"}\\' > /tmp/config.json && mv /tmp/config.json ~/.openclaw/openclaw.json\\n\\nOr use environment variables:\\nexport MEMORYRELAY_API_KEY=\\\"mem_prod_...\\\"\\nexport MEMORYRELAY_AGENT_ID=\\\"your-agent\\\"\\n\\nThen restart: openclaw gateway restart\\n\\nGet your API key from: https://memoryrelay.ai\\n')\""
   },
   "keywords": [
     "openclaw",
@@ -30,10 +33,14 @@
   "peerDependencies": {
     "openclaw": ">=2026.2.0"
   },
+  "devDependencies": {
+    "vitest": "^1.2.0",
+    "@vitest/coverage-v8": "^1.2.0"
+  },
   "openclaw": {
     "id": "plugin-memoryrelay-ai",
     "extensions": [
-      "./"
+      "./index.ts"
     ]
   },
   "files": [