@memoryrelay/plugin-memoryrelay-ai 0.7.0 → 0.8.0

package/index.ts

@@ -1,6 +1,6 @@
 /**
  * OpenClaw Memory Plugin - MemoryRelay
- * Version: 0.7.0 (Full Suite)
+ * Version: 0.8.0 (Enhanced Debug & Status)
  *
  * Long-term memory with vector search using MemoryRelay API.
  * Provides auto-recall and auto-capture via lifecycle hooks.
@@ -9,6 +9,15 @@
  * API: https://api.memoryrelay.net
  * Docs: https://memoryrelay.ai
  *
+ * ENHANCEMENTS (v0.8.0):
+ * - Debug mode with comprehensive API call logging
+ * - Enhanced status reporting with tool breakdown
+ * - Request/response capture (verbose mode)
+ * - Tool failure tracking and known issues display
+ * - Performance metrics (duration, success rate)
+ * - Recent activity display
+ * - Formatted CLI output with Unicode symbols
+ *
  * ENHANCEMENTS (v0.7.0):
  * - 39 tools covering all MemoryRelay API resources
  * - Session tracking, decision logging, pattern management, project context
@@ -21,6 +30,8 @@
  */
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import { DebugLogger, type LogEntry } from "./src/debug-logger";
+import { StatusReporter } from "./src/status-reporter";
 
 // ============================================================================
 // Constants
