@memorax/memorax-code 0.1.5 → 0.1.7

package/lib/memorax-code-backend/dist/lifecycle/orchestrator.js

@@ -5,6 +5,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { BackendConnectionAuthorityError } from "../../../memorax-code-adapter-common/src/backend-connection.mjs";
 import { RuntimeRecordError } from "../../../memorax-code-adapter-common/src/runtime-record.mjs";
+import { withSetupCompletionLock } from "../../../memorax-code-adapter-common/src/setup-completion.mjs";
 import { runBackendStatus } from "./backend/status.js";
 import { readBackendServiceState, preflightBackendServiceStart, startBackendService, stopBackendService, } from "./backend/service.js";
 import { backendServiceHome, BackendLifecycleLockError, withBackendLifecycleLock, } from "./lock.js";
@@ -17,6 +18,7 @@ import { claudeAdapterLifecycle } from "../clients/claude/lifecycle.js";
 import { collectDshAdapterLifecycleStatus, withDshAdapterLifecycleLock, } from "../clients/dsh/lifecycle.js";
 import { openCodeAdapterLifecycle } from "../clients/opencode/lifecycle.js";
 const PACKAGE_REPLACEMENT_ENV = "MEMORAX_CODE_PACKAGE_REPLACEMENT";
+const DSH_OPTIONAL_ENV = "MEMORAX_CODE_DSH_ADAPTER_OPTIONAL";
 const DSH_RECOVERY_ENV = "MEMORAX_CODE_DSH_ADAPTER_RECOVERY";
 const DSH_RECOVERY_REVISION_ENV = "MEMORAX_CODE_DSH_ADAPTER_EXPECTED_REVISION";
 export async function collectMemoraxCodeStatus(backendUrl, backendToken, serviceOptions, argv) {
@@ -50,9 +52,9 @@ export async function collectMemoraxCodeStatus(backendUrl, backendToken, service
     const claudeAdapter = clients.claude
         ? await claudeAdapterLifecycle.status({ argv, serviceOptions, backendUrl })
         : undefined;
-    const dshAdapter = clients.dsh
+    const dshAdapter = markOptionalDshAdapter(clients.dsh
         ? await collectDshAdapterLifecycleStatus({ argv, serviceOptions, backendUrl })
-        : undefined;
+        : undefined, clients.dsh && isOptionalDshSelection(argv));
     const opencodeAdapter = clients.opencode
         ? await openCodeAdapterLifecycle.status({ argv, serviceOptions, backendUrl })
         : undefined;
@@ -60,13 +62,15 @@ export async function collectMemoraxCodeStatus(backendUrl, backendToken, service
     const claudeReady = claudeAdapter ? isAdapterReady(claudeAdapter) : true;
     const dshReady = dshAdapter ? isAdapterReady(dshAdapter) : true;
     const opencodeReady = opencodeAdapter ? isAdapterReady(opencodeAdapter) : true;
+    const optionalDshUnavailable = isOptionalUnavailableDshAdapter(dshAdapter);
     return {
         ok: backend.ok
             && codexReady
             && opencodeReady
             && (isOptionalUnconfiguredClaudeAdapter(claudeAdapter, codexAdapter) || claudeReady)
-            && (isOptionalUnavailableDshAdapter(dshAdapter) || dshReady),
+            && (optionalDshUnavailable || dshReady),
         action: "status",
+        ...(optionalDshUnavailable ? { degraded: true } : {}),
         backend,
         ...(codexAdapter ? { codexAdapter } : {}),
         ...(claudeAdapter ? { claudeAdapter } : {}),
@@ -104,16 +108,22 @@ async function startMemoraxCodeServiceLocked(serviceOptions, argv) {
     if (serviceStateFailure) {
         return { ok: false, action: "start", backend: serviceStateFailure };
     }
-    const config = loadManagedClientsConfig(memoraxCodeHome);
-    const requestedClients = resolveManagedClients(argv, config);
+    const packageReplacement = isPackageReplacement();
+    // Active client intent must not bypass strict lifecycle config validation.
+    if (packageReplacement)
+        loadManagedClientsConfig(memoraxCodeHome);
+    const requestedClients = managedClientsFor(argv, serviceOptions, {
+        preferActive: packageReplacement,
+    });
     const clients = isDshAdapterRecovery()
         ? { ...requestedClients, dsh: true }
         : requestedClients;
     const previousClients = readActiveManagedClients(memoraxCodeHome);
+    const optionalDsh = clients.dsh && isOptionalDshSelection(argv);
     const context = { argv, serviceOptions };
     if (clients.dsh || previousClients?.dsh || isDshAdapterRecovery()) {
         try {
-            return await withDshAdapterLifecycleLock(context, (dshLifecycle) => (executeMemoraxCodeStart(serviceOptions, argv, backendUrl, memoraxCodeHome, clients, previousClients, dshLifecycle)));
+            return await withDshAdapterLifecycleLock(context, (dshLifecycle) => (executeMemoraxCodeStart(serviceOptions, argv, backendUrl, memoraxCodeHome, clients, previousClients, dshLifecycle, optionalDsh)));
         }
         catch (error) {
             return dshLifecycleFailure("start", error);
@@ -121,7 +131,7 @@ async function startMemoraxCodeServiceLocked(serviceOptions, argv) {
     }
     return executeMemoraxCodeStart(serviceOptions, argv, backendUrl, memoraxCodeHome, clients, previousClients);
 }
-async function executeMemoraxCodeStart(serviceOptions, argv, backendUrl, memoraxCodeHome, clients, previousClients, dshLifecycle) {
+async function executeMemoraxCodeStart(serviceOptions, argv, backendUrl, memoraxCodeHome, clients, previousClients, dshLifecycle, optionalDsh = false) {
     const lifecycleContext = { argv, serviceOptions };
     const lifecycleBackendContext = { ...lifecycleContext, backendUrl };
     if (isDshAdapterRecovery() && dshLifecycle) {
@@ -148,7 +158,7 @@ async function executeMemoraxCodeStart(serviceOptions, argv, backendUrl, memorax
     const quiescedDsh = dshLifecycle && (clients.dsh || previousClients?.dsh)
         ? await dshLifecycle.quiesce?.(lifecycleContext)
         : undefined;
-    if (quiescedDsh?.ok === false) {
+    if (quiescedDsh?.ok === false && !optionalDsh) {
         return {
             ok: false,
             action: "start",
@@ -249,10 +259,12 @@ async function executeMemoraxCodeStart(serviceOptions, argv, backendUrl, memorax
             opencodeAdapter,
         };
     }
-    const preparedDshAdapter = clients.dsh && dshLifecycle
-        ? await dshLifecycle.prepareEnable(lifecycleBackendContext)
-        : undefined;
-    if (preparedDshAdapter?.ok === false) {
+    const preparedDshAdapter = markOptionalDshAdapter(quiescedDsh?.ok === false
+        ? quiescedDsh
+        : clients.dsh && dshLifecycle
+            ? await dshLifecycle.prepareEnable(lifecycleBackendContext)
+            : undefined, optionalDsh);
+    if (preparedDshAdapter?.ok === false && !optionalDsh) {
         const recovery = await recoverPreparationFailure("dsh_adapter_enable_failed");
         return {
             ok: false,
@@ -286,12 +298,15 @@ async function executeMemoraxCodeStart(serviceOptions, argv, backendUrl, memorax
             ...(disabledOpenCode ? { opencodeAdapter: disabledOpenCode } : {}),
         };
     }
-    const dshAdapter = preparedDshAdapter?.installed === true
+    const dshAdapter = markOptionalDshAdapter(preparedDshAdapter?.installed === true
         ? await dshLifecycle?.activate?.(lifecycleBackendContext)
-        : preparedDshAdapter;
+        : preparedDshAdapter, optionalDsh);
+    const optionalDshUnavailable = isOptionalUnavailableDshAdapter(dshAdapter);
     return {
-        ok: claudeAdapter?.ok !== false && dshAdapter?.ok !== false,
+        ok: claudeAdapter?.ok !== false
+            && (!dshAdapter || isAdapterReady(dshAdapter) || optionalDshUnavailable),
         action: "start",
+        ...(optionalDshUnavailable ? { degraded: true } : {}),
         backend,
         ...(codexAdapter ? { codexAdapter } : {}),
         ...(claudeAdapter ? { claudeAdapter } : {}),
@@ -426,7 +441,9 @@ async function executeMemoraxCodeStop(serviceOptions, argv, context, dshLifecycl
             ...(dshAdapter ? { dshAdapter } : {}),
             ...(opencodeAdapter ? { opencodeAdapter } : {}),
         },
-        remainingClients: remaining && hasRemainingClients ? remaining : undefined,
+        remainingClients: packageReplacement
+            ? activeClients
+            : remaining && hasRemainingClients ? remaining : undefined,
     };
 }
 export async function restartMemoraxCodeService(serviceOptions, argv, commitReadyState) {
@@ -457,7 +474,39 @@ async function restartMemoraxCodeServiceLocked(serviceOptions, argv) {
     return { ...started, action: "restart" };
 }
 export async function uninstallMemoraxCodeService(serviceOptions, argv) {
-    return withMemoraxCodeLifecycleLock("uninstall", serviceOptions, () => uninstallMemoraxCodeServiceLocked(serviceOptions, argv));
+    const memoraxCodeHome = memoraxCodeHomeForService(serviceOptions);
+    let report;
+    let lifecycleEntered = false;
+    try {
+        return await withSetupCompletionLock(memoraxCodeHome, async (_completion, mutation) => {
+            lifecycleEntered = true;
+            report = await withMemoraxCodeLifecycleLock("uninstall", serviceOptions, () => uninstallMemoraxCodeServiceLocked(serviceOptions, argv));
+            if (isCompleteSuccessfulUninstall(report))
+                mutation.clear();
+            return report;
+        });
+    }
+    catch (error) {
+        if (lifecycleEntered && !report)
+            throw error;
+        if (!report) {
+            return {
+                ok: false,
+                action: "uninstall",
+                reason: "setup_completion_lock_failed",
+                message: error instanceof Error ? error.message : String(error),
+                npmPackageRemoval: skippedNpmPackageRemoval("setup_completion_lock_failed"),
+                removesPlugin: false,
+                removesUserState: false,
+            };
+        }
+        return {
+            ...report,
+            ok: false,
+            reason: "setup_completion_clear_failed",
+            message: error instanceof Error ? error.message : String(error),
+        };
+    }
 }
 async function uninstallMemoraxCodeServiceLocked(serviceOptions, argv) {
     const context = memoraxCodeStopContext(serviceOptions, argv);
@@ -537,6 +586,11 @@ async function executeMemoraxCodeUninstall(serviceOptions, argv, context, dshLif
 function skippedNpmPackageRemoval(reason) {
     return { ok: true, action: "npm-package-remove", skipped: true, reason };
 }
+function isCompleteSuccessfulUninstall(report) {
+    return report.ok
+        && report.npmPackageRemoval !== undefined
+        && report.npmPackageRemoval.reason !== "partial_client_uninstall";
+}
 async function removeNpmPackageIfInstalled(argv) {
     if (argv.includes("--no-npm-uninstall")) {
         return { ok: true, action: "npm-package-remove", skipped: true, reason: "disabled_by_flag" };
@@ -638,6 +692,10 @@ function commitActiveManagedClients(memoraxCodeHome, clients) {
 function hasExplicitClientSelection(argv) {
     return argv.includes("--clients");
 }
+function isOptionalDshSelection(argv) {
+    return !isDshAdapterRecovery()
+        && (!hasExplicitClientSelection(argv) || truthyEnv(process.env[DSH_OPTIONAL_ENV]));
+}
 function argValue(argv, name) {
     const index = argv.indexOf(name);
     return index >= 0 ? argv[index + 1] : undefined;
@@ -777,11 +835,12 @@ export function isAdapterReady(report) {
         && report.opencodeSkills?.ok !== false;
 }
 export function isOptionalUnavailableDshAdapter(report) {
-    return Boolean(report
-        && report.ok !== false
-        && report.skipped === true
-        && report.managed !== true
-        && report.reason === "no_existing_profiles");
+    return Boolean(report?.optional === true && !isAdapterReady(report));
+}
+function markOptionalDshAdapter(report, optional) {
+    return report && optional && !isAdapterReady(report)
+        ? { ...report, optional: true }
+        : report;
 }
 export function isOptionalUnconfiguredClaudeAdapter(report, codexAdapter) {
     return Boolean(report

package/lib/memorax-code-backend/dist/memorax-cli.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 import { runMemoryCli } from "./memory/cli.js";
 runMemoryCli(process.argv.slice(2)).then((result) => {
+    if (!process.argv.includes("--json") && result.ok && result.quotaNotice) {
+        console.warn(result.quotaNotice);
+    }
     if (!process.argv.includes("--json") && result.ok && result.action === "memory.search") {
         if (result.userNotice)
             console.warn(`Warning: ${result.userNotice}`);

package/lib/memorax-code-backend/dist/memory/automatic-retrieval.js

@@ -48,6 +48,7 @@ export async function retrieveAutomaticMemoryContext(options) {
     }, {
         config,
         diagnosticLogger: options.diagnosticLogger,
+        env,
         fetchImpl: options.fetchImpl,
         observability: options.memoryObservability,
         observabilitySource: options.memoryObservabilitySource ?? "automatic_retrieval",
@@ -57,6 +58,9 @@ export async function retrieveAutomaticMemoryContext(options) {
     if (!response.ok)
         return finish(skipped("retrieve_failed", response.error));
     const result = response.result ?? {};
+    const userNotice = result.quota && options.claimQuotaNotice
+        ? await options.claimQuotaNotice(config, result.quota, { diagnosticLogger: options.diagnosticLogger, env })
+        : undefined;
     const payload = isRecord(result.tool_result_payload) ? result.tool_result_payload : {};
     const memoryItems = Array.isArray(payload.items) ? payload.items : [];
     const contextBlocks = Array.isArray(payload.contextBlocks) ? payload.contextBlocks : [];
@@ -69,7 +73,7 @@ export async function retrieveAutomaticMemoryContext(options) {
             itemCount: memoryItems.length,
             contextBlockCount: contextBlocks.length,
             blockChars,
-        }));
+        }, userNotice));
     }
     return finish({
         context,
@@ -77,6 +81,7 @@ export async function retrieveAutomaticMemoryContext(options) {
         itemCount: memoryItems.length,
         contextBlockCount: contextBlocks.length,
         blockChars,
+        ...(userNotice ? { userNotice } : {}),
     });
 }
 function isAutomaticMemoryControlCommand(text) {
@@ -85,7 +90,7 @@ function isAutomaticMemoryControlCommand(text) {
         return true;
     return /^(?:memorax-code|memorax-cli)(?:\s|$)/i.test(trimmed);
 }
-function skipped(skipReason, error, fields = {}) {
+function skipped(skipReason, error, fields = {}, userNotice) {
     return {
         retrieved: false,
         skipReason,
@@ -93,6 +98,7 @@ function skipped(skipReason, error, fields = {}) {
         contextBlockCount: fields.contextBlockCount ?? 0,
         blockChars: fields.blockChars ?? 0,
         ...(error ? { error } : {}),
+        ...(userNotice ? { userNotice } : {}),
     };
 }
 function automaticMemoryContextText(result) {

package/lib/memorax-code-backend/dist/memory/automatic-writeback.js

@@ -12,6 +12,7 @@ const AUTOMATIC_MEMORY_WRITEBACK_MAX_RETRY_DELAY_MS = 5_000;
 export function createAutomaticMemoryWritebackRuntime(options = {}) {
     const state = {
         diagnosticLogger: options.diagnosticLogger ?? (() => { }),
+        queueQuotaNotice: options.queueQuotaNotice,
         pendingWritebacks: new Map(),
         writebackBuffer: createMemoryWritebackBufferRuntime(),
         accepting: true,
@@ -243,8 +244,11 @@ async function enqueueAutomaticMemoryWritebackAsync(state, decision, options) {
                     errorKind: response.ok ? undefined : response.errorKind,
                     httpStatus: response.ok ? undefined : response.httpStatus,
                 });
-                if (response.ok)
+                if (response.ok) {
+                    if (response.result.quota)
+                        queueQuotaNoticeBestEffort(state, response.result.quota);
                     break;
+                }
                 if (!retrying) {
                     releasePendingWritebacks(state, [decision.idempotencyKey, ...(decision.dedupeKeys ?? [])]);
                     return;
@@ -283,6 +287,14 @@ function trackAutomaticMemoryWriteback(state, writeback) {
     state.inFlight.add(writeback);
     void writeback.then(() => state.inFlight.delete(writeback), () => state.inFlight.delete(writeback));
 }
+function queueQuotaNoticeBestEffort(state, quota) {
+    try {
+        state.queueQuotaNotice?.(quota);
+    }
+    catch {
+        state.diagnosticLogger("memory.automatic_writeback.quota_notice_queue_failed", {});
+    }
+}
 function hasPendingWriteback(state, idempotencyKey) {
     prunePendingWritebacks(state);
     return state.pendingWritebacks.has(idempotencyKey);

package/lib/memorax-code-backend/dist/memory/cli.js

@@ -7,6 +7,7 @@ import { resolveConfiguredRepositoryMemory, } from "./repository-session.js";
 import { repositoryMemoryScopeContainsWorkspace, repositoryMemoryScopeKind, repositoryMemoryScopesMatch, } from "../repository/scope.js";
 import { isTraceClient } from "../trace/context.js";
 import { readCurrentTraceTurn, recordTraceEvent } from "../trace/store.js";
+import { claimQuotaNotice, } from "./quota-notice.js";
 export async function runMemoryCli(args, options = {}) {
     const command = args[0] || "status";
     const env = options.env ?? process.env;
@@ -88,6 +89,7 @@ async function memorySearch(args, options) {
     }, {
         config: repositoryMemory.memory.config,
         diagnosticLogger: backendDebug,
+        env: options.env,
         fetchImpl: options.fetchImpl,
         observability: observability.hook,
         observabilitySource: "memory_cli",
@@ -96,6 +98,9 @@ async function memorySearch(args, options) {
     await observability.flush();
     if (!response.ok)
         return { ok: false, action: "memory.search", query, error: response.error };
+    const quotaNotice = response.result.quota
+        ? await (options.claimQuotaNotice ?? claimQuotaNotice)(repositoryMemory.memory.config, response.result.quota, { diagnosticLogger: backendDebug, env: options.env })
+        : undefined;
     const payload = isRecord(response.result.tool_result_payload) ? response.result.tool_result_payload : {};
     return {
         ok: true,
@@ -106,6 +111,7 @@ async function memorySearch(args, options) {
         answer: typeof payload.answer === "string" ? payload.answer : "",
         items: Array.isArray(payload.items) ? payload.items : [],
         receipt: response.result.dispatch_receipt ?? null,
+        ...(quotaNotice ? { quotaNotice } : {}),
     };
 }
 async function memoryAdd(args, options) {
@@ -167,12 +173,16 @@ async function memoryAdd(args, options) {
     await observability.flush();
     if (!response.ok)
         return { ok: false, action: "memory.add", error: response.error };
+    const quotaNotice = response.result.quota
+        ? await (options.claimQuotaNotice ?? claimQuotaNotice)(repositoryMemory.memory.config, response.result.quota, { diagnosticLogger: backendDebug, env })
+        : undefined;
     return {
         ok: true,
         action: "memory.add",
         provider: "memory.memorax",
         ...memoryCliIdentityFields(repositoryMemory.memory),
         receipt: response.result.dispatch_receipt ?? null,
+        ...(quotaNotice ? { quotaNotice } : {}),
     };
 }
 async function resolveMemoryCliRepositoryMemory(options) {

package/lib/memorax-code-backend/dist/memory/quota-notice.js

@@ -0,0 +1,208 @@
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { withJsonFileLockAsync, } from "../../../memorax-code-adapter-common/src/config-utils.mjs";
+import { readJsonRuntimeRecord, writePrivateJsonRecord, } from "../../../memorax-code-adapter-common/src/runtime-record.mjs";
+import { MEMORAX_ACCOUNT_URL, } from "../../../memorax-code-adapter-common/src/memorax-defaults.mjs";
+import { defaultMemoraxCodeHome } from "../config/memorax-code.js";
+const QUOTA_NOTICE_STATE_VERSION = 1;
+const DEFAULT_NOTICE_TIMEOUT_MS = 6_000;
+const LOCK_TIMEOUT_MS = 500;
+const ANONYMOUS_QUOTA_LIMIT = 100;
+const NOTICE_LEVELS = [10, 0];
+const QUOTA_NOTICE_STATE_KEYS = new Set([
+    "version",
+    "connection_fingerprint",
+    "last_notified_write_level",
+    "last_notified_search_level",
+]);
+const SHA256_PATTERN = /^[0-9a-f]{64}$/;
+export const claimQuotaNotice = async (config, quota, options = {}) => {
+    const env = options.env ?? process.env;
+    const transitionState = options.transitionState ?? transitionQuotaNoticeState;
+    const timeoutMs = positiveTimeout(options.timeoutMs);
+    const controller = new AbortController();
+    const level = quotaNoticeLevel(quota);
+    const initial = initialQuotaNoticeState(config);
+    const noticeField = quota.featureCode === "memory_write"
+        ? "last_notified_write_level"
+        : "last_notified_search_level";
+    let timeout;
+    let claimed = false;
+    try {
+        await Promise.race([
+            transitionState(initial, (current) => {
+                const lastNotifiedLevel = current[noticeField];
+                if (level === undefined) {
+                    return lastNotifiedLevel === null
+                        ? undefined
+                        : { ...current, [noticeField]: null };
+                }
+                if (lastNotifiedLevel !== null && level >= lastNotifiedLevel) {
+                    return undefined;
+                }
+                claimed = true;
+                return { ...current, [noticeField]: level };
+            }, {
+                memoraxCodeHome: defaultMemoraxCodeHome(env),
+                signal: controller.signal,
+                timeoutMs: LOCK_TIMEOUT_MS,
+            }),
+            new Promise((_resolve, reject) => {
+                timeout = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error("Quota notice state update timed out"));
+                }, timeoutMs);
+                timeout.unref?.();
+            }),
+        ]);
+    }
+    catch {
+        options.diagnosticLogger?.("memorax_quota_notice.update_failed", {});
+        return undefined;
+    }
+    finally {
+        if (timeout)
+            clearTimeout(timeout);
+    }
+    return claimed && level !== undefined
+        ? quotaNotice(quota, level, config.memoryOutputLanguage)
+        : undefined;
+};
+export function createPendingQuotaNoticeRuntime(options = {}) {
+    const { claimQuotaNotice: claim = claimQuotaNotice, ...noticeOptions } = options;
+    let pendingQuota;
+    let closed = false;
+    return {
+        queue(quota) {
+            if (closed || quota.featureCode !== "memory_write")
+                return;
+            if (!pendingQuota || quotaRemainingRatio(quota) < quotaRemainingRatio(pendingQuota)) {
+                pendingQuota = { ...quota };
+            }
+        },
+        async claim(config) {
+            if (closed || !pendingQuota)
+                return undefined;
+            const quota = pendingQuota;
+            pendingQuota = undefined;
+            try {
+                return await claim(config, quota, noticeOptions);
+            }
+            catch {
+                options.diagnosticLogger?.("memorax_quota_notice.claim_failed", {});
+                return undefined;
+            }
+        },
+        close() {
+            closed = true;
+            pendingQuota = undefined;
+        },
+    };
+}
+async function transitionQuotaNoticeState(initial, operation, options) {
+    const path = join(options.memoraxCodeHome, "runtime", "memory", "quota-notices.json");
+    return await withJsonFileLockAsync(path, async () => {
+        const stored = readQuotaNoticeState(path);
+        const current = stored?.connection_fingerprint === initial.connection_fingerprint
+            ? stored
+            : initial;
+        const next = operation(current);
+        if (!next)
+            return current;
+        writePrivateJsonRecord(path, next, { durableBoundary: options.memoraxCodeHome });
+        return next;
+    }, {
+        signal: options.signal,
+        timeoutMs: options.timeoutMs,
+    });
+}
+function readQuotaNoticeState(path) {
+    const state = readJsonRuntimeRecord(path);
+    if (state.status === "absent")
+        return undefined;
+    if (state.status !== "present")
+        throw new Error("Quota notice state is unreadable");
+    const value = state.value;
+    if (value.version !== QUOTA_NOTICE_STATE_VERSION
+        || Object.keys(value).some((key) => !QUOTA_NOTICE_STATE_KEYS.has(key))
+        || Object.keys(value).length !== QUOTA_NOTICE_STATE_KEYS.size
+        || typeof value.connection_fingerprint !== "string"
+        || !SHA256_PATTERN.test(value.connection_fingerprint)
+        || !validNoticeLevel(value.last_notified_write_level)
+        || !validNoticeLevel(value.last_notified_search_level)) {
+        throw new Error("Quota notice state is invalid");
+    }
+    return {
+        version: QUOTA_NOTICE_STATE_VERSION,
+        connection_fingerprint: value.connection_fingerprint,
+        last_notified_write_level: value.last_notified_write_level,
+        last_notified_search_level: value.last_notified_search_level,
+    };
+}
+function initialQuotaNoticeState(config) {
+    return {
+        version: QUOTA_NOTICE_STATE_VERSION,
+        connection_fingerprint: createHash("sha256")
+            .update(config.baseUrl)
+            .update("\0")
+            .update(config.apiKey)
+            .digest("hex"),
+        last_notified_write_level: null,
+        last_notified_search_level: null,
+    };
+}
+function positiveTimeout(value) {
+    return typeof value === "number" && Number.isSafeInteger(value) && value > 0
+        ? value
+        : DEFAULT_NOTICE_TIMEOUT_MS;
+}
+function quotaNoticeLevel(quota) {
+    if (quota.remaining === 0)
+        return 0;
+    if (quota.limit <= 0)
+        return undefined;
+    const percentage = quotaRemainingRatio(quota) * 100;
+    if (percentage <= 10)
+        return 10;
+    return undefined;
+}
+function quotaRemainingRatio(quota) {
+    return quota.limit === 0 ? 0 : quota.remaining / quota.limit;
+}
+function validNoticeLevel(value) {
+    return value === null || NOTICE_LEVELS.some((level) => value === level);
+}
+function quotaNotice(quota, level, language) {
+    if (language === "zh") {
+        const quotaName = quota.featureCode === "memory_write" ? "记忆写入" : "记忆搜索";
+        const quotaStatus = level === 0 ? "已用完" : `剩余不超过 ${level}%`;
+        if (quota.limit !== ANONYMOUS_QUOTA_LIMIT) {
+            return [
+                `额度提醒：您的 MemoraX Code ${quotaName}额度${quotaStatus}。`,
+                `请访问 ${MEMORAX_ACCOUNT_URL} 查看额度或管理账户。`,
+            ].join(" ");
+        }
+        return [
+            `额度提醒：您的 MemoraX Code ${quotaName}额度${quotaStatus}。`,
+            `请访问 ${MEMORAX_ACCOUNT_URL} 查看额度、注册或管理账户。`,
+            "若本机使用的是尚未注册的匿名身份，可以在本机终端运行 `memorax-code account --show-mark-id` 获取用于认领当前身份的 Mark ID。",
+            "请妥善保管，不要在聊天中分享。",
+        ].join(" ");
+    }
+    const quotaName = quota.featureCode === "memory_write" ? "memory write" : "memory search";
+    const quotaStatus = level === 0
+        ? "has been used up"
+        : `has ${level}% or less remaining`;
+    if (quota.limit !== ANONYMOUS_QUOTA_LIMIT) {
+        return [
+            `Quota reminder: Your MemoraX Code ${quotaName} quota ${quotaStatus}.`,
+            `Visit ${MEMORAX_ACCOUNT_URL} to view your quota or manage your account.`,
+        ].join(" ");
+    }
+    return [
+        `Quota reminder: Your MemoraX Code ${quotaName} quota ${quotaStatus}.`,
+        `Visit ${MEMORAX_ACCOUNT_URL} to view your quota, register, or manage your account.`,
+        "If this device uses an unregistered anonymous identity, run `memorax-code account --show-mark-id` in your local terminal to retrieve the Mark ID used to claim it.",
+        "Keep it private and do not share it in chat.",
+    ].join(" ");
+}

package/lib/memorax-code-backend/dist/memory/service.js

@@ -5,9 +5,16 @@ import { createDshMemoryHookRuntime, } from "../clients/dsh/memory-hook-runtime.
 import { createOpenCodeMemoryHookRuntime, } from "../clients/opencode/memory-hook-runtime.js";
 import { createMemoryTurnCoordinator } from "./turn-coordinator.js";
 import { createRepositoryMemorySessionRuntime, } from "./repository-session.js";
+import { createPendingQuotaNoticeRuntime } from "./quota-notice.js";
 export function createMemoryService(options = {}) {
+    const pendingQuotaNotice = createPendingQuotaNoticeRuntime({
+        claimQuotaNotice: options.claimQuotaNotice,
+        diagnosticLogger: options.diagnosticLogger,
+        env: options.env,
+    });
     const automaticWriteback = createAutomaticMemoryWritebackRuntime({
         diagnosticLogger: options.diagnosticLogger,
+        queueQuotaNotice: pendingQuotaNotice.queue,
     });
     const repositoryMemorySession = createRepositoryMemorySessionRuntime({
         onScopeUpgrade: automaticWriteback.discardForScopeUpgrade,
@@ -21,16 +28,19 @@ export function createMemoryService(options = {}) {
     });
     const codexHook = createCodexMemoryHookRuntime({
         ...options,
+        pendingQuotaNotice,
         repositoryMemorySession,
         turnCoordinator,
     });
     const claudeHook = createClaudeMemoryHookRuntime({
         ...options,
+        pendingQuotaNotice,
         repositoryMemorySession,
         turnCoordinator,
     });
     const openCodeHook = createOpenCodeMemoryHookRuntime({
         ...options,
+        pendingQuotaNotice,
         repositoryMemorySession,
         turnCoordinator,
     });
@@ -81,6 +91,7 @@ export function createMemoryService(options = {}) {
             turnCoordinator.close();
             repositoryMemorySession.close();
             automaticWriteback.close();
+            pendingQuotaNotice.close();
         },
     };
 }

package/lib/memorax-code-backend/dist/provider/memorax/adapter.js

@@ -40,7 +40,7 @@ export async function invokeMemoraxMemoryProvider(run, request, options = {}) {
         return repositoryScope;
     const payload = buildMemoraxSearchPayload(config, query, context, repositoryScope.scope);
     try {
-        const raw = await callMemoSearch(config, payload, options.fetchImpl);
+        const { body: raw, quota } = await callMemoSearch(config, payload, options.fetchImpl);
         const items = extractMemoraxSearchItems(raw);
         const contextBlocks = renderMemoraxContextBlocks(items, config);
         const promptFragments = contextBlocks.map((block) => ({
@@ -72,6 +72,7 @@ export async function invokeMemoraxMemoryProvider(run, request, options = {}) {
                 slot: request.slot || "state_context",
                 operation,
                 prompt_fragments: promptFragments,
+                ...(quota ? { quota } : {}),
                 tool_result_payload: {
                     answer: contextBlocks.map((block) => block.content).join("\n\n"),
                     items,
@@ -195,7 +196,7 @@ async function invokeMemoraxWriteback(run, request, config, repositoryScope, opt
         return { ok: false, error: addOptions.error };
     const payload = buildMemoraxAddPayload(config, run, messages, context, idempotencyKey, repositoryScope, addOptions.options);
     try {
-        const raw = await callMemoAdd(config, payload, options.fetchImpl);
+        const { body: raw, quota } = await callMemoAdd(config, payload, options.fetchImpl);
         recordMemoryObservabilityEvent(options, {
             operation: "writeback",
             ok: true,
@@ -217,6 +218,7 @@ async function invokeMemoraxWriteback(run, request, config, repositoryScope, opt
                 slot: request.slot || "state_context",
                 operation: "writeback",
                 prompt_fragments: [],
+                ...(quota ? { quota } : {}),
                 tool_result_payload: {
                     accepted: true,
                     receiptId: memoraxReceiptId(raw),