@memoryrelay/plugin-memoryrelay-ai 0.11.5 → 0.12.1

package/index.ts

@@ -1,16 +1,37 @@
 /**
  * OpenClaw Memory Plugin - MemoryRelay
- * Version: 0.11.5 (Full Single-File)
+ * Version: 0.12.0 (Phase 1 - Adoption Framework)
  *
  * Long-term memory with vector search using MemoryRelay API.
  * Provides auto-recall and auto-capture via lifecycle hooks.
  * Includes: memories, entities, agents, sessions, decisions, patterns, projects.
+ * New in v0.12.0: Smart auto-capture, daily stats, CLI commands, onboarding
  *
  * API: https://api.memoryrelay.net
  * Docs: https://memoryrelay.ai
  */
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+import {
+  calculateStats,
+  morningCheck,
+  eveningReview,
+  shouldRunHeartbeat,
+  formatStatsForDisplay,
+  type DailyStatsConfig,
+  type MemoryStats,
+} from "./src/heartbeat/daily-stats.js";
+import {
+  statsCommand,
+  type StatsCommandOptions,
+} from "./src/cli/stats-command.js";
+import {
+  checkFirstRun,
+  generateOnboardingPrompt,
+  generateSuccessMessage,
+  runSimpleOnboarding,
+  type OnboardingResult,
+} from "./src/onboarding/first-run.js";
 
 // ============================================================================
 // Constants
@@ -131,7 +152,7 @@ interface MemoryStats {
 interface PluginConfig {
   agentId: string;
   autoRecall: boolean;
-  autoCapture: boolean;
+  autoCapture: AutoCaptureConfig; // Updated in v0.12.0
   recallLimit: number;
   recallThreshold: number;
   excludeChannels: string[];
@@ -283,7 +304,10 @@ class StatusReporter {
       ? `✓ Enabled (limit: ${report.config.recallLimit}, threshold: ${report.config.recallThreshold})`
       : "✗ Disabled";
     lines.push(`  Auto-Recall:   ${recallStatus}`);
-    lines.push(`  Auto-Capture:  ${report.config.autoCapture ? "✓ Enabled" : "✗ Disabled"}`);
+    const captureStatus = report.config.autoCapture.enabled
+      ? `✓ Enabled (tier: ${report.config.autoCapture.tier})`
+      : "✗ Disabled";
+    lines.push(`  Auto-Capture:  ${captureStatus}`);
     if (report.config.defaultProject) {
       lines.push(`  Default Project: ${report.config.defaultProject}`);
     }
@@ -377,17 +401,35 @@ class StatusReporter {
   }
 }
 
+// Auto-capture configuration types (Phase 1 - Issue #12)
+type AutoCaptureTier = "off" | "conservative" | "smart" | "aggressive";
+
+interface AutoCaptureConfig {
+  enabled: boolean;
+  tier: AutoCaptureTier;
+  confirmFirst?: number; // Number of captures to confirm (default: 5)
+  categories?: {
+    credentials?: boolean;
+    preferences?: boolean;
+    technical?: boolean;
+    personal?: boolean;
+  };
+  blocklist?: string[]; // Regex patterns to never capture
+}
+
 interface MemoryRelayConfig {
   apiKey?: string;
   agentId?: string;
   apiUrl?: string;
-  autoCapture?: boolean;
+  autoCapture?: boolean | AutoCaptureConfig; // Enhanced in v0.12.0
   autoRecall?: boolean;
   recallLimit?: number;
   recallThreshold?: number;
   excludeChannels?: string[];
   defaultProject?: string;
   enabledTools?: string;
+  // Daily stats configuration (v0.12.0)
+  dailyStats?: DailyStatsConfig;
   // Debug and logging options (v0.8.0)
   debug?: boolean;
   verbose?: boolean;
@@ -471,6 +513,100 @@ async function fetchWithTimeout(
   }
 }
 
+// ============================================================================
+// Auto-Capture Configuration Helpers (Phase 1 - Issue #12)
+// ============================================================================
+
+/**
+ * Normalize auto-capture config from boolean or object format
+ */
+function normalizeAutoCaptureConfig(
+  config: boolean | AutoCaptureConfig | undefined
+): AutoCaptureConfig {
+  // Default configuration (smart auto-capture enabled by default in v0.12.0)
+  const defaultConfig: AutoCaptureConfig = {
+    enabled: true,
+    tier: "smart",
+    confirmFirst: 5,
+    categories: {
+      credentials: true,
+      preferences: true,
+      technical: true,
+      personal: false, // Privacy: personal info requires confirmation
+    },
+    blocklist: [
+      // Privacy patterns - never auto-capture
+      /password\s*[:=]\s*[^\s]+/i,
+      /credit\s*card/i,
+      /ssn\s*[:=]/i,
+      /social\s*security/i,
+    ].map((r) => r.source),
+  };
+
+  // Handle legacy boolean config
+  if (typeof config === "boolean") {
+    return {
+      ...defaultConfig,
+      enabled: config,
+    };
+  }
+
+  // Handle undefined (use smart default in v0.12.0+)
+  if (config === undefined) {
+    return defaultConfig;
+  }
+
+  // Merge provided config with defaults
+  return {
+    enabled: config.enabled ?? defaultConfig.enabled,
+    tier: config.tier ?? defaultConfig.tier,
+    confirmFirst: config.confirmFirst ?? defaultConfig.confirmFirst,
+    categories: {
+      ...defaultConfig.categories,
+      ...config.categories,
+    },
+    blocklist: config.blocklist ?? defaultConfig.blocklist,
+  };
+}
+
+/**
+ * Check if content matches any blocklist patterns
+ */
+function isBlocklisted(content: string, blocklist: string[]): boolean {
+  return blocklist.some((pattern) => {
+    try {
+      return new RegExp(pattern, "i").test(content);
+    } catch {
+      return false; // Invalid regex, skip
+    }
+  });
+}
+
+/**
+ * Mask sensitive data in content (API keys, tokens, etc.)
+ */
+function maskSensitiveData(content: string): string {
+  // Mask API keys (show only last 4 chars)
+  content = content.replace(
+    /\b([a-z]{2,}_)?([a-z]{4,}_)?[a-f0-9]{32,}\b/gi,
+    (match) => {
+      if (match.length <= 8) return match;
+      return `${match.slice(0, 4)}...${match.slice(-4)}`;
+    }
+  );
+
+  // Mask email addresses (show only domain)
+  content = content.replace(
+    /\b[a-z0-9._%+-]+@[a-z0-9.-]+\.[a-z]{2,}\b/gi,
+    (match) => {
+      const domain = match.split("@")[1];
+      return `***@${domain}`;
+    }
+  );
+
+  return content;
+}
+
 // ============================================================================
 // MemoryRelay API Client (Full Suite)
 // ============================================================================
@@ -1208,11 +1344,13 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
         total_memories: memoryCount,
       };
       
-      // Get config
+      // Get config - normalize autoCapture to new format
+      const autoCaptureConfig = normalizeAutoCaptureConfig(cfg?.autoCapture);
+      
       const pluginConfig = {
         agentId: agentId,
         autoRecall: cfg?.autoRecall ?? true,
-        autoCapture: cfg?.autoCapture ?? false,
+        autoCapture: autoCaptureConfig,
         recallLimit: cfg?.recallLimit ?? 5,
         recallThreshold: cfg?.recallThreshold ?? 0.3,
         excludeChannels: cfg?.excludeChannels ?? [],
@@ -3641,7 +3779,9 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   });
 
   // Auto-capture: analyze and store important information after agent ends
