@memoryrelay/plugin-memoryrelay-ai 0.12.0 → 0.12.1

package/src/heartbeat/daily-stats.ts

@@ -0,0 +1,233 @@
+/**
+ * Daily Memory Stats for Heartbeat (Phase 1 - Issue #10)
+ * 
+ * Provides morning and evening memory stat summaries for agent heartbeat checks.
+ * Shows growth trends, categories, and most valuable memories.
+ */
+
+export interface DailyStatsConfig {
+  enabled: boolean;
+  morningTime?: string; // HH:MM format (default: "09:00")
+  eveningTime?: string; // HH:MM format (default: "20:00")
+  timezone?: string; // IANA timezone (default: system timezone)
+}
+
+export interface MemoryStats {
+  total: number;
+  today: number;
+  thisWeek: number;
+  weeklyGrowth: number; // Percentage change from last week
+  topCategories: Array<{ category: string; count: number }>;
+  mostValuable?: {
+    id: string;
+    content: string;
+    recallCount: number;
+  };
+}
+
+export interface HeartbeatResult {
+  shouldNotify: boolean;
+  message?: string;
+  stats?: MemoryStats;
+}
+
+/**
+ * Calculate memory statistics for the current period
+ */
+export async function calculateStats(
+  getAllMemories: () => Promise<Array<{ id: string; content: string; metadata: Record<string, string>; created_at: number }>>,
+  getRecallCount: (memoryId: string) => number = () => 0
+): Promise<MemoryStats> {
+  const memories = await getAllMemories();
+  const now = Date.now();
+  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;
+
+  // Count memories 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;
+
+  // Calculate weekly growth
+  const weeklyGrowth = lastWeek > 0 ? ((thisWeek - lastWeek) / lastWeek) * 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, 5);
+
+  // Most valuable memory (by recall count - simulated for now)
+  let mostValuable: MemoryStats["mostValuable"];
+  if (memories.length > 0) {
+    const memoriesWithRecalls = memories.map((m) => ({
+      ...m,
+      recallCount: getRecallCount(m.id),
+    }));
+    memoriesWithRecalls.sort((a, b) => b.recallCount - a.recallCount);
+
+    if (memoriesWithRecalls[0].recallCount > 0) {
+      mostValuable = {
+        id: memoriesWithRecalls[0].id,
+        content: memoriesWithRecalls[0].content.slice(0, 100) + "...",
+        recallCount: memoriesWithRecalls[0].recallCount,
+      };
+    }
+  }
+
+  return {
+    total,
+    today,
+    thisWeek,
+    weeklyGrowth,
+    topCategories,
+    mostValuable,
+  };
+}
+
+/**
+ * Morning check: Show memory stats and growth
+ */
+export async function morningCheck(
+  stats: MemoryStats
+): Promise<HeartbeatResult> {
+  // Don't notify if no activity or very early in adoption
+  if (stats.total < 5 && stats.today === 0) {
+    return { shouldNotify: false };
+  }
+
+  // Build morning message
+  const lines: string[] = [];
+  lines.push("📊 Morning Memory Check");
+  lines.push("");
+  lines.push(`📚 Total memories: ${stats.total}`);
+  
+  if (stats.today > 0) {
+    lines.push(`✨ Added today: ${stats.today}`);
+  }
+  
+  if (stats.thisWeek > 0) {
+    const growthIndicator = stats.weeklyGrowth > 0 ? "📈" : stats.weeklyGrowth < 0 ? "📉" : "➡️";
+    lines.push(`${growthIndicator} This week: ${stats.thisWeek} (${stats.weeklyGrowth > 0 ? '+' : ''}${stats.weeklyGrowth.toFixed(0)}%)`);
+  }
+
+  if (stats.topCategories.length > 0) {
+    lines.push("");
+    lines.push("🏆 Top categories:");
+    for (const cat of stats.topCategories.slice(0, 3)) {
+      lines.push(`  • ${cat.category}: ${cat.count}`);
+    }
+  }
+
+  return {
+    shouldNotify: true,
+    message: lines.join("\n"),
+    stats,
+  };
+}
+
+/**
+ * Evening review: Show today's activity and most valuable memory
+ */
+export async function eveningReview(
+  stats: MemoryStats
+): Promise<HeartbeatResult> {
+  // Don't notify if no activity today
+  if (stats.today === 0 && !stats.mostValuable) {
+    return { shouldNotify: false };
+  }
+
+  const lines: string[] = [];
+  lines.push("🌙 Evening Memory Review");
+  lines.push("");
+
+  if (stats.today > 0) {
+    lines.push(`✅ Stored today: ${stats.today} memories`);
+  } else {
+    lines.push("📝 No new memories today");
+  }
+
+  if (stats.mostValuable) {
+    lines.push("");
+    lines.push("💎 Most valuable memory:");
+    lines.push(`  "${stats.mostValuable.content}"`);
+    lines.push(`  Recalled ${stats.mostValuable.recallCount} times`);
+  }
+
+  return {
+    shouldNotify: stats.today > 0 || (stats.mostValuable !== undefined),
+    message: lines.join("\n"),
+    stats,
+  };
+}
+
+/**
+ * Check if it's time for a heartbeat notification
+ */
+export function shouldRunHeartbeat(
+  config: DailyStatsConfig,
+  currentTime: Date = new Date()
+): "morning" | "evening" | null {
+  if (!config.enabled) return null;
+
+  const morningTime = config.morningTime || "09:00";
+  const eveningTime = config.eveningTime || "20:00";
+
+  const [morningHour, morningMin] = morningTime.split(":").map(Number);
+  const [eveningHour, eveningMin] = eveningTime.split(":").map(Number);
+
+  const currentHour = currentTime.getHours();
+  const currentMin = currentTime.getMinutes();
+
+  // Check if within 5-minute window of morning time
+  const morningStart = morningHour * 60 + morningMin;
+  const morningEnd = morningStart + 5;
+  const currentMinutes = currentHour * 60 + currentMin;
+
+  if (currentMinutes >= morningStart && currentMinutes < morningEnd) {
+    return "morning";
+  }
+
+  // Check if within 5-minute window of evening time
+  const eveningStart = eveningHour * 60 + eveningMin;
+  const eveningEnd = eveningStart + 5;
+
+  if (currentMinutes >= eveningStart && currentMinutes < eveningEnd) {
+    return "evening";
+  }
+
+  return null;
+}
+
+/**
+ * Format stats for console/log output
+ */
+export function formatStatsForDisplay(stats: MemoryStats): string {
+  const lines: string[] = [];
+  lines.push(`Total: ${stats.total} | Today: ${stats.today} | Week: ${stats.thisWeek}`);
+  
+  if (stats.weeklyGrowth !== 0) {
+    const sign = stats.weeklyGrowth > 0 ? "+" : "";
+    lines.push(`Growth: ${sign}${stats.weeklyGrowth.toFixed(0)}%`);
+  }
+
+  if (stats.topCategories.length > 0) {
+    const topCats = stats.topCategories
+      .slice(0, 3)
+      .map((c) => `${c.category}(${c.count})`)
+      .join(", ");
+    lines.push(`Top: ${topCats}`);
+  }
+
+  return lines.join(" | ");
+}

