@xdarkicex/openclaw-memory-libravdb 1.4.11 → 1.4.13

package/dist/context-engine.d.ts

@@ -17,6 +17,18 @@ type OpenClawCompatibleAssembleResult = {
     systemPromptAddition: string;
     debug?: AssembleContextInternalResponse["debug"];
 };
+type OpenClawCompatibleCompactResult = {
+    ok: boolean;
+    compacted: boolean;
+    reason?: string;
+    result?: {
+        summary?: string;
+        firstKeptEntryId?: string;
+        tokensBefore: number;
+        tokensAfter?: number;
+        details?: unknown;
+    };
+};
 export declare function normalizeKernelMessage(message: {
     role: string;
     content: unknown;
@@ -77,7 +89,7 @@ export declare function buildContextEngineFactory(runtime: PluginRuntime, cfg: P
         force?: boolean;
         targetSize?: number;
         tokenBudget?: number;
-    }): Promise<any>;
+    }): Promise<OpenClawCompatibleCompactResult>;
     afterTurn(args: {
         sessionId: string;
         sessionKey?: string;

package/dist/context-engine.js

@@ -1,3 +1,35 @@
+const APPROX_CHARS_PER_TOKEN = 4;
+const ASSEMBLE_BUDGET_HEADROOM_TOKENS = 256;
+const DEFAULT_COMPACTION_THRESHOLD_FRACTION = 0.8;
+function requireSessionId(sessionId, operation) {
+    const normalized = typeof sessionId === "string" ? sessionId.trim() : "";
+    if (normalized.length > 0) {
+        return normalized;
+    }
+    throw new Error(`LibraVDB ${operation} requires a non-empty sessionId; refusing ambiguous request.`);
+}
+function normalizeCompactResult(response) {
+    const didCompact = response?.didCompact === true;
+    const details = {
+        clustersFormed: typeof response?.clustersFormed === "number" ? response.clustersFormed : undefined,
+        clustersDeclined: typeof response?.clustersDeclined === "number" ? response.clustersDeclined : undefined,
+        turnsRemoved: typeof response?.turnsRemoved === "number" ? response.turnsRemoved : undefined,
+        summaryMethod: typeof response?.summaryMethod === "string" && response.summaryMethod.length > 0
+            ? response.summaryMethod
+            : undefined,
+        meanConfidence: typeof response?.meanConfidence === "number" ? response.meanConfidence : undefined,
+    };
+    return {
+        ok: true,
+        compacted: didCompact,
+        ...(didCompact ? {} : { reason: "not_compacted" }),
+        result: {
+            tokensBefore: 0,
+            ...(details.summaryMethod ? { summary: details.summaryMethod } : {}),
+            details,
+        },
+    };
+}
 function describeUnexpectedContent(value) {
     try {
         const serialized = JSON.stringify(value);
@@ -57,6 +89,108 @@ function normalizeKernelContent(content) {
     }
     return content.map(stringifyKernelBlock).filter((part) => part.length > 0).join("\n");
 }
+function approximateTokenCount(text) {
+    if (!text)
+        return 0;
+    return Math.ceil(text.length / APPROX_CHARS_PER_TOKEN);
+}
+function approximateMessageTokens(message) {
+    // Approximate per-message wrapper overhead so trimming is conservative.
+    return approximateTokenCount(message.content) + 8;
+}
+function approximateMessagesTokens(messages) {
+    return messages.reduce((sum, message) => sum + approximateMessageTokens(message), 0);
+}
+function normalizeTokenBudget(tokenBudget) {
+    if (typeof tokenBudget !== "number" || !Number.isFinite(tokenBudget) || tokenBudget <= 0) {
+        return undefined;
+    }
+    return Math.max(1, Math.floor(tokenBudget));
+}
+function resolveEffectiveAssembleBudget(tokenBudget) {
+    const normalized = normalizeTokenBudget(tokenBudget) ?? 1;
+    return Math.max(1, normalized - ASSEMBLE_BUDGET_HEADROOM_TOKENS);
+}
+function normalizeThresholdFraction(fraction) {
+    if (typeof fraction !== "number" || !Number.isFinite(fraction)) {
+        return DEFAULT_COMPACTION_THRESHOLD_FRACTION;
+    }
+    return Math.min(0.99, Math.max(0.05, fraction));
+}
+function resolveDynamicCompactThreshold(tokenBudget, compactThreshold, compactionThresholdFraction) {
+    if (typeof compactThreshold === "number" && Number.isFinite(compactThreshold) && compactThreshold > 0) {
+        return Math.max(1, Math.floor(compactThreshold));
+    }
+    const normalizedBudget = normalizeTokenBudget(tokenBudget);
+    if (normalizedBudget == null) {
+        return undefined;
+    }
+    const fraction = normalizeThresholdFraction(compactionThresholdFraction);
+    return Math.max(1, Math.floor(normalizedBudget * fraction));
+}
+function truncateContentToTokenBudget(content, tokenBudget) {
+    if (tokenBudget <= 0)
+        return "";
+    const maxChars = Math.max(1, tokenBudget * APPROX_CHARS_PER_TOKEN);
+    if (content.length <= maxChars)
+        return content;
+    // Keep the tail so recent tool output / latest answer content is preserved.
+    return content.slice(content.length - maxChars);
+}
+function trimMessagesToBudget(messages, tokenBudget) {
+    if (tokenBudget <= 0 || messages.length === 0) {
+        return [];
+    }
+    const kept = [];
+    let used = 0;
+    for (let i = messages.length - 1; i >= 0; i -= 1) {
+        const candidate = messages[i];
+        const cost = approximateMessageTokens(candidate);
+        if (used + cost > tokenBudget) {
+            continue;
+        }
+        kept.push(candidate);
+        used += cost;
+    }
+    if (kept.length > 0) {
+        return kept.reverse();
+    }
+    const last = messages[messages.length - 1];
+    const contentBudget = Math.max(1, tokenBudget - 8);
+    const truncated = truncateContentToTokenBudget(last.content, contentBudget);
+    if (!truncated) {
+        return [];
+    }
+    return [{ ...last, content: truncated }];
+}
+function enforceTokenBudgetInvariant(result, tokenBudget) {
+    if (typeof tokenBudget !== "number" || !Number.isFinite(tokenBudget) || tokenBudget <= 0) {
+        return result;
+    }
+    const hardBudget = Math.max(1, Math.floor(tokenBudget));
+    const effectiveBudget = resolveEffectiveAssembleBudget(hardBudget);
+    const estimated = typeof result.estimatedTokens === "number" ? result.estimatedTokens : 0;
+    const approxFromMessages = approximateMessagesTokens(result.messages);
+    if (estimated <= effectiveBudget && approxFromMessages <= effectiveBudget) {
+        return result;
+    }
+    const trimmedMessages = trimMessagesToBudget(result.messages, effectiveBudget);
+    const trimmedEstimate = approximateMessagesTokens(trimmedMessages);
+    return {
+        ...result,
+        messages: trimmedMessages,
+        estimatedTokens: Math.min(effectiveBudget, trimmedEstimate),
+    };
+}
+function buildBudgetFallbackContext(messages, tokenBudget) {
+    const effectiveBudget = resolveEffectiveAssembleBudget(tokenBudget);
+    const fallbackMessages = trimMessagesToBudget(messages.map((message) => ({ ...message })), effectiveBudget);
+    return {
+        messages: fallbackMessages,
+        estimatedTokens: approximateMessagesTokens(fallbackMessages),
+        systemPromptAddition: "",
+    };
+}
 export function normalizeKernelMessage(message) {
     return {
         role: message.role,
@@ -87,6 +221,38 @@ export function normalizeAssembleResult(result) {
     };
 }
 export function buildContextEngineFactory(runtime, cfg, recallCache, logger = console) {
+    const getDynamicCompactThreshold = (tokenBudget) => resolveDynamicCompactThreshold(tokenBudget, cfg.compactThreshold, cfg.compactionThresholdFraction);
+    const buildAssemblyConfig = (tokenBudget) => ({
+        useSessionRecallProjection: cfg.useSessionRecallProjection,
+        useSessionSummarySearchExperiment: cfg.useSessionSummarySearchExperiment,
+        tokenBudgetFraction: cfg.tokenBudgetFraction,
+        authoredHardBudgetFraction: cfg.authoredHardBudgetFraction,
+        authoredSoftBudgetFraction: cfg.authoredSoftBudgetFraction,
+        elevatedGuidanceBudgetFraction: cfg.elevatedGuidanceBudgetFraction,
+        topK: cfg.topK,
+        continuityMinTurns: cfg.continuityMinTurns,
+        continuityTailBudgetTokens: cfg.continuityTailBudgetTokens,
+        continuityPriorContextTokens: cfg.continuityPriorContextTokens,
+        compactThreshold: getDynamicCompactThreshold(tokenBudget),
+        compactSessionTokenBudget: cfg.compactSessionTokenBudget,
+        section7Theta1: cfg.section7Theta1,
+        section7Kappa: cfg.section7Kappa,
+        section7HopEta: cfg.section7HopEta,
+        section7HopThreshold: cfg.section7HopThreshold,
+        section7CoarseTopK: cfg.section7CoarseTopK,
+        section7SecondPassTopK: cfg.section7SecondPassTopK,
+        section7AuthorityRecencyLambda: cfg.section7AuthorityRecencyLambda,
+        section7AuthorityRecencyWeight: cfg.section7AuthorityRecencyWeight,
+        section7AuthorityFrequencyWeight: cfg.section7AuthorityFrequencyWeight,
+        section7AuthorityAuthoredWeight: cfg.section7AuthorityAuthoredWeight,
+        recoveryFloorScore: cfg.recoveryFloorScore,
+        recoveryMinTopK: cfg.recoveryMinTopK,
+        recoveryMinConfidenceMean: cfg.recoveryMinConfidenceMean,
+        recencyLambdaSession: cfg.recencyLambdaSession,
+        recencyLambdaUser: cfg.recencyLambdaUser,
+        recencyLambdaGlobal: cfg.recencyLambdaGlobal,
+        ingestionGateThreshold: cfg.ingestionGateThreshold,
+    });
     function buildCompactSessionRequest(args) {
         // OpenClaw core now requests budget-style compaction using tokenBudget,
         // but the current LibraVDB compact_session wire contract still expects
@@ -94,7 +260,7 @@ export function buildContextEngineFactory(runtime, cfg, recallCache, logger = co
         // timeout retries still compact toward the host's requested prompt budget.
         const targetSize = args.targetSize ?? args.tokenBudget;
         return {
-            sessionId: args.sessionId,
+            sessionId: requireSessionId(args.sessionId, "compact"),
             force: args.force,
             ...(typeof targetSize === "number" ? { targetSize } : {}),
             ...(typeof cfg.continuityMinTurns === "number"
@@ -108,6 +274,24 @@ export function buildContextEngineFactory(runtime, cfg, recallCache, logger = co
                 : {}),
         };
     }
+    async function runCompaction(args) {
+        const request = buildCompactSessionRequest(args);
+        const kernel = runtime.getKernel();
+        try {
+            if (kernel) {
+                return normalizeCompactResult(await kernel.compactSession(request));
+            }
+            const rpc = await runtime.getRpc();
+            return normalizeCompactResult(await rpc.call("compact_session", request));
+        }
+        catch (error) {
+            return {
+                ok: false,
+                compacted: false,
+                reason: error instanceof Error ? error.message : String(error),
+            };
+        }
+    }
     return {
         info: { id: "libravdb-memory", name: "LibraVDB Memory", ownsCompaction: true },
         ownsCompaction: true,
@@ -152,70 +336,60 @@ export function buildContextEngineFactory(runtime, cfg, recallCache, logger = co
         },
         async assemble(args) {
             const messages = normalizeKernelMessages(args.messages);
+            const currentContextTokens = approximateMessagesTokens(messages) + approximateTokenCount(args.prompt ?? "");
+            const dynamicCompactThreshold = getDynamicCompactThreshold(args.tokenBudget);
+            if (dynamicCompactThreshold != null &&
+                currentContextTokens >= dynamicCompactThreshold) {
+                const compactionResult = await runCompaction({
+                    sessionId: args.sessionId,
+                    tokenBudget: args.tokenBudget,
+                    force: true,
+                });
+                if (!compactionResult.ok || !compactionResult.compacted) {
+                    logger.warn?.(`LibraVDB predictive compaction blocked assemble path at ${currentContextTokens} tokens (threshold=${dynamicCompactThreshold}): ${compactionResult.reason ?? "compaction declined"}`);
+                    return buildBudgetFallbackContext(messages, args.tokenBudget);
+                }
+            }
             const kernel = runtime.getKernel();
             if (kernel) {
-                return normalizeAssembleResult(await kernel.assembleContext({
+                try {
+                    return enforceTokenBudgetInvariant(normalizeAssembleResult(await kernel.assembleContext({
+                        sessionId: args.sessionId,
+                        sessionKey: args.sessionKey,
+                        userId: args.userId,
+                        queryText: args.prompt ?? "",
+                        visibleMessages: messages,
+                        tokenBudget: args.tokenBudget,
+                        config: buildAssemblyConfig(args.tokenBudget),
+                        emitDebug: true
+                    })), args.tokenBudget);
+                }
+                catch (error) {
+                    logger.warn?.(`LibraVDB assemble kernel failed, using budget-clamped fallback context: ${error instanceof Error ? error.message : String(error)}`);
+                    return buildBudgetFallbackContext(messages, args.tokenBudget);
+                }
+            }
+            const rpc = await runtime.getRpc();
+            try {
+                const resp = await rpc.call("assemble_context_internal", {
                     sessionId: args.sessionId,
                     sessionKey: args.sessionKey,
                     userId: args.userId,
-                    queryText: args.prompt ?? "",
-                    visibleMessages: messages,
+                    messages,
                     tokenBudget: args.tokenBudget,
-                    config: {},
-                    emitDebug: true
-                }));
+                    prompt: args.prompt,
+                    emitDebug: true,
+                    config: buildAssemblyConfig(args.tokenBudget),
+                });
+                return enforceTokenBudgetInvariant(normalizeAssembleResult(resp), args.tokenBudget);
+            }
+            catch (error) {
+                logger.warn?.(`LibraVDB assemble sidecar failed, using budget-clamped fallback context: ${error instanceof Error ? error.message : String(error)}`);
+                return buildBudgetFallbackContext(messages, args.tokenBudget);
             }
-            const rpc = await runtime.getRpc();
-            const resp = await rpc.call("assemble_context_internal", {
-                sessionId: args.sessionId,
-                sessionKey: args.sessionKey,
-                userId: args.userId,
-                messages,
-                tokenBudget: args.tokenBudget,
-                prompt: args.prompt,
-                emitDebug: true,
-                config: {
-                    useSessionRecallProjection: cfg.useSessionRecallProjection,
-                    useSessionSummarySearchExperiment: cfg.useSessionSummarySearchExperiment,
-                    tokenBudgetFraction: cfg.tokenBudgetFraction,
-                    authoredHardBudgetFraction: cfg.authoredHardBudgetFraction,
-                    authoredSoftBudgetFraction: cfg.authoredSoftBudgetFraction,
-                    elevatedGuidanceBudgetFraction: cfg.elevatedGuidanceBudgetFraction,
-                    topK: cfg.topK,
-                    continuityMinTurns: cfg.continuityMinTurns,
-                    continuityTailBudgetTokens: cfg.continuityTailBudgetTokens,
-                    continuityPriorContextTokens: cfg.continuityPriorContextTokens,
-                    compactThreshold: cfg.compactThreshold,
-                    compactSessionTokenBudget: cfg.compactSessionTokenBudget,
-                    section7Theta1: cfg.section7Theta1,
-                    section7Kappa: cfg.section7Kappa,
-                    section7HopEta: cfg.section7HopEta,
-                    section7HopThreshold: cfg.section7HopThreshold,
-                    section7CoarseTopK: cfg.section7CoarseTopK,
-                    section7SecondPassTopK: cfg.section7SecondPassTopK,
-                    section7AuthorityRecencyLambda: cfg.section7AuthorityRecencyLambda,
-                    section7AuthorityRecencyWeight: cfg.section7AuthorityRecencyWeight,
-                    section7AuthorityFrequencyWeight: cfg.section7AuthorityFrequencyWeight,
-                    section7AuthorityAuthoredWeight: cfg.section7AuthorityAuthoredWeight,
-                    recoveryFloorScore: cfg.recoveryFloorScore,
-                    recoveryMinTopK: cfg.recoveryMinTopK,
-                    recoveryMinConfidenceMean: cfg.recoveryMinConfidenceMean,
-                    recencyLambdaSession: cfg.recencyLambdaSession,
-                    recencyLambdaUser: cfg.recencyLambdaUser,
-                    recencyLambdaGlobal: cfg.recencyLambdaGlobal,
-                    ingestionGateThreshold: cfg.ingestionGateThreshold,
-                },
-            });
-            return normalizeAssembleResult(resp);
         },
         async compact(args) {
-            const request = buildCompactSessionRequest(args);
-            const kernel = runtime.getKernel();
-            if (kernel) {
-                return await kernel.compactSession(request);
-            }
-            const rpc = await runtime.getRpc();
-            return await rpc.call("compact_session", request);
+            return await runCompaction(args);
         },
         async afterTurn(args) {
             const messages = normalizeKernelMessages(args.messages);

package/dist/types.d.ts

@@ -63,6 +63,7 @@ export interface PluginConfig {
     continuityTailBudgetTokens?: number;
     continuityPriorContextTokens?: number;
     compactThreshold?: number;
+    compactionThresholdFraction?: number;
     compactSessionTokenBudget?: number;
     section7CoarseTopK?: number;
     section7SecondPassTopK?: number;

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "libravdb-memory",
   "name": "LibraVDB Memory",
   "description": "Persistent vector memory with three-tier hybrid scoring",
-  "version": "1.4.11",
+  "version": "1.4.13",
   "kind": [
     "memory",
     "context-engine"
@@ -237,6 +237,11 @@
       "compactThreshold": {
         "type": "number"
       },
+      "compactionThresholdFraction": {
+        "type": "number",
+        "default": 0.8,
+        "description": "Dynamic predictive compaction trigger ratio against the active token budget. Used when compactThreshold is not explicitly set."
+      },
       "compactSessionTokenBudget": {
         "type": "number",
         "default": 2000,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xdarkicex/openclaw-memory-libravdb",
-  "version": "1.4.11",
+  "version": "1.4.13",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",