@mem9/mem9 0.4.3 → 0.4.5

package/README.md

@@ -1,6 +1,8 @@
 # OpenClaw Plugin for mem9
 
-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`. Optional `provisionQueryParams` can forward `utm_*` attribution only during first-time auto-provisioning.
+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`. Optional `provisionToken` and `provisionQueryParams` are used only during first-time create-new setup before `apiKey` is written back.
+
+When `apiKey` is absent during create-new onboarding, the plugin does not auto-provision on startup. Instead, setup must call the explicit `mem9_provision_api_key` tool once after the first restart. The plugin coordinates that call across concurrent OpenClaw plugin registrations on the same machine and briefly reuses the generated key until config write-back completes.
 
 ## 🚀 Quick Start (Server Mode)
 
@@ -174,12 +176,13 @@ Defined in `openclaw.plugin.json`:
 |---|---|---|
 | `apiUrl` | string | mnemo-server URL |
 | `apiKey` | string | Preferred key. Uses `/v1alpha2/mem9s/...` with `X-API-Key` header |
-| `provisionQueryParams` | object | Optional `utm_*` map forwarded only to the initial `POST /v1alpha1/mem9s` auto-provision request when `apiKey` is absent |
+| `provisionToken` | string | Optional one-time create-new token used locally to ensure the explicit `mem9_provision_api_key` step runs only once before `apiKey` is persisted |
+| `provisionQueryParams` | object | Optional `utm_*` map forwarded only to the initial `POST /v1alpha1/mem9s` request made by `mem9_provision_api_key` when `apiKey` is absent |
 | `defaultTimeoutMs` | number | Default timeout for non-search mem9 API requests in milliseconds. Default: `8000` |
 | `searchTimeoutMs` | number | Timeout for `memory_search` and automatic recall search in milliseconds. Default: `15000` |
 | `tenantID` | string | Legacy alias for `apiKey`. The plugin still uses `/v1alpha2/mem9s/...` with `X-API-Key`. |
 
-> **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. `provisionQueryParams` is ignored after an `apiKey` is already configured, and non-`utm_*` keys are dropped before the provision request is sent.
+> **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. `provisionToken` and `provisionQueryParams` are ignored after an `apiKey` is already configured, and non-`utm_*` keys are dropped before the provision request is sent. During create-new onboarding, the plugin shares one in-flight explicit provision result across concurrent local registrations so repeated reloads or repeated setup retries do not create multiple keys before config write-back.
 
 ## Timeout Behavior
 
