@mem9/mem9 0.4.4 → 0.4.6

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 an explicit `apiKey` is configured.
 
-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, the first post-restart user message triggers exactly one create-new provision through the normal hook path. The plugin coordinates that call across concurrent OpenClaw plugin registrations on the same machine and reuses the generated key locally for future restarts tied to the same `provisionToken`.
 
 ## 🚀 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 first-message create-new provision runs only once and is reused on this machine until an explicit `apiKey` is configured |
+| `provisionQueryParams` | object | Optional `utm_*` map forwarded only to the initial `POST /v1alpha1/mem9s` request made during create-new 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 provision result across concurrent local registrations and reuses the persisted result for the same `provisionToken`, so repeated reloads or repeated setup retries do not create multiple keys.
 
 ## 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 retriggered create-new provisioning before the first result was reused, or an older plugin still auto-provisions on startup | Upgrade to `@mem9/mem9@0.4.7+`; newer builds provision only from the first post-restart user message and reuse 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,20 @@ import type {
   IngestResult,
 } from "./types.js";
 
+export class PendingProvisionError extends Error {
+  constructor(
+    message = "mem9 create-new setup is waiting for the first post-restart message to finish provisioning",
+  ) {
+    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";
 
 // ---------------------------------------------------------------------------
@@ -169,7 +169,11 @@ export function registerHooks(
   api: HookApi,
   backend: MemoryBackend,
   logger: Logger,
-  options?: { maxIngestBytes?: number; fallbackAgentId?: string },
+  options?: {
+    maxIngestBytes?: number;
+    fallbackAgentId?: string;
+    provisionForCreateNew?: () => Promise<string>;
+  },
 ): void {
   const maxIngestBytes = options?.maxIngestBytes ?? DEFAULT_MAX_INGEST_BYTES;
 
@@ -182,6 +186,9 @@ export function registerHooks(
       try {
         const evt = event as { prompt?: string };
         const prompt = evt?.prompt;
+        if (options?.provisionForCreateNew) {
+          await options.provisionForCreateNew();
+        }
         if (!prompt || prompt.length < MIN_PROMPT_LEN) return;
 
         const result = await backend.search({ q: prompt, limit: MAX_INJECT });
@@ -195,6 +202,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 +255,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 +359,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,28 @@ 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 }>;
+}
+
+type HookHandler = (...args: unknown[]) => unknown;
+
 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[];
+  getHook: (name: string) => HookHandler;
 }
 
 function createStubApi(
@@ -28,6 +37,10 @@ function createStubApi(
 ): StubApi {
   const infoLogs = options?.infoLogs ?? [];
   const errorLogs = options?.errorLogs ?? [];
+  const hooks = new Map<string, HookHandler>();
+  let toolFactory:
+    | ((ctx?: { agentId?: string }) => RegisteredTool[] | RegisteredTool | null | undefined)
+    | null = null;
 
   return {
     pluginConfig,
@@ -39,9 +52,32 @@ function createStubApi(
         errorLogs.push(args.map(String).join(" "));
       },
     },
-    registerTool: () => {},
+    registerTool: (factory: unknown) => {
+      toolFactory = factory as typeof toolFactory;
+    },
     registerCapability: options?.onRegisterCapability,
-    on: () => {},
+    on: (hookName: unknown, handler: unknown) => {
+      if (typeof hookName === "string" && typeof handler === "function") {
+        hooks.set(hookName, handler as HookHandler);
+      }
+    },
+    getTools: (ctx = {}) => {
+      if (!toolFactory) {
+        return [];
+      }
+      const tools = toolFactory(ctx);
+      if (!tools) {
+        return [];
+      }
+      return Array.isArray(tools) ? tools : [tools];
+    },
+    getHook: (name: string) => {
+      const hook = hooks.get(name);
+      if (!hook) {
+        throw new Error(`missing hook: ${name}`);
+      }
+      return hook;
+    },
   };
 }
 
@@ -64,22 +100,16 @@ 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 () => {
+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,14 @@ 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 the first post-restart message to finish create-new provision",
+      ),
       true,
     );
   } finally {
@@ -116,130 +141,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("first post-restart prompt 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 +201,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({
@@ -271,126 +222,112 @@ test("register reuses a shared auto-provisioned key before config write-back", a
     throw new Error(`unexpected fetch: ${url}`);
   };
 
-  try {
-    mnemoPlugin.register(
-      createStubApi(
-        { apiUrl },
-        {
-          infoLogs: infoLogsA,
-          errorLogs,
-          onRegisterCapability: (_slot, registeredCapability) => {
-            capabilityA = registeredCapability as typeof capabilityA;
-          },
+    try {
+      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 beforePromptBuild = api.getHook("before_prompt_build");
+    const hookResult = await beforePromptBuild({ prompt: "hi" });
 
-    assert.deepEqual(errorLogs, []);
+    assert.equal(hookResult, undefined);
     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 first-post-restart prompts 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 hookA = apiA.getHook("before_prompt_build");
+    const hookB = apiB.getHook("before_prompt_build");
+
+    const promiseA = hookA({ prompt: "hi" });
+    const promiseB = hookB({ prompt: "hi" });
+
+    await waitFor(() => provisionRequests === 1);
+    provisionControl.release();
+
+    await promiseA;
+    await promiseB;
+
+    assert.equal(provisionRequests, 1);
   } finally {
+    provisionControl.release();
     globalThis.fetch = originalFetch;
   }
 });
 
-test("search retries auto-provision after an eager startup failure", async () => {
+test("a second setup retry reuses the locally persisted provisioned key before config write-back", async () => {
   const originalFetch = globalThis.fetch;
-  const apiUrl = uniqueApiUrl("retry");
-  const infoLogs: string[] = [];
-  const errorLogs: string[] = [];
-  let provisionAttempts = 0;
+  const apiUrl = uniqueApiUrl("shared-retry");
+  const infoLogsA: string[] = [];
+  const infoLogsB: string[] = [];
+  let provisionRequests = 0;
   let searchRequests = 0;
-  let capability: SearchCapability | 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`) {
+      provisionRequests += 1;
+      return new Response(JSON.stringify({ id: "space-shared-retry" }), {
         status: 201,
         headers: {
           "Content-Type": "application/json",
@@ -401,8 +338,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-shared-retry");
       return new Response(
         JSON.stringify({
           memories: [],
@@ -423,35 +359,32 @@ test("search retries auto-provision after an eager startup failure", async () =>
   };
 
   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 firstHook = apiA.getHook("before_prompt_build");
+    await firstHook({ prompt: "hi" });
+
+    let capabilityB: SearchCapability | null = null;
+    const apiB = createStubApi(pluginConfig, {
+      infoLogs: infoLogsB,
+      onRegisterCapability: (_slot, registeredCapability) => {
+        capabilityB = registeredCapability as SearchCapability;
+      },
+    });
+    mnemoPlugin.register(apiB);
+    assert.notEqual(capabilityB, null);
+    const secondResult = await capabilityB!.search("hello");
 
-    assert.deepEqual(result, { data: [], total: 0 });
-    assert.equal(provisionAttempts, 2);
+    assert.equal(provisionRequests, 1);
+    assert.deepEqual(secondResult, { data: [], total: 0 });
     assert.equal(searchRequests, 1);
     assert.equal(
-      infoLogs.some((msg) => msg.includes("*** Auto-provisioned apiKey=space-2 ***")),
+      infoLogsB.includes("[mem9] reusing locally persisted create-new API key for this provisionToken"),
       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,9 +23,8 @@ 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>>();
 
 type SharedProvisionState =
@@ -107,10 +106,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 +113,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 +123,7 @@ function sharedProvisionKey(
     .update(
       JSON.stringify({
         apiUrl,
+        provisionToken,
         provisionQueryParams: normalizedProvisionQueryParams,
       }),
     )
@@ -233,11 +230,7 @@ async function waitForSharedProvisionResult(
     }
 
     if (state.status === "done") {
-      if (now - state.finishedAt <= SHARED_PROVISION_RESULT_TTL_MS) {
-        return state.apiKey;
-      }
-      await removeSharedProvisionState(filePath);
-      return null;
+      return state.apiKey;
     }
 
     if (state.status === "error") {
@@ -257,11 +250,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;
@@ -272,25 +266,21 @@ async function resolveSharedProvisionedAPIKey(
   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 auto-provisioned apiKey pending config write-back");
-          return state.apiKey;
-        }
-        await removeSharedProvisionState(filePath);
-        continue;
+        logger.info("[mem9] reusing locally persisted create-new API key for this provisionToken");
+        return state.apiKey;
       }
 
       if (state?.status === "error") {
         await removeSharedProvisionState(filePath);
       } else if (state?.status === "pending") {
+        const now = Date.now();
         if (now - state.startedAt > waitTimeoutMs) {
           await removeSharedProvisionState(filePath);
           continue;
         }
-        logger.info("[mem9] auto-provision already in progress in another mem9 instance; waiting");
+        logger.info("[mem9] create-new provision already in progress in another mem9 instance; waiting");
         const sharedApiKey = await waitForSharedProvisionResult(filePath, waitTimeoutMs);
         if (sharedApiKey) {
           return sharedApiKey;
@@ -373,7 +363,9 @@ interface AnyAgentTool {
   execute: (_id: string, params: unknown) => Promise<unknown>;
 }
 
-function buildTools(backend: MemoryBackend): AnyAgentTool[] {
+function buildTools(
+  backend: MemoryBackend,
+): AnyAgentTool[] {
   return [
     {
       name: "memory_store",
@@ -558,6 +550,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";
@@ -566,6 +562,7 @@ const mnemoPlugin = {
     }
 
     const configuredApiKey = cfg.apiKey ?? cfg.tenantID;
+    const provisionWaitTimeoutMs = Math.max(timeoutConfig.defaultTimeoutMs + 5_000, 30_000);
     if (cfg.apiKey && cfg.tenantID) {
       api.logger.info("[mem9] both apiKey and tenantID set; using apiKey");
     } else if (cfg.tenantID) {
@@ -583,42 +580,92 @@ const mnemoPlugin = {
       );
       const result = await backend.register();
       api.logger.info(
-        `[mem9] *** Auto-provisioned apiKey=${result.id} *** Save this to your config as apiKey`
+        `[mem9] *** Auto-provisioned apiKey=${result.id} *** Save this for recovery or reconnect as apiKey`
       );
       return result.id;
     };
+    let runtimeProvisionedAPIKey: string | null = null;
+    let loggedPersistedProvisionedAPIKeyReuse = false;
     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 create-new auto-provision is only available before apiKey is configured",
+          ),
+        );
+      }
+      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 = async (): Promise<string> => {
+      if (configuredApiKey) return Promise.resolve(configuredApiKey);
+      if (runtimeProvisionedAPIKey) {
+        return runtimeProvisionedAPIKey;
+      }
+      if (configuredProvisionToken) {
+        const sharedKey = sharedProvisionKey(
+          effectiveApiUrl,
+          provisionQueryParams,
+          configuredProvisionToken,
+        );
+        const sharedApiKey = await waitForSharedProvisionResult(
+          sharedProvisionStatePath(sharedKey),
+          provisionWaitTimeoutMs,
+        );
+        if (sharedApiKey) {
+          runtimeProvisionedAPIKey = sharedApiKey;
+          if (!loggedPersistedProvisionedAPIKeyReuse) {
+            api.logger.info("[mem9] reusing locally persisted create-new API key for this provisionToken");
+            loggedPersistedProvisionedAPIKeyReuse = true;
+          }
+          return sharedApiKey;
+        }
+      }
+      throw 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 the first post-restart message to finish 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,
       );
@@ -630,11 +677,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 +703,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),
       });
     }
 
@@ -657,6 +728,9 @@ const mnemoPlugin = {
     registerHooks(api, hookBackend, api.logger, {
       maxIngestBytes: cfg.maxIngestBytes,
       fallbackAgentId: hookAgentId,
+      provisionForCreateNew: configuredApiKey || !configuredProvisionToken
+        ? undefined
+        : () => provisionAPIKey(hookAgentId),
     });
   },
 };

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 first-message API-key provisioning runs only once and can be reused on this machine before apiKey is configured explicitly"
+      },
       "provisionQueryParams": {
         "type": "object",
-        "description": "Optional utm_* params forwarded only during first-time auto-provisioning",
+        "description": "Optional utm_* params forwarded only by the first create-new provision request triggered after the initial restart",
         "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.6",
   "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;