@memoryrelay/plugin-memoryrelay-ai 0.13.0 → 0.15.0

package/index.ts

@@ -709,7 +709,7 @@ class MemoryRelayClient {
           headers: {
             "Content-Type": "application/json",
             Authorization: `Bearer ${this.apiKey}`,
-            "User-Agent": "openclaw-memory-memoryrelay/0.13.0",
+            "User-Agent": "openclaw-memory-memoryrelay/0.15.0",
           },
           body: body ? JSON.stringify(body) : undefined,
         },
@@ -936,6 +936,63 @@ class MemoryRelayClient {
     });
   }
 
+  // --------------------------------------------------------------------------
+  // V2 Async API Methods (v0.15.0)
+  // --------------------------------------------------------------------------
+
+  async storeAsync(
+    content: string,
+    metadata?: Record<string, string>,
+    project?: string,
+    importance?: number,
+    tier?: string,
+  ): Promise<{ id: string; status: string; job_id: string; estimated_completion_seconds: number }> {
+    if (!content || content.length === 0 || content.length > 50000) {
+      throw new Error("Content must be between 1 and 50,000 characters");
+    }
+    const body: Record<string, unknown> = {
+      content,
+      agent_id: this.agentId,
+    };
+    if (metadata) body.metadata = metadata;
+    if (project) body.project = project;
+    if (importance != null) body.importance = importance;
+    if (tier) body.tier = tier;
+    return this.request("POST", "/v2/memories", body);
+  }
+
+  async getMemoryStatus(memoryId: string): Promise<{
+    id: string;
+    status: "pending" | "processing" | "ready" | "failed";
+    created_at: string;
+    updated_at: string;
+    error?: string;
+  }> {
+    return this.request("GET", `/v2/memories/${memoryId}/status`);
+  }
+
+  async buildContextV2(
+    query: string,
+    options?: {
+      maxMemories?: number;
+      maxTokens?: number;
+      aiEnhanced?: boolean;
+      searchMode?: "semantic" | "hybrid" | "keyword";
+      excludeMemoryIds?: string[];
+    },
+  ): Promise<any> {
+    const body: Record<string, unknown> = {
+      query,
+      agent_id: this.agentId,
+    };
+    if (options?.maxMemories != null) body.max_memories = options.maxMemories;
+    if (options?.maxTokens != null) body.max_tokens = options.maxTokens;
+    if (options?.aiEnhanced != null) body.ai_enhanced = options.aiEnhanced;
+    if (options?.searchMode) body.search_mode = options.searchMode;
+    if (options?.excludeMemoryIds) body.exclude_memory_ids = options.excludeMemoryIds;
+    return this.request("POST", "/v2/context", body);
+  }
+
   // --------------------------------------------------------------------------
   // Entity operations
   // --------------------------------------------------------------------------
@@ -1583,6 +1640,7 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
       "project_related", "project_impact", "project_shared_patterns", "project_context",
     ],
     health: ["memory_health"],
+    v2: ["memory_store_async", "memory_status", "context_build"],
   };
 
   // Build a set of enabled tool names from group names
@@ -3746,6 +3804,202 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
     );
   }
 