@@ -228,5 +231,6 @@ openclaw-plugin/
 |---|---|---|
 | `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 |
+| Multiple auto-provisioned keys appear during create-new | Setup called provision more than once before apiKey write-back, or an older plugin still auto-provisions on startup | Upgrade to `@mem9/mem9@0.4.6+`; newer builds only provision through `mem9_provision_api_key` and share one local result across duplicate setup retries |
 | Search requests time out | Hybrid/vector search exceeds plugin timeout | Increase `searchTimeoutMs` in plugin config |
 | Plugin not loading | Not in memory slot | Set `"slots": {"memory": "mem9"}` in openclaw.json |

package/backend.ts

@@ -9,6 +9,18 @@ import type {
   IngestResult,
 } from "./types.js";
 
+export class PendingProvisionError extends Error {
+  constructor(message = "mem9 create-new setup is waiting for an explicit mem9_provision_api_key call") {
+    super(message);
+    this.name = "PendingProvisionError";
+  }
+}
+
+export function isPendingProvisionError(err: unknown): err is PendingProvisionError {
+  return err instanceof PendingProvisionError
+    || (err instanceof Error && err.name === "PendingProvisionError");
+}
+
 /**
  * MemoryBackend — the abstraction that tools and hooks call through.
  */

package/hooks.ts

@@ -11,7 +11,7 @@
  * Reference: OpenClaw's built-in memory-lancedb extension uses the same pattern.
  */
 
-import type { MemoryBackend } from "./backend.js";
+import { isPendingProvisionError, type MemoryBackend } from "./backend.js";
 import type { Memory, IngestMessage } from "./types.js";
 
 // ---------------------------------------------------------------------------
@@ -195,6 +195,9 @@ export function registerHooks(
           prependContext: formatMemoriesBlock(memories),
         };
       } catch (err) {
+        if (isPendingProvisionError(err)) {
+          return;
+        }
         // Graceful degradation — never block the LLM call
         logger.error(`[mem9] before_prompt_build failed: ${String(err)}`);
       }
@@ -245,6 +248,9 @@ export function registerHooks(
 
       logger.info("[mem9] Session context saved before reset");
     } catch (err) {
+      if (isPendingProvisionError(err)) {
+        return;
+      }
       // Best-effort — never block /reset
       logger.error(`[mem9] before_reset save failed: ${String(err)}`);
     }
@@ -346,7 +352,10 @@ export function registerHooks(
           `[mem9] Ingested session: memories_changed=${result.memories_changed}, status=${result.status}`
         );
       }
-    } catch {
+    } catch (err) {
+      if (isPendingProvisionError(err)) {
+        return;
+      }
       // Best-effort — never fail the agent end phase
     }
   });

package/index.test.ts

@@ -3,15 +3,25 @@ import test from "node:test";
 
 import mnemoPlugin from "./index.js";
 
+interface RegisteredTool {
+  name: string;
+  execute: (_id: string, params: unknown) => Promise<unknown>;
+}
+
+interface SearchCapability {
+  search: (query: string, opts?: { limit?: number }) => Promise<{ data: unknown[]; total: number }>;
+}
+
 interface StubApi {
   pluginConfig?: unknown;
   logger: {
     info: (...args: unknown[]) => void;
     error: (...args: unknown[]) => void;
   };
-  registerTool: () => void;
+  registerTool: (factory: unknown, _opts?: unknown) => void;
   registerCapability?: (slot: string, capability: unknown) => void;
-  on: () => void;
+  on: (...args: unknown[]) => void;
+  getTools: (ctx?: { agentId?: string }) => RegisteredTool[];
 }
 
 function createStubApi(
@@ -24,6 +34,9 @@ function createStubApi(
 ): StubApi {
   const infoLogs = options?.infoLogs ?? [];
   const errorLogs = options?.errorLogs ?? [];
+  let toolFactory:
+    | ((ctx?: { agentId?: string }) => RegisteredTool[] | RegisteredTool | null | undefined)
+    | null = null;
 
   return {
     pluginConfig,
@@ -35,9 +48,21 @@ function createStubApi(
         errorLogs.push(args.map(String).join(" "));
       },
     },
-    registerTool: () => {},
+    registerTool: (factory: unknown) => {
+      toolFactory = factory as typeof toolFactory;
+    },
     registerCapability: options?.onRegisterCapability,
     on: () => {},
+    getTools: (ctx = {}) => {
+      if (!toolFactory) {
+        return [];
+      }
+      const tools = toolFactory(ctx);
+      if (!tools) {
+        return [];
+      }
+      return Array.isArray(tools) ? tools : [tools];
+    },
   };
 }
 
@@ -45,28 +70,54 @@ async function flushAsyncWork(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 0));
 }
 
-test("register eagerly auto-provisions when apiKey is absent", async () => {
+async function waitFor(predicate: () => boolean, timeoutMs = 2_000): Promise<void> {
+  const startedAt = Date.now();
+
+  while (!predicate()) {
+    if (Date.now() - startedAt > timeoutMs) {
+      throw new Error("timed out waiting for condition");
+    }
+    await new Promise((resolve) => setTimeout(resolve, 10));
+  }
+}
+
+function uniqueApiUrl(name: string): string {
+  return `https://api.mem9.ai/${name}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
+}
+
+function findTool(api: StubApi, name: string): RegisteredTool {
+  const tool = api.getTools({ agentId: "agent-test" }).find((item) => item.name === name);
+  if (!tool) {
+    throw new Error(`missing tool: ${name}`);
+  }
+  return tool;
+}
+
+function parseToolResult(result: unknown): unknown {
+  if (typeof result !== "string") {
+    return result;
+  }
+  return JSON.parse(result);
+}
+
+test("register does not auto-provision on startup during create-new", async () => {
   const originalFetch = globalThis.fetch;
+  const apiUrl = uniqueApiUrl("no-startup-provision");
   const requests: string[] = [];
   const infoLogs: string[] = [];
   const errorLogs: string[] = [];
 
   globalThis.fetch = async (input) => {
     requests.push(String(input));
-
-    return new Response(JSON.stringify({ id: "space-1" }), {
-      status: 201,
-      headers: {
-        "Content-Type": "application/json",
-      },
-    });
+    throw new Error("unexpected fetch");
   };
 
   try {
     mnemoPlugin.register(
       createStubApi(
         {
-          apiUrl: "https://api.mem9.ai",
+          apiUrl,
+          provisionToken: "token-startup",
           provisionQueryParams: {
             utm_source: "bosn",
           },
@@ -77,51 +128,67 @@ test("register eagerly auto-provisions when apiKey is absent", async () => {
 
     await flushAsyncWork();
 
+    assert.deepEqual(requests, []);
     assert.deepEqual(errorLogs, []);
-    assert.equal(requests.length, 1);
-    assert.equal(
-      requests[0],
-      "https://api.mem9.ai/v1alpha1/mem9s?utm_source=bosn",
-    );
     assert.equal(
-      infoLogs.includes("[mem9] apiKey not configured; starting auto-provision"),
+      infoLogs.includes("[mem9] apiKey not configured; waiting for explicit create-new provision"),
       true,
     );
-    assert.equal(
-      infoLogs.some((msg) => msg.includes("*** Auto-provisioned apiKey=space-1 ***")),
-      true,
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("memory capability stays idle until explicit provision runs", async () => {
+  const originalFetch = globalThis.fetch;
+  const apiUrl = uniqueApiUrl("pending-capability");
+  let capability: SearchCapability | null = null;
+  const requests: string[] = [];
+
+  globalThis.fetch = async (input) => {
+    requests.push(String(input));
+    throw new Error("unexpected fetch");
+  };
+
+  try {
+    mnemoPlugin.register(
+      createStubApi(
+        {
+          apiUrl,
+          provisionToken: "token-capability",
+        },
+        {
+          onRegisterCapability: (_slot, registeredCapability) => {
+            capability = registeredCapability as SearchCapability;
+          },
+        },
+      ),
     );
+
+    assert.notEqual(capability, null);
+
+    const result = await capability!.search("hello");
+
+    assert.deepEqual(result, { data: [], total: 0 });
+    assert.deepEqual(requests, []);
   } finally {
     globalThis.fetch = originalFetch;
   }
 });
 
-test("search retries auto-provision after an eager startup failure", async () => {
+test("mem9_provision_api_key provisions once and unlocks memory access", async () => {
   const originalFetch = globalThis.fetch;
-  const infoLogs: string[] = [];
-  const errorLogs: string[] = [];
-  let provisionAttempts = 0;
+  const apiUrl = uniqueApiUrl("explicit-provision");
+  let capability: SearchCapability | null = null;
+  let provisionRequests = 0;
   let searchRequests = 0;
-  let capability: {
-    search: (query: string, opts?: { limit?: number }) => Promise<{ data: unknown[]; total: number }>;
-  } | null = null;
 
   globalThis.fetch = async (input, init) => {
     const url = String(input);
 
-    if (url.includes("/v1alpha1/mem9s")) {
-      provisionAttempts += 1;
-
-      if (provisionAttempts === 1) {
-        return new Response(JSON.stringify({ error: "boom" }), {
-          status: 500,
-          headers: {
-            "Content-Type": "application/json",
-          },
-        });
-      }
-
-      return new Response(JSON.stringify({ id: "space-2" }), {
+    if (url === `${apiUrl}/v1alpha1/mem9s?utm_source=bosn`) {
+      provisionRequests += 1;
+      return new Response(JSON.stringify({ id: "space-explicit" }), {
         status: 201,
         headers: {
           "Content-Type": "application/json",
@@ -132,7 +199,7 @@ test("search retries auto-provision after an eager startup failure", async () =>
     if (url.includes("/v1alpha2/mem9s/memories")) {
       searchRequests += 1;
       const headers = init?.headers as Record<string, string> | undefined;
-      assert.equal(headers?.["X-API-Key"], "space-2");
+      assert.equal(headers?.["X-API-Key"], "space-explicit");
 
       return new Response(
         JSON.stringify({
@@ -154,37 +221,158 @@ test("search retries auto-provision after an eager startup failure", async () =>
   };
 
   try {
-    mnemoPlugin.register(
-      createStubApi(
-        {
-          apiUrl: "https://api.mem9.ai",
+    const api = createStubApi(
+      {
+        apiUrl,
+        provisionToken: "token-explicit",
+        provisionQueryParams: {
+          utm_source: "bosn",
         },
-        {
-          infoLogs,
-          errorLogs,
-          onRegisterCapability: (_slot, registeredCapability) => {
-            capability = registeredCapability as typeof capability;
-          },
+      },
+      {
+        onRegisterCapability: (_slot, registeredCapability) => {
+          capability = registeredCapability as SearchCapability;
         },
-      ),
+      },
     );
+    mnemoPlugin.register(api);
 
-    await flushAsyncWork();
+    const tool = findTool(api, "mem9_provision_api_key");
+    const provisionResult = parseToolResult(await tool.execute("tool-1", {})) as {
+      ok: boolean;
+      data?: { apiKey?: string };
+    };
 
-    assert.equal(provisionAttempts, 1);
-    assert.equal(
-      errorLogs.some((msg) => msg.includes("auto-provision failed: mem9s provision failed (500):")),
-      true,
-    );
-    assert.notEqual(capability, null);
+    assert.equal(provisionResult.ok, true);
+    assert.equal(provisionResult.data?.apiKey, "space-explicit");
+    assert.equal(provisionRequests, 1);
 
-    const result = await capability!.search("hello");
+    assert.notEqual(capability, null);
+    const searchResult = await capability!.search("hello");
 
-    assert.deepEqual(result, { data: [], total: 0 });
-    assert.equal(provisionAttempts, 2);
+    assert.deepEqual(searchResult, { data: [], total: 0 });
+    assert.equal(provisionRequests, 1);
     assert.equal(searchRequests, 1);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("concurrent explicit provision calls share one server request", async () => {
+  const originalFetch = globalThis.fetch;
+  const apiUrl = uniqueApiUrl("shared-explicit");
+  let provisionRequests = 0;
+  const provisionControl: { release: () => void } = {
+    release: () => {},
+  };
+  const provisionGate = new Promise<void>((resolve) => {
+    provisionControl.release = resolve;
+  });
+
+  globalThis.fetch = async (input) => {
+    const url = String(input);
+
+    if (url === `${apiUrl}/v1alpha1/mem9s`) {
+      provisionRequests += 1;
+      await provisionGate;
+      return new Response(JSON.stringify({ id: "space-shared-explicit" }), {
+        status: 201,
+        headers: {
+          "Content-Type": "application/json",
+        },
+      });
+    }
+
+    throw new Error(`unexpected fetch: ${url}`);
+  };
+
+  try {
+    const pluginConfig = {
+      apiUrl,
+      provisionToken: "token-shared-explicit",
+    };
+    const apiA = createStubApi(pluginConfig);
+    const apiB = createStubApi(pluginConfig);
+
+    mnemoPlugin.register(apiA);
+    mnemoPlugin.register(apiB);
+
+    const toolA = findTool(apiA, "mem9_provision_api_key");
+    const toolB = findTool(apiB, "mem9_provision_api_key");
+
+    const promiseA = toolA.execute("tool-a", {});
+    const promiseB = toolB.execute("tool-b", {});
+
+    await waitFor(() => provisionRequests === 1);
+    provisionControl.release();
+
+    const resultA = parseToolResult(await promiseA) as { ok: boolean; data?: { apiKey?: string } };
+    const resultB = parseToolResult(await promiseB) as { ok: boolean; data?: { apiKey?: string } };
+
+    assert.equal(provisionRequests, 1);
+    assert.equal(resultA.ok, true);
+    assert.equal(resultB.ok, true);
+    assert.equal(resultA.data?.apiKey, "space-shared-explicit");
+    assert.equal(resultB.data?.apiKey, "space-shared-explicit");
+  } finally {
+    provisionControl.release();
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("a second setup retry reuses the shared provisioned key before config write-back", async () => {
+  const originalFetch = globalThis.fetch;
+  const apiUrl = uniqueApiUrl("shared-retry");
+  const infoLogsA: string[] = [];
+  const infoLogsB: string[] = [];
+  let provisionRequests = 0;
+
+  globalThis.fetch = async (input) => {
+    const url = String(input);
+
+    if (url === `${apiUrl}/v1alpha1/mem9s`) {
+      provisionRequests += 1;
+      return new Response(JSON.stringify({ id: "space-shared-retry" }), {
+        status: 201,
+        headers: {
+          "Content-Type": "application/json",
+        },
+      });
+    }
+
+    throw new Error(`unexpected fetch: ${url}`);
+  };
+
+  try {
+    const pluginConfig = {
+      apiUrl,
+      provisionToken: "token-shared-retry",
+    };
+
+    const apiA = createStubApi(pluginConfig, { infoLogs: infoLogsA });
+    mnemoPlugin.register(apiA);
+    const firstTool = findTool(apiA, "mem9_provision_api_key");
+    const firstResult = parseToolResult(await firstTool.execute("tool-a", {})) as {
+      ok: boolean;
+      data?: { apiKey?: string };
+    };
+
+    assert.equal(firstResult.ok, true);
+    assert.equal(firstResult.data?.apiKey, "space-shared-retry");
+
+    const apiB = createStubApi(pluginConfig, { infoLogs: infoLogsB });
+    mnemoPlugin.register(apiB);
+    const secondTool = findTool(apiB, "mem9_provision_api_key");
+    const secondResult = parseToolResult(await secondTool.execute("tool-b", {})) as {
+      ok: boolean;
+      data?: { apiKey?: string };
+    };
+
+    assert.equal(provisionRequests, 1);
+    assert.equal(secondResult.ok, true);
+    assert.equal(secondResult.data?.apiKey, "space-shared-retry");
     assert.equal(
-      infoLogs.some((msg) => msg.includes("*** Auto-provisioned apiKey=space-2 ***")),
+      infoLogsB.includes("[mem9] reusing shared explicit-provision result pending config write-back"),
       true,
     );
   } finally {

package/index.ts

@@ -1,4 +1,9 @@
-import type { MemoryBackend } from "./backend.js";
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { PendingProvisionError, isPendingProvisionError, type MemoryBackend } from "./backend.js";
 import {
   DEFAULT_SEARCH_TIMEOUT_MS,
   DEFAULT_TIMEOUT_MS,
@@ -18,6 +23,29 @@ import type {
 
 const DEFAULT_API_URL = "https://api.mem9.ai";
 const TIMEOUT_FIELDS = ["defaultTimeoutMs", "searchTimeoutMs"] as const;
+const SHARED_PROVISION_DIR = path.join(os.homedir(), ".openclaw", "mem9", "provision");
+const SHARED_PROVISION_POLL_INTERVAL_MS = 250;
+const SHARED_PROVISION_RESULT_TTL_MS = 2 * 60 * 1000;
+const sharedProvisionPromises = new Map<string, Promise<string>>();
+
+type SharedProvisionState =
+  | {
+      status: "pending";
+      startedAt: number;
+      pid: number;
+    }
+  | {
+      status: "done";
+      startedAt: number;
+      finishedAt: number;
+      apiKey: string;
+    }
+  | {
+      status: "error";
+      startedAt: number;
+      finishedAt: number;
+      error: string;
+    };
 
 function normalizeTimeoutMs(
   value: unknown,
@@ -79,6 +107,229 @@ function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function sharedProvisionKey(
+  apiUrl: string,
+  provisionQueryParams: Record<string, string>,
+  provisionToken: string,
+): string {
+  const normalizedProvisionQueryParams = Object.fromEntries(
+    Object.entries(provisionQueryParams).sort(([left], [right]) => left.localeCompare(right)),
+  );
+
+  return createHash("sha256")
+    .update(
+      JSON.stringify({
+        apiUrl,
+        provisionToken,
+        provisionQueryParams: normalizedProvisionQueryParams,
+      }),
+    )
+    .digest("hex");
+}
+
+function sharedProvisionStatePath(sharedKey: string): string {
+  return path.join(SHARED_PROVISION_DIR, `${sharedKey}.json`);
+}
+
+async function readSharedProvisionState(filePath: string): Promise<SharedProvisionState | null> {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw) as Partial<SharedProvisionState>;
+    if (parsed.status === "pending" && typeof parsed.startedAt === "number") {
+      return {
+        status: "pending",
+        startedAt: parsed.startedAt,
+        pid: typeof parsed.pid === "number" ? parsed.pid : 0,
+      };
+    }
+    if (
+      parsed.status === "done"
+      && typeof parsed.startedAt === "number"
+      && typeof parsed.finishedAt === "number"
+      && typeof parsed.apiKey === "string"
+    ) {
+      return {
+        status: "done",
+        startedAt: parsed.startedAt,
+        finishedAt: parsed.finishedAt,
+        apiKey: parsed.apiKey,
+      };
+    }
+    if (
+      parsed.status === "error"
+      && typeof parsed.startedAt === "number"
+      && typeof parsed.finishedAt === "number"
+      && typeof parsed.error === "string"
+    ) {
+      return {
+        status: "error",
+        startedAt: parsed.startedAt,
+        finishedAt: parsed.finishedAt,
+        error: parsed.error,
+      };
+    }
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+      return null;
+    }
+  }
+  return null;
+}
+
+async function writeSharedProvisionState(
+  filePath: string,
+  state: SharedProvisionState,
+): Promise<void> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(filePath, JSON.stringify(state), "utf8");
+}
+
+async function createSharedProvisionPendingState(
+  filePath: string,
+  startedAt: number,
+): Promise<boolean> {
+  await mkdir(path.dirname(filePath), { recursive: true });
+  try {
+    await writeFile(
+      filePath,
+      JSON.stringify({
+        status: "pending",
+        startedAt,
+        pid: process.pid,
+      } satisfies SharedProvisionState),
+      { encoding: "utf8", flag: "wx" },
+    );
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "EEXIST") {
+      return false;
+    }
+    throw err;
+  }
+}
+
+async function removeSharedProvisionState(filePath: string): Promise<void> {
+  await rm(filePath, { force: true });
+}
+
+async function waitForSharedProvisionResult(
+  filePath: string,
+  waitTimeoutMs: number,
+): Promise<string | null> {
+  const deadline = Date.now() + waitTimeoutMs;
+
+  while (true) {
+    const state = await readSharedProvisionState(filePath);
+    const now = Date.now();
+
+    if (!state) {
+      return null;
+    }
+
+    if (state.status === "done") {
+      if (now - state.finishedAt <= SHARED_PROVISION_RESULT_TTL_MS) {
+        return state.apiKey;
+      }
+      await removeSharedProvisionState(filePath);
+      return null;
+    }
+
+    if (state.status === "error") {
+      await removeSharedProvisionState(filePath);
+      throw new Error(state.error);
+    }
+
+    if (now - state.startedAt > waitTimeoutMs || now >= deadline) {
+      await removeSharedProvisionState(filePath);
+      return null;
+    }
+
+    await sleep(SHARED_PROVISION_POLL_INTERVAL_MS);
+  }
+}
+
+async function resolveSharedProvisionedAPIKey(
+  apiUrl: string,
+  provisionQueryParams: Record<string, string>,
+  provisionToken: string,
+  timeouts: Required<BackendTimeouts>,
+  logger: OpenClawPluginApi["logger"],
+  registerTenant: () => Promise<string>,
+): Promise<string> {
+  const key = sharedProvisionKey(apiUrl, provisionQueryParams, provisionToken);
+  const existingPromise = sharedProvisionPromises.get(key);
+  if (existingPromise) {
+    return existingPromise;
+  }
+
+  const waitTimeoutMs = Math.max(timeouts.defaultTimeoutMs + 5_000, 30_000);
+  const filePath = sharedProvisionStatePath(key);
+  const sharedPromise = (async () => {
+    while (true) {
+      const state = await readSharedProvisionState(filePath);
+      const now = Date.now();
+
+      if (state?.status === "done") {
+        if (now - state.finishedAt <= SHARED_PROVISION_RESULT_TTL_MS) {
+          logger.info("[mem9] reusing shared explicit-provision result pending config write-back");
+          return state.apiKey;
+        }
+        await removeSharedProvisionState(filePath);
+        continue;
+      }
+
+      if (state?.status === "error") {
+        await removeSharedProvisionState(filePath);
+      } else if (state?.status === "pending") {
+        if (now - state.startedAt > waitTimeoutMs) {
+          await removeSharedProvisionState(filePath);
+          continue;
+        }
+        logger.info("[mem9] explicit provision already in progress in another mem9 instance; waiting");
+        const sharedApiKey = await waitForSharedProvisionResult(filePath, waitTimeoutMs);
+        if (sharedApiKey) {
+          return sharedApiKey;
+        }
+        continue;
+      }
+
+      const startedAt = Date.now();
+      const acquired = await createSharedProvisionPendingState(filePath, startedAt);
+      if (!acquired) {
+        continue;
+      }
+
+      try {
+        const apiKey = await registerTenant();
+        await writeSharedProvisionState(filePath, {
+          status: "done",
+          startedAt,
+          finishedAt: Date.now(),
+          apiKey,
+        });
+        return apiKey;
+      } catch (err) {
+        await writeSharedProvisionState(filePath, {
+          status: "error",
+          startedAt,
+          finishedAt: Date.now(),
+          error: errorMessage(err),
+        });
+        throw err;
+      }
+    }
+  })().finally(() => {
+    sharedProvisionPromises.delete(key);
+  });
+
+  sharedProvisionPromises.set(key, sharedPromise);
+  return sharedPromise;
+}
+
 interface MemoryCapability {
   search: (query: string, opts?: { limit?: number }) => Promise<{ data: Memory[]; total: number }>;
   store: (content: string, opts?: { tags?: string[]; source?: string }) => Promise<unknown>;
@@ -121,7 +372,10 @@ interface AnyAgentTool {
   execute: (_id: string, params: unknown) => Promise<unknown>;
 }
 
-function buildTools(backend: MemoryBackend): AnyAgentTool[] {
+function buildTools(
+  backend: MemoryBackend,
+  provisionAPIKey: (() => Promise<string>) | null,
+): AnyAgentTool[] {
   return [
     {
       name: "memory_store",
@@ -294,6 +548,41 @@ function buildTools(backend: MemoryBackend): AnyAgentTool[] {
         }
       },
     },
+
+    {
+      name: "mem9_provision_api_key",
+      label: "Provision mem9 API Key",
+      description:
+        "Create exactly one mem9 API key during create-new setup after the first restart. Use only when apiKey is absent.",
+      parameters: {
+        type: "object",
+        properties: {},
+        required: [],
+      },
+      async execute(_id: string, _params: unknown) {
+        if (!provisionAPIKey) {
+          return jsonResult({
+            ok: false,
+            error: "mem9_provision_api_key is only available during create-new setup before apiKey is persisted",
+          });
+        }
+
+        try {
+          const apiKey = await provisionAPIKey();
+          return jsonResult({
+            ok: true,
+            data: {
+              apiKey,
+            },
+          });
+        } catch (err) {
+          return jsonResult({
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        }
+      },
+    },
   ];
 }
 
@@ -306,6 +595,11 @@ const mnemoPlugin = {
   register(api: OpenClawPluginApi) {
     const cfg = (api.pluginConfig ?? {}) as PluginConfig;
     const effectiveApiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
+    const configuredProvisionToken =
+      typeof cfg.provisionToken === "string" && cfg.provisionToken.trim() !== ""
+        ? cfg.provisionToken.trim()
+        : null;
+    const provisionQueryParams = cfg.provisionQueryParams ?? {};
     const timeoutConfig = resolveTimeouts(cfg, api.logger);
     const hookAgentId = cfg.agentName ?? "agent";
     if (!cfg.apiUrl) {
@@ -325,7 +619,7 @@ const mnemoPlugin = {
         agentName,
         {
           timeouts: timeoutConfig,
-          provisionQueryParams: cfg.provisionQueryParams ?? {},
+          provisionQueryParams,
         },
       );
       const result = await backend.register();
@@ -334,36 +628,70 @@ const mnemoPlugin = {
       );
       return result.id;
     };
+    let runtimeProvisionedAPIKey: string | null = null;
     let registrationPromise: Promise<string> | null = null;
-    const resolveAPIKey = (agentName: string): Promise<string> => {
-      if (configuredApiKey) return Promise.resolve(configuredApiKey);
+    const provisionAPIKey = (agentName: string): Promise<string> => {
+      if (configuredApiKey) {
+        return Promise.reject(
+          new Error(
+            "mem9_provision_api_key is only available during create-new setup before apiKey is persisted",
+          ),
+        );
+      }
+      if (runtimeProvisionedAPIKey) {
+        return Promise.resolve(runtimeProvisionedAPIKey);
+      }
+      if (!configuredProvisionToken) {
+        return Promise.reject(
+          new Error("mem9 create-new setup cannot provision because provisionToken is missing"),
+        );
+      }
       if (!registrationPromise) {
-        registrationPromise = registerTenant(agentName).catch((err) => {
-          registrationPromise = null;
-          throw err;
-        });
+        registrationPromise = resolveSharedProvisionedAPIKey(
+          effectiveApiUrl,
+          provisionQueryParams,
+          configuredProvisionToken,
+          timeoutConfig,
+          api.logger,
+          () => registerTenant(agentName),
+        )
+          .then((apiKey) => {
+            runtimeProvisionedAPIKey = apiKey;
+            return apiKey;
+          })
+          .catch((err) => {
+            registrationPromise = null;
+            throw err;
+          });
       }
       return registrationPromise;
     };
+    const resolveAPIKey = (): Promise<string> => {
+      if (configuredApiKey) return Promise.resolve(configuredApiKey);
+      if (runtimeProvisionedAPIKey) {
+        return Promise.resolve(runtimeProvisionedAPIKey);
+      }
+      return Promise.reject(new PendingProvisionError());
+    };
 
     api.logger.info("[mem9] Server mode (v1alpha2)");
-
     if (!configuredApiKey) {
-      api.logger.info("[mem9] apiKey not configured; starting auto-provision");
-      void resolveAPIKey(hookAgentId).catch((err) => {
-        api.logger.error(`[mem9] auto-provision failed: ${errorMessage(err)}`);
-      });
+      if (configuredProvisionToken) {
+        api.logger.info("[mem9] apiKey not configured; waiting for explicit create-new provision");
+      } else {
+        api.logger.info("[mem9] apiKey not configured; mem9 will stay idle until apiKey is configured");
+      }
     }
 
     const factory: ToolFactory = (ctx: ToolContext) => {
       const agentId = ctx.agentId ?? cfg.agentName ?? "agent";
       const backend = new LazyServerBackend(
         effectiveApiUrl,
-        () => resolveAPIKey(agentId),
+        resolveAPIKey,
         agentId,
         timeoutConfig,
       );
-      return buildTools(backend);
+      return buildTools(backend, configuredApiKey ? null : () => provisionAPIKey(agentId));
     };
 
     api.registerTool(factory, { names: toolNames });
@@ -371,11 +699,25 @@ const mnemoPlugin = {
     // Shared lazy backend for hooks and capability registration.
     const hookBackend = new LazyServerBackend(
       effectiveApiUrl,
-      () => resolveAPIKey(hookAgentId),
+      resolveAPIKey,
       hookAgentId,
       timeoutConfig,
     );
 
+    const withPendingProvisionFallback = async <T>(
+      action: () => Promise<T>,
+      fallback: T,
+    ): Promise<T> => {
+      try {
+        return await action();
+      } catch (err) {
+        if (isPendingProvisionError(err)) {
+          return fallback;
+        }
+        throw err;
+      }
+    };
+
     // Register memory capability so OpenClaw 2026.4.2+ binds this plugin to
     // the memory slot. Without this, the plugin is treated as a legacy
     // hook-only plugin and automatic context injection won't work.
@@ -383,14 +725,24 @@ const mnemoPlugin = {
     if (typeof api.registerCapability === "function") {
       api.registerCapability("memory", {
         search: async (query, opts) => {
-          const result = await hookBackend.search({ q: query, limit: opts?.limit });
+          const result = await withPendingProvisionFallback(
+            () => hookBackend.search({ q: query, limit: opts?.limit }),
+            { data: [], total: 0, limit: opts?.limit ?? 20, offset: 0 },
+          );
           return { data: result.data, total: result.total };
         },
         store: async (content, opts) => {
-          return hookBackend.store({ content, tags: opts?.tags, source: opts?.source });
+          try {
+            return await hookBackend.store({ content, tags: opts?.tags, source: opts?.source });
+          } catch (err) {
+            if (isPendingProvisionError(err)) {
+              return null;
+            }
+            throw err;
+          }
         },
-        get: (id) => hookBackend.get(id),
-        remove: (id) => hookBackend.remove(id),
+        get: (id) => withPendingProvisionFallback(() => hookBackend.get(id), null),
+        remove: (id) => withPendingProvisionFallback(() => hookBackend.remove(id), false),
       });
     }
 
@@ -408,6 +760,7 @@ const toolNames = [
   "memory_get",
   "memory_update",
   "memory_delete",
+  "mem9_provision_api_key",
 ];
 
 class LazyServerBackend implements MemoryBackend {

package/openclaw.plugin.json

@@ -14,9 +14,13 @@
         "type": "string",
         "description": "mem9 API key (secret — do not share)"
       },
+      "provisionToken": {
+        "type": "string",
+        "description": "One-time create-new token used locally to ensure explicit API-key provisioning runs only once before apiKey is persisted"
+      },
       "provisionQueryParams": {
         "type": "object",
-        "description": "Optional utm_* params forwarded only during first-time auto-provisioning",
+        "description": "Optional utm_* params forwarded only by the explicit first-time create-new provision step",
         "additionalProperties": {
           "type": "string"
         }
@@ -47,6 +51,10 @@
       "placeholder": "key...",
       "sensitive": true
     },
+    "provisionToken": {
+      "label": "Provision Token",
+      "placeholder": "create-new only"
+    },
     "defaultTimeoutMs": {
       "label": "Default Timeout (ms)",
       "placeholder": "8000"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem9/mem9",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "OpenClaw shared memory plugin — cloud-persistent memory with hybrid vector + keyword search via mnemo-server",
   "type": "module",
   "license": "Apache-2.0",

package/server-backend.test.ts

@@ -3,7 +3,7 @@ import test from "node:test";
 
 import { ServerBackend } from "./server-backend.js";
 
-test("register forwards only utm_* params during auto-provision", async () => {
+test("register forwards only utm_* params during create-new provision", async () => {
   const originalFetch = globalThis.fetch;
   let requestedURL = "";
 

package/types.ts

@@ -2,6 +2,7 @@ export interface PluginConfig {
   // Server mode (apiUrl present → server)
   apiUrl?: string;
   apiKey?: string;
+  provisionToken?: string;
   provisionQueryParams?: Record<string, string>;
   tenantID?: string;
   defaultTimeoutMs?: number;