package/src/onboarding/first-run.ts

@@ -0,0 +1,236 @@
+/**
+ * First-Run Onboarding Wizard (Phase 1 - Issue #9)
+ * 
+ * Detects first run and guides user through initial setup
+ * Stores first memory, configures auto-capture preferences
+ */
+
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+
+export interface OnboardingState {
+  completed: boolean;
+  completedAt?: number;
+  firstMemoryId?: string;
+  autoCaptureOptIn?: boolean;
+}
+
+export interface OnboardingResult {
+  isFirstRun: boolean;
+  shouldOnboard: boolean;
+  state?: OnboardingState;
+}
+
+/**
+ * Get onboarding state file path
+ */
+function getStateFilePath(): string {
+  const homeDir = os.homedir();
+  const openclawDir = path.join(homeDir, ".openclaw");
+  return path.join(openclawDir, "memoryrelay-onboarding.json");
+}
+
+/**
+ * Check if this is the first run
+ */
+export async function checkFirstRun(
+  getTotalMemories: () => Promise<number>
+): Promise<OnboardingResult> {
+  const stateFile = getStateFilePath();
+  
+  try {
+    // Check if state file exists
+    const stateContent = await fs.readFile(stateFile, "utf-8");
+    const state: OnboardingState = JSON.parse(stateContent);
+    
+    // Already onboarded
+    if (state.completed) {
+      return {
+        isFirstRun: false,
+        shouldOnboard: false,
+        state,
+      };
+    }
+  } catch (err) {
+    // State file doesn't exist - might be first run
+  }
+
+  // Check if there are any memories
+  const totalMemories = await getTotalMemories();
+  
+  // First run if: no state file AND no memories
+  const isFirstRun = totalMemories === 0;
+  
+  return {
+    isFirstRun,
+    shouldOnboard: isFirstRun,
+  };
+}
+
+/**
+ * Mark onboarding as complete
+ */
+export async function markOnboardingComplete(
+  firstMemoryId: string,
+  autoCaptureOptIn: boolean
+): Promise<void> {
+  const stateFile = getStateFilePath();
+  const state: OnboardingState = {
+    completed: true,
+    completedAt: Date.now(),
+    firstMemoryId,
+    autoCaptureOptIn,
+  };
+
+  // Ensure directory exists
+  const dir = path.dirname(stateFile);
+  await fs.mkdir(dir, { recursive: true });
+
+  // Write state file
+  await fs.writeFile(stateFile, JSON.stringify(state, null, 2), "utf-8");
+}
+
+/**
+ * Generate onboarding prompt text
+ */
+export function generateOnboardingPrompt(): string {
+  const lines: string[] = [];
+  
+  lines.push("👋 Welcome to MemoryRelay!");
+  lines.push("");
+  lines.push("This is your first time using MemoryRelay. Let's get you set up!");
+  lines.push("");
+  lines.push("MemoryRelay helps you remember important information across conversations.");
+  lines.push("It uses semantic search to recall relevant context when you need it.");
+  lines.push("");
+  lines.push("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  lines.push("");
+  lines.push("🎯 QUICK START");
+  lines.push("");
+  lines.push("1. Store your first memory (try: 'I prefer concise responses')");
+  lines.push("2. Later, I'll automatically recall it when relevant");
+  lines.push("3. Your memories grow smarter over time");
+  lines.push("");
+  lines.push("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
+  lines.push("");
+  lines.push("⚙️  SMART AUTO-CAPTURE");
+  lines.push("");
+  lines.push("MemoryRelay can automatically detect and store important information:");
+  lines.push("");
+  lines.push("  ✅ Credentials (API keys, connection strings)");
+  lines.push("  ✅ Preferences (communication style, tool choices)");
+  lines.push("  ✅ Technical facts (commands, configs, troubleshooting)");
+  lines.push("  ❌ Personal info (requires your confirmation first)");
+  lines.push("");
+  lines.push("Your first 5 auto-captures will ask for confirmation to ensure");
+  lines.push("you're comfortable with what's being stored. After that, it runs");
+  lines.push("silently in the background.");
+  lines.push("");
+  lines.push("Would you like to enable smart auto-capture? (Recommended)");
+  lines.push("");
+  lines.push("Type 'yes' to enable, or 'no' to manually store memories");
+  lines.push("");
+  
+  return lines.join("\n");
+}
+
+/**
+ * Generate success message after onboarding
+ */
+export function generateSuccessMessage(
+  firstMemoryContent: string,
+  autoCaptureEnabled: boolean
+): string {
+  const lines: string[] = [];
+  
+  lines.push("✅ Onboarding Complete!");
+  lines.push("");
+  lines.push(`Your first memory has been stored:`);
+  lines.push(`"${firstMemoryContent}"`);
+  lines.push("");
+  
+  if (autoCaptureEnabled) {
+    lines.push("🎯 Smart auto-capture is enabled");
+    lines.push("   I'll detect and store important information automatically");
+    lines.push("   (Your first 5 captures will ask for confirmation)");
+  } else {
+    lines.push("📝 Manual mode selected");
+    lines.push("   Use memory_store tool to save memories manually");
+    lines.push("   You can enable auto-capture anytime in config");
+  }
+  
+  lines.push("");
+  lines.push("💡 Quick tips:");
+  lines.push("  • Store preferences, facts, commands, and insights");
+  lines.push("  • I'll automatically recall relevant memories in future conversations");
+  lines.push("  • Check stats anytime with: openclaw gateway-call memoryrelay.stats");
+  lines.push("  • Morning/evening summaries show your memory growth");
+  lines.push("");
+  lines.push("Ready to remember everything! 🚀");
+  lines.push("");
+  
+  return lines.join("\n");
+}
+
+/**
+ * Interactive onboarding flow (for CLI or chat)
+ */
+export async function runOnboardingFlow(
+  storeMemory: (content: string, metadata?: Record<string, string>) => Promise<{ id: string }>,
+  getUserResponse: (prompt: string) => Promise<string>
+): Promise<{
+  completed: boolean;
+  firstMemoryId?: string;
+  autoCaptureEnabled?: boolean;
+}> {
+  // Show welcome
+  const welcomePrompt = generateOnboardingPrompt();
+  const autoCaptureResponse = await getUserResponse(welcomePrompt);
+  
+  // Parse auto-capture preference
+  const autoCaptureEnabled = autoCaptureResponse.toLowerCase().includes("yes");
+  
+  // Prompt for first memory
+  const firstMemoryPrompt = [
+    "",
+    "Great! Let's store your first memory.",
+    "",
+    "What would you like me to remember?",
+    "(Examples: 'I prefer Python', 'My project uses PostgreSQL', 'I'm building a chatbot')",
+    "",
+  ].join("\n");
+  
+  const firstMemoryContent = await getUserResponse(firstMemoryPrompt);
+  
+  // Store first memory
+  const result = await storeMemory(firstMemoryContent, {
+    category: "onboarding",
+    source: "first-run-wizard",
+  });
+  
+  // Mark complete
+  await markOnboardingComplete(result.id, autoCaptureEnabled);
+  
+  return {
+    completed: true,
+    firstMemoryId: result.id,
+    autoCaptureEnabled,
+  };
+}
+
+/**
+ * Simple non-interactive onboarding (for automatic setup)
+ */
+export async function runSimpleOnboarding(
+  storeMemory: (content: string, metadata?: Record<string, string>) => Promise<{ id: string }>,
+  defaultMemory: string = "MemoryRelay onboarding complete",
+  autoCaptureEnabled: boolean = true
+): Promise<void> {
+  const result = await storeMemory(defaultMemory, {
+    category: "system",
+    source: "auto-onboarding",
+  });
+  
+  await markOnboardingComplete(result.id, autoCaptureEnabled);
+}

package/src/status-reporter.test.ts

@@ -0,0 +1,230 @@
+/**
+ * StatusReporter Tests (Simplified)
+ * 
+ * Tests matching actual implementation
+ */
+
+import { describe, test, expect, beforeEach } from "vitest";
+import { StatusReporter, type ConnectionStatus, type PluginConfig, type MemoryStats } from "./status-reporter";
+import { DebugLogger } from "./debug-logger";
+
+describe("StatusReporter", () => {
+  let reporter: StatusReporter;
+  let debugLogger: DebugLogger;
+  let mockConnection: ConnectionStatus;
+  let mockConfig: PluginConfig;
+  let mockStats: MemoryStats;
+
+  beforeEach(() => {
+    debugLogger = new DebugLogger({
+      enabled: true,
+      verbose: false,
+      maxEntries: 100,
+    });
+    reporter = new StatusReporter(debugLogger);
+
+    mockConnection = {
+      status: "connected",
+      endpoint: "https://api.memoryrelay.net",
+      lastCheck: new Date().toISOString(),
+      responseTime: 45,
+    };
+
+    mockConfig = {
+      agentId: "test-agent",
+      autoRecall: true,
+      autoCapture: false,
+      recallLimit: 5,
+      recallThreshold: 0.3,
+      excludeChannels: [],
+    };
+
+    mockStats = {
+      total_memories: 100,
+    };
+  });
+
+  test("records and clears tool failures", () => {
+    reporter.recordFailure("memory_store", "500 Error");
+    let issues = reporter.getIssues();
+    expect(issues).toHaveLength(1);
+    expect(issues[0].tool).toBe("memory_store");
+
+    reporter.recordSuccess("memory_store");
+    issues = reporter.getIssues();
+    expect(issues).toHaveLength(0);
+  });
+
+  test("buildReport creates status report", () => {
+    const toolGroups = {
+      "Core Memory": ["memory_store", "memory_recall"],
+      "Projects": ["project_list"],
+    };
+
+    const report = reporter.buildReport(
+      mockConnection,
+      mockConfig,
+      mockStats,
+      toolGroups,
+    );
+
+    expect(report.connection).toEqual(mockConnection);
+    expect(report.config).toEqual(mockConfig);
+    expect(report.stats).toEqual(mockStats);
+    expect(report.tools["Core Memory"]).toBeDefined();
+    expect(report.tools["Projects"]).toBeDefined();
+  });
+
+  test("buildReport includes tool status from debug logs", () => {
+    debugLogger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 142,
+      status: "success",
+    });
+
+    const toolGroups = {
+      "Core Memory": ["memory_store"],
+    };
+
+    const report = reporter.buildReport(
+      mockConnection,
+      mockConfig,
+      mockStats,
+      toolGroups,
+    );
+
+    const memoryTools = report.tools["Core Memory"];
+    expect(memoryTools.available).toBe(1);
+    expect(memoryTools.failed).toBe(0);
+    expect(memoryTools.tools[0].status).toBe("working");
+  });
+
+  test("buildReport shows failed tools", () => {
+    debugLogger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 156,
+      status: "error",
+      error: "500 Internal Server Error",
+    });
+
+    const toolGroups = {
+      "Core Memory": ["memory_store"],
+    };
+
+    const report = reporter.buildReport(
+      mockConnection,
+      mockConfig,
+      mockStats,
+      toolGroups,
+    );
+
+    const memoryTools = report.tools["Core Memory"];
+    expect(memoryTools.available).toBe(0);
+    expect(memoryTools.failed).toBe(1);
+    expect(memoryTools.tools[0].status).toBe("error");
+    expect(memoryTools.tools[0].error).toBe("500 Internal Server Error");
+  });
+
+  test("buildReport includes recent calls", () => {
+    debugLogger.log({
+      timestamp: new Date().toISOString(),
+      tool: "memory_store",
+      method: "POST",
+      path: "/v1/memories",
+      duration: 142,
+      status: "success",
+    });
+
+    const toolGroups = {
+      "Core Memory": ["memory_store"],
+    };
+
+    const report = reporter.buildReport(
+      mockConnection,
+      mockConfig,
+      mockStats,
+      toolGroups,
+    );
+
+    expect(report.recentCalls).toHaveLength(1);
+    expect(report.recentCalls[0].tool).toBe("memory_store");
+  });
+
+  test("formatReport creates human-readable output", () => {
+    const toolGroups = {
+      "Core Memory": ["memory_store", "memory_recall"],
+    };
+
+    const report = reporter.buildReport(
+      mockConnection,
+      mockConfig,
+      mockStats,
+      toolGroups,
+    );
+
+    const formatted = StatusReporter.formatReport(report);
+    expect(formatted).toContain("MemoryRelay Plugin Status");
+    expect(formatted).toContain("connected");
+    expect(formatted).toContain("Core Memory");
+  });
+
+  test("formatCompact creates brief output", () => {
+    const toolGroups = {
+      "Core Memory": ["memory_store"],
+    };
+
+    const report = reporter.buildReport(
+      mockConnection,
+      mockConfig,
+      mockStats,
+      toolGroups,
+    );
+
+    const compact = StatusReporter.formatCompact(report);
+    expect(compact).toContain("connected");
+    expect(compact.length).toBeLessThan(200); // Should be brief
+  });
+
+  test("handles disconnected status", () => {
+    mockConnection.status = "disconnected";
+
+    const toolGroups = {
+      "Core Memory": ["memory_store"],
+    };
+
+    const report = reporter.buildReport(
+      mockConnection,
+      mockConfig,
+      mockStats,
+      toolGroups,
+    );
+
+    expect(report.connection.status).toBe("disconnected");
+    const formatted = StatusReporter.formatReport(report);
+    expect(formatted).toContain("disconnected");
+  });
+
+  test("includes issues in report", () => {
+    reporter.recordFailure("memory_batch_store", "500 Error");
+
+    const toolGroups = {
+      "Core Memory": ["memory_batch_store"],
+    };
+
+    const report = reporter.buildReport(
+      mockConnection,
+      mockConfig,
+      mockStats,
+      toolGroups,
+    );
+
+    expect(report.issues).toHaveLength(1);
+    expect(report.issues[0].tool).toBe("memory_batch_store");
+  });
+});