@mem9/mem9 0.4.11 → 0.4.13

package/README.md

@@ -2,7 +2,7 @@
 
 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, 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`.
+When `apiKey` is absent during create-new onboarding, the plugin does not auto-provision on startup. Instead, the first post-restart OpenClaw agent turn that runs `before_prompt_build` triggers exactly one create-new provision. Setup/control chats such as TUI local embedded sessions may not run that plugin hook themselves, so onboarding can trigger one minimal OpenClaw agent turn to complete provisioning. 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)
 
@@ -182,7 +182,7 @@ 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 first-message create-new provision runs only once and is reused on this machine until an explicit `apiKey` is configured |
+| `provisionToken` | string | Optional one-time create-new token used locally to ensure create-new provisioning runs only once from an OpenClaw agent turn 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` |
@@ -247,7 +247,7 @@ 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 |
 | `config reload skipped (invalid config): plugins.entries.mem9: Unrecognized key: "apiKey"` | Setup wrote `plugins.entries.mem9.apiKey` instead of `plugins.entries.mem9.config.apiKey` | Remove the invalid top-level key and keep the secret only under `config.apiKey` |
-| 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 |
+| 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 an OpenClaw agent turn that runs `before_prompt_build` and reuse one local result across duplicate setup retries |
 | Search requests time out | Hybrid/vector search exceeds plugin timeout | Increase `searchTimeoutMs` in plugin config |
 | Conversations are not uploaded on OpenClaw 4.23+ | `agent_end` does not include conversation messages without explicit hook permission | Set `plugins.entries.mem9.hooks.allowConversationAccess` to `true` and restart OpenClaw |
 | Plugin not loading | Not in memory slot | Set `"slots": {"memory": "mem9"}` in openclaw.json |

package/dist/backend.js

@@ -1,5 +1,5 @@
 export class PendingProvisionError extends Error {
-    constructor(message = "mem9 create-new setup is waiting for the first post-restart message to finish provisioning") {
+    constructor(message = "mem9 create-new setup is waiting for an OpenClaw agent turn that runs before_prompt_build to finish provisioning") {
         super(message);
         this.name = "PendingProvisionError";
     }

package/dist/hooks.js

@@ -11,6 +11,7 @@
  * Reference: OpenClaw's built-in memory-lancedb extension uses the same pattern.
  */
 import { isPendingProvisionError } from "./backend.js";
+import { formatRuntimeQuotaNotice } from "./quota-error.js";
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
@@ -21,6 +22,7 @@ const MAX_CONTENT_LEN = 500; // truncate individual memory content in prompt
 // Ingest defaults — configurable via maxIngestBytes in plugin config
 const DEFAULT_MAX_INGEST_BYTES = 200_000; // ~200KB safe for most LLM context windows
 const MAX_INGEST_MESSAGES = 20; // absolute cap even if small messages
+const BACKGROUND_QUOTA_PAUSED_LOG = "[mem9] memory saving paused by runtime quota";
 function previewText(text, maxLen = 160) {
     const normalized = text.replace(/\s+/g, " ").trim();
     if (normalized.length <= maxLen) {
@@ -166,6 +168,13 @@ export function registerHooks(api, backend, logger, options) {
             if (isPendingProvisionError(err)) {
                 return;
             }
+            const quotaNotice = formatRuntimeQuotaNotice(err, "recall paused");
+            if (quotaNotice) {
+                logger.info(quotaNotice);
+                return {
+                    prependContext: quotaNotice,
+                };
+            }
             // Graceful degradation — never block the LLM call
             logger.error(`[mem9] before_prompt_build failed: ${String(err)}`);
         }
@@ -215,6 +224,11 @@ export function registerHooks(api, backend, logger, options) {
             if (isPendingProvisionError(err)) {
                 return;
             }
+            const quotaNotice = formatRuntimeQuotaNotice(err, "before_reset save paused");
+            if (quotaNotice) {
+                logger.info(BACKGROUND_QUOTA_PAUSED_LOG);
+                return;
+            }
             // Best-effort — never block /reset
             logger.error(`[mem9] before_reset save failed: ${String(err)}`);
         }
@@ -310,6 +324,11 @@ export function registerHooks(api, backend, logger, options) {
             if (isPendingProvisionError(err)) {
                 return;
             }
+            const quotaNotice = formatRuntimeQuotaNotice(err, "agent_end ingest paused");
+            if (quotaNotice) {
+                logger.info(BACKGROUND_QUOTA_PAUSED_LOG);
+                return;
+            }
             // Best-effort — never fail the agent end phase
         }
     });

package/dist/index.js

@@ -5,6 +5,7 @@ import path from "node:path";
 import { PendingProvisionError, isPendingProvisionError } from "./backend.js";
 import { DEFAULT_SEARCH_TIMEOUT_MS, DEFAULT_TIMEOUT_MS, ServerBackend, } from "./server-backend.js";
 import { registerHooks } from "./hooks.js";
+import { toolErrorPayload } from "./quota-error.js";
 const DEFAULT_API_URL = "https://api.mem9.ai";
 const TIMEOUT_FIELDS = ["defaultTimeoutMs", "searchTimeoutMs"];
 const SHARED_PROVISION_DIR = path.join(os.homedir(), ".openclaw", "mem9", "provision");
@@ -47,6 +48,9 @@ function jsonResult(data) {
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
+function jsonToolError(err) {
+    return jsonResult(toolErrorPayload(err));
+}
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -248,10 +252,7 @@ function buildTools(backend) {
                     return jsonResult({ ok: true, data: result });
                 }
                 catch (err) {
-                    return jsonResult({
-                        ok: false,
-                        error: err instanceof Error ? err.message : String(err),
-                    });
+                    return jsonToolError(err);
                 }
             },
         },
@@ -287,10 +288,7 @@ function buildTools(backend) {
                     return jsonResult({ ok: true, ...result });
                 }
                 catch (err) {
-                    return jsonResult({
-                        ok: false,
-                        error: err instanceof Error ? err.message : String(err),
-                    });
+                    return jsonToolError(err);
                 }
             },
         },
