@mem9/mem9 0.3.3 → 0.3.5-rc.1

package/README.md

@@ -1,6 +1,6 @@
 # OpenClaw Plugin for mnemos
 
-Memory plugin for [OpenClaw](https://github.com/openclaw) — replaces the built-in memory slot with cloud-persistent shared memory. Runs in server mode only, connecting to `mnemo-server` via `apiUrl` + `tenantID`.
+Memory plugin for [OpenClaw](https://github.com/openclaw) — replaces the built-in memory slot with cloud-persistent shared memory. Runs in server mode only, connecting to `mnemo-server` via `apiUrl` + `apiKey` (preferred) or legacy `tenantID`.
 
 ## 🚀 Quick Start (Server Mode)
 
@@ -17,7 +17,7 @@ curl -s -X POST http://localhost:8080/v1alpha1/mem9s \
   -d '{"name":"openclaw-tenant"}'
 
 # Response:
-# {"id": "uuid", "claim_url": "..."}
+# {"id": "uuid"}
 ```
 
 Add mnemo to your project's `openclaw.json`:
@@ -31,7 +31,7 @@ Add mnemo to your project's `openclaw.json`:
         "enabled": true,
         "config": {
           "apiUrl": "http://localhost:8080",
-          "tenantID": "uuid"
+          "apiKey": "uuid"
         }
       }
     }
@@ -41,7 +41,7 @@ Add mnemo to your project's `openclaw.json`:
 
 **That's it!** Restart OpenClaw and your agent now has persistent cloud memory.
 
-All memory calls use `/v1alpha1/mem9s/{tenantID}/memories/...` — the tenant ID is carried in the URL path, and no special headers are required.
+The plugin always uses `/v1alpha2/mem9s/memories/...` with `X-API-Key: <key>`. Legacy `tenantID` config is still supported as an alias for `apiKey`.
 
 ---
 
@@ -96,8 +96,8 @@ openclaw plugins install @mem9/openclaw
 ### Method B: From source
 
 ```bash
-git clone https://github.com/qiffang/mnemos.git
-cd mnemos/openclaw-plugin
+git clone https://github.com/mem9-ai/mem9.git
+cd mem9/openclaw-plugin
 npm install
 ```
 
@@ -127,12 +127,12 @@ curl -s -X POST http://localhost:8080/v1alpha1/mem9s \
   -d '{"name":"openclaw-tenant"}'
 
 # Response:
-# {"id": "uuid", "claim_url": "..."}
+# {"id": "uuid"}
 ```
 
 **Step 3: Configure each OpenClaw instance**
 
-Each agent uses the same `tenantID` for the shared memory pool. The tenant ID is part of the URL path for all memory calls.
+Each agent uses the same `apiKey` for the shared memory pool. The plugin sends that value in `X-API-Key` and never places it in the URL path. Legacy `tenantID` config still works as an alias for the same value.
 
 ```json
 {
@@ -145,7 +145,7 @@ Each agent uses the same `tenantID` for the shared memory pool. The tenant ID is
         "enabled": true,
         "config": {
           "apiUrl": "http://your-server:8080",
-          "tenantID": "uuid"
+          "apiKey": "uuid"
         }
       }
     }
@@ -153,17 +153,17 @@ Each agent uses the same `tenantID` for the shared memory pool. The tenant ID is
 }
 ```
 
-That's it. The server handles scoping and conflict resolution. Conceptually, the only required values are `apiUrl` + `tenantID`.
+That's it. The server handles scoping and conflict resolution. Conceptually, the only required values are `apiUrl` + `apiKey`.
 
 ### Verify
 
 Start OpenClaw. You should see:
 
 ```
-[mnemo] Server mode
+[mem9] Server mode
 ```
 
-If you see `[mnemo] No mode configured...`, check your `openclaw.json` config.
+If you see `[mem9] No mode configured...`, check your `openclaw.json` config.
 
 ## Config Schema
 
@@ -172,11 +172,10 @@ Defined in `openclaw.plugin.json`:
 | Field | Type | Description |
 |---|---|---|
 | `apiUrl` | string | mnemo-server URL |
-| `tenantID` | string | Tenant ID used in `/v1alpha1/mem9s/{tenantID}/memories` (preferred) |
-| `apiToken` | string | Legacy alias for `tenantID` — kept for backward compatibility |
-| `userToken` | string | Legacy alias for `tenantID` — kept for backward compatibility |
+| `apiKey` | string | Preferred key. Uses `/v1alpha2/mem9s/...` with `X-API-Key` header |
+| `tenantID` | string | Legacy alias for `apiKey`. The plugin still uses `/v1alpha2/mem9s/...` with `X-API-Key`. |
 
-> **Note**: `tenantID` is the preferred config field. For legacy setups, the plugin checks `tenantID` first, then falls back to `apiToken`, then `userToken`.
+> **Note**: `apiKey` takes precedence when both fields are set. If only `tenantID` is present, the plugin treats it as a legacy alias for `apiKey`, still uses v1alpha2, and logs a deprecation warning once at startup.
 
 ## File Structure
 
@@ -196,6 +195,6 @@ openclaw-plugin/
 
 | Problem | Cause | Fix |
 |---|---|---|
-| `No mode configured` | Missing config | Add `apiUrl` and `tenantID` (or legacy `apiToken`/`userToken`) to plugin config |
-| `Server mode requires...` | Missing tenant ID | Add `tenantID` (or legacy `apiToken`/`userToken`) to config |
+| `No mode configured` | Missing config | Add `apiUrl` and `apiKey` (or legacy `tenantID`) to plugin config |
+| `Server mode requires...` | Missing key | Add `apiKey` (or legacy `tenantID`) to config |
 | Plugin not loading | Not in memory slot | Set `"slots": {"memory": "openclaw"}` in openclaw.json |

package/backend.ts

@@ -21,7 +21,7 @@ export interface MemoryBackend {
 
   /**
    * Ingest messages into the smart memory pipeline.
-   * POST /v1alpha1/mem9s/{tenantID}/memories (messages body) → LLM extraction + reconciliation.
+   * POST /v1alpha{1,2}/mem9s/.../memories (messages body) → LLM extraction + reconciliation.
    */
   ingest(input: IngestInput): Promise<IngestResult>;
 }

package/hooks.ts

@@ -193,14 +193,14 @@ export function registerHooks(
 
         if (memories.length === 0) return;
 
-        logger.info(`[mnemo] Injecting ${memories.length} memories into prompt context`);
+        logger.info(`[mem9] Injecting ${memories.length} memories into prompt context`);
 
         return {
           prependContext: formatMemoriesBlock(memories),
         };
       } catch (err) {
         // Graceful degradation — never block the LLM call
-        logger.error(`[mnemo] before_prompt_build failed: ${String(err)}`);
+        logger.error(`[mem9] before_prompt_build failed: ${String(err)}`);
       }
     },
     { priority: 50 }, // Run after most plugins but before agent start
@@ -210,7 +210,7 @@ export function registerHooks(
   // after_compaction — no-op placeholder (no client-side cache to invalidate)
   // --------------------------------------------------------------------------
   api.on("after_compaction", async (_event: unknown) => {
-    logger.info("[mnemo] Compaction detected — memories will be re-queried on next prompt");
+    logger.info("[mem9] Compaction detected — memories will be re-queried on next prompt");
   });
 
   // --------------------------------------------------------------------------
@@ -247,10 +247,10 @@ export function registerHooks(
         tags: ["auto-capture", "session-summary", "pre-reset"],
       });
 
-      logger.info("[mnemo] Session context saved before reset");
+      logger.info("[mem9] Session context saved before reset");
     } catch (err) {
       // Best-effort — never block /reset
-      logger.error(`[mnemo] before_reset save failed: ${String(err)}`);
+      logger.error(`[mem9] before_reset save failed: ${String(err)}`);
     }
   });
 
