@mem9/mem9 0.4.4 → 0.4.5

package/README.md

@@ -1,8 +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 coordinates auto-provision across concurrent OpenClaw plugin registrations on the same machine and briefly reuses the generated key until config write-back completes. This avoids duplicate mem9 spaces when the host reloads the plugin multiple times around a restart.
+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)
 
@@ -176,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. During create-new onboarding, the plugin also shares one in-flight auto-provision result across concurrent local registrations so repeated plugin reloads do not create multiple keys before config write-back.
+> **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
 
@@ -230,6 +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 | Host reloaded the plugin before config write-back | Upgrade to `@mem9/mem9@0.4.4+`; the plugin now shares one local auto-provision result across concurrent registrations |
+| 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,19 +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;
-}
-
-interface SearchCapability {
-  search: (query: string, opts?: { limit?: number }) => Promise<{ data: unknown[]; total: number }>;
+  on: (...args: unknown[]) => void;
+  getTools: (ctx?: { agentId?: string }) => RegisteredTool[];
 }
 
 function createStubApi(
@@ -28,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,
@@ -39,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];
+    },
   };
 }
 
@@ -64,22 +85,31 @@ function uniqueApiUrl(name: string): string {
   return `https://api.mem9.ai/${name}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 }
 
-test("register eagerly auto-provisions when apiKey is absent", async () => {
+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("eager");
+  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 {
@@ -87,6 +117,7 @@ test("register eagerly auto-provisions when apiKey is absent", async () => {
       createStubApi(
         {
           apiUrl,
+          provisionToken: "token-startup",
           provisionQueryParams: {
             utm_source: "bosn",
           },
@@ -95,20 +126,12 @@ test("register eagerly auto-provisions when apiKey is absent", async () => {
       ),
     );
 
-    await waitFor(() => requests.length === 1);
+    await flushAsyncWork();
 
+    assert.deepEqual(requests, []);
     assert.deepEqual(errorLogs, []);
-    assert.equal(requests.length, 1);
-    assert.equal(
-      requests[0],
-      `${apiUrl}/v1alpha1/mem9s?utm_source=bosn`,
-    );
-    assert.equal(
-      infoLogs.includes("[mem9] apiKey not configured; starting auto-provision"),
-      true,
-    );
     assert.equal(
-      infoLogs.some((msg) => msg.includes("*** Auto-provisioned apiKey=space-1 ***")),
+      infoLogs.includes("[mem9] apiKey not configured; waiting for explicit create-new provision"),
       true,
     );
   } finally {
@@ -116,130 +139,56 @@ test("register eagerly auto-provisions when apiKey is absent", async () => {
   }
 });
 
-test("register shares an in-flight auto-provision across concurrent plugin registrations", async () => {
+test("memory capability stays idle until explicit provision runs", async () => {
   const originalFetch = globalThis.fetch;
-  const apiUrl = uniqueApiUrl("shared-pending");
-  const infoLogsA: string[] = [];
-  const infoLogsB: string[] = [];
-  const errorLogs: string[] = [];
-  let capabilityA: SearchCapability | null = null;
-  let capabilityB: SearchCapability | null = null;
-  let provisionRequests = 0;
-  let searchRequests = 0;
-  const provisionControl: { release: () => void } = {
-    release: () => {},
-  };
-  const provisionGate = new Promise<void>((resolve) => {
-    provisionControl.release = resolve;
-  });
-
-  globalThis.fetch = async (input, init) => {
-    const url = String(input);
-
-    if (url === `${apiUrl}/v1alpha1/mem9s`) {
-      provisionRequests += 1;
-      await provisionGate;
-      return new Response(JSON.stringify({ id: "space-shared-pending" }), {
-        status: 201,
-        headers: {
-          "Content-Type": "application/json",
-        },
-      });
-    }
-
-    if (url.includes("/v1alpha2/mem9s/memories")) {
-      searchRequests += 1;
-      const headers = init?.headers as Record<string, string> | undefined;
-      assert.equal(headers?.["X-API-Key"], "space-shared-pending");
-
-      return new Response(
-        JSON.stringify({
-          memories: [],
-          total: 0,
-          limit: 20,
-          offset: 0,
-        }),
-        {
-          status: 200,
-          headers: {
-            "Content-Type": "application/json",
-          },
-        },
-      );
-    }
+  const apiUrl = uniqueApiUrl("pending-capability");
+  let capability: SearchCapability | null = null;
+  const requests: string[] = [];
 
-    throw new Error(`unexpected fetch: ${url}`);
+  globalThis.fetch = async (input) => {
+    requests.push(String(input));
+    throw new Error("unexpected fetch");
   };
 
   try {
     mnemoPlugin.register(
       createStubApi(
-        { apiUrl },
         {
-          infoLogs: infoLogsA,
-          errorLogs,
-          onRegisterCapability: (_slot, registeredCapability) => {
-            capabilityA = registeredCapability as typeof capabilityA;
-          },
+          apiUrl,
+          provisionToken: "token-capability",
         },
-      ),
-    );
-    mnemoPlugin.register(
-      createStubApi(
-        { apiUrl },
         {
-          infoLogs: infoLogsB,
-          errorLogs,
           onRegisterCapability: (_slot, registeredCapability) => {
-            capabilityB = registeredCapability as typeof capabilityB;
+            capability = registeredCapability as SearchCapability;
           },
         },
       ),
     );
 
-    await waitFor(() => provisionRequests === 1);
-
-    assert.equal(provisionRequests, 1);
-    provisionControl.release();
-
-    await waitFor(() => searchRequests === 0);
-
-    assert.deepEqual(errorLogs, []);
-    if (!capabilityA || !capabilityB) {
-      throw new Error("capability registration did not complete");
-    }
-
-    const readyCapabilityA: SearchCapability = capabilityA;
-    const readyCapabilityB: SearchCapability = capabilityB;
+    assert.notEqual(capability, null);
 
-    await readyCapabilityA.search("hello");
-    await readyCapabilityB.search("hello");
+    const result = await capability!.search("hello");
 
-    assert.equal(provisionRequests, 1);
-    assert.equal(searchRequests, 2);
+    assert.deepEqual(result, { data: [], total: 0 });
+    assert.deepEqual(requests, []);
   } finally {
-    provisionControl.release();
     globalThis.fetch = originalFetch;
   }
 });
 
-test("register reuses a shared auto-provisioned key before config write-back", async () => {
+test("mem9_provision_api_key provisions once and unlocks memory access", async () => {
   const originalFetch = globalThis.fetch;
-  const apiUrl = uniqueApiUrl("shared-done");
-  const infoLogsA: string[] = [];
-  const infoLogsB: string[] = [];
-  const errorLogs: string[] = [];
-  let capabilityA: SearchCapability | null = null;
-  let capabilityB: SearchCapability | null = null;
+  const apiUrl = uniqueApiUrl("explicit-provision");
+  let capability: SearchCapability | null = null;
   let provisionRequests = 0;
   let searchRequests = 0;
 
   globalThis.fetch = async (input, init) => {
     const url = String(input);
 
-    if (url === `${apiUrl}/v1alpha1/mem9s`) {
+    if (url === `${apiUrl}/v1alpha1/mem9s?utm_source=bosn`) {
       provisionRequests += 1;
-      return new Response(JSON.stringify({ id: "space-shared-done" }), {
+      return new Response(JSON.stringify({ id: "space-explicit" }), {
         status: 201,
         headers: {
           "Content-Type": "application/json",
@@ -250,7 +199,7 @@ test("register reuses a shared auto-provisioned key before config write-back", a
     if (url.includes("/v1alpha2/mem9s/memories")) {
       searchRequests += 1;
       const headers = init?.headers as Record<string, string> | undefined;
-      assert.equal(headers?.["X-API-Key"], "space-shared-done");
+      assert.equal(headers?.["X-API-Key"], "space-explicit");
 
       return new Response(
         JSON.stringify({
@@ -272,125 +221,118 @@ test("register reuses a shared auto-provisioned key before config write-back", a
   };
 
   try {
-    mnemoPlugin.register(
-      createStubApi(
-        { apiUrl },
-        {
-          infoLogs: infoLogsA,
-          errorLogs,
-          onRegisterCapability: (_slot, registeredCapability) => {
-            capabilityA = registeredCapability as typeof capabilityA;
-          },
+    const api = createStubApi(
+      {
+        apiUrl,
+        provisionToken: "token-explicit",
+        provisionQueryParams: {
+          utm_source: "bosn",
         },
-      ),
-    );
-
-    await waitFor(() =>
-      infoLogsA.some((msg) => msg.includes("*** Auto-provisioned apiKey=space-shared-done ***")),
-    );
-
-    mnemoPlugin.register(
-      createStubApi(
-        { apiUrl },
-        {
-          infoLogs: infoLogsB,
-          errorLogs,
-          onRegisterCapability: (_slot, registeredCapability) => {
-            capabilityB = registeredCapability as typeof capabilityB;
-          },
+      },
+      {
+        onRegisterCapability: (_slot, registeredCapability) => {
+          capability = registeredCapability as SearchCapability;
         },
-      ),
+      },
     );
+    mnemoPlugin.register(api);
 
-    await waitFor(() =>
-      infoLogsB.includes("[mem9] reusing shared auto-provisioned apiKey pending config write-back"),
-    );
+    const tool = findTool(api, "mem9_provision_api_key");
+    const provisionResult = parseToolResult(await tool.execute("tool-1", {})) as {
+      ok: boolean;
+      data?: { apiKey?: string };
+    };
 
-    assert.deepEqual(errorLogs, []);
+    assert.equal(provisionResult.ok, true);
+    assert.equal(provisionResult.data?.apiKey, "space-explicit");
     assert.equal(provisionRequests, 1);
-    if (!capabilityA || !capabilityB) {
-      throw new Error("capability registration did not complete");
-    }
 
-    const readyCapabilityA: SearchCapability = capabilityA;
-    const readyCapabilityB: SearchCapability = capabilityB;
-
-    await readyCapabilityA.search("hello");
-    await readyCapabilityB.search("hello");
+    assert.notEqual(capability, null);
+    const searchResult = await capability!.search("hello");
 
-    assert.equal(searchRequests, 2);
-    assert.equal(
-      infoLogsB.includes("[mem9] reusing shared auto-provisioned apiKey pending config write-back"),
-      true,
-    );
+    assert.deepEqual(searchResult, { data: [], total: 0 });
+    assert.equal(provisionRequests, 1);
+    assert.equal(searchRequests, 1);
   } finally {
     globalThis.fetch = originalFetch;
   }
 });
 
-test("register does not auto-provision on empty config", async () => {
+test("concurrent explicit provision calls share one server request", async () => {
   const originalFetch = globalThis.fetch;
-  const requests: string[] = [];
-  const infoLogs: string[] = [];
-  const errorLogs: string[] = [];
+  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) => {
-    requests.push(String(input));
+    const url = String(input);
 
-    return new Response(JSON.stringify({ id: "space-unexpected" }), {
-      status: 201,
-      headers: {
-        "Content-Type": "application/json",
-      },
-    });
+    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 {
-    mnemoPlugin.register(
-      createStubApi(
-        {},
-        { infoLogs, errorLogs },
-      ),
-    );
+    const pluginConfig = {
+      apiUrl,
+      provisionToken: "token-shared-explicit",
+    };
+    const apiA = createStubApi(pluginConfig);
+    const apiB = createStubApi(pluginConfig);
 
-    await flushAsyncWork();
+    mnemoPlugin.register(apiA);
+    mnemoPlugin.register(apiB);
 
-    assert.deepEqual(requests, []);
-    assert.deepEqual(errorLogs, []);
-    assert.equal(
-      infoLogs.includes("[mem9] apiKey not configured; starting auto-provision"),
-      false,
-    );
+    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("search retries auto-provision after an eager startup failure", async () => {
+test("a second setup retry reuses the shared provisioned key before config write-back", async () => {
   const originalFetch = globalThis.fetch;
-  const apiUrl = uniqueApiUrl("retry");
-  const infoLogs: string[] = [];
-  const errorLogs: string[] = [];
-  let provisionAttempts = 0;
-  let searchRequests = 0;
-  let capability: SearchCapability | null = null;
+  const apiUrl = uniqueApiUrl("shared-retry");
+  const infoLogsA: string[] = [];
+  const infoLogsB: string[] = [];
+  let provisionRequests = 0;
 
-  globalThis.fetch = async (input, init) => {
+  globalThis.fetch = async (input) => {
     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`) {
+      provisionRequests += 1;
+      return new Response(JSON.stringify({ id: "space-shared-retry" }), {
         status: 201,
         headers: {
           "Content-Type": "application/json",
@@ -398,60 +340,39 @@ 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");
-
-      return new Response(
-        JSON.stringify({
-          memories: [],
-          total: 0,
-          limit: 20,
-          offset: 0,
-        }),
-        {
-          status: 200,
-          headers: {
-            "Content-Type": "application/json",
-          },
-        },
-      );
-    }
-
     throw new Error(`unexpected fetch: ${url}`);
   };
 
   try {
-    mnemoPlugin.register(
-      createStubApi(
-        { apiUrl },
-        {
-          infoLogs,
-          errorLogs,
-          onRegisterCapability: (_slot, registeredCapability) => {
-            capability = registeredCapability as typeof capability;
-          },
-        },
-      ),
-    );
-
-    await waitFor(() => provisionAttempts === 1);
-
-    assert.equal(provisionAttempts, 1);
-    assert.equal(
-      errorLogs.some((msg) => msg.includes("auto-provision failed: mem9s provision failed (500):")),
-      true,
-    );
-    assert.notEqual(capability, null);
-
-    const result = await capability!.search("hello");
+    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.deepEqual(result, { data: [], total: 0 });
-    assert.equal(provisionAttempts, 2);
-    assert.equal(searchRequests, 1);
+    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

@@ -3,7 +3,7 @@ import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 
-import type { MemoryBackend } from "./backend.js";
+import { PendingProvisionError, isPendingProvisionError, type MemoryBackend } from "./backend.js";
 import {
   DEFAULT_SEARCH_TIMEOUT_MS,
   DEFAULT_TIMEOUT_MS,
@@ -23,7 +23,7 @@ import type {
 
 const DEFAULT_API_URL = "https://api.mem9.ai";
 const TIMEOUT_FIELDS = ["defaultTimeoutMs", "searchTimeoutMs"] as const;
-const SHARED_PROVISION_DIR = path.join(os.tmpdir(), "mem9-openclaw");
+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>>();
@@ -107,10 +107,6 @@ function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
 
-function shouldEagerAutoProvision(cfg: PluginConfig): boolean {
-  return cfg.apiUrl != null || cfg.provisionQueryParams != null;
-}
-
 function sleep(ms: number): Promise<void> {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -118,6 +114,7 @@ function sleep(ms: number): Promise<void> {
 function sharedProvisionKey(
   apiUrl: string,
   provisionQueryParams: Record<string, string>,
+  provisionToken: string,
 ): string {
   const normalizedProvisionQueryParams = Object.fromEntries(
     Object.entries(provisionQueryParams).sort(([left], [right]) => left.localeCompare(right)),
@@ -127,6 +124,7 @@ function sharedProvisionKey(
     .update(
       JSON.stringify({
         apiUrl,
+        provisionToken,
         provisionQueryParams: normalizedProvisionQueryParams,
       }),
     )
@@ -257,11 +255,12 @@ async function waitForSharedProvisionResult(
 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);
+  const key = sharedProvisionKey(apiUrl, provisionQueryParams, provisionToken);
   const existingPromise = sharedProvisionPromises.get(key);
   if (existingPromise) {
     return existingPromise;
@@ -276,7 +275,7 @@ async function resolveSharedProvisionedAPIKey(
 
       if (state?.status === "done") {
         if (now - state.finishedAt <= SHARED_PROVISION_RESULT_TTL_MS) {
-          logger.info("[mem9] reusing shared auto-provisioned apiKey pending config write-back");
+          logger.info("[mem9] reusing shared explicit-provision result pending config write-back");
           return state.apiKey;
         }
         await removeSharedProvisionState(filePath);
@@ -290,7 +289,7 @@ async function resolveSharedProvisionedAPIKey(
           await removeSharedProvisionState(filePath);
           continue;
         }
-        logger.info("[mem9] auto-provision already in progress in another mem9 instance; waiting");
+        logger.info("[mem9] explicit provision already in progress in another mem9 instance; waiting");
         const sharedApiKey = await waitForSharedProvisionResult(filePath, waitTimeoutMs);
         if (sharedApiKey) {
           return sharedApiKey;
@@ -373,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",
@@ -546,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),
+          });
+        }
+      },
+    },
   ];
 }
 
@@ -558,6 +595,10 @@ 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";
@@ -587,42 +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 = resolveSharedProvisionedAPIKey(
           effectiveApiUrl,
           provisionQueryParams,
+          configuredProvisionToken,
           timeoutConfig,
           api.logger,
           () => registerTenant(agentName),
-        ).catch((err) => {
-          registrationPromise = null;
-          throw err;
-        });
+        )
+          .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 && shouldEagerAutoProvision(cfg)) {
-      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 (!configuredApiKey) {
+      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 });
@@ -630,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.
@@ -642,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),
       });
     }
 
@@ -667,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.4",
+  "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;