@mem9/mem9 0.4.5 → 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 `provisionToken` and `provisionQueryParams` are used only during first-time create-new setup before `apiKey` is written back.
+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 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.
+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,13 +176,13 @@ Defined in `openclaw.plugin.json`:
 |---|---|---|
 | `apiUrl` | string | mnemo-server URL |
 | `apiKey` | string | Preferred key. Uses `/v1alpha2/mem9s/...` with `X-API-Key` header |
-| `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 |
+| `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. `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.
+> **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
 
@@ -231,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 | 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 |
+| 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

@@ -10,7 +10,9 @@ import type {
 } from "./types.js";
 
 export class PendingProvisionError extends Error {
-  constructor(message = "mem9 create-new setup is waiting for an explicit mem9_provision_api_key call") {
+  constructor(
+    message = "mem9 create-new setup is waiting for the first post-restart message to finish provisioning",
+  ) {
     super(message);
     this.name = "PendingProvisionError";
   }

package/hooks.ts

@@ -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 });

package/index.test.ts

@@ -12,6 +12,8 @@ interface SearchCapability {
   search: (query: string, opts?: { limit?: number }) => Promise<{ data: unknown[]; total: number }>;
 }
 
+type HookHandler = (...args: unknown[]) => unknown;
+
 interface StubApi {
   pluginConfig?: unknown;
   logger: {
@@ -22,6 +24,7 @@ interface StubApi {
   registerCapability?: (slot: string, capability: unknown) => void;
   on: (...args: unknown[]) => void;
   getTools: (ctx?: { agentId?: string }) => RegisteredTool[];
+  getHook: (name: string) => HookHandler;
 }
 
 function createStubApi(
@@ -34,6 +37,7 @@ 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;
@@ -52,7 +56,11 @@ function createStubApi(
       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 [];
@@ -63,6 +71,13 @@ function createStubApi(
       }
       return Array.isArray(tools) ? tools : [tools];
     },
+    getHook: (name: string) => {
+      const hook = hooks.get(name);
+      if (!hook) {
+        throw new Error(`missing hook: ${name}`);
+      }
+      return hook;
+    },
   };
 }
 
@@ -85,21 +100,6 @@ function uniqueApiUrl(name: string): string {
   return `https://api.mem9.ai/${name}-${Date.now()}-${Math.random().toString(16).slice(2)}`;
 }
 
