@juspay/neurolink 9.14.0 → 9.16.0

package/dist/lib/core/redisConversationMemoryManager.js

@@ -2,6 +2,8 @@
  * Redis Conversation Memory Manager for NeuroLink
  * Redis-based implementation of conversation storage with same interface as ConversationMemoryManager
  */
+import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { tracers } from "../telemetry/tracers.js";
 import { randomUUID } from "crypto";
 import { MESSAGES_PER_TURN } from "../config/conversationMemory.js";
 import { generateToolOutputPreview } from "../context/toolOutputLimits.js";
@@ -9,8 +11,10 @@ import { SummarizationEngine } from "../context/summarizationEngine.js";
 import { NeuroLink } from "../neurolink.js";
 import { ConversationMemoryError } from "../types/conversation.js";
 import { buildContextFromPointer, getEffectiveTokenThreshold, } from "../utils/conversationMemory.js";
+import { runWithCurrentLangfuseContext } from "../services/server/ai/observability/instrumentation.js";
 import { logger } from "../utils/logger.js";
 import { createRedisClient, deserializeConversation, getNormalizedConfig, getPooledRedisClient, getSessionKey, getUserSessionsKey, releasePooledRedisClient, scanKeys, serializeConversation, } from "../utils/redis.js";
+const redisTracer = tracers.redis;
 /**
  * Redis-based implementation of the ConversationMemoryManager
  * Uses the same interface but stores data in Redis
@@ -48,40 +52,57 @@ export class RedisConversationMemoryManager {
             logger.debug("[RedisConversationMemoryManager] Already initialized, skipping");
             return;
         }
-        try {
-            logger.debug("[RedisConversationMemoryManager] Initializing with config", {
-                host: this.redisConfig.host,
-                port: this.redisConfig.port,
-                keyPrefix: this.redisConfig.keyPrefix,
-                ttl: this.redisConfig.ttl,
-            });
-            this.redisClient = await getPooledRedisClient(this.redisConfig);
-            this.isInitialized = true;
-            logger.info("RedisConversationMemoryManager initialized", {
-                storage: "redis",
-                host: this.redisConfig.host,
-                port: this.redisConfig.port,
-                maxSessions: this.config.maxSessions,
-                maxTurnsPerSession: this.config.maxTurnsPerSession,
-            });
-            logger.debug("[RedisConversationMemoryManager] Redis client created successfully", {
-                clientType: this.redisClient?.constructor?.name || "unknown",
-                isConnected: !!this.redisClient,
-            });
-        }
-        catch (error) {
-            logger.error("[RedisConversationMemoryManager] Failed to initialize", {
-                error: error instanceof Error ? error.message : String(error),
-                stack: error instanceof Error ? error.stack : undefined,
-                config: {
+        await redisTracer.startActiveSpan("neurolink.memory.initialize", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "redis.host": this.redisConfig.host,
+                "redis.port": this.redisConfig.port,
+                "redis.key_prefix": this.redisConfig.keyPrefix,
+            },
+        }, async (span) => {
+            try {
+                logger.debug("[RedisConversationMemoryManager] Initializing with config", {
                     host: this.redisConfig.host,
                     port: this.redisConfig.port,
-                },
-            });
-            throw new ConversationMemoryError("Failed to initialize Redis conversation memory", "CONFIG_ERROR", {
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
+                    keyPrefix: this.redisConfig.keyPrefix,
+                    ttl: this.redisConfig.ttl,
+                });
+                this.redisClient = await getPooledRedisClient(this.redisConfig);
+                this.isInitialized = true;
+                logger.info("RedisConversationMemoryManager initialized", {
+                    storage: "redis",
+                    host: this.redisConfig.host,
+                    port: this.redisConfig.port,
+                    maxSessions: this.config.maxSessions,
+                    maxTurnsPerSession: this.config.maxTurnsPerSession,
+                });
+                logger.debug("[RedisConversationMemoryManager] Redis client created successfully", {
+                    clientType: this.redisClient?.constructor?.name || "unknown",
+                    isConnected: !!this.redisClient,
+                });
+            }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                logger.error("[RedisConversationMemoryManager] Failed to initialize", {
+                    error: error instanceof Error ? error.message : String(error),
+                    stack: error instanceof Error ? error.stack : undefined,
+                    config: {
+                        host: this.redisConfig.host,
+                        port: this.redisConfig.port,
+                    },
+                });
+                throw new ConversationMemoryError("Failed to initialize Redis conversation memory", "CONFIG_ERROR", {
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+            finally {
+                span.end();
+            }
+        });
     }
     /** Whether this memory manager can persist data (Redis connected and initialized) */
     get canPersist() {
@@ -108,63 +129,80 @@ export class RedisConversationMemoryManager {
         if (!this.redisClient) {
             return undefined;
         }
-        try {
-            const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
-            const conversationData = await this.redisClient.get(redisKey);
-            const conversation = deserializeConversation(conversationData || null);
-            if (!conversation) {
-                return undefined;
+        return redisTracer.startActiveSpan("neurolink.memory.getSession", { kind: SpanKind.CLIENT, attributes: { "session.id": sessionId } }, async (span) => {
+            if (userId) {
+                span.setAttribute("user.id", userId);
             }
-            // Log session load metadata for observability
-            const blobSizeBytes = conversationData
-                ? Buffer.byteLength(conversationData, "utf8")
-                : 0;
-            const messageCount = conversation.messages.length;
-            const hasSummary = !!conversation.summarizedUpToMessageId;
-            const pointerIndex = hasSummary
-                ? conversation.messages.findIndex((msg) => msg.id === conversation.summarizedUpToMessageId)
-                : -1;
-            const recentMessageCount = hasSummary && pointerIndex !== -1
-                ? messageCount - pointerIndex - 1
-                : messageCount;
-            logger.info("[ConversationMemory] Session loaded", {
-                requestId,
-                sessionId,
-                blobSizeBytes,
-                messageCount,
-                hasSummary,
-                recentMessageCount,
-            });
-            if (blobSizeBytes > 512 * 1024) {
-                logger.warn("[ConversationMemory] Large session blob", {
+            try {
+                const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+                const conversationData = await this.redisClient.get(redisKey);
+                const conversation = deserializeConversation(conversationData || null);
+                if (!conversation) {
+                    span.setAttribute("session.found", false);
+                    return undefined;
+                }
+                span.setAttribute("session.found", true);
+                // Log session load metadata for observability
+                const blobSizeBytes = conversationData
+                    ? Buffer.byteLength(conversationData, "utf8")
+                    : 0;
+                const messageCount = conversation.messages.length;
+                const hasSummary = !!conversation.summarizedUpToMessageId;
+                const pointerIndex = hasSummary
+                    ? conversation.messages.findIndex((msg) => msg.id === conversation.summarizedUpToMessageId)
+                    : -1;
+                const recentMessageCount = hasSummary && pointerIndex !== -1
+                    ? messageCount - pointerIndex - 1
+                    : messageCount;
+                span.setAttribute("message.count", messageCount);
+                span.setAttribute("blob.size_bytes", blobSizeBytes);
+                logger.info("[ConversationMemory] Session loaded", {
                     requestId,
                     sessionId,
                     blobSizeBytes,
                     messageCount,
+                    hasSummary,
+                    recentMessageCount,
                 });
+                if (blobSizeBytes > 512 * 1024) {
+                    logger.warn("[ConversationMemory] Large session blob", {
+                        requestId,
+                        sessionId,
+                        blobSizeBytes,
+                        messageCount,
+                    });
+                }
+                return {
+                    sessionId: conversation.sessionId,
+                    userId: conversation.userId,
+                    messages: conversation.messages,
+                    summarizedUpToMessageId: conversation.summarizedUpToMessageId,
+                    summarizedMessage: conversation.summarizedMessage,
+                    tokenThreshold: conversation.tokenThreshold,
+                    lastTokenCount: conversation.lastTokenCount,
+                    lastCountedAt: conversation.lastCountedAt,
+                    lastApiTokenCount: conversation.lastApiTokenCount,
+                    createdAt: new Date(conversation.createdAt).getTime(),
+                    lastActivity: new Date(conversation.updatedAt).getTime(),
+                };
             }
-            return {
-                sessionId: conversation.sessionId,
-                userId: conversation.userId,
-                messages: conversation.messages,
-                summarizedUpToMessageId: conversation.summarizedUpToMessageId,
-                summarizedMessage: conversation.summarizedMessage,
-                tokenThreshold: conversation.tokenThreshold,
-                lastTokenCount: conversation.lastTokenCount,
-                lastCountedAt: conversation.lastCountedAt,
-                lastApiTokenCount: conversation.lastApiTokenCount,
-                createdAt: new Date(conversation.createdAt).getTime(),
-                lastActivity: new Date(conversation.updatedAt).getTime(),
-            };
-        }
-        catch (error) {
-            logger.error("[RedisConversationMemoryManager] Failed to get session", {
-                sessionId,
-                userId,
-                error: error instanceof Error ? error.message : String(error),
-            });
-            return undefined;
-        }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                logger.error("[RedisConversationMemoryManager] Failed to get session", {
+                    sessionId,
+                    userId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return undefined;
+            }
+            finally {
+                span.end();
+            }
+        });
     }
     /**
      * Get raw session data without any filtering or transformation.
@@ -335,156 +373,183 @@ export class RedisConversationMemoryManager {
             userId: options.userId,
         });
         await this.ensureInitialized();
-        try {
-            if (!this.redisClient) {
-                throw new Error("Redis client not initialized");
-            }
-            const redisKey = getSessionKey(this.redisConfig, options.sessionId, options.userId);
-            const conversationData = await this.redisClient.get(redisKey);
-            let conversation = deserializeConversation(conversationData);
-            const currentTime = new Date().toISOString();
-            const normalizedUserId = options.userId || "randomUser";
-            if (!conversation) {
-                const titleGenerationKey = `${options.sessionId}:${normalizedUserId}`;
-                setImmediate(async () => {
-                    if (this.titleGenerationInProgress.has(titleGenerationKey)) {
-                        return;
-                    }
-                    this.titleGenerationInProgress.add(titleGenerationKey);
-                    try {
-                        const title = await this.generateConversationTitle(options.userMessage);
-                        const updatedRedisKey = getSessionKey(this.redisConfig, options.sessionId, options.userId || undefined);
-                        const updatedConversationData = await this.redisClient?.get(updatedRedisKey);
-                        const updatedConversation = deserializeConversation(updatedConversationData || null);
-                        if (updatedConversation) {
-                            updatedConversation.title = title;
-                            updatedConversation.updatedAt = new Date().toISOString();
-                            const serializedData = serializeConversation(updatedConversation);
-                            await this.redisClient?.set(updatedRedisKey, serializedData);
-                            if (this.redisConfig.ttl > 0) {
-                                await this.redisClient?.expire(updatedRedisKey, this.redisConfig.ttl);
-                            }
-                        }
-                    }
-                    catch (titleError) {
-                        logger.warn("[RedisConversationMemoryManager] Failed to generate conversation title in background", {
-                            sessionId: options.sessionId,
-                            userId: normalizedUserId,
-                            error: titleError instanceof Error
-                                ? titleError.message
-                                : String(titleError),
-                        });
-                    }
-                    finally {
-                        this.titleGenerationInProgress.delete(titleGenerationKey);
-                    }
-                });
-                conversation = {
-                    id: randomUUID(),
-                    title: "New Conversation", // Temporary title until generated
-                    sessionId: options.sessionId,
-                    userId: normalizedUserId,
-                    createdAt: options.startTimeStamp?.toISOString() || currentTime,
-                    updatedAt: options.startTimeStamp?.toISOString() || currentTime,
-                    messages: [],
-                };
-            }
-            else {
-                conversation.updatedAt = currentTime;
-            }
-            const tokenThreshold = options.providerDetails
-                ? getEffectiveTokenThreshold(options.providerDetails.provider, options.providerDetails.model, this.config.tokenThreshold, conversation.tokenThreshold)
-                : this.config.tokenThreshold || 50000;
-            const userMsg = {
-                id: randomUUID(),
-                timestamp: options.startTimeStamp?.toISOString() || this.generateTimestamp(),
-                role: "user",
-                content: options.userMessage,
-            };
-            conversation.messages.push(userMsg);
-            await this.flushPendingToolData(conversation, options.sessionId, normalizedUserId);
-            const assistantMsg = {
-                id: randomUUID(),
-                timestamp: this.generateTimestamp(),
-                role: "assistant",
-                content: options.aiResponse,
-                events: options.events || undefined,
-            };
-            conversation.messages.push(assistantMsg);
-            // Store API-reported token counts if available
-            if (options.tokenUsage) {
-                conversation.lastApiTokenCount = options.tokenUsage;
-            }
-            logger.info("[RedisConversationMemoryManager] Added new messages", {
-                sessionId: conversation.sessionId,
-                userId: conversation.userId,
-            });
-            // Use per-request enableSummarization with higher priority than instance config
-            const shouldSummarize = options.enableSummarization !== undefined
-                ? options.enableSummarization
-                : this.config.enableSummarization;
-            if (shouldSummarize) {
+        // NLK-GAP-012: Add span for storeTurn CRUD operation
+        return redisTracer.startActiveSpan("neurolink.memory.storeTurn", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "session.id": options.sessionId,
+                ...(options.userId && { "user.id": options.userId }),
+            },
+        }, async (span) => {
+            try {
+                if (!this.redisClient) {
+                    throw new Error("Redis client not initialized");
+                }
+                const redisKey = getSessionKey(this.redisConfig, options.sessionId, options.userId);
+                const conversationData = await this.redisClient.get(redisKey);
+                let conversation = deserializeConversation(conversationData);
+                const currentTime = new Date().toISOString();
                 const normalizedUserId = options.userId || "randomUser";
-                const summarizationKey = `${options.sessionId}:${normalizedUserId}`;
-                // Only trigger summarization if not already in progress for this session
-                if (!this.summarizationInProgress.has(summarizationKey)) {
-                    setImmediate(async () => {
+                if (!conversation) {
+                    const titleGenerationKey = `${options.sessionId}:${normalizedUserId}`;
+                    // Capture the current Langfuse ALS context before setImmediate,
+                    // which breaks automatic AsyncLocalStorage propagation and would
+                    // otherwise cause orphaned traces in Langfuse.
+                    const generateTitleWithContext = runWithCurrentLangfuseContext(async () => {
+                        if (this.titleGenerationInProgress.has(titleGenerationKey)) {
+                            return;
+                        }
+                        this.titleGenerationInProgress.add(titleGenerationKey);
                         try {
-                            await this.checkAndSummarize(conversation, tokenThreshold, options.sessionId, options.userId, options.requestId);
+                            const title = await this.generateConversationTitle(options.userMessage);
+                            const updatedRedisKey = getSessionKey(this.redisConfig, options.sessionId, options.userId || undefined);
+                            const updatedConversationData = await this.redisClient?.get(updatedRedisKey);
+                            const updatedConversation = deserializeConversation(updatedConversationData || null);
+                            if (updatedConversation) {
+                                updatedConversation.title = title;
+                                updatedConversation.updatedAt = new Date().toISOString();
+                                const serializedData = serializeConversation(updatedConversation);
+                                await this.redisClient?.set(updatedRedisKey, serializedData);
+                                if (this.redisConfig.ttl > 0) {
+                                    await this.redisClient?.expire(updatedRedisKey, this.redisConfig.ttl);
+                                }
+                            }
                         }
-                        catch (error) {
-                            logger.error("Background summarization failed", {
-                                sessionId: conversation.sessionId,
-                                error: error instanceof Error ? error.message : String(error),
+                        catch (titleError) {
+                            logger.warn("[RedisConversationMemoryManager] Failed to generate conversation title in background", {
+                                sessionId: options.sessionId,
+                                userId: normalizedUserId,
+                                error: titleError instanceof Error
+                                    ? titleError.message
+                                    : String(titleError),
                             });
                         }
+                        finally {
+                            this.titleGenerationInProgress.delete(titleGenerationKey);
+                        }
                     });
-                }
-                else {
-                    logger.debug("[RedisConversationMemoryManager] Summarization already in progress, skipping", {
+                    setImmediate(generateTitleWithContext);
+                    conversation = {
+                        id: randomUUID(),
+                        title: "New Conversation", // Temporary title until generated
                         sessionId: options.sessionId,
                         userId: normalizedUserId,
-                    });
+                        createdAt: options.startTimeStamp?.toISOString() || currentTime,
+                        updatedAt: options.startTimeStamp?.toISOString() || currentTime,
+                        messages: [],
+                    };
                 }
-            }
-            const serializedData = serializeConversation(conversation);
-            await this.redisClient.set(redisKey, serializedData);
-            // Log turn storage metadata for observability
-            const blobSizeBytes = Buffer.byteLength(serializedData, "utf8");
-            logger.info("[ConversationMemory] Turn stored", {
-                requestId: options.requestId,
-                sessionId: options.sessionId,
-                blobSizeBytes,
-                totalMessages: conversation.messages.length,
-                userMsgChars: options.userMessage.length,
-                assistantMsgChars: options.aiResponse.length,
-            });
-            if (blobSizeBytes > 512 * 1024) {
-                logger.warn("[ConversationMemory] Large session blob", {
+                else {
+                    conversation.updatedAt = currentTime;
+                }
+                const tokenThreshold = options.providerDetails
+                    ? getEffectiveTokenThreshold(options.providerDetails.provider, options.providerDetails.model, this.config.tokenThreshold, conversation.tokenThreshold)
+                    : this.config.tokenThreshold || 50000;
+                const userMsg = {
+                    id: randomUUID(),
+                    timestamp: options.startTimeStamp?.toISOString() || this.generateTimestamp(),
+                    role: "user",
+                    content: options.userMessage,
+                };
+                conversation.messages.push(userMsg);
+                await this.flushPendingToolData(conversation, options.sessionId, normalizedUserId);
+                const assistantMsg = {
+                    id: randomUUID(),
+                    timestamp: this.generateTimestamp(),
+                    role: "assistant",
+                    content: options.aiResponse,
+                    events: options.events || undefined,
+                };
+                conversation.messages.push(assistantMsg);
+                // Store API-reported token counts if available
+                if (options.tokenUsage) {
+                    conversation.lastApiTokenCount = options.tokenUsage;
+                }
+                logger.info("[RedisConversationMemoryManager] Added new messages", {
+                    sessionId: conversation.sessionId,
+                    userId: conversation.userId,
+                });
+                // Use per-request enableSummarization with higher priority than instance config
+                const shouldSummarize = options.enableSummarization !== undefined
+                    ? options.enableSummarization
+                    : this.config.enableSummarization;
+                if (shouldSummarize) {
+                    const normalizedUserId = options.userId || "randomUser";
+                    const summarizationKey = `${options.sessionId}:${normalizedUserId}`;
+                    // Only trigger summarization if not already in progress for this session
+                    if (!this.summarizationInProgress.has(summarizationKey)) {
+                        // Capture the current Langfuse ALS context before setImmediate,
+                        // which breaks automatic AsyncLocalStorage propagation and would
+                        // otherwise cause orphaned traces in Langfuse.
+                        const summarizeWithContext = runWithCurrentLangfuseContext(async () => {
+                            try {
+                                await this.checkAndSummarize(conversation, tokenThreshold, options.sessionId, options.userId, options.requestId);
+                            }
+                            catch (error) {
+                                logger.error("Background summarization failed", {
+                                    sessionId: conversation.sessionId,
+                                    error: error instanceof Error ? error.message : String(error),
+                                });
+                            }
+                        });
+                        setImmediate(summarizeWithContext);
+                    }
+                    else {
+                        logger.debug("[RedisConversationMemoryManager] Summarization already in progress, skipping", {
+                            sessionId: options.sessionId,
+                            userId: normalizedUserId,
+                        });
+                    }
+                }
+                const serializedData = serializeConversation(conversation);
+                await this.redisClient.set(redisKey, serializedData);
+                // Log turn storage metadata for observability
+                const blobSizeBytes = Buffer.byteLength(serializedData, "utf8");
+                logger.info("[ConversationMemory] Turn stored", {
                     requestId: options.requestId,
                     sessionId: options.sessionId,
                     blobSizeBytes,
-                    messageCount: conversation.messages.length,
+                    totalMessages: conversation.messages.length,
+                    userMsgChars: options.userMessage.length,
+                    assistantMsgChars: options.aiResponse.length,
+                });
+                if (blobSizeBytes > 512 * 1024) {
+                    logger.warn("[ConversationMemory] Large session blob", {
+                        requestId: options.requestId,
+                        sessionId: options.sessionId,
+                        blobSizeBytes,
+                        messageCount: conversation.messages.length,
+                    });
+                }
+                if (this.redisConfig.ttl > 0) {
+                    await this.redisClient.expire(redisKey, this.redisConfig.ttl);
+                }
+                if (options.userId) {
+                    await this.addUserSession(options.userId, options.sessionId);
+                }
+                span.setAttribute("message.count", conversation.messages.length);
+                span.setStatus({ code: SpanStatusCode.OK });
+                logger.debug("[RedisConversationMemoryManager] Successfully stored conversation turn", {
+                    sessionId: options.sessionId,
+                    totalMessages: conversation.messages.length,
+                    title: conversation.title,
                 });
             }
-            if (this.redisConfig.ttl > 0) {
-                await this.redisClient.expire(redisKey, this.redisConfig.ttl);
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                throw new ConversationMemoryError(`Failed to store conversation turn in Redis for session ${options.sessionId}`, "STORAGE_ERROR", {
+                    sessionId: options.sessionId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
             }
-            if (options.userId) {
-                await this.addUserSession(options.userId, options.sessionId);
+            finally {
+                span.end();
             }
-            logger.debug("[RedisConversationMemoryManager] Successfully stored conversation turn", {
-                sessionId: options.sessionId,
-                totalMessages: conversation.messages.length,
-                title: conversation.title,
-            });
-        }
-        catch (error) {
-            throw new ConversationMemoryError(`Failed to store conversation turn in Redis for session ${options.sessionId}`, "STORAGE_ERROR", {
-                sessionId: options.sessionId,
-                error: error instanceof Error ? error.message : String(error),
-            });
-        }
+        });
     }
     /**
      * Check if summarization is needed based on token count
@@ -521,10 +586,24 @@ export class RedisConversationMemoryManager {
                 conversation.summarizedMessage = session.summarizedMessage;
                 if (this.redisClient) {
                     const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
-                    const serializedData = serializeConversation(conversation);
-                    await this.redisClient.set(redisKey, serializedData);
-                    if (this.redisConfig.ttl > 0) {
-                        await this.redisClient.expire(redisKey, this.redisConfig.ttl);
+                    // Re-read current state to avoid clobbering messages added during summarization
+                    const latestData = await this.redisClient.get(redisKey);
+                    if (latestData) {
+                        const latestConversation = deserializeConversation(latestData);
+                        if (latestConversation) {
+                            // Apply only summarization metadata onto the fresh state
+                            latestConversation.summarizedUpToMessageId =
+                                conversation.summarizedUpToMessageId;
+                            latestConversation.summarizedMessage =
+                                conversation.summarizedMessage;
+                            latestConversation.lastTokenCount = conversation.lastTokenCount;
+                            latestConversation.lastCountedAt = conversation.lastCountedAt;
+                            const freshSerialized = serializeConversation(latestConversation);
+                            await this.redisClient.set(redisKey, freshSerialized);
+                            if (this.redisConfig.ttl > 0) {
+                                await this.redisClient.expire(redisKey, this.redisConfig.ttl);
+                            }
+                        }
                     }
                 }
             }
@@ -545,62 +624,93 @@ export class RedisConversationMemoryManager {
      * Applies sendToolPreview toggle and hydrates result.result for backward compat
      */
     async buildContextMessages(sessionId, userId, enableSummarization, requestId) {
-        logger.info("[RedisConversationMemoryManager] Building context messages", {
-            sessionId,
-            userId,
-            method: "buildContextMessages",
-        });
-        const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
-        const conversationData = await this.redisClient?.get(redisKey);
-        const conversation = deserializeConversation(conversationData || null);
-        if (!conversation) {
+        await this.ensureInitialized();
+        if (!this.redisClient) {
+            logger.warn("[RedisConversationMemoryManager] Redis client not available in buildContextMessages");
             return [];
         }
-        const session = {
-            sessionId: conversation.sessionId,
-            userId: conversation.userId,
-            messages: conversation.messages,
-            summarizedUpToMessageId: conversation.summarizedUpToMessageId,
-            summarizedMessage: conversation.summarizedMessage,
-            tokenThreshold: conversation.tokenThreshold,
-            lastTokenCount: conversation.lastTokenCount,
-            lastCountedAt: conversation.lastCountedAt,
-            createdAt: new Date(conversation.createdAt).getTime(),
-            lastActivity: new Date(conversation.updatedAt).getTime(),
-        };
-        const contextMessages = buildContextFromPointer(session, requestId);
-        const sendToolPreview = this.config?.contextCompaction?.sendToolPreview === true;
-        // Map tool_result messages: apply preview toggle + hydrate result.result
-        const finalMessages = contextMessages.map((msg) => {
-            if (msg.role !== "tool_result") {
-                return msg;
-            }
-            // Toggle: swap content to preview if enabled AND a preview exists
-            const content = sendToolPreview && msg.metadata?.toolOutputPreview
-                ? msg.metadata.toolOutputPreview
-                : msg.content;
-            // Hydrate result.result from content for backward compatibility
-            // (result.result is no longer stored — inferred from content at read time)
-            let hydratedResult = msg.result;
-            if (msg.result && msg.result.result === undefined) {
-                let parsedResult = content;
-                try {
-                    parsedResult = JSON.parse(content);
-                }
-                catch {
-                    /* plain text — use as-is */
+        // NLK-GAP-012: Add span for buildContext CRUD operation
+        return redisTracer.startActiveSpan("neurolink.memory.buildContext", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "session.id": sessionId,
+                ...(userId && { "user.id": userId }),
+            },
+        }, async (span) => {
+            try {
+                logger.info("[RedisConversationMemoryManager] Building context messages", {
+                    sessionId,
+                    userId,
+                    method: "buildContextMessages",
+                });
+                const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+                const conversationData = await this.redisClient.get(redisKey);
+                const conversation = deserializeConversation(conversationData || null);
+                if (!conversation) {
+                    span.setAttribute("session.found", false);
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    return [];
                 }
-                hydratedResult = { ...msg.result, result: parsedResult };
+                const session = {
+                    sessionId: conversation.sessionId,
+                    userId: conversation.userId,
+                    messages: conversation.messages,
+                    summarizedUpToMessageId: conversation.summarizedUpToMessageId,
+                    summarizedMessage: conversation.summarizedMessage,
+                    tokenThreshold: conversation.tokenThreshold,
+                    lastTokenCount: conversation.lastTokenCount,
+                    lastCountedAt: conversation.lastCountedAt,
+                    createdAt: new Date(conversation.createdAt).getTime(),
+                    lastActivity: new Date(conversation.updatedAt).getTime(),
+                };
+                const contextMessages = buildContextFromPointer(session, requestId);
+                const sendToolPreview = this.config?.contextCompaction?.sendToolPreview === true;
+                // Map tool_result messages: apply preview toggle + hydrate result.result
+                const finalMessages = contextMessages.map((msg) => {
+                    if (msg.role !== "tool_result") {
+                        return msg;
+                    }
+                    // Toggle: swap content to preview if enabled AND a preview exists
+                    const content = sendToolPreview && msg.metadata?.toolOutputPreview
+                        ? msg.metadata.toolOutputPreview
+                        : msg.content;
+                    // Hydrate result.result from content for backward compatibility
+                    // (result.result is no longer stored — inferred from content at read time)
+                    let hydratedResult = msg.result;
+                    if (msg.result && msg.result.result === undefined) {
+                        let parsedResult = content;
+                        try {
+                            parsedResult = JSON.parse(content);
+                        }
+                        catch {
+                            /* plain text — use as-is */
+                        }
+                        hydratedResult = { ...msg.result, result: parsedResult };
+                    }
+                    return { ...msg, content, result: hydratedResult };
+                });
+                // Tool messages now have real content and participate in context properly.
+                // The tool output pruner (Stage 1) handles bounding old tool outputs.
+                span.setAttribute("context.message_count", finalMessages.length);
+                span.setStatus({ code: SpanStatusCode.OK });
+                logger.info("[RedisConversationMemoryManager] Retrieved context messages", {
+                    sessionId,
+                    userId,
+                });
+                return finalMessages;
+            }
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                throw error;
+            }
+            finally {
+                span.end();
             }
-            return { ...msg, content, result: hydratedResult };
-        });
-        // Tool messages now have real content and participate in context properly.
-        // The tool output pruner (Stage 1) handles bounding old tool outputs.
-        logger.info("[RedisConversationMemoryManager] Retrieved context messages", {
-            sessionId,
-            userId,
         });
-        return finalMessages;
     }
     /**
      * Get session metadata for a specific user session (optimized for listing)
@@ -798,7 +908,7 @@ User message: "${userMessage}"`;
                 input: { text: titlePrompt },
                 provider: this.config.summarizationProvider || "vertex",
                 model: this.config.summarizationModel || "gemini-2.5-flash",
-                disableTools: false,
+                disableTools: true, // Title generation doesn't need tools — saves ~600 tokens of tool descriptions
             });
             // Clean up the generated title
             let title = result.content?.trim() || "New Conversation";
@@ -964,17 +1074,43 @@ User message: "${userMessage}"`;
         if (!this.redisClient) {
             return false;
         }
-        const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
-        const result = await this.redisClient.del(redisKey);
-        if (result > 0) {
-            // Remove session from user's session set
-            if (userId) {
-                await this.removeUserSession(userId, sessionId);
+        // NLK-GAP-012: Add span for clearSession CRUD operation
+        return redisTracer.startActiveSpan("neurolink.memory.clear", {
+            kind: SpanKind.CLIENT,
+            attributes: {
+                "session.id": sessionId,
+                ...(userId && { "user.id": userId }),
+            },
+        }, async (span) => {
+            try {
+                const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
+                const result = await this.redisClient.del(redisKey);
+                if (result > 0) {
+                    // Remove session from user's session set
+                    if (userId) {
+                        await this.removeUserSession(userId, sessionId);
+                    }
+                    span.setAttribute("session.deleted", true);
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    logger.info("Redis session cleared", { sessionId });
+                    return true;
+                }
+                span.setAttribute("session.deleted", false);
+                span.setStatus({ code: SpanStatusCode.OK });
+                return false;
             }
-            logger.info("Redis session cleared", { sessionId });
-            return true;
-        }
-        return false;
+            catch (error) {
+                span.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+                span.recordException(error instanceof Error ? error : new Error(String(error)));
+                throw error;
+            }
+            finally {
+                span.end();
+            }
+        });
     }
     /**
      * Clear all sessions