@@ -330,10 +330,10 @@ export function registerHooks(
 
 
       if (result.status === "accepted") {
-        logger.info("[mnemo] Ingest accepted for async processing");
+        logger.info("[mem9] Ingest accepted for async processing");
       } else if ((result.memories_changed ?? 0) > 0) {
         logger.info(
-          `[mnemo] Ingested session: memories_changed=${result.memories_changed}, status=${result.status}`
+          `[mem9] Ingested session: memories_changed=${result.memories_changed}, status=${result.status}`
         );
       }
     } catch {

package/index.ts

@@ -13,7 +13,17 @@ import type {
 const DEFAULT_API_URL = "https://api.mem9.ai";
 
 function jsonResult(data: unknown) {
-  return data;
+  // Older OpenClaw versions may assume tool results have a normalized
+  // assistant-content shape and can crash on plain objects that omit `content`.
+  // Returning a JSON string keeps results readable while remaining compatible
+  // with both old and new hosts.
+  // https://github.com/openclaw/openclaw/blob/936607ca221a2f0c37ad976ddefcd39596f54793/CHANGELOG.md?plain=1#L1144
+  if (typeof data === "string") return data;
+  try {
+    return JSON.stringify(data, null, 2);
+  } catch {
+    return String(data);
+  }
 }
 
 interface OpenClawPluginApi {
@@ -232,39 +242,39 @@ const mnemoPlugin = {
     const cfg = (api.pluginConfig ?? {}) as PluginConfig;
     const effectiveApiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
     if (!cfg.apiUrl) {
-      api.logger.info(`[mnemo] apiUrl not configured, using default ${DEFAULT_API_URL}`);
+      api.logger.info(`[mem9] apiUrl not configured, using default ${DEFAULT_API_URL}`);
     }
 
-
-    const configuredTenantID = cfg.tenantID;
+    const configuredApiKey = cfg.apiKey ?? cfg.tenantID;
+    if (cfg.apiKey && cfg.tenantID) {
+      api.logger.info("[mem9] both apiKey and tenantID set; using apiKey");
+    } else if (cfg.tenantID) {
+      api.logger.info("[mem9] tenantID is deprecated; treating it as apiKey for v1alpha2");
+    }
     const registerTenant = async (agentName: string): Promise<string> => {
       const backend = new ServerBackend(effectiveApiUrl, "", agentName);
       const result = await backend.register();
-      const claimUrl = result.claim_url ?? "(not provided)";
-      api.logger.info(
-        `[mnemo] *** Auto-provisioned tenant_id=${result.id} *** Save this tenant ID to your config as tenantID`
-      );
       api.logger.info(
-        `[mnemo] Claim your TiDB instance at: ${claimUrl}`
+        `[mem9] *** Auto-provisioned apiKey=${result.id} *** Save this to your config as apiKey`
       );
       return result.id;
     };
     let registrationPromise: Promise<string> | null = null;
-    const resolveTenantID = (agentName: string): Promise<string> => {
-      if (configuredTenantID) return Promise.resolve(configuredTenantID);
+    const resolveAPIKey = (agentName: string): Promise<string> => {
+      if (configuredApiKey) return Promise.resolve(configuredApiKey);
       if (!registrationPromise) {
         registrationPromise = registerTenant(agentName);
       }
       return registrationPromise;
     };
 
-    api.logger.info("[mnemo] Server mode (tenant-scoped mem9 API)");
+    api.logger.info("[mem9] Server mode (v1alpha2)");
 
     const factory: ToolFactory = (ctx: ToolContext) => {
       const agentId = ctx.agentId ?? cfg.agentName ?? "agent";
       const backend = new LazyServerBackend(
         effectiveApiUrl,
-        () => resolveTenantID(agentId),
+        () => resolveAPIKey(agentId),
         agentId,
       );
       return buildTools(backend);
@@ -276,7 +286,7 @@ const mnemoPlugin = {
     // Uses the default workspace/agent context for hook-triggered operations.
     const hookBackend = new LazyServerBackend(
       effectiveApiUrl,
-      () => resolveTenantID(cfg.agentName ?? "agent"),
+      () => resolveAPIKey(cfg.agentName ?? "agent"),
       cfg.agentName ?? "agent",
     );
     registerHooks(api, hookBackend, api.logger, { maxIngestBytes: cfg.maxIngestBytes });
@@ -297,7 +307,7 @@ class LazyServerBackend implements MemoryBackend {
 
   constructor(
     private apiUrl: string,
-    private tenantIDProvider: () => Promise<string>,
+    private apiKeyProvider: () => Promise<string>,
     private agentId: string,
   ) {}
 
@@ -305,9 +315,9 @@ class LazyServerBackend implements MemoryBackend {
     if (this.resolved) return this.resolved;
     if (this.resolving) return this.resolving;
 
-    this.resolving = this.tenantIDProvider().then((tenantID) =>
+    this.resolving = this.apiKeyProvider().then((apiKey) =>
       Promise.resolve().then(() => {
-        this.resolved = new ServerBackend(this.apiUrl, tenantID, this.agentId);
+        this.resolved = new ServerBackend(this.apiUrl, apiKey, this.agentId);
         return this.resolved;
       })
     ).catch((err) => {

package/openclaw.plugin.json

@@ -10,17 +10,13 @@
         "type": "string",
         "description": "mnemo-server URL (server mode)"
       },
-      "tenantID": {
-        "type": "string",
-        "description": "Tenant ID for v1alpha1 mem9s routes (preferred)"
-      },
-      "apiToken": {
+      "apiKey": {
         "type": "string",
-        "description": "Legacy alias for tenantID (kept for backward compatibility)"
+        "description": "mem9 API key (secret — do not share)"
       },
-      "userToken": {
+      "tenantID": {
         "type": "string",
-        "description": "Legacy alias for tenantID"
+        "description": "Deprecated: use apiKey"
       }
     }
   },
@@ -29,17 +25,13 @@
       "label": "Server URL",
       "placeholder": "https://your-server.example.com"
     },
-    "tenantID": {
-      "label": "Tenant ID",
-      "placeholder": "uuid..."
-    },
-    "apiToken": {
-      "label": "Legacy Tenant ID Alias",
-      "placeholder": "uuid...",
+    "apiKey": {
+      "label": "API Key",
+      "placeholder": "key...",
       "sensitive": true
     },
-    "userToken": {
-      "label": "Legacy Tenant ID Alias",
+    "tenantID": {
+      "label": "Tenant ID (legacy)",
       "placeholder": "uuid...",
       "sensitive": true
     }

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@mem9/mem9",
-  "version": "0.3.3",
+  "version": "0.3.5-rc.1",
   "description": "OpenClaw shared memory plugin — cloud-persistent memory with hybrid vector + keyword search via mnemo-server",
   "type": "module",
   "license": "Apache-2.0",
-  "author": "qiffang",
+  "author": "mem9-ai",
   "repository": {
     "type": "git",
-    "url": "https://github.com/qiffang/mnemos.git",
+    "url": "https://github.com/mem9-ai/mem9.git",
     "directory": "openclaw-plugin"
   },
-  "homepage": "https://github.com/qiffang/mnemos/tree/main/openclaw-plugin#readme",
+  "homepage": "https://github.com/mem9-ai/mem9/tree/main/openclaw-plugin#readme",
   "keywords": [
     "openclaw",
     "openclaw-plugin",

package/server-backend.ts

@@ -12,17 +12,20 @@ import type {
 
 type ProvisionMem9sResponse = {
   id: string;
-  claim_url?: string;
 };
 
 export class ServerBackend implements MemoryBackend {
   private baseUrl: string;
-  private tenantID: string;
+  private apiKey: string;
   private agentName: string;
 
-  constructor(apiUrl: string, tenantID: string, agentName: string) {
+  constructor(
+    apiUrl: string,
+    apiKey: string,
+    agentName: string,
+  ) {
     this.baseUrl = apiUrl.replace(/\/+$/, "");
-    this.tenantID = tenantID;
+    this.apiKey = apiKey;
     this.agentName = agentName;
   }
 
@@ -39,22 +42,22 @@ export class ServerBackend implements MemoryBackend {
 
     const data = (await resp.json()) as ProvisionMem9sResponse;
     if (!data?.id) {
-      throw new Error("mem9s provision did not return tenant ID");
+      throw new Error("mem9s provision did not return API key");
     }
 
-    this.tenantID = data.id;
+    this.apiKey = data.id;
     return data;
   }
 
-  private tenantPath(path: string): string {
-    if (!this.tenantID) {
-      throw new Error("tenant ID is not configured");
+  private memoryPath(path: string): string {
+    if (!this.apiKey) {
+      throw new Error("API key is not configured");
     }
-    return `/v1alpha1/mem9s/${this.tenantID}${path}`;
+    return `/v1alpha2/mem9s${path}`;
   }
 
   async store(input: CreateMemoryInput): Promise<StoreResult> {
-    return this.request<StoreResult>("POST", this.tenantPath("/memories"), input);
+    return this.request<StoreResult>("POST", this.memoryPath("/memories"), input);
   }
 
   async search(input: SearchInput): Promise<SearchResult> {
@@ -71,7 +74,7 @@ export class ServerBackend implements MemoryBackend {
       total: number;
       limit: number;
       offset: number;
-    }>("GET", `${this.tenantPath("/memories")}${qs ? "?" + qs : ""}`);
+    }>("GET", `${this.memoryPath("/memories")}${qs ? "?" + qs : ""}`);
     return {
       data: raw.memories ?? [],
       total: raw.total,
@@ -82,7 +85,7 @@ export class ServerBackend implements MemoryBackend {
 
   async get(id: string): Promise<Memory | null> {
     try {
-      return await this.request<Memory>("GET", this.tenantPath(`/memories/${id}`));
+      return await this.request<Memory>("GET", this.memoryPath(`/memories/${id}`));
     } catch {
       return null;
     }
@@ -90,7 +93,7 @@ export class ServerBackend implements MemoryBackend {
 
   async update(id: string, input: UpdateMemoryInput): Promise<Memory | null> {
     try {
-      return await this.request<Memory>("PUT", this.tenantPath(`/memories/${id}`), input);
+      return await this.request<Memory>("PUT", this.memoryPath(`/memories/${id}`), input);
     } catch {
       return null;
     }
@@ -98,7 +101,7 @@ export class ServerBackend implements MemoryBackend {
 
   async remove(id: string): Promise<boolean> {
     try {
-      await this.request("DELETE", this.tenantPath(`/memories/${id}`));
+      await this.request("DELETE", this.memoryPath(`/memories/${id}`));
       return true;
     } catch {
       return false;
@@ -106,7 +109,7 @@ export class ServerBackend implements MemoryBackend {
   }
 
   async ingest(input: IngestInput): Promise<IngestResult> {
-    return this.request<IngestResult>("POST", this.tenantPath("/memories"), input);
+    return this.request<IngestResult>("POST", this.memoryPath("/memories"), input);
   }
 
   private async requestRaw(
@@ -118,6 +121,7 @@ export class ServerBackend implements MemoryBackend {
     const headers: Record<string, string> = {
       "Content-Type": "application/json",
       "X-Mnemo-Agent-Id": this.agentName,
+      "X-API-Key": this.apiKey,
     };
     return fetch(url, {
       method,

package/types.ts

@@ -1,9 +1,8 @@
 export interface PluginConfig {
   // Server mode (apiUrl present → server)
   apiUrl?: string;
+  apiKey?: string;
   tenantID?: string;
-  apiToken?: string;
-  userToken?: string;
 
   tenantName?: string;