+  // 40. memory_store_async
+  // --------------------------------------------------------------------------
+  if (isToolEnabled("memory_store_async")) {
+    api.registerTool((_ctx) => ({
+      name: "memory_store_async",
+      description:
+        "Store a memory asynchronously using V2 API. Returns immediately (<50ms) with a job ID. Background workers generate the embedding. Use memory_status to poll for completion. Prefer this over memory_store for high-throughput or latency-sensitive applications." +
+        (defaultProject ? ` Project defaults to '${defaultProject}' if not specified.` : ""),
+      parameters: {
+        type: "object",
+        properties: {
+          content: {
+            type: "string",
+            description: "The memory content to store (1–50,000 characters).",
+          },
+          metadata: {
+            type: "object",
+            description: "Optional key-value metadata to attach to the memory.",
+            additionalProperties: { type: "string" },
+          },
+          project: {
+            type: "string",
+            description: "Project slug to associate with this memory (max 100 characters).",
+            maxLength: 100,
+          },
+          importance: {
+            type: "number",
+            description: "Importance score (0-1). Higher values are retained longer.",
+            minimum: 0,
+            maximum: 1,
+          },
+          tier: {
+            type: "string",
+            description: "Memory tier: hot, warm, or cold.",
+            enum: ["hot", "warm", "cold"],
+          },
+        },
+        required: ["content"],
+      },
+      execute: async (
+        _id,
+        args: {
+          content: string;
+          metadata?: Record<string, string>;
+          project?: string;
+          importance?: number;
+          tier?: string;
+        },
+      ) => {
+        try {
+          const { content, metadata, importance, tier } = args;
+          let project = args.project;
+          if (!project && defaultProject) project = defaultProject;
+          const result = await client.storeAsync(content, metadata, project, importance, tier);
+          return {
+            content: [
+              {
+                type: "text",
+                text: `Memory queued for async storage (id: ${result.id}, job_id: ${result.job_id}). Use memory_status to check completion.`,
+              },
+            ],
+            details: result,
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Failed to queue memory: ${String(err)}` }],
+            details: { error: String(err) },
+          };
+        }
+      },
+    }), { name: "memory_store_async" });
+  }
+
+  // 41. memory_status
+  // --------------------------------------------------------------------------
+  if (isToolEnabled("memory_status")) {
+    api.registerTool((_ctx) => ({
+      name: "memory_status",
+      description:
+        "Check the processing status of a memory created via memory_store_async. Status values: pending (waiting for worker), processing (generating embedding), ready (searchable), failed (error occurred).",
+      parameters: {
+        type: "object",
+        properties: {
+          memory_id: {
+            type: "string",
+            description: "The memory ID returned by memory_store_async.",
+          },
+        },
+        required: ["memory_id"],
+      },
+      execute: async (
+        _id,
+        args: { memory_id: string },
+      ) => {
+        try {
+          const status = await client.getMemoryStatus(args.memory_id);
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(status, null, 2),
+              },
+            ],
+            details: status,
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Failed to get memory status: ${String(err)}` }],
+            details: { error: String(err) },
+          };
+        }
+      },
+    }), { name: "memory_status" });
+  }
+
+  // 42. context_build
+  // --------------------------------------------------------------------------
+  if (isToolEnabled("context_build")) {
+    api.registerTool((_ctx) => ({
+      name: "context_build",
+      description:
+        "Build a ranked context bundle from memories with optional AI summarization. Searches for relevant memories, ranks them by composite score, and optionally generates an AI summary. Useful for building token-efficient context windows.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: {
+            type: "string",
+            description: "The query to build context for.",
+          },
+          max_memories: {
+            type: "number",
+            description: "Maximum number of memories to include (1-100).",
+            minimum: 1,
+            maximum: 100,
+          },
+          max_tokens: {
+            type: "number",
+            description: "Maximum tokens for the context bundle (100-128000).",
+            minimum: 100,
+            maximum: 128000,
+          },
+          ai_enhanced: {
+            type: "boolean",
+            description: "If true, generate an AI summary of the retrieved memories.",
+          },
+          search_mode: {
+            type: "string",
+            description: "Search strategy: semantic, hybrid, or keyword.",
+            enum: ["semantic", "hybrid", "keyword"],
+          },
+          exclude_memory_ids: {
+            type: "array",
+            description: "Memory IDs to exclude from results.",
+            items: { type: "string" },
+          },
+        },
+        required: ["query"],
+      },
+      execute: async (
+        _id,
+        args: {
+          query: string;
+          max_memories?: number;
+          max_tokens?: number;
+          ai_enhanced?: boolean;
+          search_mode?: "semantic" | "hybrid" | "keyword";
+          exclude_memory_ids?: string[];
+        },
+      ) => {
+        try {
+          const context = await client.buildContextV2(args.query, {
+            maxMemories: args.max_memories,
+            maxTokens: args.max_tokens,
+            aiEnhanced: args.ai_enhanced,
+            searchMode: args.search_mode,
+            excludeMemoryIds: args.exclude_memory_ids,
+          });
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(context, null, 2),
+              },
+            ],
+            details: context,
+          };
+        } catch (err) {
+          return {
+            content: [{ type: "text", text: `Failed to build context: ${String(err)}` }],
+            details: { error: String(err) },
+          };
+        }
+      },
+    }), { name: "context_build" });
+  }
+
   // ========================================================================
   // CLI Commands
   // ========================================================================