-  if (cfg?.autoCapture) {
+  const autoCaptureConfig = normalizeAutoCaptureConfig(cfg?.autoCapture);
+  
+  if (autoCaptureConfig.enabled) {
     api.on("agent_end", async (event) => {
       if (!event.success || !event.messages || event.messages.length === 0) {
         return;
@@ -3673,7 +3813,13 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
           }
         }
 
-        const toCapture = texts.filter((text) => text && shouldCapture(text));
+        const toCapture = texts.filter((text) => {
+          if (!text || !shouldCapture(text)) return false;
+          // Check blocklist
+          if (isBlocklisted(text, autoCaptureConfig.blocklist || [])) return false;
+          return true;
+        });
+        
         if (toCapture.length === 0) return;
 
         let stored = 0;
@@ -3696,9 +3842,43 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   }
 
   api.logger.info?.(
-    `memory-memoryrelay: plugin v0.11.4 loaded (39 tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${cfg?.autoCapture}, debug: ${debugEnabled})`,
+    `memory-memoryrelay: plugin v0.12.0 loaded (39 tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${autoCaptureConfig.enabled ? autoCaptureConfig.tier : 'off'}, debug: ${debugEnabled})`,
   );
 
+  // ========================================================================
+  // First-Run Onboarding (Phase 1 - Issue #9)
+  // ========================================================================
+
+  // Check if this is the first run and auto-onboard if needed
+  try {
+    const onboardingCheck = await checkFirstRun(async () => {
+      const memories = await client.list(1);
+      return memories.length;
+    });
+
+    if (onboardingCheck.shouldOnboard) {
+      // Auto-onboard with simple setup
+      await runSimpleOnboarding(
+        async (content, metadata) => {
+          const memory = await client.store(content, metadata || {});
+          return { id: memory.id };
+        },
+        "Welcome to MemoryRelay! This is your first memory. Use memory_store to add more.",
+        autoCaptureConfig.enabled
+      );
+
+      const successMsg = generateSuccessMessage(
+        "Welcome to MemoryRelay! This is your first memory.",
+        autoCaptureConfig.enabled
+      );
+
+      api.logger.info?.(`\n${successMsg}`);
+    }
+  } catch (err) {
+    // Don't fail plugin load if onboarding fails
+    api.logger.warn?.(`memory-memoryrelay: onboarding check failed: ${String(err)}`);
+  }
+
   // ========================================================================
   // CLI Helper Tools (v0.8.0)
   // ========================================================================
@@ -3860,6 +4040,92 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
     });
   }
 
