@matrixorigin/thememoria 0.4.0 → 0.4.1

package/openclaw/__tests__/http-client.test.ts

@@ -0,0 +1,290 @@
+/**
+ * Group 3: Cloud API Communication
+ * "Does the plugin talk to Memoria API correctly?"
+ *
+ * Bug 2 regression: no X-User-Id header should be sent (API key determines identity).
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { MemoriaHttpTransport } from "../http-client.js";
+import { buildApiConfig, mockFetch, type MockFetchCall } from "./helpers.js";
+
+let fetchMock: ReturnType<typeof mockFetch>;
+let transport: MemoriaHttpTransport;
+const originalFetch = globalThis.fetch;
+
+beforeEach(() => {
+  fetchMock = mockFetch();
+  transport = new MemoriaHttpTransport(buildApiConfig(), "test-user");
+});
+
+afterEach(() => {
+  globalThis.fetch = originalFetch;
+});
+
+describe("Group 3: Cloud API Communication", () => {
+  // ── Constructor & lifecycle ──────────────────────────────
+
+  describe("Constructor & lifecycle", () => {
+    it("3.1 missing apiUrl throws", () => {
+      expect(() => new MemoriaHttpTransport(
+        buildApiConfig({ apiUrl: undefined }), "u",
+      )).toThrow(/apiUrl/);
+    });
+
+    it("3.2 missing apiKey throws", () => {
+      expect(() => new MemoriaHttpTransport(
+        buildApiConfig({ apiKey: undefined }), "u",
+      )).toThrow(/apiKey/);
+    });
+
+    it("3.3 trailing slash stripped from apiUrl", async () => {
+      const t = new MemoriaHttpTransport(
+        buildApiConfig({ apiUrl: "https://example.com///" }), "u",
+      );
+      fetchMock.respondWith(200, { status: "ok" });
+      await t.healthCheck();
+      expect(fetchMock.lastCall()!.url).toMatch(/^https:\/\/example\.com\/health/);
+    });
+
+    it("3.4 isAlive() always returns true", () => {
+      expect(transport.isAlive()).toBe(true);
+    });
+
+    it("3.5 close() is a no-op", () => {
+      expect(() => transport.close()).not.toThrow();
+    });
+  });
+
+  // ── Auth & headers (Bug 2 regression) ────────────────────
+
+  describe("Auth & headers", () => {
+    it("3.6 every request has Authorization: Bearer <key>", async () => {
+      fetchMock.respondWith(200, { results: [] });
+      await transport.callTool("memory_retrieve", { query: "test", top_k: 5 });
+      expect(fetchMock.lastCall()!.headers["Authorization"]).toBe("Bearer sk-test-key-123");
+    });
+
+    it("3.7 every request has Content-Type: application/json", async () => {
+      fetchMock.respondWith(200, { results: [] });
+      await transport.callTool("memory_retrieve", { query: "test", top_k: 5 });
+      expect(fetchMock.lastCall()!.headers["Content-Type"]).toBe("application/json");
+    });
+
+    it("3.8 NO X-User-Id header sent (Bug 2 fix)", async () => {
+      fetchMock.respondWith(200, { results: [] });
+      await transport.callTool("memory_retrieve", { query: "test", top_k: 5 });
+      expect(fetchMock.lastCall()!.headers["X-User-Id"]).toBeUndefined();
+    });
+  });
+
+  // ── Tool → endpoint mapping (table-driven) ──────────────
+
+  describe("Tool → endpoint mapping", () => {
+    const cases: Array<{
+      id: string;
+      tool: string;
+      args: Record<string, unknown>;
+      method: string;
+      pathPattern: RegExp;
+    }> = [
+      { id: "3.9", tool: "memory_store", args: { content: "hi" }, method: "POST", pathPattern: /\/v1\/memories$/ },
+      { id: "3.10", tool: "memory_retrieve", args: { query: "q" }, method: "POST", pathPattern: /\/v1\/memories\/retrieve$/ },
+      { id: "3.11", tool: "memory_search", args: { query: "q" }, method: "POST", pathPattern: /\/v1\/memories\/search$/ },
+      { id: "3.12", tool: "memory_list", args: { limit: 10 }, method: "GET", pathPattern: /\/v1\/memories\?limit=10/ },
+      { id: "3.13", tool: "memory_profile", args: {}, method: "GET", pathPattern: /\/v1\/profiles\/me$/ },
+      { id: "3.14", tool: "memory_correct", args: { memory_id: "abc", new_content: "x" }, method: "PUT", pathPattern: /\/v1\/memories\/abc\/correct$/ },
+      { id: "3.15", tool: "memory_correct", args: { query: "q", new_content: "x" }, method: "POST", pathPattern: /\/v1\/memories\/correct$/ },
+      { id: "3.16", tool: "memory_purge", args: { topic: "old" }, method: "POST", pathPattern: /\/v1\/memories\/purge$/ },
+      { id: "3.17", tool: "memory_observe", args: { messages: [] }, method: "POST", pathPattern: /\/v1\/observe$/ },
+      { id: "3.18", tool: "memory_governance", args: {}, method: "POST", pathPattern: /\/v1\/governance$/ },
+      { id: "3.19", tool: "memory_snapshot", args: { name: "s1" }, method: "POST", pathPattern: /\/v1\/snapshots$/ },
+      { id: "3.20", tool: "memory_snapshots", args: {}, method: "GET", pathPattern: /\/v1\/snapshots\?/ },
+      { id: "3.21", tool: "memory_rollback", args: { name: "s1" }, method: "POST", pathPattern: /\/v1\/snapshots\/s1\/rollback$/ },
+      { id: "3.22", tool: "memory_branch", args: { name: "b1" }, method: "POST", pathPattern: /\/v1\/branches$/ },
+      { id: "3.23", tool: "memory_branches", args: {}, method: "GET", pathPattern: /\/v1\/branches$/ },
+      { id: "3.24", tool: "memory_checkout", args: { name: "b1" }, method: "POST", pathPattern: /\/v1\/branches\/b1\/checkout$/ },
+      { id: "3.25", tool: "memory_branch_delete", args: { name: "b1" }, method: "DELETE", pathPattern: /\/v1\/branches\/b1$/ },
+      { id: "3.26", tool: "memory_merge", args: { source: "b1" }, method: "POST", pathPattern: /\/v1\/branches\/b1\/merge$/ },
+      { id: "3.27", tool: "memory_diff", args: { source: "b1" }, method: "GET", pathPattern: /\/v1\/branches\/b1\/diff\?/ },
+    ];
+
+    for (const { id, tool, args, method, pathPattern } of cases) {
+      it(`${id} ${tool} → ${method} ${pathPattern.source}`, async () => {
+        fetchMock.respondWith(200, tool === "memory_store"
+          ? { memory_id: "new-id", content: args.content ?? "" }
+          : tool.includes("retrieve") || tool.includes("search") || tool === "memory_list"
+            ? { results: [] }
+            : tool === "memory_profile"
+              ? { profile: "test" }
+              : tool === "memory_purge"
+                ? { purged: 1 }
+                : tool === "memory_correct"
+                  ? { memory_id: "abc", content: "x" }
+                  : tool === "memory_snapshots"
+                    ? { snapshots: [] }
+                    : tool === "memory_branches"
+                      ? { branches: [] }
+                      : { ok: true });
+        await transport.callTool(tool, args);
+        const call = fetchMock.lastCall()!;
+        expect(call.method).toBe(method);
+        expect(call.url).toMatch(pathPattern);
+      });
+    }
+
+    it("3.28 memory_rebuild_index returns cloud message, no HTTP call", async () => {
+      fetchMock.reset();
+      const result = await transport.callTool("memory_rebuild_index", {});
+      expect(fetchMock.calls.length).toBe(0);
+      const text = JSON.parse((result as any).content[0].text);
+      expect(text.message).toMatch(/cloud/i);
+    });
+
+    it("3.29 healthCheck → GET /health/instance", async () => {
+      fetchMock.respondWith(200, { status: "ok", instance_id: "i-1", db: true });
+      const result = await transport.healthCheck();
+      expect(fetchMock.lastCall()!.method).toBe("GET");
+      expect(fetchMock.lastCall()!.url).toMatch(/\/health\/instance$/);
+      expect(result.status).toBe("ok");
+      expect(result.instance_id).toBe("i-1");
+    });
+
+    it("3.30 unknown tool throws", async () => {
+      await expect(transport.callTool("memory_nonexistent", {}))
+        .rejects.toThrow(/Unknown Memoria tool/);
+    });
+  });
+
+  // ── MCP envelope compatibility ───────────────────────────
+
+  describe("MCP envelope", () => {
+    it("3.31 callTool wraps result in MCP content block", async () => {
+      fetchMock.respondWith(200, { memory_id: "x", content: "hello" });
+      const result = await transport.callTool("memory_store", { content: "hello" }) as any;
+      expect(result.content).toBeInstanceOf(Array);
+      expect(result.content[0].type).toBe("text");
+      expect(typeof result.content[0].text).toBe("string");
+    });
+
+    it("3.32 string result wrapped as-is", async () => {
+      fetchMock.respondWith(200, { profile: "User likes cats" });
+      const result = await transport.callTool("memory_profile", {}) as any;
+      expect(result.content[0].text).toBe("User likes cats");
+    });
+  });
+
+  // ── Response text formatting ─────────────────────────────
+
+  describe("Response text formatting", () => {
+    it("3.34 memory_store → 'Stored memory <id>: <content>'", async () => {
+      fetchMock.respondWith(200, { memory_id: "m1", content: "hello world" });
+      const result = await transport.callTool("memory_store", { content: "hello world" }) as any;
+      expect(result.content[0].text).toBe("Stored memory m1: hello world");
+    });
+
+    it("3.35 memory_retrieve with results → '[id] (type) content' per line", async () => {
+      fetchMock.respondWith(200, {
+        results: [
+          { memory_id: "m1", memory_type: "semantic", content: "First" },
+          { memory_id: "m2", memory_type: "profile", content: "Second" },
+        ],
+      });
+      const result = await transport.callTool("memory_retrieve", { query: "q" }) as any;
+      const text = result.content[0].text;
+      expect(text).toContain("[m1] (semantic) First");
+      expect(text).toContain("[m2] (profile) Second");
+    });
+
+    it("3.36 memory_retrieve empty → 'No relevant memories found.'", async () => {
+      fetchMock.respondWith(200, { results: [] });
+      const result = await transport.callTool("memory_retrieve", { query: "q" }) as any;
+      expect(result.content[0].text).toBe("No relevant memories found.");
+    });
+
+    it("3.38 memory_profile with profile → profile text", async () => {
+      fetchMock.respondWith(200, { profile: "Likes TypeScript" });
+      const result = await transport.callTool("memory_profile", {}) as any;
+      expect(result.content[0].text).toBe("Likes TypeScript");
+    });
+
+    it("3.39 memory_profile no profile → 'No profile memories found.'", async () => {
+      fetchMock.respondWith(200, { profile: null });
+      const result = await transport.callTool("memory_profile", {}) as any;
+      expect(result.content[0].text).toBe("No profile memories found.");
+    });
+
+    it("3.40 memory_correct → 'Corrected memory <id>: <content>'", async () => {
+      fetchMock.respondWith(200, { memory_id: "m1", content: "updated" });
+      const result = await transport.callTool("memory_correct", {
+        memory_id: "m1", new_content: "updated",
+      }) as any;
+      expect(result.content[0].text).toBe("Corrected memory m1: updated");
+    });
+
+    it("3.41 memory_purge → 'Purged N memory(ies).'", async () => {
+      fetchMock.respondWith(200, { purged: 3 });
+      const result = await transport.callTool("memory_purge", { topic: "old" }) as any;
+      expect(result.content[0].text).toBe("Purged 3 memory(ies).");
+    });
+
+    it("3.42 memory_snapshots with items → formatted list", async () => {
+      fetchMock.respondWith(200, {
+        snapshots: [
+          { name: "snap1", timestamp: "2026-03-23T10:00:00Z" },
+          { name: "snap2", timestamp: "2026-03-23T11:00:00Z" },
+        ],
+      });
+      const result = await transport.callTool("memory_snapshots", {}) as any;
+      const text = result.content[0].text;
+      expect(text).toContain("Snapshots (2):");
+      expect(text).toContain("snap1 (2026-03-23T10:00:00Z)");
+      expect(text).toContain("snap2 (2026-03-23T11:00:00Z)");
+    });
+
+    it("3.43 memory_snapshots empty → 'Snapshots (0):'", async () => {
+      fetchMock.respondWith(200, { snapshots: [] });
+      const result = await transport.callTool("memory_snapshots", {}) as any;
+      expect(result.content[0].text).toBe("Snapshots (0):");
+    });
+
+    it("3.44 memory_branches with items → formatted list with active marker", async () => {
+      fetchMock.respondWith(200, {
+        branches: [
+          { name: "main", active: true },
+          { name: "experiment", active: false },
+        ],
+      });
+      const result = await transport.callTool("memory_branches", {}) as any;
+      const text = result.content[0].text;
+      expect(text).toContain("Branches:");
+      expect(text).toContain("main ← active");
+      expect(text).toContain("experiment");
+      expect(text).not.toContain("experiment ← active");
+    });
+
+    it("3.45 memory_branches empty → default main active", async () => {
+      fetchMock.respondWith(200, { branches: [] });
+      const result = await transport.callTool("memory_branches", {}) as any;
+      expect(result.content[0].text).toContain("main ← active");
+    });
+  });
+
+  // ── Error handling ───────────────────────────────────────
+
+  describe("Error handling", () => {
+    it("3.46 non-2xx HTTP → error with method, path, status", async () => {
+      fetchMock.respondWith(500, "Internal Server Error");
+      await expect(transport.callTool("memory_retrieve", { query: "q" }))
+        .rejects.toThrow(/POST.*\/v1\/memories\/retrieve.*500/);
+    });
+
+    it("3.48 empty response body → { ok: true }", async () => {
+      // Override fetch to return empty body
+      globalThis.fetch = async () => new Response("", { status: 200 });
+      const t = new MemoriaHttpTransport(buildApiConfig(), "u");
+      const result = await t.callTool("memory_consolidate", {}) as any;
+      // Should not throw, result wraps { ok: true }
+      expect(result.content[0].text).toContain("ok");
+    });
+  });
+});

package/openclaw/__tests__/parsers.test.ts

@@ -0,0 +1,197 @@
+/**
+ * Group 4: Response Parsing
+ * "Can the plugin understand what Memoria returns?"
+ *
+ * Tests the text parsers that bridge Memoria's output to typed data structures.
+ * These parsers are used by both embedded (MCP binary) and api (HTTP) modes.
+ *
+ * Note: parsers are not exported from client.ts, so we test them indirectly
+ * through MemoriaClient methods with a mocked transport.
+ * For direct parser testing, we import the module and use the internal functions
+ * via a re-export helper or test the formatted text round-trip.
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { MemoriaHttpTransport } from "../http-client.js";
+import { buildApiConfig, mockFetch } from "./helpers.js";
+
+// We test parsers indirectly: http-client produces formatted text that
+// matches the Rust MCP binary format, and client.ts parsers consume it.
+// Here we verify the http-client output IS parseable by checking the
+// text format matches the expected patterns.
+
+const originalFetch = globalThis.fetch;
+let fetchHelper: ReturnType<typeof mockFetch>;
+
+function setup() {
+  fetchHelper = mockFetch();
+  return new MemoriaHttpTransport(buildApiConfig(), "test-user");
+}
+
+function teardown() {
+  globalThis.fetch = originalFetch;
+}
+
+describe("Group 4: Response Parsing (format round-trip)", () => {
+  afterEach(teardown);
+
+  // ── Memory list parsing ──────────────────────────────────
+
+  describe("Memory list text format", () => {
+    it("4.1 single memory → [id] (type) content", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, {
+        results: [{ memory_id: "abc-123", memory_type: "semantic", content: "Hello world" }],
+      });
+      const result = await t.callTool("memory_retrieve", { query: "q" }) as any;
+      const text = result.content[0].text;
+      expect(text).toMatch(/^\[abc-123\] \(semantic\) Hello world$/);
+    });
+
+    it("4.2 multiple memories → one per line", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, {
+        results: [
+          { memory_id: "m1", memory_type: "semantic", content: "First" },
+          { memory_id: "m2", memory_type: "profile", content: "Second" },
+        ],
+      });
+      const result = await t.callTool("memory_search", { query: "q" }) as any;
+      const lines = result.content[0].text.split("\n");
+      expect(lines).toHaveLength(2);
+      expect(lines[0]).toMatch(/^\[m1\] \(semantic\) First$/);
+      expect(lines[1]).toMatch(/^\[m2\] \(profile\) Second$/);
+    });
+
+    it("4.3 empty results → 'No relevant memories found.'", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, { results: [] });
+      const result = await t.callTool("memory_retrieve", { query: "q" }) as any;
+      expect(result.content[0].text).toBe("No relevant memories found.");
+    });
+
+    it("4.4 array response shape (no results wrapper)", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, [
+        { memory_id: "m1", memory_type: "semantic", content: "Direct array" },
+      ]);
+      const result = await t.callTool("memory_retrieve", { query: "q" }) as any;
+      expect(result.content[0].text).toContain("[m1] (semantic) Direct array");
+    });
+  });
+
+  // ── Store/correct/purge parsing ──────────────────────────
+
+  describe("Store/correct/purge text format", () => {
+    it("4.5 store → 'Stored memory <id>: <content>'", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, { memory_id: "new-1", content: "Test memory" });
+      const result = await t.callTool("memory_store", { content: "Test memory" }) as any;
+      expect(result.content[0].text).toBe("Stored memory new-1: Test memory");
+    });
+
+    it("4.6 store with missing id → uses empty string", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, { content: "No id returned" });
+      const result = await t.callTool("memory_store", { content: "No id returned" }) as any;
+      expect(result.content[0].text).toBe("Stored memory : No id returned");
+    });
+
+    it("4.7 correct by id → 'Corrected memory <id>: <content>'", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, { memory_id: "m1", content: "Fixed" });
+      const result = await t.callTool("memory_correct", {
+        memory_id: "m1", new_content: "Fixed",
+      }) as any;
+      expect(result.content[0].text).toBe("Corrected memory m1: Fixed");
+    });
+
+    it("4.8 correct by query → same format", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, { memory_id: "m2", content: "Updated" });
+      const result = await t.callTool("memory_correct", {
+        query: "old content", new_content: "Updated",
+      }) as any;
+      expect(result.content[0].text).toBe("Corrected memory m2: Updated");
+    });
+
+    it("4.9 purge → 'Purged N memory(ies).'", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, { purged: 5 });
+      const result = await t.callTool("memory_purge", { topic: "test" }) as any;
+      expect(result.content[0].text).toBe("Purged 5 memory(ies).");
+    });
+
+    it("4.10 purge with zero → 'Purged 0 memory(ies).'", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, { purged: 0 });
+      const result = await t.callTool("memory_purge", { topic: "nothing" }) as any;
+      expect(result.content[0].text).toBe("Purged 0 memory(ies).");
+    });
+  });
+
+  // ── Snapshot list parsing ────────────────────────────────
+
+  describe("Snapshot list text format", () => {
+    it("4.11 snapshots → 'Snapshots (N):\\n  name (ts)'", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, {
+        snapshots: [
+          { name: "before-refactor", timestamp: "2026-03-23T10:00:00Z" },
+        ],
+      });
+      const result = await t.callTool("memory_snapshots", {}) as any;
+      const text = result.content[0].text;
+      expect(text).toMatch(/^Snapshots \(1\):/);
+      expect(text).toContain("before-refactor (2026-03-23T10:00:00Z)");
+    });
+
+    it("4.12 empty snapshots → 'Snapshots (0):'", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, { snapshots: [] });
+      const result = await t.callTool("memory_snapshots", {}) as any;
+      expect(result.content[0].text).toBe("Snapshots (0):");
+    });
+  });
+
+  // ── Branch list parsing ──────────────────────────────────
+
+  describe("Branch list text format", () => {
+    it("4.14 branches with active marker", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, {
+        branches: [
+          { name: "main", active: true },
+          { name: "experiment", active: false },
+        ],
+      });
+      const result = await t.callTool("memory_branches", {}) as any;
+      const text = result.content[0].text;
+      expect(text).toContain("main ← active");
+      expect(text).toMatch(/^\s*experiment$/m);
+    });
+
+    it("4.15 branches with no active → main defaults active", async () => {
+      // When API returns no active flag, formatBranchList just passes through
+      // The client-side parseBranches defaults main to active
+      const t = setup();
+      fetchHelper.respondWith(200, {
+        branches: [
+          { name: "main", active: false },
+          { name: "dev", active: false },
+        ],
+      });
+      const result = await t.callTool("memory_branches", {}) as any;
+      const text = result.content[0].text;
+      // formatBranchList respects the active flag from API
+      expect(text).toContain("Branches:");
+      expect(text).toContain("main");
+    });
+
+    it("4.16 empty branches → default main active", async () => {
+      const t = setup();
+      fetchHelper.respondWith(200, { branches: [] });
+      const result = await t.callTool("memory_branches", {}) as any;
+      expect(result.content[0].text).toContain("main ← active");
+    });
+  });
+});

package/openclaw/client.ts

@@ -6,6 +6,7 @@ import type {
   MemoriaTrustTier,
 } from "./config.js";
 import { MEMORIA_MEMORY_TYPES } from "./config.js";
+import { MemoriaHttpTransport } from "./http-client.js";
 
 export type MemoriaMemoryRecord = {
   memory_id: string;
@@ -85,7 +86,7 @@ type McpContentBlock = {
 };
 
 const MCP_PROTOCOL_VERSION = "2024-11-05";
-const PLUGIN_VERSION = "0.3.0";
+const PLUGIN_VERSION = "0.4.0";
 const MEMORY_LINE_RE = /^\[([^\]]+)\] \(([^)]+)\) ?([\s\S]*)$/;
 
 function asRecord(value: unknown): Record<string, unknown> | null {
@@ -425,13 +426,8 @@ class MemoriaMcpSession {
 
   private buildArgs(): string[] {
     const args = ["mcp"];
-    if (this.config.backend === "http") {
-      args.push("--api-url", this.config.apiUrl!);
-      args.push("--token", this.config.apiKey!);
-      args.push("--user", this.userId);
-      return args;
-    }
-
+    // MemoriaMcpSession is only used for embedded mode now.
+    // API mode uses MemoriaHttpTransport directly.
     args.push("--db-url", this.config.dbUrl);
     args.push("--user", this.userId);
     return args;
@@ -543,7 +539,7 @@ class MemoriaMcpSession {
 }
 
 export class MemoriaClient {
-  private readonly sessions = new Map<string, MemoriaMcpSession>();
+  private readonly sessions = new Map<string, MemoriaMcpSession | MemoriaHttpTransport>();
   private readonly memoryCache = new Map<string, MemoriaMemoryRecord>();
 
   constructor(private readonly config: MemoriaPluginConfig) {}
@@ -556,6 +552,17 @@ export class MemoriaClient {
   }
 
   async health(userId: string) {
+    if (this.config.backend === "api") {
+      const transport = this.getSession(userId) as MemoriaHttpTransport;
+      const result = await transport.healthCheck();
+      return {
+        status: result.status,
+        mode: this.config.backend,
+        instance_id: result.instance_id,
+        db: result.db,
+        warnings: [],
+      };
+    }
     await this.callToolText(userId, "memory_list", { limit: 1 });
     return {
       status: "ok",
@@ -865,6 +872,9 @@ export class MemoriaClient {
   }
 
   async rebuildIndex(table: string) {
+    if (this.config.backend === "api") {
+      return { message: "rebuild_index is managed by the cloud service and not available via API." };
+    }
     return parseGenericResult(
       await this.callToolText(this.config.defaultUserId, "memory_rebuild_index", {
         table,
@@ -1016,14 +1026,20 @@ export class MemoriaClient {
     throw new Error(`Memoria tool '${name}' returned no text content.`);
   }
 
-  private getSession(userId: string): MemoriaMcpSession {
+  private getSession(userId: string): MemoriaMcpSession | MemoriaHttpTransport {
     const key = `${this.config.backend}:${userId}`;
     const existing = this.sessions.get(key);
     if (existing?.isAlive()) {
       return existing;
     }
     existing?.close();
-    const created = new MemoriaMcpSession(this.config, userId);
+
+    let created: MemoriaMcpSession | MemoriaHttpTransport;
+    if (this.config.backend === "api") {
+      created = new MemoriaHttpTransport(this.config, userId);
+    } else {
+      created = new MemoriaMcpSession(this.config, userId);
+    }
     this.sessions.set(key, created);
     return created;
   }

package/openclaw/config.ts

@@ -9,7 +9,7 @@ export const MEMORIA_MEMORY_TYPES = [
 ] as const;
 
 export const MEMORIA_TRUST_TIERS = ["T1", "T2", "T3", "T4"] as const;
-export const MEMORIA_BACKENDS = ["embedded", "http"] as const;
+export const MEMORIA_BACKENDS = ["embedded", "api"] as const;
 export const MEMORIA_USER_ID_STRATEGIES = ["config", "agentId", "sessionKey"] as const;
 
 export type MemoriaMemoryType = (typeof MEMORIA_MEMORY_TYPES)[number];
@@ -84,7 +84,7 @@ const UI_HINTS: Record<
 > = {
   backend: {
     label: "Backend Mode",
-    help: "embedded runs the Rust memoria CLI locally against MatrixOne; http connects to an existing Memoria API.",
+    help: "embedded runs the Rust memoria CLI locally against MatrixOne; api connects directly to the Memoria REST API over HTTP.",
     placeholder: DEFAULTS.backend,
   },
   dbUrl: {
@@ -94,14 +94,14 @@ const UI_HINTS: Record<
   },
   apiUrl: {
     label: "Memoria API URL",
-    help: "Only used when backend=http.",
+    help: "Only used when backend=api.",
     placeholder: DEFAULTS.apiUrl,
   },
   apiKey: {
     label: "Memoria API Token",
-    help: "Bearer token for backend=http.",
+    help: "Bearer token for backend=api.",
     sensitive: true,
-    placeholder: "mem-...",
+    placeholder: "sk-...",
   },
   memoriaExecutable: {
     label: "Memoria Executable",
@@ -511,18 +511,26 @@ export function parseMemoriaPluginConfig(value: unknown): MemoriaPluginConfig {
   const input = asObject(value ?? {});
   assertNoUnknownKeys(input);
 
+  // Reject legacy "http" backend — it was removed in favor of "api"
+  if (typeof input.backend === "string" && input.backend.trim().toLowerCase() === "http") {
+    fail(
+      "backend 'http' is no longer supported. Use 'api' for cloud mode (direct HTTP to Memoria REST API, no binary needed).",
+      ["backend"],
+    );
+  }
+
   const backend = readEnum(input, "backend", MEMORIA_BACKENDS, DEFAULTS.backend);
   const apiUrl = optional(readString(input, "apiUrl", { defaultValue: DEFAULTS.apiUrl }))?.replace(
     /\/+$/,
     "",
   );
   const apiKey = optional(readString(input, "apiKey"));
-  if (backend === "http") {
+  if (backend === "api") {
     if (!apiUrl) {
-      fail("apiUrl required when backend=http", ["apiUrl"]);
+      fail("apiUrl required when backend=api", ["apiUrl"]);
     }
     if (!apiKey) {
-      fail("apiKey required when backend=http", ["apiKey"]);
+      fail("apiKey required when backend=api", ["apiKey"]);
     }
   }