@@ -4236,7 +4490,7 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   });
 
   api.logger.info?.(
-    `memory-memoryrelay: plugin v0.13.0 loaded (39 tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${autoCaptureConfig.enabled ? autoCaptureConfig.tier : 'off'}, debug: ${debugEnabled})`,
+    `memory-memoryrelay: plugin v0.15.0 loaded (${Object.values(TOOL_GROUPS).flat().length} tools, autoRecall: ${cfg?.autoRecall}, autoCapture: ${autoCaptureConfig.enabled ? autoCaptureConfig.tier : 'off'}, debug: ${debugEnabled})`,
   );
 
   // ========================================================================
@@ -4586,7 +4840,65 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
   });
 
   // ========================================================================
-  // Direct Commands (5 total) — bypass LLM, execute immediately
+  // 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 (16 total) — bypass LLM, execute immediately
   // ========================================================================
 
   // /memory-status — Show full plugin status report
@@ -4789,6 +5101,485 @@ export default async function plugin(api: OpenClawPluginApi): Promise<void> {
     },
   });
 
+  // ========================================================================
+  // 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 };
+      }
+    },
+  });
+
+  // /memory-context — Build a context bundle from memories using V2 API
+  api.registerCommand?.({
+    name: "memory-context",
+    description: "Build a ranked context bundle from memories for a given query",
+    requireAuth: true,
+    acceptsArgs: true,
+    handler: async (ctx) => {
+      const { positional, flags } = parseCommandArgs(ctx.args);
+      const query = positional.join(" ").trim();
+      if (!query) {
+        return {
+          text: [
+            "Usage: /memory-context <query> [options]",
+            "",
+            "Options:",
+            "  --max-memories <n>    Maximum memories to include (1-100)",
+            "  --max-tokens <n>      Maximum tokens for context (100-128000)",
+            "  --ai-enhanced         Generate an AI summary of memories",
+            "  --search-mode <mode>  Search strategy: semantic, hybrid, keyword",
+          ].join("\n"),
+        };
+      }
+      try {
+        const options: {
+          maxMemories?: number;
+          maxTokens?: number;
+          aiEnhanced?: boolean;
+          searchMode?: "semantic" | "hybrid" | "keyword";
+        } = {};
+        if (flags["max-memories"]) options.maxMemories = parseInt(String(flags["max-memories"]), 10);
+        if (flags["max-tokens"]) options.maxTokens = parseInt(String(flags["max-tokens"]), 10);
+        if (flags["ai-enhanced"] === true) options.aiEnhanced = true;
+        if (flags["search-mode"]) options.searchMode = String(flags["search-mode"]) as "semantic" | "hybrid" | "keyword";
+
+        const context = await client.buildContextV2(query, options);
+
+        if (!context || (Array.isArray(context.memories) && context.memories.length === 0)) {
+          return { text: `No memories found for query: "${query}"` };
+        }
+
+        return { text: JSON.stringify(context, null, 2) };
+      } catch (err) {
+        return { text: `Error: ${String(err)}`, isError: true };
+      }
+    },
+  });
+
   // ========================================================================
   // Stale Session Cleanup Service (v0.13.0)
   // ========================================================================