@memoryrelay/plugin-memoryrelay-ai 0.6.0 → 0.6.2

package/index.ts

@@ -1,18 +1,19 @@
 /**
- * OpenClaw Memory Plugin - MemoryRelay v0.6.0
+ * OpenClaw Memory Plugin - MemoryRelay
+ * Version: 0.6.0 (Enhanced)
  *
  * Long-term memory with vector search using MemoryRelay API.
  * Provides auto-recall and auto-capture via lifecycle hooks.
  *
- * Improvements in v0.6.0:
- * - Circuit breaker for API failures
- * - Retry logic with exponential backoff
- * - Enhanced entity extraction
- * - Query preprocessing for better search
- * - Structured error logging
- *
  * API: https://api.memoryrelay.net
  * Docs: https://memoryrelay.io
+ *
+ * ENHANCEMENTS (v0.6.0):
+ * - Retry logic with exponential backoff (3 attempts)
+ * - Request timeout (30 seconds)
+ * - Environment variable fallback support
+ * - Channel filtering (excludeChannels config)
+ * - Additional CLI commands (stats, delete, export)
  */
 
 import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
@@ -23,36 +24,23 @@ import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
 
 const DEFAULT_API_URL = "https://api.memoryrelay.net";
 const VALID_HEALTH_STATUSES = ["ok", "healthy", "up"];