@@ -314,10 +312,7 @@ function buildTools(backend) {
                     return jsonResult({ ok: true, data: result });
                 }
                 catch (err) {
-                    return jsonResult({
-                        ok: false,
-                        error: err instanceof Error ? err.message : String(err),
-                    });
+                    return jsonToolError(err);
                 }
             },
         },
@@ -349,10 +344,7 @@ function buildTools(backend) {
                     return jsonResult({ ok: true, data: result });
                 }
                 catch (err) {
-                    return jsonResult({
-                        ok: false,
-                        error: err instanceof Error ? err.message : String(err),
-                    });
+                    return jsonToolError(err);
                 }
             },
         },
@@ -376,10 +368,7 @@ function buildTools(backend) {
                     return jsonResult({ ok: true });
                 }
                 catch (err) {
-                    return jsonResult({
-                        ok: false,
-                        error: err instanceof Error ? err.message : String(err),
-                    });
+                    return jsonToolError(err);
                 }
             },
         },
@@ -471,7 +460,7 @@ const mnemoPlugin = {
         api.logger.info("[mem9] Server mode (v1alpha2)");
         if (!configuredApiKey) {
             if (configuredProvisionToken) {
-                api.logger.info("[mem9] apiKey not configured; waiting for the first post-restart message to finish create-new provision");
+                api.logger.info("[mem9] apiKey not configured; waiting for an OpenClaw agent turn that runs before_prompt_build to finish create-new provision");
             }
             else {
                 api.logger.info("[mem9] apiKey not configured; mem9 will stay idle until apiKey is configured");

package/dist/quota-error.js

@@ -0,0 +1,215 @@
+export class Mem9HttpError extends Error {
+    status;
+    body;
+    data;
+    constructor(message, status, body, data) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.data = data;
+        this.name = "Mem9HttpError";
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizeString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function normalizePositiveInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}
+export function parseJsonOrUndefined(text) {
+    if (!text.trim()) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function messageFromErrorBody(status, body, data) {
+    if (isRecord(data)) {
+        const message = normalizeString(data.message);
+        if (message) {
+            return message;
+        }
+        const error = normalizeString(data.error);
+        if (error) {
+            return error;
+        }
+    }
+    const text = body.trim();
+    return text || `HTTP ${status}`;
+}
+function normalizeRecommendedAction(runtimeQuota) {
+    const nested = isRecord(runtimeQuota.recommendedAction) ? runtimeQuota.recommendedAction : {};
+    const providerActionCode = normalizeString(nested.providerActionCode);
+    const severity = normalizeString(nested.severity);
+    const type = normalizeString(nested.type);
+    const url = normalizeString(nested.url);
+    if (!providerActionCode && !severity && !type && !url) {
+        return null;
+    }
+    return {
+        ...(providerActionCode ? { providerActionCode } : {}),
+        ...(severity ? { severity } : {}),
+        ...(type ? { type } : {}),
+        ...(url ? { url } : {}),
+    };
+}
+function quotaGateReason(runtimeQuota) {
+    const quotaGateResult = isRecord(runtimeQuota.quotaGateResult) ? runtimeQuota.quotaGateResult : {};
+    return normalizeString(quotaGateResult.reason);
+}
+function retryAfterSeconds(runtimeQuota) {
+    const direct = normalizePositiveInteger(runtimeQuota.retryAfterSeconds);
+    if (direct !== null) {
+        return direct;
+    }
+    const quotaGateResult = isRecord(runtimeQuota.quotaGateResult) ? runtimeQuota.quotaGateResult : {};
+    const postQuotaRateLimit = isRecord(quotaGateResult.postQuotaRateLimit) ? quotaGateResult.postQuotaRateLimit : {};
+    return normalizePositiveInteger(postQuotaRateLimit.retryAfterSeconds);
+}
+function isPostQuotaRateLimited(denied) {
+    return denied.status === 429 ||
+        denied.quotaGateReason === "postQuotaRateLimitExceeded";
+}
+function quotaReason(denied) {
+    if (isPostQuotaRateLimited(denied)) {
+        return "this API key has reached the temporary request limit for this memory feature";
+    }
+    const providerActionCode = normalizeString(denied.recommendedAction?.providerActionCode);
+    if (providerActionCode === "claimApiKey") {
+        return "the included usage quota for this API key has been used up";
+    }
+    if (providerActionCode === "increaseSpendingLimit") {
+        return "the configured spending limit would be exceeded";
+    }
+    if (providerActionCode === "enableOnDemand") {
+        return "the included usage quota has been used up and on-demand usage is not enabled";
+    }
+    if (providerActionCode === "upgradePlan") {
+        return "the included usage quota for this mem9 account has been used up";
+    }
+    if (providerActionCode === "resolveAccountState") {
+        return "the current account or billing state blocks runtime memory access";
+    }
+    return "the runtime quota check blocked this request";
+}
+function quotaNoticeSubject(denied, operation) {
+    const meter = normalizeString(denied.meter);
+    if (meter === "memory_write_requests") {
+        return {
+            headline: "Mem9 memory saving is temporarily unavailable",
+            userState: "mem9 cannot save new memories right now",
+        };
+    }
+    if (meter === "memory_recall_requests") {
+        return {
+            headline: "Mem9 recall is temporarily unavailable",
+            userState: "mem9 cannot recall memories right now",
+        };
+    }
+    const operationText = normalizeString(operation).toLowerCase();
+    if (/\b(ingest|save|store|write)\b/.test(operationText)) {
+        return {
+            headline: "Mem9 memory saving is temporarily unavailable",
+            userState: "mem9 cannot save new memories right now",
+        };
+    }
+    if (/\b(recall|search)\b/.test(operationText)) {
+        return {
+            headline: "Mem9 recall is temporarily unavailable",
+            userState: "mem9 cannot recall memories right now",
+        };
+    }
+    return {
+        headline: "Mem9 memory is temporarily unavailable",
+        userState: "mem9 cannot complete the memory request right now",
+    };
+}
+function actionUrlForDenied(denied) {
+    return normalizeString(denied.recommendedAction?.url);
+}
+function actionInstruction(denied) {
+    const action = denied.recommendedAction;
+    const providerActionCode = normalizeString(action?.providerActionCode);
+    const actionUrl = actionUrlForDenied(denied);
+    if (!actionUrl) {
+        if (isPostQuotaRateLimited(denied)) {
+            return "Tell them that the quota/rate-limit check blocked this request and to retry later or open the mem9 console to review account and billing settings.";
+        }
+        return "Ask them to open the mem9 console to resolve the account or billing state.";
+    }
+    switch (providerActionCode) {
+        case "claimApiKey":
+            return `Ask them to open this link to sign in or create a mem9 account and claim this API key: ${actionUrl}. After claiming the key, they can upgrade their plan or set up billing to get more usage. Include the link exactly as written.`;
+        case "upgradePlan":
+            return `Ask them to open this link to upgrade their mem9 plan and get more included usage: ${actionUrl}. Include the link exactly as written.`;
+        case "increaseSpendingLimit":
+            return `Ask them to open this link to increase the mem9 spending limit or adjust billing settings: ${actionUrl}. Include the link exactly as written.`;
+        case "enableOnDemand":
+            return `Ask them to open this link to enable billing or on-demand usage for mem9: ${actionUrl}. Include the link exactly as written.`;
+        case "resolveAccountState":
+            return `Ask them to open this mem9 link to resolve the account or billing state: ${actionUrl}. Include the link exactly as written.`;
+        default:
+            return `Ask them to open this mem9 link to resolve the account or billing state: ${actionUrl}. Include the link exactly as written.`;
+    }
+}
+export function parseRuntimeQuotaDenied(value) {
+    const payload = value instanceof Mem9HttpError ? value.data : value;
+    if (!isRecord(payload)) {
+        return null;
+    }
+    const details = isRecord(payload.details) ? payload.details : {};
+    if (normalizeString(details.errorCategory) !== "runtime_quota_denied") {
+        return null;
+    }
+    const runtimeQuota = isRecord(details.runtimeQuota) ? details.runtimeQuota : {};
+    const recommendedAction = normalizeRecommendedAction(runtimeQuota);
+    const retryAfter = retryAfterSeconds(runtimeQuota);
+    const reason = quotaGateReason(runtimeQuota);
+    return {
+        status: value instanceof Mem9HttpError ? value.status : null,
+        code: "runtime_quota_denied",
+        message: normalizeString(payload.error) || "Runtime usage quota denied.",
+        ...(normalizeString(runtimeQuota.meter) ? { meter: normalizeString(runtimeQuota.meter) } : {}),
+        ...(reason ? { quotaGateReason: reason } : {}),
+        ...(retryAfter !== null ? { retryAfterSeconds: retryAfter } : {}),
+        ...(recommendedAction ? { recommendedAction } : {}),
+    };
+}
+export function formatRuntimeQuotaNotice(value, operation) {
+    const denied = parseRuntimeQuotaDenied(value);
+    if (!denied) {
+        return "";
+    }
+    const subject = quotaNoticeSubject(denied, operation);
+    return `${subject.headline} because ${quotaReason(denied)}. In your reply, briefly tell the user that ${subject.userState}. ${actionInstruction(denied)}`;
+}
+export function toolErrorPayload(error) {
+    const denied = parseRuntimeQuotaDenied(error);
+    if (denied) {
+        const actionUrl = actionUrlForDenied(denied);
+        return {
+            ok: false,
+            error: denied.message,
+            status_code: denied.status,
+            code: denied.code,
+            quota: {
+                code: denied.code,
+                message: denied.message,
+                ...(denied.retryAfterSeconds !== undefined ? { retryAfterSeconds: denied.retryAfterSeconds } : {}),
+                ...(denied.recommendedAction ? { recommendedAction: denied.recommendedAction } : {}),
+            },
+            ...(actionUrl ? { action_url: actionUrl } : {}),
+        };
+    }
+    return {
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+    };
+}

package/dist/server-backend.js

@@ -1,3 +1,4 @@
+import { Mem9HttpError, messageFromErrorBody, parseJsonOrUndefined, } from "./quota-error.js";
 export const DEFAULT_TIMEOUT_MS = 8_000;
 export const DEFAULT_SEARCH_TIMEOUT_MS = 15_000;
 export class ServerBackend {
@@ -76,16 +77,22 @@ export class ServerBackend {
         try {
             return await this.request("GET", this.memoryPath(`/memories/${id}`));
         }
-        catch {
-            return null;
+        catch (err) {
+            if (err instanceof Mem9HttpError && err.status === 404) {
+                return null;
+            }
+            throw err;
         }
     }
     async update(id, input) {
         try {
             return await this.request("PUT", this.memoryPath(`/memories/${id}`), input);
         }
-        catch {
-            return null;
+        catch (err) {
+            if (err instanceof Mem9HttpError && err.status === 404) {
+                return null;
+            }
+            throw err;
         }
     }
     async remove(id) {
@@ -93,8 +100,11 @@ export class ServerBackend {
             await this.request("DELETE", this.memoryPath(`/memories/${id}`));
             return true;
         }
-        catch {
-            return false;
+        catch (err) {
+            if (err instanceof Mem9HttpError && err.status === 404) {
+                return false;
+            }
+            throw err;
         }
     }
     async ingest(input) {
@@ -119,10 +129,11 @@ export class ServerBackend {
         if (resp.status === 204) {
             return undefined;
         }
-        const data = await resp.json();
+        const text = await resp.text();
         if (!resp.ok) {
-            throw new Error(data.error || `HTTP ${resp.status}`);
+            const data = parseJsonOrUndefined(text);
+            throw new Mem9HttpError(messageFromErrorBody(resp.status, text, data), resp.status, text, data);
         }
-        return data;
+        return JSON.parse(text);
     }
 }

package/openclaw.plugin.json

@@ -16,11 +16,11 @@
       },
       "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"
+        "description": "One-time create-new token used locally to ensure API-key provisioning runs only once from an OpenClaw agent turn and can be reused on this machine before apiKey is configured explicitly"
       },
       "provisionQueryParams": {
         "type": "object",
-        "description": "Optional utm_* params forwarded only by the first create-new provision request triggered after the initial restart",
+        "description": "Optional utm_* params forwarded only by the first create-new provision request triggered by an OpenClaw agent turn after the initial restart",
         "additionalProperties": {
           "type": "string"
         }

package/package.json

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