-function findTool(api: StubApi, name: string): RegisteredTool {
-  const tool = api.getTools({ agentId: "agent-test" }).find((item) => item.name === name);
-  if (!tool) {
-    throw new Error(`missing tool: ${name}`);
-  }
-  return tool;
-}
-
-function parseToolResult(result: unknown): unknown {
-  if (typeof result !== "string") {
-    return result;
-  }
-  return JSON.parse(result);
-}
-
 test("register does not auto-provision on startup during create-new", async () => {
   const originalFetch = globalThis.fetch;
   const apiUrl = uniqueApiUrl("no-startup-provision");
@@ -131,7 +131,9 @@ test("register does not auto-provision on startup during create-new", async () =
     assert.deepEqual(requests, []);
     assert.deepEqual(errorLogs, []);
     assert.equal(
-      infoLogs.includes("[mem9] apiKey not configured; waiting for explicit create-new provision"),
+      infoLogs.includes(
+        "[mem9] apiKey not configured; waiting for the first post-restart message to finish create-new provision",
+      ),
       true,
     );
   } finally {
@@ -176,7 +178,7 @@ test("memory capability stays idle until explicit provision runs", async () => {
   }
 });
 
-test("mem9_provision_api_key provisions once and unlocks memory access", async () => {
+test("first post-restart prompt provisions once and unlocks memory access", async () => {
   const originalFetch = globalThis.fetch;
   const apiUrl = uniqueApiUrl("explicit-provision");
   let capability: SearchCapability | null = null;
@@ -220,8 +222,8 @@ test("mem9_provision_api_key provisions once and unlocks memory access", async (
     throw new Error(`unexpected fetch: ${url}`);
   };
 
-  try {
-    const api = createStubApi(
+    try {
+      const api = createStubApi(
       {
         apiUrl,
         provisionToken: "token-explicit",
@@ -237,14 +239,10 @@ test("mem9_provision_api_key provisions once and unlocks memory access", async (
     );
     mnemoPlugin.register(api);
 
-    const tool = findTool(api, "mem9_provision_api_key");
-    const provisionResult = parseToolResult(await tool.execute("tool-1", {})) as {
-      ok: boolean;
-      data?: { apiKey?: string };
-    };
+    const beforePromptBuild = api.getHook("before_prompt_build");
+    const hookResult = await beforePromptBuild({ prompt: "hi" });
 
-    assert.equal(provisionResult.ok, true);
-    assert.equal(provisionResult.data?.apiKey, "space-explicit");
+    assert.equal(hookResult, undefined);
     assert.equal(provisionRequests, 1);
 
     assert.notEqual(capability, null);
@@ -258,7 +256,7 @@ test("mem9_provision_api_key provisions once and unlocks memory access", async (
   }
 });
 
-test("concurrent explicit provision calls share one server request", async () => {
+test("concurrent first-post-restart prompts share one server request", async () => {
   const originalFetch = globalThis.fetch;
   const apiUrl = uniqueApiUrl("shared-explicit");
   let provisionRequests = 0;
@@ -297,37 +295,34 @@ test("concurrent explicit provision calls share one server request", async () =>
     mnemoPlugin.register(apiA);
     mnemoPlugin.register(apiB);
 
-    const toolA = findTool(apiA, "mem9_provision_api_key");
-    const toolB = findTool(apiB, "mem9_provision_api_key");
+    const hookA = apiA.getHook("before_prompt_build");
+    const hookB = apiB.getHook("before_prompt_build");
 
-    const promiseA = toolA.execute("tool-a", {});
-    const promiseB = toolB.execute("tool-b", {});
+    const promiseA = hookA({ prompt: "hi" });
+    const promiseB = hookB({ prompt: "hi" });
 
     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 } };
+    await promiseA;
+    await promiseB;
 
     assert.equal(provisionRequests, 1);
-    assert.equal(resultA.ok, true);
-    assert.equal(resultB.ok, true);
-    assert.equal(resultA.data?.apiKey, "space-shared-explicit");
-    assert.equal(resultB.data?.apiKey, "space-shared-explicit");
   } finally {
     provisionControl.release();
     globalThis.fetch = originalFetch;
   }
 });
 
-test("a second setup retry reuses the shared provisioned key before config write-back", async () => {
+test("a second setup retry reuses the locally persisted provisioned key before config write-back", async () => {
   const originalFetch = globalThis.fetch;
   const apiUrl = uniqueApiUrl("shared-retry");
   const infoLogsA: string[] = [];
   const infoLogsB: string[] = [];
   let provisionRequests = 0;
+  let searchRequests = 0;
 
-  globalThis.fetch = async (input) => {
+  globalThis.fetch = async (input, init) => {
     const url = String(input);
 
     if (url === `${apiUrl}/v1alpha1/mem9s`) {
@@ -340,6 +335,26 @@ test("a second setup retry reuses the shared provisioned key before config write
       });
     }
 
+    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-retry");
+      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}`);
   };
 
@@ -351,28 +366,25 @@ test("a second setup retry reuses the shared provisioned key before config write
 
     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 });
+    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);
-    const secondTool = findTool(apiB, "mem9_provision_api_key");
-    const secondResult = parseToolResult(await secondTool.execute("tool-b", {})) as {
-      ok: boolean;
-      data?: { apiKey?: string };
-    };
+    assert.notEqual(capabilityB, null);
+    const secondResult = await capabilityB!.search("hello");
 
     assert.equal(provisionRequests, 1);
-    assert.equal(secondResult.ok, true);
-    assert.equal(secondResult.data?.apiKey, "space-shared-retry");
+    assert.deepEqual(secondResult, { data: [], total: 0 });
+    assert.equal(searchRequests, 1);
     assert.equal(
-      infoLogsB.includes("[mem9] reusing shared explicit-provision result pending config write-back"),
+      infoLogsB.includes("[mem9] reusing locally persisted create-new API key for this provisionToken"),
       true,
     );
   } finally {

package/index.ts

@@ -25,7 +25,6 @@ const DEFAULT_API_URL = "https://api.mem9.ai";
 const TIMEOUT_FIELDS = ["defaultTimeoutMs", "searchTimeoutMs"] as const;
 const SHARED_PROVISION_DIR = path.join(os.homedir(), ".openclaw", "mem9", "provision");
 const SHARED_PROVISION_POLL_INTERVAL_MS = 250;
-const SHARED_PROVISION_RESULT_TTL_MS = 2 * 60 * 1000;
 const sharedProvisionPromises = new Map<string, Promise<string>>();
 
 type SharedProvisionState =
@@ -231,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") {
@@ -271,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 explicit-provision result 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] explicit 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;
@@ -374,7 +365,6 @@ interface AnyAgentTool {
 
 function buildTools(
   backend: MemoryBackend,
-  provisionAPIKey: (() => Promise<string>) | null,
 ): AnyAgentTool[] {
   return [
     {
@@ -548,41 +538,6 @@ function buildTools(
         }
       },
     },
-
-    {
-      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),
-          });
-        }
-      },
-    },
   ];
 }
 
@@ -607,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) {
@@ -624,17 +580,18 @@ 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 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",
+            "mem9 create-new auto-provision is only available before apiKey is configured",
           ),
         );
       }
@@ -666,18 +623,39 @@ const mnemoPlugin = {
       }
       return registrationPromise;
     };
-    const resolveAPIKey = (): Promise<string> => {
+    const resolveAPIKey = async (): Promise<string> => {
       if (configuredApiKey) return Promise.resolve(configuredApiKey);
       if (runtimeProvisionedAPIKey) {
-        return Promise.resolve(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;
+        }
       }
-      return Promise.reject(new PendingProvisionError());
+      throw new PendingProvisionError();
     };
 
     api.logger.info("[mem9] Server mode (v1alpha2)");
     if (!configuredApiKey) {
       if (configuredProvisionToken) {
-        api.logger.info("[mem9] apiKey not configured; waiting for explicit create-new provision");
+        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");
       }
@@ -691,7 +669,7 @@ const mnemoPlugin = {
         agentId,
         timeoutConfig,
       );
-      return buildTools(backend, configuredApiKey ? null : () => provisionAPIKey(agentId));
+      return buildTools(backend);
     };
 
     api.registerTool(factory, { names: toolNames });
@@ -750,6 +728,9 @@ const mnemoPlugin = {
     registerHooks(api, hookBackend, api.logger, {
       maxIngestBytes: cfg.maxIngestBytes,
       fallbackAgentId: hookAgentId,
+      provisionForCreateNew: configuredApiKey || !configuredProvisionToken
+        ? undefined
+        : () => provisionAPIKey(hookAgentId),
     });
   },
 };
@@ -760,7 +741,6 @@ const toolNames = [
   "memory_get",
   "memory_update",
   "memory_delete",
-  "mem9_provision_api_key",
 ];
 
 class LazyServerBackend implements MemoryBackend {

package/openclaw.plugin.json

@@ -16,11 +16,11 @@
       },
       "provisionToken": {
         "type": "string",
-        "description": "One-time create-new token used locally to ensure explicit API-key provisioning runs only once before apiKey is persisted"
+        "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 by the explicit first-time create-new provision step",
+        "description": "Optional utm_* params forwarded only by the first create-new provision request triggered after the initial restart",
         "additionalProperties": {
           "type": "string"
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mem9/mem9",
-  "version": "0.4.5",
+  "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",