@juspay/neurolink 10.10.6 → 10.10.7

package/dist/constants/contextWindows.js

@@ -376,7 +376,16 @@ export const MODEL_CONTEXT_WINDOWS = {
  * `lm-studio` -> `lmstudio`, `nvidia-nim` -> `nvidianim`, `llama.cpp` -> `llamacpp`.
  */
 const PROVIDER_ALIAS_MAP = {
-    googleaistudio: "google-ai-studio",
+    // Both spellings resolve to `google-ai`, the ONLY key this table holds for
+    // AI Studio. `google-ai-studio` was never a key, so every realistic spelling
+    // ("googleAiStudio" from the native client, "google-ai-studio", "googleai")
+    // missed the table and fell back to DEFAULT_CONTEXT_WINDOW — reporting
+    // 128K for a 1,048,576-token Gemini. That understated the loop-guard budget
+    // by ~8x, so AI Studio agent loops reclaimed tool history that still fitted
+    // comfortably. `google-ai` itself only resolved via the raw-provider
+    // fallback below, which the normalized lookup now covers directly.
+    googleaistudio: "google-ai",
+    googleai: "google-ai",
     lmstudio: "lm-studio",
     llamacpp: "llamacpp",
     nvidianim: "nvidia-nim",

package/dist/context/anthropicLoopGuard.d.ts

@@ -43,4 +43,5 @@ export declare function planAnthropicLoopReclaim(args: {
     observedPromptTokens?: number;
     previousSentEstimate?: number;
     onSentEstimate?: (tokens: number) => void;
+    observedDescribesCurrentPayload?: boolean;
 }): LoopGuardPlan | undefined;

package/dist/context/anthropicLoopGuard.js

@@ -125,25 +125,43 @@ export function isAnthropicToolResultMessage(message) {
  * `cache_control` prefix this path depends on.
  */
 export function planAnthropicLoopReclaim(args) {
-    const { conversation, availableInputTokens, fixedOverheadTokens, provider, observedPromptTokens, previousSentEstimate, onSentEstimate, } = args;
+    const { conversation, availableInputTokens, fixedOverheadTokens, provider, observedPromptTokens, previousSentEstimate, onSentEstimate, observedDescribesCurrentPayload = false, } = args;
     const entries = toEntries(conversation, provider);
     const rawEstimate = fixedOverheadTokens + entries.reduce((sum, e) => sum + e.tokens, 0);
-    // Calibration compares a real prompt-token count against THIS guard's
-    // estimate for the very request that produced it. Dividing by the estimate
-    // for the CURRENT conversation would be a category error: the loop has since
-    // appended an assistant tool_use message plus its tool_result, so the
-    // denominator is always larger than the numerator's request. The ratio then
-    // reads below 1 and the `Math.max(1, …)` floor pins calibration at 1 — the
-    // correction silently never applies, which is exactly when a dense-code run
-    // overflows the window.
+    // Calibration divides a real prompt-token count by THIS guard's estimate for
+    // the payload that count describes. Both halves must describe the SAME
+    // payload, and there are two legitimate pairings:
+    //
+    //  - A caller that plans on EVERY step passes the provider's count for the
+    //    previous request together with `previousSentEstimate`, the estimate
+    //    recorded for that same request. Dividing that count by the estimate for
+    //    the CURRENT conversation would be a category error — the loop has since
+    //    appended an assistant tool_use message plus its tool_result, so the
+    //    denominator is always the larger of the two, the ratio reads below 1 and
+    //    the `Math.max(1, …)` floor pins calibration at 1. The correction then
+    //    silently never applies, which is exactly when a dense-code run overflows.
+    //
+    //  - A caller that plans only when a real-token guard trips has no estimate
+    //    for an earlier request, but its trigger (`projectedNextPromptTokens`) is
+    //    already a projection of the payload ABOUT TO BE SENT. It sets
+    //    `observedDescribesCurrentPayload`, and the denominator is this module's
+    //    estimate of the current history — the same payload again.
+    //
+    // Without the flag such a caller gets calibration 1, which makes its reclaim
+    // inert: the guard trips on real tokens at the same ratio this planner tests
+    // its (smaller) char estimate against, so the plan never fires and the loop
+    // falls back to stopping the turn.
+    const sentEstimate = observedDescribesCurrentPayload
+        ? rawEstimate
+        : previousSentEstimate;
     let calibration = 1;
     if (observedPromptTokens &&
         observedPromptTokens > 0 &&
-        previousSentEstimate &&
-        previousSentEstimate > 0) {
+        sentEstimate &&
+        sentEstimate > 0) {
         // Clamped: real tokenizers run up to ~1.3x the char estimate on dense
         // code, and an unbounded ratio would compact the loop into uselessness.
-        calibration = Math.min(3, Math.max(1, observedPromptTokens / previousSentEstimate));
+        calibration = Math.min(3, Math.max(1, observedPromptTokens / sentEstimate));
     }
     const plan = planLoopGuardReclaim(entries, {
         availableInputTokens,

package/dist/context/contextCompactor.js

@@ -200,6 +200,25 @@ export class ContextCompactor {
                     stagesUsed,
                     durationMs: Date.now() - spanStartTime,
                 });
+                // A compaction that was ASKED to reclaim and reclaimed nothing is the
+                // signature of a mis-aimed target: the caller decided the request was
+                // over budget, but every stage gate compared against a number that
+                // said otherwise, so the pipeline no-opped and the request went out
+                // oversized anyway. That is exactly how the history-budget defect hid
+                // in production — silently, because "Complete" looked healthy. Warn
+                // loudly and stamp the span so it is greppable and alertable.
+                const reclaimedNothing = stagesUsed.length === 0;
+                if (reclaimedNothing) {
+                    logger.warn("[Compaction] No-op — invoked but reclaimed nothing", {
+                        requestId,
+                        tokensBefore,
+                        targetTokens,
+                        messageCount: currentMessages.length,
+                    });
+                }
+                span = SpanSerializer.updateAttributes(span, {
+                    "context.noop": reclaimedNothing,
+                });
                 const result = {
                     compacted: stagesUsed.length > 0,
                     stagesUsed,

package/dist/context/geminiLoopGuard.d.ts

@@ -0,0 +1,54 @@
+/**
+ * In-turn context guard for Gemini-shaped agent loops (native Vertex + AI
+ * Studio + Gemini 3).
+ *
+ * These loops already had `createContextGuard`, but it is **stop-only**: once
+ * the projected prompt crosses the threshold it breaks the loop and synthesizes
+ * an answer from whatever it has. That avoids a provider rejection, but it also
+ * ends the turn early — the model stops doing work it was mid-way through.
+ *
+ * This module brings them to parity with the other loops: reclaim budget and
+ * CONTINUE, falling back to the existing stop only when reclaiming cannot get
+ * back under the line. The reclaim policy is shared with every other provider
+ * via `loopGuardCore`; this module owns only the Gemini shape mapping.
+ *
+ * Gemini history is `{ role, parts[] }`, where a part is a `functionCall`
+ * (tool invocation) or `functionResponse` (its result). One model turn can
+ * carry several `functionCall` parts and the following user turn carries the
+ * matching `functionResponse` parts, so the CONTENT is the batch unit —
+ * dropping a call turn together with its response turn can never orphan a part,
+ * which Gemini rejects.
+ */
+import type { GeminiGuardContent, LoopGuardPlan } from "../types/index.js";
+/** Marker left where dropped history used to be. */
+export declare const GEMINI_ELISION_NOTE = "[Earlier tool exchanges were removed to fit the context window.]";
+/** True when this content carries tool results worth previewing. */
+export declare function isGeminiToolResponseContent(content: GeminiGuardContent): boolean;
+/** Head/tail preview for an oversized tool response payload. */
+export declare function previewGeminiToolResponseText(text: string): string;
+/**
+ * Decide what to reclaim from a Gemini agent loop.
+ *
+ * Returns `undefined` when the history still fits, in which case the caller
+ * must leave it byte-identical — any rewrite invalidates the provider's cached
+ * prefix, so "no change" has to mean no change.
+ *
+ * `observedPromptTokens` must be a count for the payload ABOUT TO BE SENT —
+ * every Gemini-shaped loop plans only when its `createContextGuard` trips, and
+ * that guard's `projectedNextPromptTokens` is exactly that: the provider's real
+ * count for the last request plus the growth measured since. Dividing it by
+ * this module's estimate of the current history therefore compares two views of
+ * one payload, which is what makes the correction meaningful. A count for an
+ * EARLIER request must not be passed here: the loop has appended a model turn
+ * and its tool turn since, so the denominator would always be the larger of the
+ * two, the ratio would read below 1 and the `Math.max(1, …)` floor would pin
+ * calibration at 1 — silently disabling the correction. `planAnthropicLoopReclaim`
+ * carries `previousSentEstimate` for callers in that other position.
+ */
+export declare function planGeminiLoopReclaim(args: {
+    contents: readonly GeminiGuardContent[];
+    availableInputTokens: number;
+    fixedOverheadTokens?: number;
+    provider?: string;
+    observedPromptTokens?: number;
+}): LoopGuardPlan | undefined;

package/dist/context/geminiLoopGuard.js

@@ -0,0 +1,140 @@
+/**
+ * In-turn context guard for Gemini-shaped agent loops (native Vertex + AI
+ * Studio + Gemini 3).
+ *
+ * These loops already had `createContextGuard`, but it is **stop-only**: once
+ * the projected prompt crosses the threshold it breaks the loop and synthesizes
+ * an answer from whatever it has. That avoids a provider rejection, but it also
+ * ends the turn early — the model stops doing work it was mid-way through.
+ *
+ * This module brings them to parity with the other loops: reclaim budget and
+ * CONTINUE, falling back to the existing stop only when reclaiming cannot get
+ * back under the line. The reclaim policy is shared with every other provider
+ * via `loopGuardCore`; this module owns only the Gemini shape mapping.
+ *
+ * Gemini history is `{ role, parts[] }`, where a part is a `functionCall`
+ * (tool invocation) or `functionResponse` (its result). One model turn can
+ * carry several `functionCall` parts and the following user turn carries the
+ * matching `functionResponse` parts, so the CONTENT is the batch unit —
+ * dropping a call turn together with its response turn can never orphan a part,
+ * which Gemini rejects.
+ */
+import { estimateTokens, TOKENS_PER_MESSAGE, } from "../utils/tokenEstimation.js";
+import { generateToolOutputPreview } from "./toolOutputLimits.js";
+import { planLoopGuardReclaim } from "./loopGuardCore.js";
+import { logger } from "../utils/logger.js";
+/** Preview budget for an old tool output. Matches the other loop guards. */
+const OLD_TOOL_OUTPUT_PREVIEW_BYTES = 2_048;
+const OLD_TOOL_OUTPUT_PREVIEW_LINES = 60;
+/** Marker left where dropped history used to be. */
+export const GEMINI_ELISION_NOTE = "[Earlier tool exchanges were removed to fit the context window.]";
+/** Serialize any value for estimation. Never throws. */
+function toText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value === null || value === undefined) {
+        return "";
+    }
+    try {
+        return JSON.stringify(value) ?? "";
+    }
+    catch {
+        // Past V8's string cap: enormous by definition, so charge a large fixed
+        // size rather than aborting the estimate and with it the turn.
+        return "x".repeat(200_000);
+    }
+}
+function hasPart(content, key) {
+    return (Array.isArray(content.parts) &&
+        content.parts.some((part) => part && typeof part === "object" && key in part));
+}
+/** True when this content carries tool results worth previewing. */
+export function isGeminiToolResponseContent(content) {
+    return hasPart(content, "functionResponse");
+}
+/** Head/tail preview for an oversized tool response payload. */
+export function previewGeminiToolResponseText(text) {
+    const { preview } = generateToolOutputPreview(text, {
+        maxBytes: OLD_TOOL_OUTPUT_PREVIEW_BYTES,
+        maxLines: OLD_TOOL_OUTPUT_PREVIEW_LINES,
+    });
+    return preview;
+}
+function contentTokens(content, provider) {
+    return estimateTokens(toText(content.parts), provider) + TOKENS_PER_MESSAGE;
+}
+/** Map Gemini history onto the neutral view the shared policy operates on. */
+function toEntries(contents, provider) {
+    return contents.map((content) => {
+        const tokens = contentTokens(content, provider);
+        if (isGeminiToolResponseContent(content)) {
+            // Only advertise a preview when it actually saves something: an
+            // already-small response must fall through to stage 2 rather than look
+            // shrinkable and stall the reclaim.
+            const previewed = toText(content.parts);
+            const previewTokens = previewed.length > OLD_TOOL_OUTPUT_PREVIEW_BYTES
+                ? estimateTokens(previewGeminiToolResponseText(previewed), provider) +
+                    TOKENS_PER_MESSAGE
+                : tokens;
+            return {
+                kind: "toolResult",
+                tokens,
+                ...(previewTokens < tokens ? { previewTokens } : {}),
+            };
+        }
+        if (hasPart(content, "functionCall")) {
+            return { kind: "toolCall", tokens };
+        }
+        return { kind: "other", tokens };
+    });
+}
+/**
+ * Decide what to reclaim from a Gemini agent loop.
+ *
+ * Returns `undefined` when the history still fits, in which case the caller
+ * must leave it byte-identical — any rewrite invalidates the provider's cached
+ * prefix, so "no change" has to mean no change.
+ *
+ * `observedPromptTokens` must be a count for the payload ABOUT TO BE SENT —
+ * every Gemini-shaped loop plans only when its `createContextGuard` trips, and
+ * that guard's `projectedNextPromptTokens` is exactly that: the provider's real
+ * count for the last request plus the growth measured since. Dividing it by
+ * this module's estimate of the current history therefore compares two views of
+ * one payload, which is what makes the correction meaningful. A count for an
+ * EARLIER request must not be passed here: the loop has appended a model turn
+ * and its tool turn since, so the denominator would always be the larger of the
+ * two, the ratio would read below 1 and the `Math.max(1, …)` floor would pin
+ * calibration at 1 — silently disabling the correction. `planAnthropicLoopReclaim`
+ * carries `previousSentEstimate` for callers in that other position.
+ */
+export function planGeminiLoopReclaim(args) {
+    const { contents, availableInputTokens, fixedOverheadTokens = 0, provider, observedPromptTokens, } = args;
+    const entries = toEntries(contents, provider);
+    let calibration = 1;
+    if (observedPromptTokens && observedPromptTokens > 0) {
+        const rawEstimate = fixedOverheadTokens + entries.reduce((sum, e) => sum + e.tokens, 0);
+        if (rawEstimate > 0) {
+            // Clamped: real tokenizers run up to ~1.3x the char estimate on dense
+            // code, and an unbounded ratio would compact the loop into uselessness.
+            calibration = Math.min(3, Math.max(1, observedPromptTokens / rawEstimate));
+        }
+    }
+    const plan = planLoopGuardReclaim(entries, {
+        availableInputTokens,
+        fixedOverheadTokens,
+        calibration,
+    });
+    if (!plan.fire) {
+        return undefined;
+    }
+    logger.info("[GeminiLoopGuard] Reclaiming agent-loop context", {
+        provider,
+        contents: contents.length,
+        toolResponsesTruncated: plan.truncate.length,
+        contentsDropped: plan.drop.length,
+        projectedTokens: plan.projectedTokens,
+        calibration,
+    });
+    return plan;
+}

package/dist/core/redisConversationMemoryManager.d.ts

@@ -93,6 +93,33 @@ export declare class RedisConversationMemoryManager implements IConversationMemo
      * Check if summarization is needed based on token count
      */
     private checkAndSummarize;
+    /**
+     * True only for keys holding a conversation BLOB — the sole key type these
+     * scan-then-GET paths may read.
+     *
+     * `${keyPrefix}*` also matches the companion message LISTs and, when a
+     * custom key prefix does not end in `conversation:`, the user-index SETs
+     * (whose derived prefix then collapses onto `keyPrefix`). `GET` against
+     * either raises WRONGTYPE, and counting them would inflate session totals.
+     */
+    private isConversationBlobKey;
+    /**
+     * Hydrate a deserialized blob's messages from the companion LIST when the
+     * session uses split storage. Legacy blobs (messages inline) pass through
+     * untouched — that is what makes the migration backward compatible.
+     */
+    private hydrateMessages;
+    /** Message count without materializing them — LLEN for split sessions. */
+    private countMessages;
+    /** Load a session, messages included, regardless of storage format. */
+    private loadConversation;
+    /**
+     * Persist a conversation, splitting messages into the companion LIST.
+     * `appendFrom` appends only messages from that index onward (the per-turn
+     * fast path); omit it to rewrite the LIST wholesale, which is also how a
+     * legacy blob gets converted.
+     */
+    private persistConversation;
     /**
      * Build context messages for AI prompt injection (TOKEN-BASED)
      * Returns messages from pointer onwards (or all if no pointer)

package/dist/core/redisConversationMemoryManager.js

@@ -15,7 +15,7 @@ import { withTimeout } from "../utils/errorHandling.js";
 import { buildContextFromPointer, getEffectiveTokenThreshold, } from "../utils/conversationMemory.js";
 import { runWithCurrentLangfuseContext } from "../services/server/ai/observability/instrumentation.js";
 import { logger } from "../utils/logger.js";
-import { deserializeConversation, getNormalizedConfig, getPooledRedisClient, getSessionKey, getUserSessionsKey, releasePooledRedisClient, scanKeys, serializeConversation, } from "../utils/redis.js";
+import { deserializeConversation, encodeStoredMessages, getSessionMessagesKey, MESSAGES_KEY_SUFFIX, isSessionMessagesKey, parseStoredMessages, serializeConversationMetadata, usesSplitMessageStorage, getNormalizedConfig, getPooledRedisClient, getSessionKey, getUserSessionsKey, releasePooledRedisClient, scanKeys, serializeConversation, } from "../utils/redis.js";
 const redisTracer = tracers.redis;
 const REDIS_TIMEOUT_MS = 5000;
 /**
@@ -140,7 +140,7 @@ export class RedisConversationMemoryManager {
             try {
                 const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
                 const conversationData = await withTimeout(redisClient.get(redisKey), REDIS_TIMEOUT_MS);
-                const conversation = deserializeConversation(conversationData || null);
+                const conversation = await this.hydrateMessages(deserializeConversation(conversationData || null), redisKey);
                 if (!conversation) {
                     span.setAttribute("session.found", false);
                     return undefined;
@@ -221,7 +221,7 @@ export class RedisConversationMemoryManager {
             }
             const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
             const conversationData = await this.redisClient.get(redisKey);
-            return deserializeConversation(conversationData || null);
+            return this.hydrateMessages(deserializeConversation(conversationData || null), redisKey);
         }
         catch (error) {
             logger.error("[RedisConversationMemoryManager] Failed to get raw session", {
@@ -391,7 +391,13 @@ export class RedisConversationMemoryManager {
                 }
                 const redisKey = getSessionKey(this.redisConfig, options.sessionId, options.userId);
                 const conversationData = await this.redisClient.get(redisKey);
-                let conversation = deserializeConversation(conversationData);
+                let conversation = await this.hydrateMessages(deserializeConversation(conversationData), redisKey);
+                // Split-storage bookkeeping: whether this session already keeps its
+                // messages in the companion LIST, and how many it held before this
+                // turn — so only the new ones are appended rather than rewriting the
+                // whole conversation on every turn.
+                const wasSplitStorage = usesSplitMessageStorage(conversation);
+                const messageCountBeforeTurn = conversation?.messages.length ?? 0;
                 const currentTime = new Date().toISOString();
                 const normalizedUserId = options.userId || "randomUser";
                 if (!conversation) {
@@ -486,6 +492,16 @@ export class RedisConversationMemoryManager {
                 const shouldSummarize = options.enableSummarization !== undefined
                     ? options.enableSummarization
                     : this.config.enableSummarization;
+                // Append-only: push just this turn's messages and persist a SMALL
+                // metadata blob. A session not yet using split storage (new, or a
+                // legacy blob) is converted once here, then every later turn appends.
+                await this.persistConversation(conversation, options.sessionId, options.userId, wasSplitStorage ? messageCountBeforeTurn : undefined);
+                // Scheduled AFTER the write, never before it. On the single turn that
+                // converts a legacy session, `checkAndSummarize` re-reads the blob and
+                // writes it back; observing the pre-conversion blob would make it
+                // re-serialize the record WITHOUT the split marker, so a later SET
+                // would strip the marker while the companion LIST already held the
+                // messages — the next read would then serve the stale inline copy.
                 if (shouldSummarize) {
                     const normalizedUserId = options.userId || "randomUser";
                     const summarizationKey = `${options.sessionId}:${normalizedUserId}`;
@@ -514,10 +530,8 @@ export class RedisConversationMemoryManager {
                         });
                     }
                 }
-                const serializedData = serializeConversation(conversation);
-                await this.redisClient.set(redisKey, serializedData);
                 // Log turn storage metadata for observability
-                const blobSizeBytes = Buffer.byteLength(serializedData, "utf8");
+                const blobSizeBytes = Buffer.byteLength(serializeConversationMetadata(conversation), "utf8");
                 logger.info("[ConversationMemory] Turn stored", {
                     requestId: options.requestId,
                     sessionId: options.sessionId,
@@ -611,7 +625,14 @@ export class RedisConversationMemoryManager {
                                 conversation.summarizedMessage;
                             latestConversation.lastTokenCount = conversation.lastTokenCount;
                             latestConversation.lastCountedAt = conversation.lastCountedAt;
-                            const freshSerialized = serializeConversation(latestConversation);
+                            // Only summarization metadata changed, so the companion LIST is
+                            // left alone. Critical: this re-read was NOT hydrated, so for a
+                            // split session `messages` is empty — writing it with
+                            // serializeConversation would drop the marker and make the record
+                            // look like a legacy blob with zero messages (silent data loss).
+                            const freshSerialized = usesSplitMessageStorage(latestConversation)
+                                ? serializeConversationMetadata(latestConversation)
+                                : serializeConversation(latestConversation);
                             await this.redisClient.set(redisKey, freshSerialized);
                             if (this.redisConfig.ttl > 0) {
                                 await this.redisClient.expire(redisKey, this.redisConfig.ttl);
@@ -631,6 +652,95 @@ export class RedisConversationMemoryManager {
             this.summarizationInProgress.delete(summarizationKey);
         }
     }
+    /**
+     * True only for keys holding a conversation BLOB — the sole key type these
+     * scan-then-GET paths may read.
+     *
+     * `${keyPrefix}*` also matches the companion message LISTs and, when a
+     * custom key prefix does not end in `conversation:`, the user-index SETs
+     * (whose derived prefix then collapses onto `keyPrefix`). `GET` against
+     * either raises WRONGTYPE, and counting them would inflate session totals.
+     */
+    isConversationBlobKey(key) {
+        return (!isSessionMessagesKey(key) &&
+            !key.endsWith(":sessions") &&
+            !key.startsWith(this.redisConfig.userSessionsKeyPrefix));
+    }
+    /**
+     * Hydrate a deserialized blob's messages from the companion LIST when the
+     * session uses split storage. Legacy blobs (messages inline) pass through
+     * untouched — that is what makes the migration backward compatible.
+     */
+    async hydrateMessages(conversation, redisKey) {
+        if (!conversation || !usesSplitMessageStorage(conversation)) {
+            return conversation;
+        }
+        if (!this.redisClient) {
+            return conversation;
+        }
+        // `getSession` and `buildContextMessages` guard their own GET with
+        // `withTimeout`; both now also depend on this read, so leaving it unguarded
+        // would let a hung LIST read block the request thread anyway.
+        const entries = await withTimeout(this.redisClient.lRange(`${redisKey}${MESSAGES_KEY_SUFFIX}`, 0, -1), REDIS_TIMEOUT_MS);
+        // `lRange` is typed `(string | Buffer)[]` — the client returns Buffers when
+        // a connection is opened in binary mode. Normalize rather than assert, so
+        // a binary-mode client reads its history instead of throwing on parse.
+        conversation.messages = parseStoredMessages(entries.map((entry) => entry.toString()));
+        return conversation;
+    }
+    /** Message count without materializing them — LLEN for split sessions. */
+    async countMessages(conversation, redisKey) {
+        if (!usesSplitMessageStorage(conversation) || !this.redisClient) {
+            return conversation.messages.length;
+        }
+        // `lLen` is typed `number | \`${number}\`` (RESP3 can deliver it as a
+        // string), and callers add it to numbers — coerce so the count never
+        // concatenates instead of summing.
+        return Number(await withTimeout(this.redisClient.lLen(`${redisKey}${MESSAGES_KEY_SUFFIX}`), REDIS_TIMEOUT_MS));
+    }
+    /** Load a session, messages included, regardless of storage format. */
+    async loadConversation(sessionId, userId) {
+        if (!this.redisClient) {
+            return null;
+        }
+        const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+        return this.hydrateMessages(deserializeConversation(await this.redisClient.get(redisKey)), redisKey);
+    }
+    /**
+     * Persist a conversation, splitting messages into the companion LIST.
+     * `appendFrom` appends only messages from that index onward (the per-turn
+     * fast path); omit it to rewrite the LIST wholesale, which is also how a
+     * legacy blob gets converted.
+     */
+    async persistConversation(conversation, sessionId, userId, appendFrom) {
+        if (!this.redisClient) {
+            return;
+        }
+        const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+        const messagesKey = getSessionMessagesKey(this.redisConfig, sessionId, userId);
+        // One MULTI, not four to six independent commands. The replace path is a
+        // DEL followed by an RPUSH, and on the legacy-conversion path the inline
+        // blob is the only copy of the history until the SET lands — so a failure
+        // between any two of them leaves the session either empty or unrecoverable.
+        // Grouping them also collapses the round trips, which is the point of the
+        // append-only layout.
+        const tx = this.redisClient.multi();
+        if (appendFrom === undefined) {
+            tx.del(messagesKey);
+        }
+        const toPush = appendFrom === undefined
+            ? conversation.messages
+            : conversation.messages.slice(appendFrom);
+        if (toPush.length > 0) {
+            tx.rPush(messagesKey, encodeStoredMessages(toPush));
+        }
+        tx.set(redisKey, serializeConversationMetadata(conversation));
+        if (this.redisConfig.ttl > 0) {
+            tx.expire(redisKey, this.redisConfig.ttl);
+            tx.expire(messagesKey, this.redisConfig.ttl);
+        }
+        await withTimeout(tx.exec(), REDIS_TIMEOUT_MS);
+    }
     /**
      * Build context messages for AI prompt injection (TOKEN-BASED)
      * Returns messages from pointer onwards (or all if no pointer)
@@ -664,7 +774,7 @@ export class RedisConversationMemoryManager {
                 });
                 const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
                 const conversationData = await withTimeout(redisClient.get(redisKey), REDIS_TIMEOUT_MS);
-                const conversation = deserializeConversation(conversationData || null);
+                const conversation = await this.hydrateMessages(deserializeConversation(conversationData || null), redisKey);
                 logger.debug("[RedisConversationMemoryManager] Retrieved conversation for context building", {
                     sessionId,
                     userId,
@@ -895,7 +1005,7 @@ export class RedisConversationMemoryManager {
                 return null;
             }
             // Deserialize the complete conversation object
-            const conversation = deserializeConversation(conversationData);
+            const conversation = await this.hydrateMessages(deserializeConversation(conversationData), sessionKey);
             if (!conversation) {
                 logger.debug("[RedisConversationMemoryManager] Failed to deserialize conversation data", {
                     userId,
@@ -1014,7 +1124,7 @@ User message: "${userMessage}"`;
         try {
             const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
             const conversationData = await this.redisClient.get(redisKey);
-            const conversation = deserializeConversation(conversationData || null);
+            const conversation = await this.hydrateMessages(deserializeConversation(conversationData || null), redisKey);
             return conversation?.messages ?? [];
         }
         catch (error) {
@@ -1050,11 +1160,8 @@ User message: "${userMessage}"`;
             conversation.summarizedMessage = undefined;
             conversation.lastTokenCount = undefined;
             conversation.lastCountedAt = undefined;
-            const serializedData = serializeConversation(conversation);
-            await this.redisClient.set(redisKey, serializedData);
-            if (this.redisConfig.ttl > 0) {
-                await this.redisClient.expire(redisKey, this.redisConfig.ttl);
-            }
+            // Wholesale replacement: rewrite the LIST rather than appending.
+            await this.persistConversation(conversation, sessionId, userId);
             logger.debug("[RedisConversationMemoryManager] Session messages replaced", {
                 sessionId,
                 userId,
@@ -1097,11 +1204,16 @@ User message: "${userMessage}"`;
             pattern,
             keyCount: keys.length,
         });
+        // Companion message LISTs share the session key prefix, so the SCAN above
+        // returns them too. GET on a LIST raises WRONGTYPE, and counting them as
+        // sessions would double `totalSessions` — filter them out exactly as the
+        // session listing already skips `:sessions` index keys.
+        const sessionKeys = keys.filter((key) => this.isConversationBlobKey(key));
         // Count messages in each session
         let totalTurns = 0;
-        for (const key of keys) {
+        for (const key of sessionKeys) {
             const conversationData = await this.redisClient.get(key);
-            const conversation = deserializeConversation(conversationData);
+            const conversation = await this.hydrateMessages(deserializeConversation(conversationData), key);
             if (conversation?.messages) {
                 // Pinned skill messages are extra rows inside a turn — exclude them
                 // so a skill-activating turn still counts as one turn.
@@ -1110,7 +1222,7 @@ User message: "${userMessage}"`;
             }
         }
         return {
-            totalSessions: keys.length,
+            totalSessions: sessionKeys.length,
             totalTurns,
         };
     }
@@ -1133,7 +1245,9 @@ User message: "${userMessage}"`;
         }, async (span) => {
             try {
                 const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
-                const result = await withTimeout(redisClient.del(redisKey), REDIS_TIMEOUT_MS);
+                // Delete the companion message LIST as well: leaving it behind would
+                // leak the messages and let a re-created session inherit them.
+                const result = await withTimeout(redisClient.del([redisKey, `${redisKey}${MESSAGES_KEY_SUFFIX}`]), REDIS_TIMEOUT_MS);
                 if (Number(result) > 0) {
                     // Remove session from user's session set
                     if (userId) {
@@ -1307,8 +1421,9 @@ User message: "${userMessage}"`;
             // List all sessions across all users by scanning Redis keys
             const keys = await scanKeys(this.redisClient, `${this.redisConfig.keyPrefix}*`);
             for (const key of keys) {
-                // Skip user session index keys (they end with :sessions)
-                if (key.endsWith(":sessions")) {
+                // Skip user session index keys (they end with :sessions) and the
+                // companion message LISTs — GET on a LIST raises WRONGTYPE.
+                if (!this.isConversationBlobKey(key)) {
                     continue;
                 }
                 const raw = await this.redisClient.get(key);
@@ -1325,7 +1440,9 @@ User message: "${userMessage}"`;
                     createdAt: session.createdAt,
                     updatedAt: session.updatedAt,
                     userId: session.userId,
-                    messageCount: session.messages.length,
+                    // LLEN for split sessions: the blob's inline array is empty here
+                    // because this branch reads the raw key without hydrating.
+                    messageCount: await this.countMessages(session, key),
                     lastActive: this.formatTimeAgo(now - new Date(session.updatedAt).getTime()),
                 });
             }
@@ -1571,8 +1688,12 @@ User message: "${userMessage}"`;
                 logger.debug("[RedisConversationMemoryManager] Added new agentic loop report", { sessionId, reportId: report.reportId });
             }
             conversation.updatedAt = new Date().toISOString();
-            // Write back to Redis
-            const serializedData = serializeConversation(conversation);
+            // Write back to Redis. Metadata-only change, so the companion LIST is
+            // untouched — but the split marker must survive (see the summarization
+            // writeback above for why dropping it loses messages).
+            const serializedData = usesSplitMessageStorage(conversation)
+                ? serializeConversationMetadata(conversation)
+                : serializeConversation(conversation);
             await withTimeout(this.redisClient.set(redisKey, serializedData), 5000);
             if (this.redisConfig.ttl > 0) {
                 await withTimeout(this.redisClient.expire(redisKey, this.redisConfig.ttl), 5000);