@memoryrelay/plugin-memoryrelay-ai 0.12.11 → 0.14.0

package/index.ts

@@ -1,12 +1,13 @@
 /**
  * OpenClaw Memory Plugin - MemoryRelay
- * Version: 0.12.8 (Session Context Integration)
+ * Version: 0.13.0 (SDK Enhancements)
  *
  * 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.6: OpenClaw session context integration for session tracking
- * New in v0.12.3: Smart auto-capture, daily stats, CLI commands, onboarding
+ * New in v0.13.0: External session IDs, get-or-create sessions, multi-agent collaboration
+ * New in v0.12.7: OpenClaw session context integration for session tracking
+ * New in v0.12.0: Smart auto-capture, daily stats, CLI commands, onboarding
  *
  * API: https://api.memoryrelay.net
  * Docs: https://memoryrelay.ai
@@ -583,6 +584,44 @@ function isBlocklisted(content: string, blocklist: string[]): boolean {
   });
 }
 
+/**
+ * Redact sensitive patterns from content using the blocklist.
+ * Returns the content with matches replaced by [REDACTED].
+ */
+function redactSensitive(content: string, blocklist: string[]): string {
+  let redacted = content;
+  for (const pattern of blocklist) {
+    try {
+      redacted = redacted.replace(new RegExp(pattern, "gi"), "[REDACTED]");
+    } catch {
+      // Invalid regex, skip
+    }
+  }
+  return redacted;
+}
+
+/**
+ * Extract storable content from messages about to be lost (compaction/reset).
+ * Only keeps assistant messages longer than 200 chars.
+ * Respects the privacy blocklist.
+ */
+function extractRescueContent(
+  messages: unknown[],
+  blocklist: string[]
+): string[] {
+  const rescued: string[] = [];
+  for (const msg of messages) {
+    if (!msg || typeof msg !== "object") continue;
+    const m = msg as Record<string, unknown>;
+    if (m.role !== "assistant") continue;
+    const content = typeof m.content === "string" ? m.content : "";
+    if (content.length < 200) continue;
+    if (isBlocklisted(content, blocklist)) continue;
+    rescued.push(content.slice(0, 500));
+  }
+  return rescued.slice(0, 3);
+}
+
 /**
  * Mask sensitive data in content (API keys, tokens, etc.)
  */
@@ -670,7 +709,7 @@ class MemoryRelayClient {
           headers: {
             "Content-Type": "application/json",
             Authorization: `Bearer ${this.apiKey}`,
-            "User-Agent": "openclaw-memory-memoryrelay/0.8.0",
+            "User-Agent": "openclaw-memory-memoryrelay/0.13.0",
           },
           body: body ? JSON.stringify(body) : undefined,
         },
