@mem9/mem9 0.4.12 → 0.4.13

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

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/package.json

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