@juspay/neurolink 8.19.1 → 8.20.0

package/dist/lib/types/conversation.d.ts

@@ -11,14 +11,10 @@ export type ConversationMemoryConfig = {
     enabled: boolean;
     /** Maximum number of sessions to keep in memory (default: 50) */
     maxSessions?: number;
-    /** Maximum number of conversation turns to keep per session (default: 20) */
-    maxTurnsPerSession?: number;
     /** Enable automatic summarization */
     enableSummarization?: boolean;
-    /** Turn count to trigger summarization */
-    summarizationThresholdTurns?: number;
-    /** Target turn count for the summary */
-    summarizationTargetTurns?: number;
+    /** Token threshold to trigger summarization (optional - defaults to 80% of model context) */
+    tokenThreshold?: number;
     /** Provider to use for summarization */
     summarizationProvider?: string;
     /** Model to use for summarization */
@@ -29,6 +25,12 @@ export type ConversationMemoryConfig = {
     mem0Config?: Mem0Config;
     /** Redis configuration (optional) - overrides environment variables */
     redisConfig?: RedisStorageConfig;
+    /** @deprecated Use tokenThreshold instead - Maximum number of conversation turns to keep per session (default: 20) */
+    maxTurnsPerSession?: number;
+    /** @deprecated Use tokenThreshold instead - Turn count to trigger summarization */
+    summarizationThresholdTurns?: number;
+    /** @deprecated Use tokenThreshold instead - Target turn count for the summary */
+    summarizationTargetTurns?: number;
 };
 /**
  * Complete memory for a conversation session
@@ -47,6 +49,16 @@ export type SessionMemory = {
     createdAt: number;
     /** When this session was last active */
     lastActivity: number;
+    /** Pointer to last summarized message ID (NEW - for token-based memory) */
+    summarizedUpToMessageId?: string;
+    /** Stored summary message that condenses conversation history up to summarizedUpToMessageId */
+    summarizedMessage?: string;
+    /** Per-session token threshold override (NEW - for token-based memory) */
+    tokenThreshold?: number;
+    /** Cached token count for performance (NEW - for token-based memory) */
+    lastTokenCount?: number;
+    /** When token count was last calculated (NEW - for token-based memory) */
+    lastCountedAt?: number;
     /** Optional session metadata */
     metadata?: {
         /** User role or permissions */
@@ -70,13 +82,13 @@ export type ConversationMemoryStats = {
  * Chat message format for conversation history
  */
 export type ChatMessage = {
+    /** Unique message identifier (required for token-based memory) */
+    id: string;
     /** Role/type of the message */
     role: "user" | "assistant" | "system" | "tool_call" | "tool_result";
     /** Content of the message */
     content: string;
-    /** Message ID (optional) - for new format */
-    id?: string;
-    /** Timestamp (optional) - for new format */
+    /** Timestamp (ISO string) */
     timestamp?: string;
     /** Tool name (optional) - for tool_call/tool_result messages */
     tool?: string;
@@ -90,6 +102,17 @@ export type ChatMessage = {
         type?: string;
         error?: string;
     };
+    /** Message metadata (NEW - for token-based memory) */
+    metadata?: {
+        /** Is this a summary message? */
+        isSummary?: boolean;
+        /** First message ID that this summary covers */
+        summarizesFrom?: string;
+        /** Last message ID that this summary covers */
+        summarizesTo?: string;
+        /** Was this message truncated due to token limits? */
+        truncated?: boolean;
+    };
 };
 /**
  * Multimodal message types - Re-exported from multimodal.ts
@@ -152,6 +175,18 @@ export type SessionIdentifier = {
     sessionId: string;
     userId?: string;
 };
+/**
+ * Options for storing a conversation turn
+ */
+export type StoreConversationTurnOptions = {
+    sessionId: string;
+    userId?: string;
+    userMessage: string;
+    aiResponse: string;
+    startTimeStamp?: Date;
+    providerDetails?: ProviderDetails;
+    enableSummarization?: boolean;
+};
 /**
  * Lightweight session metadata for efficient session listing
  * Contains only essential information without heavy message arrays
@@ -179,6 +214,16 @@ export type ConversationBase = {
     createdAt: string;
     /** When this conversation was last updated */
     updatedAt: string;
+    /** Pointer to last summarized message (token-based memory) */
+    summarizedUpToMessageId?: string;
+    /** Stored summary message that condenses conversation history up to summarizedUpToMessageId */
+    summarizedMessage?: string;
+    /** Per-session token threshold override */
+    tokenThreshold?: number;
+    /** Cached token count for efficiency */
+    lastTokenCount?: number;
+    /** Timestamp of last token count */
+    lastCountedAt?: number;
 };
 /**
  * Redis conversation storage object format
@@ -250,3 +295,7 @@ export type RedisStorageConfig = {
         [key: string]: string | number | boolean | undefined;
     };
 };
+export type ProviderDetails = {
+    provider: string;
+    model: string;
+};

package/dist/lib/types/generateTypes.d.ts

@@ -350,6 +350,7 @@ export type TextGenerationOptions = {
         formatStyle?: "raw" | "markdown" | "json";
         includeHeaders?: boolean;
     };
+    enableSummarization?: boolean;
 };
 /**
  * Text generation result (consolidated from core types)

package/dist/lib/types/sdkTypes.d.ts

@@ -22,4 +22,4 @@ export type { Unknown, UnknownRecord, UnknownArray, JsonValue, JsonObject, JsonA
 export type { EvaluationData, EvaluationContext, EnhancedEvaluationResult, EvaluationRequest, EvaluationCriteria, } from "./evaluation.js";
 export type { TaskType, TaskClassification, ClassificationScores, ClassificationStats, ClassificationValidation, } from "./taskClassificationTypes.js";
 export type { DomainType, DomainConfig, DomainTemplate, DomainConfigOptions, DomainEvaluationCriteria, DomainValidationRule, } from "./domainTypes.js";
-export type { ConversationMemoryConfig, SessionMemory, ConversationMemoryStats, ChatMessage, MessageContent, MultimodalChatMessage, ConversationMemoryEvents, ConversationMemoryError, SessionIdentifier, SessionMetadata, RedisConversationObject, RedisStorageConfig, } from "./conversation.js";
+export type { ConversationMemoryConfig, SessionMemory, ChatMessage, MessageContent, MultimodalChatMessage, ConversationMemoryEvents, ConversationMemoryError, SessionIdentifier, SessionMetadata, RedisConversationObject, RedisStorageConfig, } from "./conversation.js";

package/dist/lib/types/streamTypes.d.ts

@@ -299,6 +299,7 @@ export type StreamOptions = {
     };
     conversationMessages?: ChatMessage[];
     middleware?: MiddlewareFactoryOptions;
+    enableSummarization?: boolean;
 };
 /**
  * Stream function result type - Primary output format for streaming

package/dist/lib/utils/conversationMemory.d.ts

@@ -2,7 +2,7 @@
  * Conversation Memory Utilities
  * Handles configuration merging and conversation memory operations
  */
-import type { ConversationMemoryConfig, ChatMessage } from "../types/conversation.js";
+import type { ConversationMemoryConfig, ChatMessage, SessionMemory } from "../types/conversation.js";
 import type { ConversationMemoryManager } from "../core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "../core/redisConversationMemoryManager.js";
 import type { TextGenerationOptions, TextGenerationResult } from "../types/generateTypes.js";
@@ -20,3 +20,45 @@ export declare function getConversationMessages(conversationMemory: Conversation
  * Saves user messages and AI responses for conversation memory
  */
 export declare function storeConversationTurn(conversationMemory: ConversationMemoryManager | RedisConversationMemoryManager | null | undefined, originalOptions: TextGenerationOptions, result: TextGenerationResult, startTimeStamp?: Date | undefined): Promise<void>;
+/**
+ * Build context messages from pointer onwards (token-based memory)
+ * Returns summary message (if exists) + all messages after the summarized pointer
+ * @param session - Session memory with pointer
+ * @returns Context messages to send to LLM
+ */
+export declare function buildContextFromPointer(session: SessionMemory): ChatMessage[];
+/**
+ * Create summarization prompt from message history
+ * Used by both in-memory and Redis conversation managers
+ * @param history - Messages to summarize
+ * @param previousSummary - Optional previous summary to build upon
+ */
+export declare function createSummarizationPrompt(history: ChatMessage[], previousSummary?: string): string;
+/**
+ * Calculate token threshold based on model's output token limit
+ * Uses existing provider token limits as proxy for context window
+ * @param provider - AI provider name
+ * @param model - Model name
+ * @returns Token threshold (80% of model's token limit)
+ */
+export declare function calculateTokenThreshold(provider: string, model: string): number;
+/**
+ * Get effective token threshold for a session
+ * Priority: session override > env var > model-based (80%) > fallback
+ * @param provider - AI provider name
+ * @param model - Model name
+ * @param envOverride - Environment variable override
+ * @param sessionOverride - Per-session token threshold override
+ * @returns Effective token threshold
+ */
+export declare function getEffectiveTokenThreshold(provider: string, model: string, envOverride?: number, sessionOverride?: number): number;
+/**
+ * Generate summary using configured provider and model
+ * Centralized summarization logic used by both ConversationMemoryManager and RedisConversationMemoryManager
+ * @param messages - Messages to summarize
+ * @param config - Conversation memory configuration containing provider/model settings
+ * @param previousSummary - Optional previous summary to build upon
+ * @param logPrefix - Prefix for log messages (e.g., "[ConversationMemory]" or "[RedisConversationMemoryManager]")
+ * @returns Summary text or null if generation fails
+ */
+export declare function generateSummary(messages: ChatMessage[], config: ConversationMemoryConfig, logPrefix?: string, previousSummary?: string): Promise<string | null>;

package/dist/lib/utils/conversationMemory.js

@@ -2,8 +2,10 @@
  * Conversation Memory Utilities
  * Handles configuration merging and conversation memory operations
  */
-import { getConversationMemoryDefaults } from "../config/conversationMemory.js";
+import { getConversationMemoryDefaults, MEMORY_THRESHOLD_PERCENTAGE, DEFAULT_FALLBACK_THRESHOLD, } from "../config/conversationMemory.js";
+import { TokenUtils } from "../constants/tokens.js";
 import { logger } from "./logger.js";
+import { NeuroLink } from "../neurolink.js";
 /**
  * Apply conversation memory defaults to user configuration
  * Merges user config with environment variables and default values
@@ -34,8 +36,8 @@ export async function getConversationMessages(conversationMemory, options) {
     try {
         // Extract userId from context
         const userId = options.context?.userId;
-        // Remove duplicate summarization logic - it should be handled in ConversationMemoryManager
-        const messages = await conversationMemory.buildContextMessages(sessionId, userId);
+        const enableSummarization = options.enableSummarization ?? undefined;
+        const messages = await conversationMemory.buildContextMessages(sessionId, userId, enableSummarization);
         logger.debug("[conversationMemoryUtils] Conversation messages retrieved successfully", {
             sessionId,
             messageCount: messages.length,
@@ -100,9 +102,24 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
         return;
     }
     const userMessage = originalOptions.originalPrompt || originalOptions.prompt || "";
-    const aiResponse = result.content;
+    const aiResponse = result.content ?? "";
+    let providerDetails = undefined;
+    if (result.provider && result.model) {
+        providerDetails = {
+            provider: result.provider,
+            model: result.model,
+        };
+    }
     try {
-        await conversationMemory.storeConversationTurn(sessionId, userId, userMessage, aiResponse, startTimeStamp);
+        await conversationMemory.storeConversationTurn({
+            sessionId,
+            userId,
+            userMessage,
+            aiResponse,
+            startTimeStamp,
+            providerDetails,
+            enableSummarization: originalOptions.enableSummarization,
+        });
         logger.debug("[conversationMemoryUtils] Conversation turn stored successfully", {
             sessionId,
             userId,
@@ -121,4 +138,163 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
         });
     }
 }
+/**
+ * Build context messages from pointer onwards (token-based memory)
+ * Returns summary message (if exists) + all messages after the summarized pointer
+ * @param session - Session memory with pointer
+ * @returns Context messages to send to LLM
+ */
+export function buildContextFromPointer(session) {
+    if (!session.summarizedUpToMessageId || !session.summarizedMessage) {
+        return session.messages;
+    }
+    // find a better way to wirte this
+    const pointerIndex = session.messages.findIndex((msg) => msg.id === session.summarizedUpToMessageId);
+    if (pointerIndex === -1) {
+        logger.warn("Pointer message not found, returning all messages", {
+            sessionId: session.sessionId,
+            pointer: session.summarizedUpToMessageId,
+            totalMessages: session.messages.length,
+        });
+        return session.messages;
+    }
+    const messagesAfterPointer = session.messages.slice(pointerIndex + 1);
+    // Construct context: summary message + recent messages
+    const summaryMessage = {
+        id: `summary-${session.summarizedUpToMessageId}`,
+        role: "system",
+        content: `Previous conversation summary: ${session.summarizedMessage}`,
+        timestamp: new Date().toISOString(),
+        metadata: {
+            isSummary: true,
+            summarizesTo: session.summarizedUpToMessageId,
+        },
+    };
+    logger.debug("Building context with summary", {
+        sessionId: session.sessionId,
+        pointerIndex,
+        messagesAfterPointer: messagesAfterPointer.length,
+        totalMessages: session.messages.length,
+        summaryLength: session.summarizedMessage.length,
+    });
+    return [summaryMessage, ...messagesAfterPointer];
+}
+/**
+ * Create summarization prompt from message history
+ * Used by both in-memory and Redis conversation managers
+ * @param history - Messages to summarize
+ * @param previousSummary - Optional previous summary to build upon
+ */
+export function createSummarizationPrompt(history, previousSummary) {
+    const formattedHistory = history
+        .map((msg) => `${msg.role}: ${msg.content}`)
+        .join("\n\n");
+    const previousSummarySection = previousSummary
+        ? `Previous Summary:
+---
+${previousSummary}
+---
+
+`
+        : "";
+    return `
+You are a context summarization AI. Your task is to condense the following conversation history for another AI assistant.
+${previousSummary ? "Build upon the previous summary and incorporate the new conversation turns below." : ""}
+The summary must be a concise, third-person narrative that retains all critical information, including key entities, technical details, decisions made, and any specific dates or times mentioned.
+Ensure the summary flows logically and is ready to be used as context for the next turn in the conversation.
+
+${previousSummarySection}Conversation History to Summarize:
+---
+${formattedHistory}
+---
+`.trim();
+}
+/**
+ * Calculate token threshold based on model's output token limit
+ * Uses existing provider token limits as proxy for context window
+ * @param provider - AI provider name
+ * @param model - Model name
+ * @returns Token threshold (80% of model's token limit)
+ */
+export function calculateTokenThreshold(provider, model) {
+    try {
+        // Get model's token limit from existing TokenUtils
+        const modelTokenLimit = TokenUtils.getProviderTokenLimit(provider, model);
+        // Return 80% of token limit for conversation memory
+        // This is conservative since output limits are typically smaller than input limits
+        return Math.floor(modelTokenLimit * MEMORY_THRESHOLD_PERCENTAGE);
+    }
+    catch (error) {
+        logger.warn("Failed to calculate model threshold, using fallback", {
+            provider,
+            model,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return DEFAULT_FALLBACK_THRESHOLD;
+    }
+}
+/**
+ * Get effective token threshold for a session
+ * Priority: session override > env var > model-based (80%) > fallback
+ * @param provider - AI provider name
+ * @param model - Model name
+ * @param envOverride - Environment variable override
+ * @param sessionOverride - Per-session token threshold override
+ * @returns Effective token threshold
+ */
+export function getEffectiveTokenThreshold(provider, model, envOverride, sessionOverride) {
+    // Priority 1: Session-level override
+    if (sessionOverride && sessionOverride > 0) {
+        return sessionOverride;
+    }
+    // Priority 2: Environment variable override
+    if (envOverride && envOverride > 0) {
+        return envOverride;
+    }
+    // Priority 3: Model-based calculation (80% of context window)
+    try {
+        return calculateTokenThreshold(provider, model);
+    }
+    catch (error) {
+        logger.warn("Failed to calculate effective threshold, using fallback", {
+            provider,
+            model,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        // Priority 4: Fallback for unknown models
+        return DEFAULT_FALLBACK_THRESHOLD;
+    }
+}
+/**
+ * Generate summary using configured provider and model
+ * Centralized summarization logic used by both ConversationMemoryManager and RedisConversationMemoryManager
+ * @param messages - Messages to summarize
+ * @param config - Conversation memory configuration containing provider/model settings
+ * @param previousSummary - Optional previous summary to build upon
+ * @param logPrefix - Prefix for log messages (e.g., "[ConversationMemory]" or "[RedisConversationMemoryManager]")
+ * @returns Summary text or null if generation fails
+ */
+export async function generateSummary(messages, config, logPrefix = "[ConversationMemory]", previousSummary) {
+    const summarizationPrompt = createSummarizationPrompt(messages, previousSummary);
+    const summarizer = new NeuroLink({
+        conversationMemory: { enabled: false },
+    });
+    try {
+        if (!config.summarizationProvider || !config.summarizationModel) {
+            logger.error(`${logPrefix} Missing summarization provider`);
+            return null;
+        }
+        const summaryResult = await summarizer.generate({
+            input: { text: summarizationPrompt },
+            provider: config.summarizationProvider,
+            model: config.summarizationModel,
+            disableTools: true,
+        });
+        return summaryResult.content || null;
+    }
+    catch (error) {
+        logger.error(`${logPrefix} Error generating summary`, { error });
+        return null;
+    }
+}
 //# sourceMappingURL=conversationMemory.js.map

package/dist/lib/utils/conversationMemoryUtils.js

@@ -58,8 +58,23 @@ export async function storeConversationTurn(conversationMemory, originalOptions,
     if (typeof sessionId !== "string" || !sessionId) {
         return;
     }
+    let providerDetails = undefined;
+    if (result.provider && result.model) {
+        providerDetails = {
+            provider: result.provider,
+            model: result.model,
+        };
+    }
     try {
-        await conversationMemory.storeConversationTurn(sessionId, userId, originalOptions.originalPrompt || originalOptions.prompt || "", result.content, startTimeStamp);
+        await conversationMemory.storeConversationTurn({
+            sessionId,
+            userId,
+            userMessage: originalOptions.originalPrompt || originalOptions.prompt || "",
+            aiResponse: result.content,
+            startTimeStamp,
+            providerDetails,
+            enableSummarization: originalOptions.enableSummarization,
+        });
         logger.debug("Conversation turn stored", {
             sessionId,
             userId,

package/dist/lib/utils/redis.js

@@ -91,14 +91,9 @@ export function serializeConversation(conversation) {
  */
 export function deserializeConversation(data) {
     if (!data) {
-        logger.debug("[redisUtils] No conversation data to deserialize, returning null");
         return null;
     }
     try {
-        logger.debug("[redisUtils] Deserializing conversation", {
-            dataLength: data.length,
-            dataPreview: data.substring(0, 100) + (data.length > 100 ? "..." : ""),
-        });
         // Parse as unknown first, then validate before casting
         const parsedData = JSON.parse(data);
         // Check if the parsed data is an object with required properties

package/dist/neurolink.js

@@ -2089,12 +2089,22 @@ Current user's request: ${currentInput}`;
                         if (self.conversationMemory && enhancedOptions.context?.sessionId) {
                             const sessionId = enhancedOptions.context?.sessionId;
                             const userId = enhancedOptions.context?.userId;
+                            let providerDetails = undefined;
+                            if (enhancedOptions.model) {
+                                providerDetails = {
+                                    provider: providerName,
+                                    model: enhancedOptions.model,
+                                };
+                            }
                             try {
-                                await self.conversationMemory.storeConversationTurn(sessionId, userId, originalPrompt ?? "", accumulatedContent, new Date(startTime));
-                                logger.debug("Stream conversation turn stored", {
+                                await self.conversationMemory.storeConversationTurn({
                                     sessionId,
-                                    userInputLength: originalPrompt?.length ?? 0,
-                                    responseLength: accumulatedContent.length,
+                                    userId,
+                                    userMessage: originalPrompt ?? "",
+                                    aiResponse: accumulatedContent,
+                                    startTimeStamp: new Date(startTime),
+                                    providerDetails,
+                                    enableSummarization: enhancedOptions.enableSummarization,
                                 });
                             }
                             catch (error) {
@@ -2194,6 +2204,7 @@ Current user's request: ${currentInput}`;
         const enhancedSystemPrompt = this.createToolAwareSystemPrompt(options.systemPrompt, availableTools);
         // Get conversation messages for context
         const conversationMessages = await getConversationMessages(this.conversationMemory, {
+            ...options,
             prompt: options.input.text,
             context: options.context,
         });
@@ -2297,12 +2308,22 @@ Current user's request: ${currentInput}`;
                     const sessionId = enhancedOptions?.context?.sessionId;
                     const userId = enhancedOptions?.context
                         ?.userId;
+                    let providerDetails = undefined;
+                    if (options.model) {
+                        providerDetails = {
+                            provider: providerName,
+                            model: options.model,
+                        };
+                    }
                     try {
-                        await self.conversationMemory.storeConversationTurn(sessionId || options.context?.sessionId, userId || options.context?.userId, originalPrompt ?? "", fallbackAccumulatedContent, new Date(startTime));
-                        logger.debug("Fallback stream conversation turn stored", {
+                        await self.conversationMemory.storeConversationTurn({
                             sessionId: sessionId || options.context?.sessionId,
-                            userInputLength: originalPrompt?.length ?? 0,
-                            responseLength: fallbackAccumulatedContent.length,
+                            userId: userId || options.context?.userId,
+                            userMessage: originalPrompt ?? "",
+                            aiResponse: fallbackAccumulatedContent,
+                            startTimeStamp: new Date(startTime),
+                            providerDetails,
+                            enableSummarization: enhancedOptions?.enableSummarization,
                         });
                     }
                     catch (error) {
@@ -4231,23 +4252,9 @@ Current user's request: ${currentInput}`;
             // Import the integration module
             const { initializeConversationMemory } = await import("./core/conversationMemoryInitializer.js");
             // Use the integration module to create the appropriate memory manager
-            const memoryManagerCreateStartTime = process.hrtime.bigint();
             const memoryManager = await initializeConversationMemory(this.conversationMemoryConfig);
             // Assign to conversationMemory with proper type to handle both memory manager types
             this.conversationMemory = memoryManager;
-            const memoryManagerCreateEndTime = process.hrtime.bigint();
-            const memoryManagerCreateDurationNs = memoryManagerCreateEndTime - memoryManagerCreateStartTime;
-            logger.info(`[NeuroLink] ✅ LOG_POINT_G004_MEMORY_LAZY_INIT_SUCCESS`, {
-                logPoint: "G004_MEMORY_LAZY_INIT_SUCCESS",
-                generateInternalId,
-                timestamp: new Date().toISOString(),
-                elapsedMs: Date.now() - generateInternalStartTime,
-                elapsedNs: (process.hrtime.bigint() - generateInternalHrTimeStart).toString(),
-                memoryManagerCreateDurationNs: memoryManagerCreateDurationNs.toString(),
-                memoryManagerCreateDurationMs: Number(memoryManagerCreateDurationNs) / 1000000,
-                storageType: process.env.STORAGE_TYPE || "memory",
-                message: "Lazy conversation memory initialization completed successfully",
-            });
             // Reset the lazy init flag since we've now initialized
             this.conversationMemoryNeedsInit = false;
         }

package/dist/types/conversation.d.ts

@@ -11,14 +11,10 @@ export type ConversationMemoryConfig = {
     enabled: boolean;
     /** Maximum number of sessions to keep in memory (default: 50) */
     maxSessions?: number;
-    /** Maximum number of conversation turns to keep per session (default: 20) */
-    maxTurnsPerSession?: number;
     /** Enable automatic summarization */
     enableSummarization?: boolean;
-    /** Turn count to trigger summarization */
-    summarizationThresholdTurns?: number;
-    /** Target turn count for the summary */
-    summarizationTargetTurns?: number;
+    /** Token threshold to trigger summarization (optional - defaults to 80% of model context) */
+    tokenThreshold?: number;
     /** Provider to use for summarization */
     summarizationProvider?: string;
     /** Model to use for summarization */
@@ -29,6 +25,12 @@ export type ConversationMemoryConfig = {
     mem0Config?: Mem0Config;
     /** Redis configuration (optional) - overrides environment variables */
     redisConfig?: RedisStorageConfig;
+    /** @deprecated Use tokenThreshold instead - Maximum number of conversation turns to keep per session (default: 20) */
+    maxTurnsPerSession?: number;
+    /** @deprecated Use tokenThreshold instead - Turn count to trigger summarization */
+    summarizationThresholdTurns?: number;
+    /** @deprecated Use tokenThreshold instead - Target turn count for the summary */
+    summarizationTargetTurns?: number;
 };
 /**
  * Complete memory for a conversation session
@@ -47,6 +49,16 @@ export type SessionMemory = {
     createdAt: number;
     /** When this session was last active */
     lastActivity: number;
+    /** Pointer to last summarized message ID (NEW - for token-based memory) */
+    summarizedUpToMessageId?: string;
+    /** Stored summary message that condenses conversation history up to summarizedUpToMessageId */
+    summarizedMessage?: string;
+    /** Per-session token threshold override (NEW - for token-based memory) */
+    tokenThreshold?: number;
+    /** Cached token count for performance (NEW - for token-based memory) */
+    lastTokenCount?: number;
+    /** When token count was last calculated (NEW - for token-based memory) */
+    lastCountedAt?: number;
     /** Optional session metadata */
     metadata?: {
         /** User role or permissions */
@@ -70,13 +82,13 @@ export type ConversationMemoryStats = {
  * Chat message format for conversation history
  */
 export type ChatMessage = {
+    /** Unique message identifier (required for token-based memory) */
+    id: string;
     /** Role/type of the message */
     role: "user" | "assistant" | "system" | "tool_call" | "tool_result";
     /** Content of the message */
     content: string;
-    /** Message ID (optional) - for new format */
-    id?: string;
-    /** Timestamp (optional) - for new format */
+    /** Timestamp (ISO string) */
     timestamp?: string;
     /** Tool name (optional) - for tool_call/tool_result messages */
     tool?: string;
@@ -90,6 +102,17 @@ export type ChatMessage = {
         type?: string;
         error?: string;
     };
+    /** Message metadata (NEW - for token-based memory) */
+    metadata?: {
+        /** Is this a summary message? */
+        isSummary?: boolean;
+        /** First message ID that this summary covers */
+        summarizesFrom?: string;
+        /** Last message ID that this summary covers */
+        summarizesTo?: string;
+        /** Was this message truncated due to token limits? */
+        truncated?: boolean;
+    };
 };
 /**
  * Multimodal message types - Re-exported from multimodal.ts
@@ -152,6 +175,18 @@ export type SessionIdentifier = {
     sessionId: string;
     userId?: string;
 };
+/**
+ * Options for storing a conversation turn
+ */
+export type StoreConversationTurnOptions = {
+    sessionId: string;
+    userId?: string;
+    userMessage: string;
+    aiResponse: string;
+    startTimeStamp?: Date;
+    providerDetails?: ProviderDetails;
+    enableSummarization?: boolean;
+};
 /**
  * Lightweight session metadata for efficient session listing
  * Contains only essential information without heavy message arrays
@@ -179,6 +214,16 @@ export type ConversationBase = {
     createdAt: string;
     /** When this conversation was last updated */
     updatedAt: string;
+    /** Pointer to last summarized message (token-based memory) */
+    summarizedUpToMessageId?: string;
+    /** Stored summary message that condenses conversation history up to summarizedUpToMessageId */
+    summarizedMessage?: string;
+    /** Per-session token threshold override */
+    tokenThreshold?: number;
+    /** Cached token count for efficiency */
+    lastTokenCount?: number;
+    /** Timestamp of last token count */
+    lastCountedAt?: number;
 };
 /**
  * Redis conversation storage object format
@@ -250,3 +295,7 @@ export type RedisStorageConfig = {
         [key: string]: string | number | boolean | undefined;
     };
 };
+export type ProviderDetails = {
+    provider: string;
+    model: string;
+};