@memoryrelay/plugin-memoryrelay-ai 0.12.0 → 0.12.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoryrelay/plugin-memoryrelay-ai",
-  "version": "0.12.0",
+  "version": "0.12.1",
   "description": "OpenClaw memory plugin for MemoryRelay API - sessions, decisions, patterns, projects & semantic search",
   "type": "module",
   "main": "index.ts",
@@ -47,7 +47,8 @@
     "index.ts",
     "openclaw.plugin.json",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "src/"
   ],
   "engines": {
     "node": ">=18.0.0"

package/src/cli/stats-command.ts

@@ -0,0 +1,166 @@
+/**
+ * CLI Stats Command (Phase 1 - Issue #11)
+ * 
+ * Provides `openclaw memoryrelay stats` command for quick stats access
+ * Supports both text and JSON output formats
+ */
+
+export interface StatsCommandOptions {
+  format?: "text" | "json";
+  verbose?: boolean;
+}
+
+export interface StatsOutput {
+  total: number;
+  today: number;
+  thisWeek: number;
+  thisMonth: number;
+  weeklyGrowth: number;
+  monthlyGrowth: number;
+  topCategories: Array<{ category: string; count: number }>;
+  recentlyAdded: Array<{
+    id: string;
+    content: string;
+    created_at: number;
+  }>;
+}
+
+/**
+ * Gather comprehensive stats for CLI output
+ */
+export async function gatherStatsForCLI(
+  getAllMemories: () => Promise<Array<{ 
+    id: string;
+    content: string;
+    metadata: Record<string, string>;
+    created_at: number;
+  }>>
+): Promise<StatsOutput> {
+  const memories = await getAllMemories();
+  const now = Date.now();
+  
+  // Time boundaries
+  const todayStart = new Date().setHours(0, 0, 0, 0);
+  const weekStart = now - 7 * 24 * 60 * 60 * 1000;
+  const lastWeekStart = now - 14 * 24 * 60 * 60 * 1000;
+  const monthStart = now - 30 * 24 * 60 * 60 * 1000;
+  const lastMonthStart = now - 60 * 24 * 60 * 60 * 1000;
+
+  // Count by period
+  const total = memories.length;
+  const today = memories.filter((m) => m.created_at >= todayStart).length;
+  const thisWeek = memories.filter((m) => m.created_at >= weekStart).length;
+  const lastWeek = memories.filter(
+    (m) => m.created_at >= lastWeekStart && m.created_at < weekStart
+  ).length;
+  const thisMonth = memories.filter((m) => m.created_at >= monthStart).length;
+  const lastMonth = memories.filter(
+    (m) => m.created_at >= lastMonthStart && m.created_at < monthStart
+  ).length;
+
+  // Growth calculations
+  const weeklyGrowth = lastWeek > 0 ? ((thisWeek - lastWeek) / lastWeek) * 100 : 0;
+  const monthlyGrowth = lastMonth > 0 ? ((thisMonth - lastMonth) / lastMonth) * 100 : 0;
+
+  // Top categories
+  const categoryCount = new Map<string, number>();
+  for (const memory of memories) {
+    const category = memory.metadata.category || "uncategorized";
+    categoryCount.set(category, (categoryCount.get(category) || 0) + 1);
+  }
+
+  const topCategories = Array.from(categoryCount.entries())
+    .map(([category, count]) => ({ category, count }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 10);
+
+  // Recently added (last 5)
+  const recentlyAdded = memories
+    .sort((a, b) => b.created_at - a.created_at)
+    .slice(0, 5)
+    .map((m) => ({
+      id: m.id,
+      content: m.content.length > 100 ? m.content.slice(0, 100) + "..." : m.content,
+      created_at: m.created_at,
+    }));
+
+  return {
+    total,
+    today,
+    thisWeek,
+    thisMonth,
+    weeklyGrowth,
+    monthlyGrowth,
+    topCategories,
+    recentlyAdded,
+  };
+}
+
+/**
+ * Format stats as human-readable text
+ */
+export function formatStatsAsText(stats: StatsOutput, verbose: boolean = false): string {
+  const lines: string[] = [];
+  
+  lines.push("📊 MemoryRelay Statistics");
+  lines.push("");
+  
+  // Overview
+  lines.push("OVERVIEW");
+  lines.push(`  Total memories: ${stats.total}`);
+  lines.push(`  Added today:    ${stats.today}`);
+  lines.push(`  This week:      ${stats.thisWeek} (${stats.weeklyGrowth > 0 ? '+' : ''}${stats.weeklyGrowth.toFixed(0)}%)`);
+  lines.push(`  This month:     ${stats.thisMonth} (${stats.monthlyGrowth > 0 ? '+' : ''}${stats.monthlyGrowth.toFixed(0)}%)`);
+  lines.push("");
+
+  // Top categories
+  if (stats.topCategories.length > 0) {
+    lines.push("TOP CATEGORIES");
+    const displayCount = verbose ? 10 : 5;
+    for (const cat of stats.topCategories.slice(0, displayCount)) {
+      const percentage = ((cat.count / stats.total) * 100).toFixed(1);
+      lines.push(`  ${cat.category.padEnd(20)} ${cat.count.toString().padStart(4)} (${percentage}%)`);
+    }
+    lines.push("");
+  }
+
+  // Recently added (verbose only)
+  if (verbose && stats.recentlyAdded.length > 0) {
+    lines.push("RECENTLY ADDED");
+    for (const memory of stats.recentlyAdded) {
+      const date = new Date(memory.created_at).toLocaleDateString();
+      lines.push(`  [${date}] ${memory.content}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Format stats as JSON
+ */
+export function formatStatsAsJSON(stats: StatsOutput): string {
+  return JSON.stringify(stats, null, 2);
+}
+
+/**
+ * Main CLI stats command handler
+ */
+export async function statsCommand(
+  getAllMemories: () => Promise<Array<{ 
+    id: string;
+    content: string;
+    metadata: Record<string, string>;
+    created_at: number;
+  }>>,
+  options: StatsCommandOptions = {}
+): Promise<string> {
+  const stats = await gatherStatsForCLI(getAllMemories);
+  
+  if (options.format === "json") {
+    return formatStatsAsJSON(stats);
+  }
+  
+  return formatStatsAsText(stats, options.verbose);
+}

package/src/debug-logger.test.ts

@@ -0,0 +1,233 @@
+/**
+ * DebugLogger Tests (Corrected)
+ * 
+ * Tests matching actual implementation
+ */
+
+import { describe, test, expect, beforeEach, vi } from "vitest";
+import { DebugLogger, type LogEntry } from "./debug-logger";
+import * as fs from "fs";
+
+vi.mock("fs");
+
+describe("DebugLogger", () => {
+  let logger: DebugLogger;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    logger = new DebugLogger({
+      enabled: true,
+      verbose: false,
+      maxEntries: 5,
+    });
+  });
+
+  test("logs are stored when enabled", () => {
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 142,
+      status: "success",
+    });
+
+    const logs = logger.getAllLogs();
+    expect(logs).toHaveLength(1);
+  });
+
+  test("logs are not stored when disabled", () => {
+    const disabledLogger = new DebugLogger({
+      enabled: false,
+      verbose: false,
+      maxEntries: 5,
+    });
+
+    disabledLogger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 142,
+      status: "success",
+    });
+
+    const logs = disabledLogger.getAllLogs();
+    expect(logs).toHaveLength(0);
+  });
+
+  test("respects circular buffer limit (FIFO)", () => {
+    for (let i = 0; i < 10; i++) {
+      logger.log({
+        timestamp: new Date(Date.now() + i).toISOString(),
+        tool: `tool_${i}`,
+        method: "GET",
+        path: `/test/${i}`,
+        duration: 100,
+        status: "success",
+      });
+    }
+
+    const logs = logger.getAllLogs();
+    expect(logs).toHaveLength(5); // maxEntries = 5
+    expect(logs[0].tool).toBe("tool_5"); // Oldest kept
+    expect(logs[4].tool).toBe("tool_9"); // Newest
+  });
+
+  test("getRecentLogs returns last N entries", () => {
+    for (let i = 0; i < 3; i++) {
+      logger.log({
+        timestamp: new Date(Date.now() + i).toISOString(),
+        tool: `tool_${i}`,
+        method: "GET",
+        path: `/test/${i}`,
+        duration: 100,
+        status: "success",
+      });
+    }
+
+    const logs = logger.getRecentLogs(2);
+    expect(logs).toHaveLength(2);
+    expect(logs[0].tool).toBe("tool_1"); // Second-to-last
+    expect(logs[1].tool).toBe("tool_2"); // Last
+  });
+
+  test("getToolLogs filters by tool name", () => {
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 142,
+      status: "success",
+    });
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_recall",
+      method: "POST",
+      path: "/v1/memories/search",
+      duration: 78,
+      status: "success",
+    });
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 156,
+      status: "error",
+      error: "500",
+    });
+
+    const logs = logger.getToolLogs("memory_store", 10);
+    expect(logs).toHaveLength(2);
+    expect(logs.every(l => l.tool === "memory_store")).toBe(true);
+  });
+
+  test("getErrorLogs filters by error status", () => {
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 142,
+      status: "success",
+    });
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_recall",
+      method: "POST",
+      path: "/v1/memories/search",
+      duration: 78,
+      status: "error",
+      error: "404",
+    });
+
+    const logs = logger.getErrorLogs(10);
+    expect(logs).toHaveLength(1);
+    expect(logs[0].status).toBe("error");
+  });
+
+  test("getStats calculates correctly", () => {
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 100,
+      status: "success",
+    });
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_recall",
+      method: "POST",
+      path: "/v1/memories/search",
+      duration: 200,
+      status: "success",
+    });
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 150,
+      status: "error",
+      error: "500",
+    });
+
+    const stats = logger.getStats();
+    expect(stats.total).toBe(3);
+    expect(stats.successful).toBe(2);
+    expect(stats.failed).toBe(1);
+    expect(stats.avgDuration).toBe(150); // (100+200+150)/3 = 150
+  });
+
+  test("clear() empties logs", () => {
+    logger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 142,
+      status: "success",
+    });
+
+    logger.clear();
+    const logs = logger.getAllLogs();
+    expect(logs).toHaveLength(0);
+  });
+
+  test("formatEntry creates human-readable output", () => {
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 142,
+      status: "success",
+    };
+
+    const formatted = DebugLogger.formatEntry(entry);
+    expect(formatted).toContain("memory_store");
+    expect(formatted).toContain("142ms");
+    expect(formatted).toContain("✓");
+  });
+
+  test("formatEntry shows error", () => {
+    const entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 156,
+      status: "error",
+      error: "500 Internal Server Error",
+    };
+
+    const formatted = DebugLogger.formatEntry(entry);
+    expect(formatted).toContain("memory_store");
+    expect(formatted).toContain("156ms");
+    expect(formatted).toContain("✗");
+    expect(formatted).toContain("500 Internal Server Error");
+  });
+});

package/src/debug-logger.ts

@@ -0,0 +1,169 @@
+/**
+ * Debug Logger for MemoryRelay OpenClaw Plugin
+ * 
+ * Provides comprehensive logging of API calls with request/response capture
+ * for troubleshooting and performance analysis.
+ * 
+ * Note: File logging has been removed in v0.8.4 to pass OpenClaw security validation.
+ * All logs are kept in-memory only. Use gateway methods (coming in v0.9.0) to access logs.
+ */
+
+export interface LogEntry {
+  timestamp: string;
+  tool: string;
+  method: string;
+  path: string;
+  duration: number;
+  status: "success" | "error";
+  requestBody?: unknown;
+  responseBody?: unknown;
+  responseStatus?: number;
+  error?: string;
+  retries?: number;
+}
+
+export interface DebugLoggerConfig {
+  enabled: boolean;
+  verbose: boolean;
+  maxEntries: number;
+  logFile?: string; // Deprecated: File logging removed for security compliance
+}
+
+export class DebugLogger {
+  private logs: LogEntry[] = [];
+  private config: DebugLoggerConfig;
+
+  constructor(config: DebugLoggerConfig) {
+    this.config = config;
+    
+    // logFile is no longer supported (v0.8.4)
+    if (config.logFile) {
+      console.warn(
+        "memoryrelay: logFile is deprecated and ignored. " +
+        "Use gateway methods to access debug logs (coming in v0.9.0)"
+      );
+    }
+  }
+
+  /**
+   * Log an API call
+   */
+  log(entry: LogEntry): void {
+    if (!this.config.enabled) return;
+
+    // Add to in-memory buffer
+    this.logs.push(entry);
+    
+    // Trim if exceeds max
+    if (this.logs.length > this.config.maxEntries) {
+      this.logs.shift();
+    }
+  }
+
+  /**
+   * Get recent logs
+   */
+  getRecentLogs(limit: number = 10): LogEntry[] {
+    return this.logs.slice(-limit);
+  }
+
+  /**
+   * Get logs for specific tool
+   */
+  getToolLogs(toolName: string, limit: number = 10): LogEntry[] {
+    return this.logs
+      .filter(log => log.tool === toolName)
+      .slice(-limit);
+  }
+
+  /**
+   * Get error logs only
+   */
+  getErrorLogs(limit: number = 10): LogEntry[] {
+    return this.logs
+      .filter(log => log.status === "error")
+      .slice(-limit);
+  }
+
+  /**
+   * Get all logs
+   */
+  getAllLogs(): LogEntry[] {
+    return [...this.logs];
+  }
+
+  /**
+   * Clear logs
+   */
+  clear(): void {
+    this.logs = [];
+  }
+
+  /**
+   * Get statistics
+   */
+  getStats() {
+    const total = this.logs.length;
+    const successful = this.logs.filter(l => l.status === "success").length;
+    const failed = total - successful;
+    const avgDuration = total > 0
+      ? this.logs.reduce((sum, l) => sum + l.duration, 0) / total
+      : 0;
+
+    return {
+      total,
+      successful,
+      failed,
+      successRate: total > 0 ? (successful / total) * 100 : 0,
+      avgDuration: Math.round(avgDuration),
+    };
+  }
+
+  /**
+   * Format log entry for display
+   */
+  static formatEntry(entry: LogEntry): string {
+    const timestamp = new Date(entry.timestamp).toLocaleTimeString();
+    const status = entry.status === "success" ? "✓" : "✗";
+    const duration = `${entry.duration}ms`;
+    
+    let output = `${timestamp}  ${entry.tool.padEnd(20)} ${duration.padStart(6)}  ${status}`;
+    
+    if (entry.error) {
+      output += `\n          Error: ${entry.error}`;
+    }
+    
+    if (entry.retries && entry.retries > 0) {
+      output += ` (${entry.retries} retries)`;
+    }
+    
+    return output;
+  }
+
+  /**
+   * Format logs as table
+   */
+  static formatTable(logs: LogEntry[]): string {
+    if (logs.length === 0) {
+      return "No logs available";
+    }
+
+    const lines = [
+      "TIMESTAMP          TOOL                    DURATION  STATUS  ERROR",
+      "━━━━━━━━━━━━━━━━━  ━━━━━━━━━━━━━━━━━━━━━  ━━━━━━━━  ━━━━━━  ━━━━━━━━━━━━━━━━━━━━━━━━━",
+    ];
+
+    for (const entry of logs) {
+      const timestamp = new Date(entry.timestamp).toLocaleTimeString();
+      const status = entry.status === "success" ? "✓" : "✗";
+      const duration = `${entry.duration}ms`;
+      const error = entry.error ? entry.error.substring(0, 30) : "";
+      
+      lines.push(
+        `${timestamp}  ${entry.tool.padEnd(20)}  ${duration.padStart(8)}  ${status.padEnd(6)}  ${error}`
+      );
+    }
+
+    return lines.join("\n");
+  }
+}