@mem9/mem9 0.4.3 → 0.4.4

package/README.md

@@ -2,6 +2,8 @@
 
 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.
 
+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.
+
 ## 🚀 Quick Start (Server Mode)
 
 **You need a running `mnemo-server` instance.**
@@ -179,7 +181,7 @@ Defined in `openclaw.plugin.json`:
 | `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. `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.
 
 ## Timeout Behavior
 
@@ -228,5 +230,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 |
 | 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/index.test.ts

@@ -14,6 +14,10 @@ interface StubApi {
   on: () => void;
 }
 
+interface SearchCapability {
+  search: (query: string, opts?: { limit?: number }) => Promise<{ data: unknown[]; total: number }>;
+}
+
 function createStubApi(
   pluginConfig: unknown,
   options?: {
@@ -45,8 +49,24 @@ async function flushAsyncWork(): Promise<void> {
   await new Promise((resolve) => setTimeout(resolve, 0));
 }
 
+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)}`;
+}
+
 test("register eagerly auto-provisions when apiKey is absent", async () => {
   const originalFetch = globalThis.fetch;
+  const apiUrl = uniqueApiUrl("eager");
   const requests: string[] = [];
   const infoLogs: string[] = [];
   const errorLogs: string[] = [];
@@ -66,7 +86,7 @@ test("register eagerly auto-provisions when apiKey is absent", async () => {
     mnemoPlugin.register(
       createStubApi(
         {
-          apiUrl: "https://api.mem9.ai",
+          apiUrl,
           provisionQueryParams: {
             utm_source: "bosn",
           },
@@ -75,13 +95,13 @@ test("register eagerly auto-provisions when apiKey is absent", async () => {
       ),
     );
 
-    await flushAsyncWork();
+    await waitFor(() => requests.length === 1);
 
     assert.deepEqual(errorLogs, []);
     assert.equal(requests.length, 1);
     assert.equal(
       requests[0],
-      "https://api.mem9.ai/v1alpha1/mem9s?utm_source=bosn",
+      `${apiUrl}/v1alpha1/mem9s?utm_source=bosn`,
     );
     assert.equal(
       infoLogs.includes("[mem9] apiKey not configured; starting auto-provision"),
@@ -96,15 +116,264 @@ test("register eagerly auto-provisions when apiKey is absent", async () => {
   }
 });
 
+test("register shares an in-flight auto-provision across concurrent plugin registrations", 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",
+          },
+        },
+      );
+    }
+
+    throw new Error(`unexpected fetch: ${url}`);
+  };
+
+  try {
+    mnemoPlugin.register(
+      createStubApi(
+        { apiUrl },
+        {
+          infoLogs: infoLogsA,
+          errorLogs,
+          onRegisterCapability: (_slot, registeredCapability) => {
+            capabilityA = registeredCapability as typeof capabilityA;
+          },
+        },
+      ),
+    );
+    mnemoPlugin.register(
+      createStubApi(
+        { apiUrl },
+        {
+          infoLogs: infoLogsB,
+          errorLogs,
+          onRegisterCapability: (_slot, registeredCapability) => {
+            capabilityB = registeredCapability as typeof capabilityB;
+          },
+        },
+      ),
+    );
+
+    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;
+
+    await readyCapabilityA.search("hello");
+    await readyCapabilityB.search("hello");
+
+    assert.equal(provisionRequests, 1);
+    assert.equal(searchRequests, 2);
+  } finally {
+    provisionControl.release();
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("register reuses a shared auto-provisioned key before config write-back", 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;
+  let provisionRequests = 0;
+  let searchRequests = 0;
+
+  globalThis.fetch = async (input, init) => {
+    const url = String(input);
+
+    if (url === `${apiUrl}/v1alpha1/mem9s`) {
+      provisionRequests += 1;
+      return new Response(JSON.stringify({ id: "space-shared-done" }), {
+        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-done");
+
+      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: infoLogsA,
+          errorLogs,
+          onRegisterCapability: (_slot, registeredCapability) => {
+            capabilityA = registeredCapability as typeof capabilityA;
+          },
+        },
+      ),
+    );
+
+    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;
+          },
+        },
+      ),
+    );
+
+    await waitFor(() =>
+      infoLogsB.includes("[mem9] reusing shared auto-provisioned apiKey pending config write-back"),
+    );
+
+    assert.deepEqual(errorLogs, []);
+    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.equal(searchRequests, 2);
+    assert.equal(
+      infoLogsB.includes("[mem9] reusing shared auto-provisioned apiKey pending config write-back"),
+      true,
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
+test("register does not auto-provision on empty config", async () => {
+  const originalFetch = globalThis.fetch;
+  const requests: string[] = [];
+  const infoLogs: string[] = [];
+  const errorLogs: string[] = [];
+
+  globalThis.fetch = async (input) => {
+    requests.push(String(input));
+
+    return new Response(JSON.stringify({ id: "space-unexpected" }), {
+      status: 201,
+      headers: {
+        "Content-Type": "application/json",
+      },
+    });
+  };
+
+  try {
+    mnemoPlugin.register(
+      createStubApi(
+        {},
+        { infoLogs, errorLogs },
+      ),
+    );
+
+    await flushAsyncWork();
+
+    assert.deepEqual(requests, []);
+    assert.deepEqual(errorLogs, []);
+    assert.equal(
+      infoLogs.includes("[mem9] apiKey not configured; starting auto-provision"),
+      false,
+    );
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});
+
 test("search retries auto-provision after an eager startup failure", async () => {
   const originalFetch = globalThis.fetch;
+  const apiUrl = uniqueApiUrl("retry");
   const infoLogs: string[] = [];
   const errorLogs: string[] = [];
   let provisionAttempts = 0;
   let searchRequests = 0;
-  let capability: {
-    search: (query: string, opts?: { limit?: number }) => Promise<{ data: unknown[]; total: number }>;
-  } | null = null;
+  let capability: SearchCapability | null = null;
 
   globalThis.fetch = async (input, init) => {
     const url = String(input);
@@ -156,9 +425,7 @@ test("search retries auto-provision after an eager startup failure", async () =>
   try {
     mnemoPlugin.register(
       createStubApi(
-        {
-          apiUrl: "https://api.mem9.ai",
-        },
+        { apiUrl },
         {
           infoLogs,
           errorLogs,
@@ -169,7 +436,7 @@ test("search retries auto-provision after an eager startup failure", async () =>
       ),
     );
 
-    await flushAsyncWork();
+    await waitFor(() => provisionAttempts === 1);
 
     assert.equal(provisionAttempts, 1);
     assert.equal(

package/index.ts

@@ -1,3 +1,8 @@
+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 type { MemoryBackend } from "./backend.js";
 import {
   DEFAULT_SEARCH_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.tmpdir(), "mem9-openclaw");
+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,230 @@ 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));
+}
+
+function sharedProvisionKey(
+  apiUrl: string,
+  provisionQueryParams: Record<string, string>,
+): string {
+  const normalizedProvisionQueryParams = Object.fromEntries(
+    Object.entries(provisionQueryParams).sort(([left], [right]) => left.localeCompare(right)),
+  );
+
+  return createHash("sha256")
+    .update(
+      JSON.stringify({
+        apiUrl,
+        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>,
+  timeouts: Required<BackendTimeouts>,
+  logger: OpenClawPluginApi["logger"],
+  registerTenant: () => Promise<string>,
+): Promise<string> {
+  const key = sharedProvisionKey(apiUrl, provisionQueryParams);
+  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 auto-provisioned apiKey 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] auto-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>;
@@ -306,6 +558,7 @@ const mnemoPlugin = {
   register(api: OpenClawPluginApi) {
     const cfg = (api.pluginConfig ?? {}) as PluginConfig;
     const effectiveApiUrl = cfg.apiUrl ?? DEFAULT_API_URL;
+    const provisionQueryParams = cfg.provisionQueryParams ?? {};
     const timeoutConfig = resolveTimeouts(cfg, api.logger);
     const hookAgentId = cfg.agentName ?? "agent";
     if (!cfg.apiUrl) {
@@ -325,7 +578,7 @@ const mnemoPlugin = {
         agentName,
         {
           timeouts: timeoutConfig,
-          provisionQueryParams: cfg.provisionQueryParams ?? {},
+          provisionQueryParams,
         },
       );
       const result = await backend.register();
@@ -338,7 +591,13 @@ const mnemoPlugin = {
     const resolveAPIKey = (agentName: string): Promise<string> => {
       if (configuredApiKey) return Promise.resolve(configuredApiKey);
       if (!registrationPromise) {
-        registrationPromise = registerTenant(agentName).catch((err) => {
+        registrationPromise = resolveSharedProvisionedAPIKey(
+          effectiveApiUrl,
+          provisionQueryParams,
+          timeoutConfig,
+          api.logger,
+          () => registerTenant(agentName),
+        ).catch((err) => {
           registrationPromise = null;
           throw err;
         });
@@ -348,7 +607,7 @@ const mnemoPlugin = {
 
     api.logger.info("[mem9] Server mode (v1alpha2)");
 
-    if (!configuredApiKey) {
+    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)}`);

package/package.json

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