+  // memoryrelay:heartbeat - Daily stats check (Phase 1 - Issue #10)
+  api.registerGatewayMethod?.("memoryrelay.heartbeat", async ({ respond, args }) => {
+    try {
+      const dailyStatsConfig: DailyStatsConfig = {
+        enabled: cfg?.dailyStats?.enabled ?? true,
+        morningTime: cfg?.dailyStats?.morningTime || "09:00",
+        eveningTime: cfg?.dailyStats?.eveningTime || "20:00",
+      };
+
+      // Check if it's time for a heartbeat
+      const heartbeatType = shouldRunHeartbeat(dailyStatsConfig);
+      
+      if (!heartbeatType) {
+        respond(true, {
+          type: "none",
+          message: "Not scheduled for heartbeat check right now",
+        });
+        return;
+      }
+
+      // Calculate stats
+      const memories = await client.list(1000); // Get recent memories
+      const stats = await calculateStats(
+        async () => memories,
+        () => 0 // Recall count not tracked yet (Phase 3)
+      );
+
+      // Run appropriate check
+      let result;
+      if (heartbeatType === "morning") {
+        result = await morningCheck(stats);
+      } else {
+        result = await eveningReview(stats);
+      }
+
+      respond(true, {
+        type: heartbeatType,
+        shouldNotify: result.shouldNotify,
+        message: result.message,
+        stats: result.stats,
+      });
+    } catch (err) {
+      respond(false, { error: String(err) });
+    }
+  });
+
+  // memoryrelay:onboarding - Show onboarding prompt (Phase 1 - Issue #9)
+  api.registerGatewayMethod?.("memoryrelay.onboarding", async ({ respond }) => {
+    try {
+      const onboardingCheck = await checkFirstRun(async () => {
+        const memories = await client.list(1);
+        return memories.length;
+      });
+
+      const prompt = generateOnboardingPrompt();
+
+      respond(true, {
+        isFirstRun: onboardingCheck.isFirstRun,
+        alreadyOnboarded: onboardingCheck.state?.completed || false,
+        prompt,
+      });
+    } catch (err) {
+      respond(false, { error: String(err) });
+    }
+  });
+
+  // memoryrelay:stats - CLI stats command (Phase 1 - Issue #11)
+  api.registerGatewayMethod?.("memoryrelay.stats", async ({ respond, args }) => {
+    try {
+      const options: StatsCommandOptions = {
+        format: (args?.format as "text" | "json") || "text",
+        verbose: Boolean(args?.verbose),
+      };
+
+      const memories = await client.list(1000);
+      const output = await statsCommand(async () => memories, options);
+
+      respond(true, {
+        output,
+        format: options.format,
+      });
+    } catch (err) {
+      respond(false, { error: String(err) });
+    }
+  });
+
   // memoryrelay:test - Test individual tool
   api.registerGatewayMethod?.("memoryrelay.test", async ({ respond, args }) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@memoryrelay/plugin-memoryrelay-ai",
-  "version": "0.11.5",
+  "version": "0.12.1",
   "description": "OpenClaw memory plugin for MemoryRelay API - sessions, decisions, patterns, projects & semantic search",
   "type": "module",
   "main": "index.ts",
@@ -33,8 +33,10 @@
     "openclaw": ">=2026.2.0"
   },
   "devDependencies": {
-    "vitest": "^1.2.0",
-    "@vitest/coverage-v8": "^1.2.0"
+    "@types/node": "^25.3.5",
+    "@vitest/coverage-v8": "^1.2.0",
+    "typescript": "^5.9.3",
+    "vitest": "^1.2.0"
   },
   "openclaw": {
     "extensions": [
@@ -45,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);
+}