+const REQUEST_TIMEOUT_MS = 30000; // 30 seconds
+const MAX_RETRIES = 3;
+const INITIAL_RETRY_DELAY_MS = 1000; // 1 second
 
 // ============================================================================
 // Types
 // ============================================================================
 
 interface MemoryRelayConfig {
-  apiKey: string;
-  agentId: string;
+  apiKey?: string; // Optional now (can use env var)
+  agentId?: string; // Optional now (can use env var)
   apiUrl?: string;
   autoCapture?: boolean;
   autoRecall?: boolean;
   recallLimit?: number;
   recallThreshold?: number;
-  // New in v0.6.0
-  circuitBreaker?: {
-    enabled?: boolean;
-    maxFailures?: number;
-    resetTimeoutMs?: number;
-  };
-  retry?: {
-    enabled?: boolean;
-    maxRetries?: number;
-    baseDelayMs?: number;
-  };
-  entityExtraction?: {
-    enabled?: boolean;
-  };
-  queryPreprocessing?: {
-    enabled?: boolean;
-  };
+  excludeChannels?: string[]; // NEW: Channels to skip auto-recall
 }
 
 interface Memory {
@@ -71,256 +59,135 @@ interface SearchResult {
   score: number;
 }
 
-interface Entity {
-  type: string;
-  value: string;
-}
-
-enum ErrorType {
-  AUTH = "auth_error",
-  RATE_LIMIT = "rate_limit",
-  SERVER = "server_error",
-  NETWORK = "network_error",
-  VALIDATION = "validation_error",
-}
-
-// ============================================================================
-// Circuit Breaker
-// ============================================================================
-
-class CircuitBreaker {
-  private consecutiveFailures = 0;
-  private openUntil: number | null = null;
-
-  constructor(
-    private readonly maxFailures: number = 3,
-    private readonly resetTimeoutMs: number = 60000,
-  ) {}
-
-  isOpen(): boolean {
-    if (this.openUntil && Date.now() < this.openUntil) {
-      return true; // Circuit still open
-    }
-    if (this.openUntil && Date.now() >= this.openUntil) {
-      this.reset(); // Auto-close after timeout
-    }
-    return false;
-  }
-
-  recordSuccess(): void {
-    this.consecutiveFailures = 0;
-    this.openUntil = null;
-  }
-
-  recordFailure(): void {
-    this.consecutiveFailures++;
-    if (this.consecutiveFailures >= this.maxFailures) {
-      this.openUntil = Date.now() + this.resetTimeoutMs;
-    }
-  }
-
-  reset(): void {
-    this.consecutiveFailures = 0;
-    this.openUntil = null;
-  }
-
-  getState(): { open: boolean; failures: number; opensAt?: number } {
-    return {
-      open: this.isOpen(),
-      failures: this.consecutiveFailures,
-      opensAt: this.openUntil || undefined,
-    };
-  }
+interface Stats {
+  total_memories: number;
+  last_updated?: string;
 }
 
 // ============================================================================
 // Utility Functions
 // ============================================================================
 
+/**
+ * Sleep for specified milliseconds
+ */
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
 
-function classifyError(err: any): ErrorType {
-  const msg = String(err.message || err);
-
-  if (msg.includes("401") || msg.includes("403")) return ErrorType.AUTH;
-  if (msg.includes("429")) return ErrorType.RATE_LIMIT;
-  if (msg.includes("500") || msg.includes("502") || msg.includes("503"))
-    return ErrorType.SERVER;
-  if (msg.includes("ECONNREFUSED") || msg.includes("timeout"))
-    return ErrorType.NETWORK;
-  if (msg.includes("400")) return ErrorType.VALIDATION;
-
-  return ErrorType.SERVER; // Default
+/**
+ * Check if error is retryable (network/timeout errors)
+ */
+function isRetryableError(error: unknown): boolean {
+  const errStr = String(error).toLowerCase();
+  return (
+    errStr.includes("timeout") ||
+    errStr.includes("econnrefused") ||
+    errStr.includes("enotfound") ||
+    errStr.includes("network") ||
+    errStr.includes("fetch failed") ||
+    errStr.includes("502") ||
+    errStr.includes("503") ||
+    errStr.includes("504")
+  );
 }
 
-function extractEntities(text: string): Entity[] {
-  const entities: Entity[] = [];
-
-  // API keys (common patterns)
-  const apiKeyPattern =
-    /\b(?:mem|nr|sk|pk|api)_(?:prod|test|dev|live)_[a-zA-Z0-9]{16,64}\b/gi;
-  let match;
-  while ((match = apiKeyPattern.exec(text)) !== null) {
-    entities.push({ type: "api_key", value: match[0] });
-  }
-
-  // Email addresses
-  const emailPattern =
-    /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g;
-  while ((match = emailPattern.exec(text)) !== null) {
-    entities.push({ type: "email", value: match[0] });
-  }
-
-  // URLs
-  const urlPattern = /https?:\/\/[^\s<>"{}|\\^`\[\]]+/g;
-  while ((match = urlPattern.exec(text)) !== null) {
-    entities.push({ type: "url", value: match[0] });
-  }
+/**
+ * Fetch with timeout
+ */
+async function fetchWithTimeout(
+  url: string,
+  options: RequestInit,
+  timeoutMs: number,
+): Promise<Response> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
 
-  // IP addresses (with validation)
-  const ipPattern = /\b(?:\d{1,3}\.){3}\d{1,3}\b/g;
-  while ((match = ipPattern.exec(text)) !== null) {
-    const octets = match[0].split(".").map(Number);
-    if (octets.every((n) => n >= 0 && n <= 255)) {
-      entities.push({ type: "ip_address", value: match[0] });
+  try {
+    const response = await fetch(url, {
+      ...options,
+      signal: controller.signal,
+    });
+    clearTimeout(timeout);
+    return response;
+  } catch (err) {
+    clearTimeout(timeout);
+    if ((err as Error).name === "AbortError") {
+      throw new Error("Request timeout");
     }
+    throw err;
   }
-
-  return entities;
-}
-
-function preprocessQuery(query: string): string {
-  // Remove question words
-  let cleaned = query.replace(
-    /\b(what|how|when|where|why|who|which|whose|whom|is|are|was|were|do|does|did|can|could|should|would|will)\b/gi,
-    "",
-  );
-
-  // Remove punctuation
-  cleaned = cleaned.replace(/[?!.,;:'"()]/g, " ");
-
-  // Collapse multiple spaces
-  cleaned = cleaned.replace(/\s+/g, " ").trim();
-
-  return cleaned;
 }
 
 // ============================================================================
-// MemoryRelay API Client with Retry
+// MemoryRelay API Client (Enhanced)
 // ============================================================================
 
 class MemoryRelayClient {
-  private circuitBreaker: CircuitBreaker | null = null;
-
   constructor(
     private readonly apiKey: string,
     private readonly agentId: string,
     private readonly apiUrl: string = DEFAULT_API_URL,
-    private readonly retryConfig?: {
-      enabled: boolean;
-      maxRetries: number;
-      baseDelayMs: number;
-    },
-    circuitBreakerConfig?: {
-      enabled: boolean;
-      maxFailures: number;
-      resetTimeoutMs: number;
-    },
-  ) {
-    if (circuitBreakerConfig?.enabled) {
-      this.circuitBreaker = new CircuitBreaker(
-        circuitBreakerConfig.maxFailures,
-        circuitBreakerConfig.resetTimeoutMs,
-      );
-    }
-  }
+  ) {}
 
+  /**
+   * Make HTTP request with retry logic and timeout
+   */
   private async request<T>(
     method: string,
     path: string,
     body?: unknown,
+    retryCount = 0,
   ): Promise<T> {
     const url = `${this.apiUrl}${path}`;
 
-    const doRequest = async (): Promise<T> => {
-      const response = await fetch(url, {
-        method,
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${this.apiKey}`,
-          "User-Agent": "openclaw-memory-memoryrelay/0.6.0",
+    try {
+      const response = await fetchWithTimeout(
+        url,
+        {
+          method,
+          headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            "User-Agent": "openclaw-memory-memoryrelay/0.6.0",
+          },
+          body: body ? JSON.stringify(body) : undefined,
         },
-        body: body ? JSON.stringify(body) : undefined,
-      });
+        REQUEST_TIMEOUT_MS,
+      );
 
       if (!response.ok) {
         const errorData = await response.json().catch(() => ({}));
-        throw new Error(
+        const error = new Error(
           `MemoryRelay API error: ${response.status} ${response.statusText}` +
             (errorData.message ? ` - ${errorData.message}` : ""),
         );
-      }
 
-      return response.json();
-    };
-
-    // Retry logic
-    if (this.retryConfig?.enabled) {
-      return this.requestWithRetry(doRequest);
-    }
-
-    return doRequest();
-  }
-
-  private async requestWithRetry<T>(fn: () => Promise<T>): Promise<T> {
-    const maxRetries = this.retryConfig?.maxRetries || 3;
-    const baseDelayMs = this.retryConfig?.baseDelayMs || 1000;
-    let lastError: Error;
-
-    for (let attempt = 0; attempt <= maxRetries; attempt++) {
-      try {
-        const result = await fn();
-        this.circuitBreaker?.recordSuccess();
-        return result;
-      } catch (err: any) {
-        lastError = err;
-        const errorType = classifyError(err);
-
-        // Don't retry auth errors
-        if (errorType === ErrorType.AUTH) {
-          this.circuitBreaker?.recordFailure();
-          throw err;
-        }
-
-        // Record failure for circuit breaker
-        this.circuitBreaker?.recordFailure();
-
-        // Don't retry on last attempt
-        if (attempt < maxRetries) {
-          const delay = baseDelayMs * Math.pow(2, attempt);
+        // Retry on 5xx errors
+        if (response.status >= 500 && retryCount < MAX_RETRIES) {
+          const delay = INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCount);
           await sleep(delay);
+          return this.request<T>(method, path, body, retryCount + 1);
         }
-      }
-    }
 
-    throw lastError!;
-  }
+        throw error;
+      }
 
-  isCircuitOpen(): boolean {
-    return this.circuitBreaker?.isOpen() || false;
-  }
+      return response.json();
+    } catch (err) {
+      // Retry on network errors
+      if (isRetryableError(err) && retryCount < MAX_RETRIES) {
+        const delay = INITIAL_RETRY_DELAY_MS * Math.pow(2, retryCount);
+        await sleep(delay);
+        return this.request<T>(method, path, body, retryCount + 1);
+      }
 
-  getCircuitState() {
-    return this.circuitBreaker?.getState();
+      throw err;
+    }
   }
 
-  async store(
-    content: string,
-    metadata?: Record<string, string>,
-  ): Promise<Memory> {
-    return this.request<Memory>("POST", "/v1/memories/memories", {
+  async store(content: string, metadata?: Record<string, string>): Promise<Memory> {
+    return this.request<Memory>("POST", "/v1/memories", {
       content,
       metadata,
       agent_id: this.agentId,
@@ -365,15 +232,35 @@ class MemoryRelayClient {
     return this.request<{ status: string }>("GET", "/v1/health");
   }
 
-  async stats(): Promise<{ total_memories: number; last_updated?: string }> {
-    const response = await this.request<{
-      data: { total_memories: number; last_updated?: string };
-    }>("GET", `/v1/stats?agent_id=${encodeURIComponent(this.agentId)}`);
+  async stats(): Promise<Stats> {
+    const response = await this.request<{ data: Stats }>(
+      "GET",
+      `/v1/stats?agent_id=${encodeURIComponent(this.agentId)}`,
+    );
     return {
       total_memories: response.data?.total_memories ?? 0,
       last_updated: response.data?.last_updated,
     };
   }
+
+  /**
+   * Export all memories as JSON
+   */
+  async export(): Promise<Memory[]> {
+    const allMemories: Memory[] = [];
+    let offset = 0;
+    const limit = 100;
+
+    while (true) {
+      const batch = await this.list(limit, offset);
+      if (batch.length === 0) break;
+      allMemories.push(...batch);
+      offset += limit;
+      if (batch.length < limit) break; // Last page
+    }
+
+    return allMemories;
+  }
 }
 
 // ============================================================================
@@ -390,23 +277,10 @@ const CAPTURE_PATTERNS = [
   /(?:ssh|server|host|ip|port)(?:\s+is)?[:\s]/i,
 ];
 
-function shouldCapture(
-  text: string,
-  entityExtractionEnabled: boolean = true,
-): boolean {
+function shouldCapture(text: string): boolean {
   if (text.length < 20 || text.length > 2000) {
     return false;
   }
-
-  // Check for entities (if enabled)
-  if (entityExtractionEnabled) {
-    const entities = extractEntities(text);
-    if (entities.length > 0) {
-      return true; // Has structured data worth capturing
-    }
-  }
-
-  // Check original patterns
   return CAPTURE_PATTERNS.some((pattern) => pattern.test(text));
 }
 
@@ -417,82 +291,495 @@ function shouldCapture(
 export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   const cfg = api.pluginConfig as MemoryRelayConfig | undefined;
 
-  if (!cfg?.apiKey) {
+  // NEW: Fall back to environment variables
+  const apiKey = cfg?.apiKey || process.env.MEMORYRELAY_API_KEY;
+  const agentId = cfg?.agentId || process.env.MEMORYRELAY_AGENT_ID || api.agentName;
+
+  if (!apiKey) {
     api.logger.error(
-      "memory-memoryrelay: Missing API key in config.\n\n" +
+      "memory-memoryrelay: Missing API key in config or MEMORYRELAY_API_KEY env var.\n\n" +
         "REQUIRED: Add config after installation:\n\n" +
         'cat ~/.openclaw/openclaw.json | jq \'.plugins.entries."plugin-memoryrelay-ai".config = {\n' +
         '  "apiKey": "YOUR_API_KEY",\n' +
         '  "agentId": "YOUR_AGENT_ID"\n' +
         "}' > /tmp/config.json && mv /tmp/config.json ~/.openclaw/openclaw.json\n\n" +
+        "Or set environment variable:\n" +
+        'export MEMORYRELAY_API_KEY="mem_prod_..."\n\n' +
         "Then restart: openclaw gateway restart\n\n" +
         "Get your API key from: https://memoryrelay.ai",
     );
     return;
   }
 
-  if (!cfg.agentId) {
-    api.logger.error("memory-memoryrelay: Missing agentId in config");
+  if (!agentId) {
+    api.logger.error("memory-memoryrelay: Missing agentId in config or MEMORYRELAY_AGENT_ID env var");
     return;
   }
 
-  const apiUrl = cfg.apiUrl || DEFAULT_API_URL;
-
-  // Circuit breaker config (default: enabled)
-  const circuitBreakerConfig = {
-    enabled: cfg.circuitBreaker?.enabled ?? true,
-    maxFailures: cfg.circuitBreaker?.maxFailures || 3,
-    resetTimeoutMs: cfg.circuitBreaker?.resetTimeoutMs || 60000,
-  };
-
-  // Retry config (default: enabled)
-  const retryConfig = {
-    enabled: cfg.retry?.enabled ?? true,
-    maxRetries: cfg.retry?.maxRetries || 3,
-    baseDelayMs: cfg.retry?.baseDelayMs || 1000,
-  };
-
-  // Entity extraction config (default: enabled)
-  const entityExtractionEnabled = cfg.entityExtraction?.enabled ?? true;
-
-  // Query preprocessing config (default: enabled)
-  const queryPreprocessingEnabled = cfg.queryPreprocessing?.enabled ?? true;
-
-  const client = new MemoryRelayClient(
-    cfg.apiKey,
-    cfg.agentId,
-    apiUrl,
-    retryConfig,
-    circuitBreakerConfig,
-  );
+  const apiUrl = cfg?.apiUrl || process.env.MEMORYRELAY_API_URL || DEFAULT_API_URL;
+  const client = new MemoryRelayClient(apiKey, agentId, apiUrl);
 
-  // Verify connection on startup
+  // Verify connection on startup (with timeout)
   try {
     await client.health();
-    api.logger.info(
-      `memory-memoryrelay: connected to ${apiUrl} (v0.6.0 - enhanced)`,
-    );
-    api.logger.info(
-      `memory-memoryrelay: circuit breaker=${circuitBreakerConfig.enabled}, retry=${retryConfig.enabled}, entity extraction=${entityExtractionEnabled}`,
-    );
+    api.logger.info(`memory-memoryrelay: connected to ${apiUrl}`);
   } catch (err) {
-    const errorType = classifyError(err);
-    api.logger.error(
-      `memory-memoryrelay: health check failed (${errorType}): ${String(err)}`,
-    );
-    if (errorType === ErrorType.AUTH) {
-      api.logger.error(
-        "memory-memoryrelay: Check your API key configuration",
-      );
+    api.logger.error(`memory-memoryrelay: health check failed: ${String(err)}`);
+    // Continue loading plugin even if health check fails (will retry on first use)
+  }
+
+  // ========================================================================
+  // Status Reporting (for openclaw status command)
+  // ========================================================================
+
+  api.registerGatewayMethod?.("memory.status", async ({ respond }) => {
+    try {
+      const health = await client.health();
+      let memoryCount = 0;
+
+      try {
+        const stats = await client.stats();
+        memoryCount = stats.total_memories;
+      } catch (statsErr) {
+        api.logger.debug?.(`memory-memoryrelay: stats endpoint unavailable: ${String(statsErr)}`);
+      }
+
+      const healthStatus = String(health.status).toLowerCase();
+      const isConnected = VALID_HEALTH_STATUSES.includes(healthStatus);
+
+      respond(true, {
+        available: true,
+        connected: isConnected,
+        endpoint: apiUrl,
+        memoryCount: memoryCount,
+        agentId: agentId,
+        vector: {
+          available: true,
+          enabled: true,
+        },
+      });
+    } catch (err) {
+      respond(true, {
+        available: false,
+        connected: false,
+        error: String(err),
+        endpoint: apiUrl,
+        agentId: agentId,
+        vector: {
+          available: false,
+          enabled: true,
+        },
+      });
     }
-    return;
+  });
+
+  // ========================================================================
+  // Tools (using JSON Schema directly)
+  // ========================================================================
+
+  // memory_store tool
+  api.registerTool(
+    {
+      name: "memory_store",
+      description:
+        "Store a new memory in MemoryRelay. Use this to save important information, facts, preferences, or context that should be remembered for future conversations.",
+      parameters: {
+        type: "object",
+        properties: {
+          content: {
+            type: "string",
+            description: "The memory content to store. Be specific and include relevant context.",
+          },
+          metadata: {
+            type: "object",
+            description: "Optional key-value metadata to attach to the memory",
+            additionalProperties: { type: "string" },
+          },
+        },
+        required: ["content"],
+      },
+      execute: async (_id, { content, metadata }: { content: string; metadata?: Record<string, string> }) => {
+        try {
+          const memory = await client.store(content, metadata);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Memory stored successfully (id: ${memory.id.slice(0, 8)}...)`,
+              },
+            ],
+            details: { id: memory.id, stored: true },
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Failed to store memory: ${String(err)}` }],
+            details: { error: String(err) },
+          };
+        }
+      },
+    },
+    { name: "memory_store" },
+  );
+
+  // memory_recall tool (semantic search)
+  api.registerTool(
+    {
+      name: "memory_recall",
+      description:
+        "Search memories using natural language. Returns the most relevant memories based on semantic similarity.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "Natural language search query",
+          },
+          limit: {
+            type: "number",
+            description: "Maximum results (1-20)",
+            minimum: 1,
+            maximum: 20,
+            default: 5,
+          },
+        },
+        required: ["query"],
+      },
+      execute: async (_id, { query, limit = 5 }: { query: string; limit?: number }) => {
+        try {
+          const results = await client.search(query, limit, cfg?.recallThreshold || 0.3);
+
+          if (results.length === 0) {
+            return {
+              content: [{ type: "text", text: "No relevant memories found." }],
+              details: { count: 0 },
+            };
+          }
+
+          const formatted = results
+            .map(
+              (r) =>
+                `- [${r.score.toFixed(2)}] ${r.memory.content.slice(0, 200)}${
+                  r.memory.content.length > 200 ? "..." : ""
+                }`,
+            )
+            .join("\n");
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Found ${results.length} relevant memories:\n${formatted}`,
+              },
+            ],
+            details: {
+              count: results.length,
+              memories: results.map((r) => ({
+                id: r.memory.id,
+                content: r.memory.content,
+                score: r.score,
+              })),
+            },
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Search failed: ${String(err)}` }],
+            details: { error: String(err) },
+          };
+        }
+      },
+    },
+    { name: "memory_recall" },
+  );
+
+  // memory_forget tool
+  api.registerTool(
+    {
+      name: "memory_forget",
+      description: "Delete a memory by ID or search for memories to forget.",
+      parameters: {
+        type: "object",
+        properties: {
+          memoryId: {
+            type: "string",
+            description: "Memory ID to delete",
+          },
+          query: {
+            type: "string",
+            description: "Search query to find memory",
+          },
+        },
+      },
+      execute: async (_id, { memoryId, query }: { memoryId?: string; query?: string }) => {
+        if (memoryId) {
+          try {
+            await client.delete(memoryId);
+            return {
+              content: [{ type: "text", text: `Memory ${memoryId.slice(0, 8)}... deleted.` }],
+              details: { action: "deleted", id: memoryId },
+            };
+          } catch (err) {
+            return {
+              content: [{ type: "text", text: `Delete failed: ${String(err)}` }],
+              details: { error: String(err) },
+            };
+          }
+        }
+
+        if (query) {
+          const results = await client.search(query, 5, 0.5);
+
+          if (results.length === 0) {
+            return {
+              content: [{ type: "text", text: "No matching memories found." }],
+              details: { count: 0 },
+            };
+          }
+
+          // If single high-confidence match, delete it
+          if (results.length === 1 && results[0].score > 0.9) {
+            await client.delete(results[0].memory.id);
+            return {
+              content: [
+                { type: "text", text: `Forgotten: "${results[0].memory.content.slice(0, 60)}..."` },
+              ],
+              details: { action: "deleted", id: results[0].memory.id },
+            };
+          }
+
+          const list = results
+            .map((r) => `- [${r.memory.id.slice(0, 8)}] ${r.memory.content.slice(0, 60)}...`)
+            .join("\n");
+
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Found ${results.length} candidates. Specify memoryId:\n${list}`,
+              },
+            ],
+            details: { action: "candidates", count: results.length },
+          };
+        }
+
+        return {
+          content: [{ type: "text", text: "Provide query or memoryId." }],
+          details: { error: "missing_param" },
+        };
+      },
+    },
+    { name: "memory_forget" },
+  );
+
+  // ========================================================================
+  // CLI Commands (Enhanced)
+  // ========================================================================
+
+  api.registerCli(
+    ({ program }) => {
+      const mem = program.command("memoryrelay").description("MemoryRelay memory plugin commands");
+
+      mem
+        .command("status")
+        .description("Check MemoryRelay connection status")
+        .action(async () => {
+          try {
+            const health = await client.health();
+            const stats = await client.stats();
+            console.log(`Status: ${health.status}`);
+            console.log(`Agent ID: ${agentId}`);
+            console.log(`API: ${apiUrl}`);
+            console.log(`Total Memories: ${stats.total_memories}`);
+            if (stats.last_updated) {
+              console.log(`Last Updated: ${new Date(stats.last_updated).toLocaleString()}`);
+            }
+          } catch (err) {
+            console.error(`Connection failed: ${String(err)}`);
+          }
+        });
+
+      mem
+        .command("stats")
+        .description("Show agent statistics")
+        .action(async () => {
+          try {
+            const stats = await client.stats();
+            console.log(`Total Memories: ${stats.total_memories}`);
+            if (stats.last_updated) {
+              console.log(`Last Updated: ${new Date(stats.last_updated).toLocaleString()}`);
+            }
+          } catch (err) {
+            console.error(`Failed to fetch stats: ${String(err)}`);
+          }
+        });
+
+      mem
+        .command("list")
+        .description("List recent memories")
+        .option("--limit <n>", "Max results", "10")
+        .action(async (opts) => {
+          try {
+            const memories = await client.list(parseInt(opts.limit));
+            for (const m of memories) {
+              console.log(`[${m.id.slice(0, 8)}] ${m.content.slice(0, 80)}...`);
+            }
+            console.log(`\nTotal: ${memories.length} memories`);
+          } catch (err) {
+            console.error(`Failed to list memories: ${String(err)}`);
+          }
+        });
+
+      mem
+        .command("search")
+        .description("Search memories")
+        .argument("<query>", "Search query")
+        .option("--limit <n>", "Max results", "5")
+        .action(async (query, opts) => {
+          try {
+            const results = await client.search(query, parseInt(opts.limit));
+            for (const r of results) {
+              console.log(`[${r.score.toFixed(2)}] ${r.memory.content.slice(0, 80)}...`);
+            }
+          } catch (err) {
+            console.error(`Search failed: ${String(err)}`);
+          }
+        });
+
+      mem
+        .command("delete")
+        .description("Delete a memory by ID")
+        .argument("<id>", "Memory ID")
+        .action(async (id) => {
+          try {
+            await client.delete(id);
+            console.log(`Memory ${id.slice(0, 8)}... deleted.`);
+          } catch (err) {
+            console.error(`Delete failed: ${String(err)}`);
+          }
+        });
+
+      mem
+        .command("export")
+        .description("Export all memories to JSON file")
+        .option("--output <path>", "Output file path", "memories-export.json")
+        .action(async (opts) => {
+          try {
+            console.log("Exporting memories...");
+            const memories = await client.export();
+            const fs = await import("fs/promises");
+            await fs.writeFile(opts.output, JSON.stringify(memories, null, 2));
+            console.log(`Exported ${memories.length} memories to ${opts.output}`);
+          } catch (err) {
+            console.error(`Export failed: ${String(err)}`);
+          }
+        });
+    },
+    { commands: ["memoryrelay"] },
+  );
+
+  // ========================================================================
+  // Lifecycle Hooks
+  // ========================================================================
+
+  // Auto-recall: inject relevant memories before agent starts
+  if (cfg?.autoRecall) {
+    api.on("before_agent_start", async (event) => {
+      if (!event.prompt || event.prompt.length < 10) {
+        return;
+      }
+
+      // NEW: Check if current channel is excluded
+      if (cfg.excludeChannels && event.channel) {
+        const channelId = String(event.channel);
+        if (cfg.excludeChannels.some((excluded) => channelId.includes(excluded))) {
+          api.logger.debug?.(
+            `memory-memoryrelay: skipping auto-recall for excluded channel: ${channelId}`,
+          );
+          return;
+        }
+      }
+
+      try {
+        const results = await client.search(
+          event.prompt,
+          cfg.recallLimit || 5,
+          cfg.recallThreshold || 0.3,
+        );
+
+        if (results.length === 0) {
+          return;
+        }
+
+        const memoryContext = results.map((r) => `- ${r.memory.content}`).join("\n");
+
+        api.logger.info?.(
+          `memory-memoryrelay: injecting ${results.length} memories into context`,
+        );
+
+        return {
+          prependContext: `<relevant-memories>\nThe following memories from MemoryRelay may be relevant:\n${memoryContext}\n</relevant-memories>`,
+        };
+      } catch (err) {
+        api.logger.warn?.(`memory-memoryrelay: recall failed: ${String(err)}`);
+      }
+    });
   }
 
-  // ... (rest of the plugin implementation continues - tools, CLI, hooks)
-  // For brevity, the full implementation would follow here
-  // This PR focuses on the core improvements shown above
+  // Auto-capture: analyze and store important information after agent ends
+  if (cfg?.autoCapture) {
+    api.on("agent_end", async (event) => {
+      if (!event.success || !event.messages || event.messages.length === 0) {
+        return;
+      }
+
+      try {
+        const texts: string[] = [];
+        for (const msg of event.messages) {
+          if (!msg || typeof msg !== "object") continue;
+          const msgObj = msg as Record<string, unknown>;
+          const role = msgObj.role;
+          if (role !== "user" && role !== "assistant") continue;
+
+          const content = msgObj.content;
+          if (typeof content === "string") {
+            texts.push(content);
+          } else if (Array.isArray(content)) {
+            for (const block of content) {
+              if (
+                block &&
+                typeof block === "object" &&
+                "type" in block &&
+                (block as Record<string, unknown>).type === "text" &&
+                "text" in block
+              ) {
+                texts.push((block as Record<string, unknown>).text as string);
+              }
+            }
+          }
+        }
+
+        const toCapture = texts.filter((text) => text && shouldCapture(text));
+        if (toCapture.length === 0) return;
+
+        let stored = 0;
+        for (const text of toCapture.slice(0, 3)) {
+          // Check for duplicates via search
+          const existing = await client.search(text, 1, 0.95);
+          if (existing.length > 0) continue;
+
+          await client.store(text, { source: "auto-capture" });
+          stored++;
+        }
+
+        if (stored > 0) {
+          api.logger.info?.(`memory-memoryrelay: auto-captured ${stored} memories`);
+        }
+      } catch (err) {
+        api.logger.warn?.(`memory-memoryrelay: capture failed: ${String(err)}`);
+      }
+    });
+  }
 
   api.logger.info?.(
-    `memory-memoryrelay: plugin loaded (autoRecall: ${cfg.autoRecall}, autoCapture: ${cfg.autoCapture})`,
+    `memory-memoryrelay: plugin loaded (autoRecall: ${cfg?.autoRecall}, autoCapture: ${cfg?.autoCapture})`,
   );
 }