@@ -47,6 +58,11 @@ interface MemoryRelayConfig {
   excludeChannels?: string[];
   defaultProject?: string;
   enabledTools?: string;
+  // Debug and logging options (v0.8.0)
+  debug?: boolean;
+  verbose?: boolean;
+  logFile?: string;
+  maxLogEntries?: number;
 }
 
 interface Memory {
@@ -130,11 +146,41 @@ async function fetchWithTimeout(
 // ============================================================================
 
 class MemoryRelayClient {
+  private debugLogger?: DebugLogger;
+  private statusReporter?: StatusReporter;
+
   constructor(
     private readonly apiKey: string,
     private readonly agentId: string,
     private readonly apiUrl: string = DEFAULT_API_URL,
-  ) {}
+    debugLogger?: DebugLogger,
+    statusReporter?: StatusReporter,
+  ) {
+    this.debugLogger = debugLogger;
+    this.statusReporter = statusReporter;
+  }
+
+  /**
+   * Extract tool name from API path
+   */
+  private extractToolName(path: string): string {
+    // /v1/memories -> memory
+    // /v1/memories/batch -> memory_batch
+    // /v1/sessions/123/end -> session_end
+    const parts = path.split("/").filter(Boolean);
+    if (parts.length < 2) return "unknown";
+    
+    let toolName = parts[1].replace(/s$/, ""); // Remove trailing 's'
+    
+    // Check for specific endpoints
+    if (path.includes("/batch")) toolName += "_batch";
+    if (path.includes("/recall")) toolName += "_recall";
+    if (path.includes("/context")) toolName += "_context";
+    if (path.includes("/end")) toolName += "_end";
+    if (path.includes("/health")) return "memory_health";
+    
+    return toolName;
+  }
 
   /**
    * Make HTTP request with retry logic and timeout
@@ -146,6 +192,8 @@ class MemoryRelayClient {
     retryCount = 0,
   ): Promise<T> {
     const url = `${this.apiUrl}${path}`;
+    const startTime = Date.now();
+    const toolName = this.extractToolName(path);
 
     try {
       const response = await fetchWithTimeout(
@@ -155,13 +203,15 @@ class MemoryRelayClient {
           headers: {
             "Content-Type": "application/json",
             Authorization: `Bearer ${this.apiKey}`,
-            "User-Agent": "openclaw-memory-memoryrelay/0.7.0",
+            "User-Agent": "openclaw-memory-memoryrelay/0.8.0",
           },
           body: body ? JSON.stringify(body) : undefined,
         },
         REQUEST_TIMEOUT_MS,
       );
 
+      const duration = Date.now() - startTime;
+
       if (!response.ok) {
         const errorData = await response.json().catch(() => ({}));
         const errorMsg = errorData.detail || errorData.message || "";
@@ -170,6 +220,27 @@ class MemoryRelayClient {
             (errorMsg ? ` - ${errorMsg}` : ""),
         );
 
+        // Log error
+        if (this.debugLogger) {
+          this.debugLogger.log({
+            timestamp: new Date().toISOString(),
+            tool: toolName,
+            method,
+            path,
+            duration,
+            status: "error",
+            responseStatus: response.status,
+            error: error.message,
+            retries: retryCount,
+            requestBody: this.debugLogger && body ? body : undefined,
+          });
+        }
+
+        // Track failure
+        if (this.statusReporter) {
+          this.statusReporter.recordFailure(toolName, `${response.status} ${errorMsg || response.statusText}`);
+        }
+
         // Retry on 5xx errors
         if (response.status >= 500 && retryCount < MAX_RETRIES) {
           const delay = INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCount);
@@ -180,8 +251,53 @@ class MemoryRelayClient {
         throw error;
       }
 
-      return response.json();
+      const result = await response.json();
+
+      // Log success
+      if (this.debugLogger) {
+        this.debugLogger.log({
+          timestamp: new Date().toISOString(),
+          tool: toolName,
+          method,
+          path,
+          duration,
+          status: "success",
+          responseStatus: response.status,
+          retries: retryCount,
+          requestBody: this.debugLogger && body ? body : undefined,
+          responseBody: this.debugLogger && result ? result : undefined,
+        });
+      }
+
+      // Track success
+      if (this.statusReporter) {
+        this.statusReporter.recordSuccess(toolName);
+      }
+
+      return result;
     } catch (err) {
+      const duration = Date.now() - startTime;
+
+      // Log error
+      if (this.debugLogger) {
+        this.debugLogger.log({
+          timestamp: new Date().toISOString(),
+          tool: toolName,
+          method,
+          path,
+          duration,
+          status: "error",
+          error: String(err),
+          retries: retryCount,
+          requestBody: this.debugLogger && body ? body : undefined,
+        });
+      }
+
+      // Track failure
+      if (this.statusReporter) {
+        this.statusReporter.recordFailure(toolName, String(err));
+      }
+
       // Retry on network errors
       if (isRetryableError(err) && retryCount < MAX_RETRIES) {
         const delay = INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCount);
@@ -694,7 +810,32 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
 
   const apiUrl = cfg?.apiUrl || process.env.MEMORYRELAY_API_URL || DEFAULT_API_URL;
   const defaultProject = cfg?.defaultProject || process.env.MEMORYRELAY_DEFAULT_PROJECT;
-  const client = new MemoryRelayClient(apiKey, agentId, apiUrl);
+  
+  // ========================================================================
+  // Debug Logger and Status Reporter (v0.8.0)
+  // ========================================================================
+  
+  const debugEnabled = cfg?.debug || false;
+  const verboseEnabled = cfg?.verbose || false;
+  const logFile = cfg?.logFile;
+  const maxLogEntries = cfg?.maxLogEntries || 100;
+  
+  let debugLogger: DebugLogger | undefined;
+  let statusReporter: StatusReporter | undefined;
+  
+  if (debugEnabled) {
+    debugLogger = new DebugLogger({
+      enabled: true,
+      verbose: verboseEnabled,
+      maxEntries: maxLogEntries,
+      logFile: logFile,
+    });
+    api.logger.info(`memory-memoryrelay: debug mode enabled (verbose: ${verboseEnabled}, maxEntries: ${maxLogEntries})`);
+  }
+  
+  statusReporter = new StatusReporter(debugLogger);
+  
+  const client = new MemoryRelayClient(apiKey, agentId, apiUrl, debugLogger, statusReporter);
 
   // Verify connection on startup (with timeout)
   try {
@@ -711,30 +852,87 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
 
   api.registerGatewayMethod?.("memory.status", async ({ respond }) => {
     try {
+      // Get connection status
+      const startTime = Date.now();
       const health = await client.health();
+      const responseTime = Date.now() - startTime;
+      
+      const healthStatus = String(health.status).toLowerCase();
+      const isConnected = VALID_HEALTH_STATUSES.includes(healthStatus);
+      
+      const connectionStatus = {
+        status: isConnected ? "connected" as const : "disconnected" as const,
+        endpoint: apiUrl,
+        lastCheck: new Date().toISOString(),
+        responseTime,
+      };
+      
+      // Get memory stats
       let memoryCount = 0;
-
       try {
         const stats = await client.stats();
         memoryCount = stats.total_memories;
       } catch (statsErr) {
         api.logger.debug?.(`memory-memoryrelay: stats endpoint unavailable: ${String(statsErr)}`);
       }
-
-      const healthStatus = String(health.status).toLowerCase();
-      const isConnected = VALID_HEALTH_STATUSES.includes(healthStatus);
-
-      respond(true, {
-        available: true,
-        connected: isConnected,
-        endpoint: apiUrl,
-        memoryCount: memoryCount,
+      
+      const memoryStats = {
+        total_memories: memoryCount,
+      };
+      
+      // Get config
+      const pluginConfig = {
         agentId: agentId,
-        vector: {
+        autoRecall: cfg?.autoRecall ?? true,
+        autoCapture: cfg?.autoCapture ?? false,
+        recallLimit: cfg?.recallLimit ?? 5,
+        recallThreshold: cfg?.recallThreshold ?? 0.3,
+        excludeChannels: cfg?.excludeChannels ?? [],
+        defaultProject: defaultProject,
+      };
+      
+      // Build comprehensive status report
+      if (statusReporter) {
+        const report = statusReporter.buildReport(
+          connectionStatus,
+          pluginConfig,
+          memoryStats,
+          TOOL_GROUPS,
+        );
+        
+        // Format and output
+        const formatted = StatusReporter.formatReport(report);
+        api.logger.info(formatted);
+        
+        // Also return structured data for programmatic access
+        respond(true, {
           available: true,
-          enabled: true,
-        },
-      });
+          connected: isConnected,
+          endpoint: apiUrl,
+          memoryCount: memoryCount,
+          agentId: agentId,
+          debug: debugEnabled,
+          verbose: verboseEnabled,
+          report: report,
+          vector: {
+            available: true,
+            enabled: true,
+          },
+        });
+      } else {
+        // Fallback to simple status (shouldn't happen)
+        respond(true, {
+          available: true,
+          connected: isConnected,
+          endpoint: apiUrl,
+          memoryCount: memoryCount,
+          agentId: agentId,
+          vector: {
+            available: true,
+            enabled: true,
+          },
+        });
+      }
     } catch (err) {
       respond(true, {
         available: false,
@@ -3170,6 +3368,230 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   }
 
   api.logger.info?.(
-    `memory-memoryrelay: plugin v0.7.0 loaded (39 tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${cfg?.autoCapture})`,
+    `memory-memoryrelay: plugin v0.8.0 loaded (39 tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${cfg?.autoCapture}, debug: ${debugEnabled})`,
   );
+
+  // ========================================================================
+  // CLI Helper Tools (v0.8.0)
+  // ========================================================================
+
+  // Register CLI-accessible tools for debugging and diagnostics
+  
+  // memoryrelay:logs - Get debug logs
+  if (debugLogger) {
+    api.registerGatewayMethod?.("memoryrelay.logs", async ({ respond, args }) => {
+      try {
+        const limit = args?.limit || 20;
+        const toolName = args?.tool;
+        const errorsOnly = args?.errorsOnly || false;
+
+        let logs: LogEntry[];
+        if (toolName) {
+          logs = debugLogger.getToolLogs(toolName, limit);
+        } else if (errorsOnly) {
+          logs = debugLogger.getErrorLogs(limit);
+        } else {
+          logs = debugLogger.getRecentLogs(limit);
+        }
+
+        const formatted = DebugLogger.formatTable(logs);
+        respond(true, {
+          logs,
+          formatted,
+          count: logs.length,
+        });
+      } catch (err) {
+        respond(false, { error: String(err) });
+      }
+    });
+  }
+
+  // memoryrelay:health - Comprehensive health check
+  api.registerGatewayMethod?.("memoryrelay.health", async ({ respond }) => {
+    try {
+      const startTime = Date.now();
+      const health = await client.health();
+      const healthDuration = Date.now() - startTime;
+
+      const results: any = {
+        api: {
+          status: health.status,
+          endpoint: apiUrl,
+          responseTime: healthDuration,
+          reachable: true,
+        },
+        authentication: {
+          status: "valid",
+          apiKey: apiKey.substring(0, 16) + "...",
+        },
+        tools: {},
+      };
+
+      // Test critical tools
+      const toolTests = [
+        { name: "memory_store", test: async () => {
+          const testMem = await client.store("Plugin health check test", { test: "true" });
+          await client.delete(testMem.id);
+          return { success: true };
+        }},
+        { name: "memory_recall", test: async () => {
+          await client.search("test", 1, 0.5);
+          return { success: true };
+        }},
+        { name: "memory_list", test: async () => {
+          await client.list(1);
+          return { success: true };
+        }},
+      ];
+
+      for (const { name, test } of toolTests) {
+        const testStart = Date.now();
+        try {
+          await test();
+          results.tools[name] = {
+            status: "working",
+            duration: Date.now() - testStart,
+          };
+        } catch (err) {
+          results.tools[name] = {
+            status: "error",
+            error: String(err),
+            duration: Date.now() - testStart,
+          };
+        }
+      }
+
+      // Overall status
+      const allToolsWorking = Object.values(results.tools).every(
+        (t: any) => t.status === "working"
+      );
+      results.overall = allToolsWorking ? "healthy" : "degraded";
+
+      respond(true, results);
+    } catch (err) {
+      respond(false, {
+        overall: "unhealthy",
+        error: String(err),
+      });
+    }
+  });
+
+  // memoryrelay:metrics - Performance metrics
+  if (debugLogger) {
+    api.registerGatewayMethod?.("memoryrelay.metrics", async ({ respond }) => {
+      try {
+        const stats = debugLogger.getStats();
+        const allLogs = debugLogger.getAllLogs();
+
+        // Calculate per-tool metrics
+        const toolMetrics: Record<string, any> = {};
+        for (const log of allLogs) {
+          if (!toolMetrics[log.tool]) {
+            toolMetrics[log.tool] = {
+              calls: 0,
+              successes: 0,
+              failures: 0,
+              totalDuration: 0,
+              durations: [],
+            };
+          }
+          const metric = toolMetrics[log.tool];
+          metric.calls++;
+          if (log.status === "success") {
+            metric.successes++;
+          } else {
+            metric.failures++;
+          }
+          metric.totalDuration += log.duration;
+          metric.durations.push(log.duration);
+        }
+
+        // Calculate averages and percentiles
+        for (const tool in toolMetrics) {
+          const metric = toolMetrics[tool];
+          metric.avgDuration = Math.round(metric.totalDuration / metric.calls);
+          metric.successRate = Math.round((metric.successes / metric.calls) * 100);
+          
+          // Calculate p95 and p99
+          const sorted = metric.durations.sort((a: number, b: number) => a - b);
+          const p95Index = Math.floor(sorted.length * 0.95);
+          const p99Index = Math.floor(sorted.length * 0.99);
+          metric.p95Duration = sorted[p95Index] || 0;
+          metric.p99Duration = sorted[p99Index] || 0;
+          
+          delete metric.durations; // Don't include raw data in response
+        }
+
+        respond(true, {
+          summary: stats,
+          toolMetrics,
+        });
+      } catch (err) {
+        respond(false, { error: String(err) });
+      }
+    });
+  }
+
+  // memoryrelay:test - Test individual tool
+  api.registerGatewayMethod?.("memoryrelay.test", async ({ respond, args }) => {
+    try {
+      const toolName = args?.tool;
+      if (!toolName) {
+        respond(false, { error: "Missing required argument: tool" });
+        return;
+      }
+
+      const startTime = Date.now();
+      let result: any;
+      let error: string | undefined;
+
+      // Test the specified tool
+      try {
+        switch (toolName) {
+          case "memory_store":
+            const mem = await client.store("Test memory", { test: "true" });
+            await client.delete(mem.id);
+            result = { success: true, message: "Memory stored and deleted successfully" };
+            break;
+
+          case "memory_recall":
+            const searchResults = await client.search("test", 1, 0.5);
+            result = { success: true, results: searchResults.length, message: "Search completed" };
+            break;
+
+          case "memory_list":
+            const list = await client.list(5);
+            result = { success: true, count: list.length, message: "List retrieved" };
+            break;
+
+          case "project_list":
+            const projects = await client.listProjects(5);
+            result = { success: true, count: projects.length, message: "Projects listed" };
+            break;
+
+          case "memory_health":
+            const health = await client.health();
+            result = { success: true, status: health.status, message: "Health check passed" };
+            break;
+
+          default:
+            result = { success: false, message: `Unknown tool: ${toolName}` };
+        }
+      } catch (err) {
+        error = String(err);
+        result = { success: false, error };
+      }
+
+      const duration = Date.now() - startTime;
+
+      respond(true, {
+        tool: toolName,
+        duration,
+        result,
+        error,
+      });
+    } catch (err) {
+      respond(false, { error: String(err) });
+    }
+  });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoryrelay/plugin-memoryrelay-ai",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "OpenClaw memory plugin for MemoryRelay API - sessions, decisions, patterns, projects & semantic search",
   "type": "module",
   "main": "index.ts",
@@ -43,8 +43,16 @@
       "./index.ts"
     ]
   },
+  "bin": {
+    "memoryrelay-logs": "./bin/memoryrelay-logs.js",
+    "memoryrelay-health": "./bin/memoryrelay-health.js",
+    "memoryrelay-test": "./bin/memoryrelay-test.js",
+    "memoryrelay-metrics": "./bin/memoryrelay-metrics.js"
+  },
   "files": [
     "index.ts",
+    "src/",
+    "bin/",
     "openclaw.plugin.json",
     "README.md",
     "LICENSE"