@@ -1020,6 +1059,7 @@ class MemoryRelayClient {
     project?: string,
     tags?: string[],
     status?: string,
+    metadata?: Record<string, string>,
   ): Promise<any> {
     return this.request("POST", "/v1/decisions", {
       title,
@@ -1028,6 +1068,7 @@ class MemoryRelayClient {
       project_slug: project,
       tags,
       status,
+      metadata,
       agent_id: this.agentId,
     });
   }
@@ -1314,7 +1355,9 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   const verboseEnabled = cfg?.verbose || false;
   const logFile = cfg?.logFile;
   const maxLogEntries = cfg?.maxLogEntries || 100;
-  
+  const sessionTimeoutMs = ((cfg?.sessionTimeoutMinutes as number) || 120) * 60 * 1000;
+  const sessionCleanupIntervalMs = ((cfg?.sessionCleanupIntervalMinutes as number) || 30) * 60 * 1000;
+
   let debugLogger: DebugLogger | undefined;
   let statusReporter: StatusReporter | undefined;
   
@@ -1333,14 +1376,14 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   const client = new MemoryRelayClient(apiKey, agentId, apiUrl, debugLogger, statusReporter);
 
   // ========================================================================
-  // Session Cache for External Session IDs (v0.12.11)
+  // Session Cache for External Session IDs (v0.13.0)
   // ========================================================================
   
   /**
    * Cache mapping: external_id → MemoryRelay session_id
    * Enables multi-agent collaboration and conversation-spanning sessions
    */
-  const sessionCache = new Map<string, string>();
+  const sessionCache = new Map<string, { sessionId: string; lastActivityAt: number }>();
   
   /**
    * Get or create MemoryRelay session for current workspace/project context.
@@ -1369,10 +1412,9 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
     
     // Check cache first
     if (sessionCache.has(externalId)) {
-      if (debugLogger) {
-        debugLogger.log(`Session: Cache hit for external_id="${externalId}"`, "info");
-      }
-      return sessionCache.get(externalId)!;
+      api.logger.debug?.(`Session: Cache hit for external_id="${externalId}"`);
+      touchSession(externalId);
+      return sessionCache.get(externalId)!.sessionId;
     }
     
     try {
@@ -1386,24 +1428,26 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
       );
       
       // Cache the mapping
-      sessionCache.set(externalId, response.id);
+      sessionCache.set(externalId, { sessionId: response.id, lastActivityAt: Date.now() });
       
-      if (debugLogger) {
-        debugLogger.log(
-          `Session: ${response.created ? 'Created' : 'Retrieved'} session ${response.id} for external_id="${externalId}"`,
-          "info"
-        );
-      }
+      api.logger.debug?.(
+        `Session: ${response.created ? 'Created' : 'Retrieved'} session ${response.id} for external_id="${externalId}"`
+      );
       
       return response.id;
     } catch (err) {
-      if (debugLogger) {
-        debugLogger.log(`Session: Failed to get-or-create session for ${externalId}: ${String(err)}`, "error");
-      }
+      api.logger.debug?.(`Session: Failed to get-or-create session for ${externalId}: ${String(err)}`);
       return null;
     }
   }
 
+  function touchSession(externalId: string): void {
+    const entry = sessionCache.get(externalId);
+    if (entry) {
+      entry.lastActivityAt = Date.now();
+    }
+  }
+
   // Verify connection on startup (with timeout)
   try {
     await client.health();
@@ -1632,8 +1676,14 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
           },
         ) => {
           try {
-            const { content, metadata, session_id: explicitSessionId, ...opts } = args;
-            
+            const { content, metadata: rawMetadata, session_id: explicitSessionId, ...opts } = args;
+
+            // Auto-tag with sender identity from tool context
+            const metadata = rawMetadata || {};
+            if (ctx.requesterSenderId && !metadata.sender_id) {
+              metadata.sender_id = ctx.requesterSenderId;
+            }
+
             // Apply defaultProject fallback before session resolution
             if (!opts.project && defaultProject) opts.project = defaultProject;
 
@@ -2051,6 +2101,17 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
           args: { memories: Array<{ content: string; metadata?: Record<string, string> }> },
         ) => {
           try {
+            // Auto-tag each memory with sender identity from tool context
+            if (ctx.requesterSenderId) {
+              for (const mem of args.memories) {
+                const metadata = mem.metadata || {};
+                if (!metadata.sender_id) {
+                  metadata.sender_id = ctx.requesterSenderId;
+                }
+                mem.metadata = metadata;
+              }
+            }
+
             const result = await client.batchStore(args.memories);
             return {
               content: [
@@ -2732,6 +2793,11 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
               description: "Decision status.",
               enum: ["active", "experimental"],
             },
+            metadata: {
+              type: "object",
+              description: "Optional key-value metadata to attach to the decision.",
+              additionalProperties: { type: "string" },
+            },
           },
           required: ["title", "rationale"],
         },
@@ -2744,10 +2810,18 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
             project?: string;
             tags?: string[];
             status?: string;
+            metadata?: Record<string, string>;
           },
         ) => {
           try {
             const project = args.project ?? defaultProject;
+
+            // Merge user-provided metadata with sender identity from tool context
+            const metadata: Record<string, string> = { ...(args.metadata ?? {}) };
+            if (ctx.requesterSenderId) {
+              metadata.sender_id = ctx.requesterSenderId;
+            }
+
             const result = await client.recordDecision(
               args.title,
               args.rationale,
@@ -2755,6 +2829,7 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
               project,
               args.tags,
               args.status,
+              Object.keys(metadata).length > 0 ? metadata : undefined,
             );
             return {
               content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
@@ -3969,8 +4044,199 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
     });
   }
 
+  // Session sync: auto-create MemoryRelay session when OpenClaw session starts
+  api.on("session_start", async (event, _ctx) => {
+    try {
+      const externalId = event.sessionKey || event.sessionId;
+      if (!externalId) return;
+
+      const response = await client.getOrCreateSession(
+        externalId,
+        agentId,
+        `OpenClaw session ${externalId}`,
+        defaultProject || undefined,
+        { source: "openclaw-plugin", agent: agentId, trigger: "session_start_hook" },
+      );
+
+      sessionCache.set(externalId, {
+        sessionId: response.id,
+        lastActivityAt: Date.now(),
+      });
+
+      api.logger.debug?.(`memory-memoryrelay: auto-created session ${response.id} for OpenClaw session ${externalId}`);
+    } catch (err) {
+      api.logger.warn?.(`memory-memoryrelay: session_start hook failed: ${String(err)}`);
+    }
+  });
+
+  // Session sync: auto-end MemoryRelay session when OpenClaw session ends
+  api.on("session_end", async (event, _ctx) => {
+    try {
+      const externalId = event.sessionKey || event.sessionId;
+      if (!externalId) return;
+
+      const entry = sessionCache.get(externalId);
+      if (!entry) return;
+
+      await client.endSession(entry.sessionId, `Session ended after ${event.messageCount} messages`);
+      sessionCache.delete(externalId);
+
+      api.logger.debug?.(`memory-memoryrelay: auto-ended session ${entry.sessionId}`);
+    } catch (err) {
+      api.logger.warn?.(`memory-memoryrelay: session_end hook failed: ${String(err)}`);
+    }
+  });
+
+  // ==========================================================================
+  // Tool Observation Hooks
+  // ==========================================================================
+
+  // Tool observation: no-op, registered for future extensibility
+  api.on("before_tool_call", (_event, _ctx) => {
+    // Reserved for future: tool blocking, param injection, audit
+  });
+
+  // Tool observation: update session activity + log metrics
+  api.on("after_tool_call", (event, _ctx) => {
+    // Update activity timestamp on all active sessions
+    for (const entry of sessionCache.values()) {
+      entry.lastActivityAt = Date.now();
+    }
+
+    // Log to debug logger if enabled
+    if (debugLogger) {
+      debugLogger.log({
+        timestamp: new Date().toISOString(),
+        tool: event.toolName,
+        method: "tool_call",
+        path: "",
+        duration: event.durationMs || 0,
+        status: event.error ? "error" : "success",
+        error: event.error,
+      });
+    }
+  });
+
+  // Compaction rescue: save key context before it's lost
+  api.on("before_compaction", async (event, _ctx) => {
+    if (!event.messages || event.messages.length === 0) return;
+    try {
+      const rescued = extractRescueContent(event.messages, autoCaptureConfig.blocklist || []);
+      for (const content of rescued) {
+        await client.store(content, {
+          category: "compaction-rescue",
+          source: "auto-compaction",
+          agent: agentId,
+        });
+      }
+      if (rescued.length > 0) {
+        api.logger.info?.(`memory-memoryrelay: rescued ${rescued.length} memories before compaction`);
+      }
+    } catch (err) {
+      api.logger.warn?.(`memory-memoryrelay: compaction rescue failed: ${String(err)}`);
+    }
+  });
+
+  // Session reset rescue: save key context before session is cleared
+  api.on("before_reset", async (event, _ctx) => {
+    if (!event.messages || event.messages.length === 0) return;
+    try {
+      const rescued = extractRescueContent(event.messages, autoCaptureConfig.blocklist || []);
+      for (const content of rescued) {
+        await client.store(content, {
+          category: "session-reset-rescue",
+          source: "auto-reset",
+          agent: agentId,
+        });
+      }
+      if (rescued.length > 0) {
+        api.logger.info?.(`memory-memoryrelay: rescued ${rescued.length} memories before reset`);
+      }
+    } catch (err) {
+      api.logger.warn?.(`memory-memoryrelay: reset rescue failed: ${String(err)}`);
+    }
+  });
+
+  // Message processing hooks: activity tracking and privacy redaction
+  api.on("message_received", (_event, _ctx) => {
+    // Update activity timestamps on active sessions
+    for (const entry of sessionCache.values()) {
+      entry.lastActivityAt = Date.now();
+    }
+  });
+
+  api.on("message_sending", (_event, _ctx) => {
+    // No-op: registered for future extensibility
+  });
+
+  api.on("before_message_write", (event, _ctx) => {
+    const blocklist = autoCaptureConfig.blocklist || [];
+    if (blocklist.length === 0) return;
+
+    const msg = event.message;
+    if (!msg || typeof msg !== "object") return;
+
+    const m = msg as Record<string, unknown>;
+    if (typeof m.content === "string" && isBlocklisted(m.content, blocklist)) {
+      return {
+        message: {
+          ...msg,
+          content: redactSensitive(m.content as string, blocklist),
+        } as typeof msg,
+      };
+    }
+  });
+
+  // Subagent lifecycle hooks: track multi-agent collaboration
+  api.on("subagent_spawned", async (event, _ctx) => {
+    try {
+      api.logger.debug?.(
+        `memory-memoryrelay: subagent spawned: ${event.agentId} (session: ${event.childSessionKey}, label: ${event.label || "none"})`
+      );
+    } catch (err) {
+      api.logger.warn?.(`memory-memoryrelay: subagent_spawned hook failed: ${String(err)}`);
+    }
+  });
+
+  api.on("subagent_ended", async (event, _ctx) => {
+    try {
+      const outcome = event.outcome || "unknown";
+      const summary = `Subagent ${event.targetSessionKey} ended: ${event.reason} (outcome: ${outcome})`;
+
+      await client.store(summary, {
+        category: "subagent-activity",
+        source: "subagent_ended_hook",
+        agent: agentId,
+        outcome,
+      });
+
+      api.logger.debug?.(`memory-memoryrelay: stored subagent completion: ${summary}`);
+    } catch (err) {
+      api.logger.warn?.(`memory-memoryrelay: subagent_ended hook failed: ${String(err)}`);
+    }
+  });
+
+  // Tool result redaction: apply privacy blocklist before persistence
+  api.on("tool_result_persist", (event, _ctx) => {
+    const blocklist = autoCaptureConfig.blocklist || [];
+    if (blocklist.length === 0) return;
+
+    const msg = event.message;
+    if (!msg || typeof msg !== "object") return;
+
+    const m = msg as Record<string, unknown>;
+    if (typeof m.content === "string" && isBlocklisted(m.content, blocklist)) {
+      return {
+        message: {
+          ...msg,
+          content: redactSensitive(m.content as string, blocklist),
+        } as typeof msg,
+      };
+    }
+  });
+
   api.logger.info?.(
-    `memory-memoryrelay: plugin v0.12.11 loaded (39 tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${autoCaptureConfig.enabled ? autoCaptureConfig.tier : 'off'}, debug: ${debugEnabled})`,
+    `memory-memoryrelay: plugin v0.13.0 loaded (39 tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${autoCaptureConfig.enabled ? autoCaptureConfig.tier : 'off'}, debug: ${debugEnabled})`,
   );
 
   // ========================================================================
@@ -4030,7 +4296,9 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
           logs = debugLogger.getRecentLogs(limit);
         }
 
-        const formatted = DebugLogger.formatTable(logs);
+        const formatted = logs.map((l) =>
+          `[${new Date(l.timestamp).toISOString()}] ${l.level.toUpperCase()} ${l.tool ?? "-"}: ${l.message}`
+        ).join("\n");
         respond(true, {
           logs,
           formatted,
@@ -4316,4 +4584,746 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
       respond(false, { error: String(err) });
     }
   });
+
+  // ========================================================================
+  // Command Argument Parser (v0.14.0)
+  // ========================================================================
+
+  function parseCommandArgs(input: string | undefined): { positional: string[]; flags: Record<string, string | boolean> } {
+    const positional: string[] = [];
+    const flags: Record<string, string | boolean> = {};
+
+    if (!input || input.trim() === "") {
+      return { positional, flags };
+    }
+
+    const tokens: string[] = [];
+    let current = "";
+    let inQuote: string | null = null;
+
+    for (const ch of input) {
+      if (inQuote) {
+        if (ch === inQuote) {
+          inQuote = null;
+        } else {
+          current += ch;
+        }
+      } else if (ch === '"' || ch === "'") {
+        inQuote = ch;
+      } else if (ch === " " || ch === "\t") {
+        if (current) {
+          tokens.push(current);
+          current = "";
+        }
+      } else {
+        current += ch;
+      }
+    }
+    if (current) tokens.push(current);
+
+    let i = 0;
+    while (i < tokens.length) {
+      const token = tokens[i];
+      if (token.startsWith("--")) {
+        const key = token.slice(2);
+        const next = tokens[i + 1];
+        if (next && !next.startsWith("--")) {
+          flags[key] = next;
+          i += 2;
+        } else {
+          flags[key] = true;
+          i += 1;
+        }
+      } else {
+        positional.push(token);
+        i += 1;
+      }
+    }
+
+    return { positional, flags };
+  }
+
+  // ========================================================================
+  // Direct Commands (15 total) — bypass LLM, execute immediately
+  // ========================================================================
+
+  // /memory-status — Show full plugin status report
+  api.registerCommand?.({
+    name: "memory-status",
+    description: "Show MemoryRelay connection status, tool counts, and memory stats",
+    requireAuth: true,
+    handler: async (_ctx) => {
+      try {
+        // Get connection status via health check
+        const startTime = Date.now();
+        const healthResult = await client.health();
+        const responseTime = Date.now() - startTime;
+
+        const healthStatus = String(healthResult.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) {
+          // stats endpoint may be unavailable
+        }
+
+        const memoryStats = { total_memories: memoryCount };
+
+        const pluginConfig = {
+          agentId,
+          autoRecall: cfg?.autoRecall ?? true,
+          autoCapture: autoCaptureConfig,
+          recallLimit: cfg?.recallLimit ?? 5,
+          recallThreshold: cfg?.recallThreshold ?? 0.3,
+          excludeChannels: cfg?.excludeChannels ?? [],
+          defaultProject,
+        };
+
+        if (statusReporter) {
+          const report = statusReporter.buildReport(
+            connectionStatus,
+            pluginConfig,
+            memoryStats,
+            TOOL_GROUPS,
+          );
+          const formatted = StatusReporter.formatReport(report);
+          return { text: formatted };
+        }
+
+        // Fallback: simple text status
+        return {
+          text: `MemoryRelay: ${isConnected ? "connected" : "disconnected"} | Endpoint: ${apiUrl} | Memories: ${memoryCount} | Agent: ${agentId}`,
+        };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-stats — Show daily memory statistics
+  api.registerCommand?.({
+    name: "memory-stats",
+    description: "Show daily memory statistics (total, today, weekly growth, top categories)",
+    requireAuth: true,
+    handler: async (_ctx) => {
+      try {
+        const memories = await client.list(1000);
+        const stats = await calculateStats(
+          async () => memories,
+          () => 0,
+        );
+        const formatted = formatStatsForDisplay(stats);
+        return { text: formatted };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-health — Quick health check with response time
+  api.registerCommand?.({
+    name: "memory-health",
+    description: "Check MemoryRelay API health and response time",
+    requireAuth: true,
+    handler: async (_ctx) => {
+      try {
+        const startTime = Date.now();
+        const healthResult = await client.health();
+        const responseTime = Date.now() - startTime;
+
+        const healthStatus = String(healthResult.status).toLowerCase();
+        const isHealthy = VALID_HEALTH_STATUSES.includes(healthStatus);
+        const symbol = isHealthy ? "OK" : "DEGRADED";
+
+        return {
+          text: `MemoryRelay Health: ${symbol}\n  Status:        ${healthResult.status}\n  Response Time: ${responseTime}ms\n  Endpoint:      ${apiUrl}`,
+        };
+      } catch (err) {
+        return { text: `MemoryRelay Health: UNREACHABLE\n  Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-logs — Show recent debug log entries
+  api.registerCommand?.({
+    name: "memory-logs",
+    description: "Show recent MemoryRelay debug log entries",
+    requireAuth: true,
+    handler: async (_ctx) => {
+      try {
+        if (!debugLogger) {
+          return { text: "Debug logging is disabled. Enable it with debug: true in plugin config." };
+        }
+
+        const logs = debugLogger.getRecentLogs(10);
+        if (logs.length === 0) {
+          return { text: "No recent log entries." };
+        }
+
+        const lines: string[] = ["Recent MemoryRelay Logs", "━".repeat(50)];
+        for (const entry of logs) {
+          const statusSymbol = entry.status === "success" ? "OK" : "ERR";
+          lines.push(
+            `[${entry.timestamp}] ${statusSymbol} ${entry.method} ${entry.path} (${entry.duration}ms)` +
+            (entry.error ? ` - ${entry.error}` : ""),
+          );
+        }
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-metrics — Show per-tool performance metrics
+  api.registerCommand?.({
+    name: "memory-metrics",
+    description: "Show per-tool call counts, success rates, and latency metrics",
+    requireAuth: true,
+    handler: async (_ctx) => {
+      try {
+        if (!debugLogger) {
+          return { text: "Debug logging is disabled. Enable it with debug: true in plugin config." };
+        }
+
+        const allLogs = debugLogger.getAllLogs();
+        if (allLogs.length === 0) {
+          return { text: "No metrics data available yet." };
+        }
+
+        // Build per-tool metrics
+        const toolMetrics = new Map<string, { calls: number; successes: number; durations: number[] }>();
+        for (const entry of allLogs) {
+          let metrics = toolMetrics.get(entry.tool);
+          if (!metrics) {
+            metrics = { calls: 0, successes: 0, durations: [] };
+            toolMetrics.set(entry.tool, metrics);
+          }
+          metrics.calls++;
+          if (entry.status === "success") metrics.successes++;
+          metrics.durations.push(entry.duration);
+        }
+
+        // Format table
+        const lines: string[] = [
+          "MemoryRelay Tool Metrics",
+          "━".repeat(65),
+          `${"Tool".padEnd(22)} ${"Calls".padStart(6)} ${"Success%".padStart(9)} ${"Avg(ms)".padStart(8)} ${"P95(ms)".padStart(8)}`,
+          "─".repeat(65),
+        ];
+
+        for (const [tool, m] of Array.from(toolMetrics.entries()).sort((a, b) => b[1].calls - a[1].calls)) {
+          const successRate = m.calls > 0 ? ((m.successes / m.calls) * 100).toFixed(1) : "0.0";
+          const avg = m.durations.length > 0
+            ? Math.round(m.durations.reduce((s, d) => s + d, 0) / m.durations.length)
+            : 0;
+          const sorted = [...m.durations].sort((a, b) => a - b);
+          const p95idx = Math.min(Math.ceil(sorted.length * 0.95) - 1, sorted.length - 1);
+          const p95 = sorted.length > 0 ? sorted[Math.max(0, p95idx)] : 0;
+
+          lines.push(
+            `${tool.padEnd(22)} ${String(m.calls).padStart(6)} ${(successRate + "%").padStart(9)} ${String(avg).padStart(8)} ${String(p95).padStart(8)}`,
+          );
+        }
+
+        lines.push("─".repeat(65));
+        lines.push(`Total entries: ${allLogs.length}`);
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // ========================================================================
+  // Direct Commands (10 new — v0.14.0)
+  // ========================================================================
+
+  // /memory-search — Semantic memory search
+  api.registerCommand?.({
+    name: "memory-search",
+    description: "Semantic search across stored memories",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { positional, flags } = parseCommandArgs(ctx.args);
+        const query = positional[0];
+        if (!query) {
+          return { text: "Usage: /memory-search <query> [--limit 10] [--project slug] [--threshold 0.3]" };
+        }
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 10;
+        const threshold = flags["threshold"] ? parseFloat(String(flags["threshold"])) : 0.3;
+        const project = flags["project"] ? String(flags["project"]) : undefined;
+
+        const results = await client.search(query, limit, threshold, { project });
+        const items: unknown[] = Array.isArray(results) ? results : (results as { data?: unknown[] }).data ?? [];
+
+        if (items.length === 0) {
+          return { text: `No memories found for: "${query}"` };
+        }
+
+        const lines: string[] = [`Memory Search: "${query}"`, "━".repeat(60)];
+        for (const item of items) {
+          const m = item as Record<string, unknown>;
+          const content = String(m["content"] ?? "").slice(0, 120);
+          const score = typeof m["similarity"] === "number" ? `${Math.round(m["similarity"] as number * 100)}%` : "N/A";
+          const category = String(m["category"] ?? "general");
+          const date = m["created_at"] ? new Date(String(m["created_at"])).toLocaleDateString() : "unknown";
+          const id = String(m["id"] ?? "");
+          lines.push(`[${score}] ${content}`);
+          lines.push(`  Category: ${category} | Date: ${date} | ID: ${id}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-validate — Production readiness check
+  api.registerCommand?.({
+    name: "memory-validate",
+    description: "Run production readiness checks for the MemoryRelay plugin",
+    requireAuth: true,
+    handler: async (_ctx) => {
+      try {
+        const results: Array<{ label: string; status: "PASS" | "FAIL" | "WARN"; detail: string }> = [];
+
+        // 1. API connectivity
+        try {
+          await client.health();
+          results.push({ label: "API connectivity", status: "PASS", detail: "Health endpoint reachable" });
+        } catch (err) {
+          results.push({ label: "API connectivity", status: "FAIL", detail: String(err) });
+        }
+
+        // 2. API health status
+        try {
+          const h = await client.health();
+          const statusStr = String(h.status).toLowerCase();
+          if (VALID_HEALTH_STATUSES.includes(statusStr)) {
+            results.push({ label: "API health", status: "PASS", detail: `Status: ${h.status}` });
+          } else {
+            results.push({ label: "API health", status: "WARN", detail: `Unexpected status: ${h.status}` });
+          }
+        } catch (err) {
+          results.push({ label: "API health", status: "FAIL", detail: String(err) });
+        }
+
+        // 3. Core tools
+        const allTools = Object.values(TOOL_GROUPS).flat();
+        const coreTools = ["memory_store", "memory_recall", "memory_list"];
+        const missing = coreTools.filter((t) => !allTools.includes(t));
+        if (missing.length === 0) {
+          results.push({ label: "Core tools", status: "PASS", detail: "memory_store, memory_recall, memory_list present" });
+        } else {
+          results.push({ label: "Core tools", status: "FAIL", detail: `Missing: ${missing.join(", ")}` });
+        }
+
+        // 4. Auto-recall enabled
+        const autoRecall = cfg?.autoRecall ?? true;
+        results.push({
+          label: "Auto-recall enabled",
+          status: autoRecall ? "PASS" : "WARN",
+          detail: autoRecall ? "Enabled" : "Disabled in config",
+        });
+
+        // 5. Auto-capture enabled
+        results.push({
+          label: "Auto-capture enabled",
+          status: autoCaptureConfig.enabled ? "PASS" : "WARN",
+          detail: autoCaptureConfig.enabled ? `Enabled (tier: ${autoCaptureConfig.tier})` : "Disabled in config",
+        });
+
+        // 6. Memory storage
+        try {
+          await client.list(1);
+          results.push({ label: "Memory storage", status: "PASS", detail: "Storage accessible" });
+        } catch (err) {
+          results.push({ label: "Memory storage", status: "FAIL", detail: String(err) });
+        }
+
+        // 7. Agent ID configured
+        const agentIdOk = agentId && agentId !== "" && agentId !== "default";
+        results.push({
+          label: "Agent ID configured",
+          status: agentIdOk ? "PASS" : "WARN",
+          detail: agentIdOk ? `ID: ${agentId}` : `Agent ID is "${agentId}" — consider setting a unique ID`,
+        });
+
+        const passes = results.filter((r) => r.status === "PASS").length;
+        const failures = results.filter((r) => r.status === "FAIL").length;
+        let grade: string;
+        if (passes === 7) grade = "A+";
+        else if (passes === 6) grade = "A";
+        else if (passes === 5) grade = "B+";
+        else if (passes === 4) grade = "B";
+        else grade = "F";
+
+        const lines: string[] = ["MemoryRelay Production Readiness", "━".repeat(50)];
+        for (const r of results) {
+          lines.push(`[${r.status.padEnd(4)}] ${r.label}: ${r.detail}`);
+        }
+        lines.push("─".repeat(50));
+        lines.push(`Checks passed: ${passes}/7 | Grade: ${grade} | Production ready: ${failures === 0 ? "Yes" : "No"}`);
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-config — Read-only config display
+  api.registerCommand?.({
+    name: "memory-config",
+    description: "Display current MemoryRelay plugin configuration",
+    requireAuth: true,
+    handler: async (_ctx) => {
+      try {
+        const lines: string[] = ["MemoryRelay Configuration", "━".repeat(50)];
+        lines.push(`API URL:             ${apiUrl}`);
+        lines.push(`Agent ID:            ${agentId}`);
+        lines.push(`Default Project:     ${defaultProject || "(none)"}`);
+        lines.push(`Enabled Tools:       ${cfg?.enabledTools ?? "all"}`);
+        lines.push(`Auto-Recall:         ${cfg?.autoRecall ?? true}`);
+        lines.push(`Auto-Capture:        ${autoCaptureConfig.enabled} (tier: ${autoCaptureConfig.tier})`);
+        lines.push(`Recall Limit:        ${cfg?.recallLimit ?? 5}`);
+        lines.push(`Recall Threshold:    ${cfg?.recallThreshold ?? 0.3}`);
+        lines.push(`Exclude Channels:    ${(cfg?.excludeChannels ?? []).join(", ") || "(none)"}`);
+        lines.push(`Session Timeout:     ${cfg?.sessionTimeoutMinutes ?? 120} min`);
+        lines.push(`Cleanup Interval:    ${cfg?.sessionCleanupIntervalMinutes ?? 30} min`);
+        lines.push(`Debug:               ${cfg?.debug ?? false}`);
+        lines.push(`Verbose:             ${cfg?.verbose ?? false}`);
+        lines.push(`Max Log Entries:     ${cfg?.maxLogEntries ?? 100}`);
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-sessions — List sessions
+  api.registerCommand?.({
+    name: "memory-sessions",
+    description: "List MemoryRelay sessions",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 10;
+        const project = flags["project"] ? String(flags["project"]) : undefined;
+        let status: string | undefined = flags["status"] ? String(flags["status"]) : undefined;
+        if (flags["active"]) status = "active";
+
+        const raw = await client.listSessions(limit, project, status);
+        const sessions: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (sessions.length === 0) {
+          return { text: "No sessions found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Sessions", "━".repeat(60)];
+        for (const session of sessions) {
+          const s = session as Record<string, unknown>;
+          const sid = String(s["id"] ?? "");
+          const sessionStatus = String(s["status"] ?? "unknown").toUpperCase();
+          const startedAt = s["started_at"] ? new Date(String(s["started_at"])).toLocaleString() : "unknown";
+          let duration = "ongoing";
+          if (s["started_at"] && s["ended_at"]) {
+            const diffMs = new Date(String(s["ended_at"])).getTime() - new Date(String(s["started_at"])).getTime();
+            const diffMin = Math.round(diffMs / 60000);
+            duration = `${diffMin}m`;
+          }
+          const summary = String(s["summary"] ?? "").slice(0, 80);
+          lines.push(`[${sessionStatus}] ${sid}`);
+          lines.push(`  Started: ${startedAt} | Duration: ${duration}`);
+          if (summary) lines.push(`  ${summary}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-decisions — List decisions
+  api.registerCommand?.({
+    name: "memory-decisions",
+    description: "List architectural decisions stored in MemoryRelay",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 10;
+        const project = flags["project"] ? String(flags["project"]) : undefined;
+        const status = flags["status"] ? String(flags["status"]) : undefined;
+        const tags = flags["tags"] ? String(flags["tags"]) : undefined;
+
+        const raw = await client.listDecisions(limit, project, status, tags);
+        const decisions: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (decisions.length === 0) {
+          return { text: "No decisions found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Decisions", "━".repeat(60)];
+        for (const decision of decisions) {
+          const d = decision as Record<string, unknown>;
+          const decisionStatus = String(d["status"] ?? "unknown").toUpperCase();
+          const title = String(d["title"] ?? "(untitled)");
+          const date = d["created_at"] ? new Date(String(d["created_at"])).toLocaleDateString() : "unknown";
+          const rationale = String(d["rationale"] ?? "").slice(0, 100);
+          lines.push(`[${decisionStatus}] ${title} (${date})`);
+          if (rationale) lines.push(`  ${rationale}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-patterns — List/search patterns
+  api.registerCommand?.({
+    name: "memory-patterns",
+    description: "List or search memory patterns",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { positional, flags } = parseCommandArgs(ctx.args);
+        const query = positional[0] ?? "";
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 10;
+        const category = flags["category"] ? String(flags["category"]) : undefined;
+        const project = flags["project"] ? String(flags["project"]) : undefined;
+
+        const raw = await client.searchPatterns(query, category, project, limit);
+        const patterns: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (patterns.length === 0) {
+          return { text: query ? `No patterns found for: "${query}"` : "No patterns found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Patterns", "━".repeat(60)];
+        for (const pattern of patterns) {
+          const p = pattern as Record<string, unknown>;
+          const name = String(p["name"] ?? "(unnamed)");
+          const cat = String(p["category"] ?? "general");
+          const description = String(p["description"] ?? "").slice(0, 100);
+          lines.push(`${name} [${cat}]`);
+          if (description) lines.push(`  ${description}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-entities — List entities
+  api.registerCommand?.({
+    name: "memory-entities",
+    description: "List entities stored in MemoryRelay",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 20;
+
+        const raw = await client.listEntities(limit);
+        const entities: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (entities.length === 0) {
+          return { text: "No entities found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Entities", "━".repeat(60)];
+        for (const entity of entities) {
+          const e = entity as Record<string, unknown>;
+          const name = String(e["name"] ?? "(unnamed)");
+          const type = String(e["type"] ?? "unknown");
+          const relationships = Array.isArray(e["relationships"]) ? e["relationships"].length : (typeof e["relationship_count"] === "number" ? e["relationship_count"] : 0);
+          lines.push(`${name} [${type}] (${relationships} relationships)`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-projects — List projects
+  api.registerCommand?.({
+    name: "memory-projects",
+    description: "List projects in MemoryRelay",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 20;
+
+        const raw = await client.listProjects(limit);
+        const projects: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (projects.length === 0) {
+          return { text: "No projects found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Projects", "━".repeat(60)];
+        for (const project of projects) {
+          const p = project as Record<string, unknown>;
+          const slug = String(p["slug"] ?? "(no-slug)");
+          const description = String(p["description"] ?? "").slice(0, 80);
+          const memoryCount = typeof p["memory_count"] === "number" ? p["memory_count"] : 0;
+          lines.push(`${slug} — ${description || "(no description)"} (${memoryCount} memories)`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-agents — List agents
+  api.registerCommand?.({
+    name: "memory-agents",
+    description: "List agents registered in MemoryRelay",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      try {
+        const { flags } = parseCommandArgs(ctx.args);
+        const limit = flags["limit"] ? parseInt(String(flags["limit"]), 10) : 20;
+
+        const raw = await client.listAgents(limit);
+        const agents: unknown[] = Array.isArray(raw) ? raw : (raw as { data?: unknown[] }).data ?? [];
+
+        if (agents.length === 0) {
+          return { text: "No agents found." };
+        }
+
+        const lines: string[] = ["MemoryRelay Agents", "━".repeat(60)];
+        for (const agent of agents) {
+          const a = agent as Record<string, unknown>;
+          const id = String(a["id"] ?? "(no-id)");
+          const name = String(a["name"] ?? "");
+          const description = String(a["description"] ?? "");
+          lines.push(`${id}${name ? ` (${name})` : ""}${description ? `, ${description}` : ""}`);
+        }
+
+        return { text: lines.join("\n") };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
+  // /memory-forget — Delete a memory by ID
+  api.registerCommand?.({
+    name: "memory-forget",
+    description: "Delete a specific memory by ID",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const { positional } = parseCommandArgs(ctx.args);
+      const memoryId = positional[0];
+      if (!memoryId) {
+        return { text: "Usage: /memory-forget <memory-id>" };
+      }
+      try {
+        let preview = "";
+        try {
+          const existing = await client.get(memoryId);
+          const m = existing as Record<string, unknown>;
+          preview = String(m["content"] ?? "").slice(0, 120);
+        } catch (_) {
+          // preview unavailable — proceed with delete
+        }
+
+        await client.delete(memoryId);
+
+        const lines = [`Memory deleted: ${memoryId}`];
+        if (preview) lines.push(`Content: ${preview}`);
+        return { text: lines.join("\n") };
+      } catch (err) {
+        const msg = String(err);
+        if (msg.toLowerCase().includes("not found") || msg.includes("404")) {
+          return { text: `Memory not found: ${memoryId}`, isError: true };
+        }
+        return { text: `Error: ${msg}`, isError: true };
+      }
+    },
+  });
+
+  // ========================================================================
+  // Stale Session Cleanup Service (v0.13.0)
+  // ========================================================================
+
+  let sessionCleanupInterval: ReturnType<typeof setInterval> | null = null;
+
+  api.registerService({
+    id: "memoryrelay-session-cleanup",
+    start: async (_ctx) => {
+      sessionCleanupInterval = setInterval(async () => {
+        const now = Date.now();
+        const staleEntries: string[] = [];
+
+        for (const [externalId, entry] of sessionCache.entries()) {
+          if (now - entry.lastActivityAt > sessionTimeoutMs) {
+            staleEntries.push(externalId);
+          }
+        }
+
+        for (const externalId of staleEntries) {
+          const entry = sessionCache.get(externalId);
+          if (!entry) continue;
+
+          try {
+            await client.endSession(
+              entry.sessionId,
+              `Auto-closed: inactive for >${Math.round(sessionTimeoutMs / 60000)} minutes`
+            );
+            sessionCache.delete(externalId);
+            api.logger.info?.(
+              `memory-memoryrelay: auto-closed stale session ${entry.sessionId} (external: ${externalId})`
+            );
+          } catch (err) {
+            api.logger.warn?.(
+              `memory-memoryrelay: failed to auto-close session ${entry.sessionId}: ${String(err)}`
+            );
+          }
+        }
+      }, sessionCleanupIntervalMs);
+    },
+    stop: async (_ctx) => {
+      if (sessionCleanupInterval) {
+        clearInterval(sessionCleanupInterval);
+        sessionCleanupInterval = null;
+      }
+    },
+  });
 }