@juspay/neurolink 7.11.0 → 7.12.0

package/dist/lib/neurolink.d.ts

@@ -11,6 +11,7 @@ import type { StreamOptions, StreamResult } from "./types/streamTypes.js";
 import type { SimpleTool } from "./sdk/toolRegistration.js";
 import type { InMemoryMCPServerConfig } from "./types/mcpTypes.js";
 import { EventEmitter } from "events";
+import type { ConversationMemoryConfig } from "./types/conversationTypes.js";
 export interface ProviderStatus {
     provider: string;
     status: "working" | "failed" | "not-configured";
@@ -55,7 +56,10 @@ export declare class NeuroLink {
      * @param success - Whether the tool execution was successful
      */
     private emitToolEndEvent;
-    constructor();
+    private conversationMemory?;
+    constructor(config?: {
+        conversationMemory?: Partial<ConversationMemoryConfig>;
+    });
     /**
      * Initialize MCP registry with enhanced error handling and resource cleanup
      * Uses isolated async context to prevent hanging
@@ -75,9 +79,11 @@ export declare class NeuroLink {
      * REDESIGNED INTERNAL GENERATION - NO CIRCULAR DEPENDENCIES
      *
      * This method implements a clean fallback chain:
-     * 1. Try MCP-enhanced generation if available
-     * 2. Fall back to direct provider generation
-     * 3. No recursive calls - each method has a specific purpose
+     * 1. Initialize conversation memory if enabled
+     * 2. Inject conversation history into prompt
+     * 3. Try MCP-enhanced generation if available
+     * 4. Fall back to direct provider generation
+     * 5. Store conversation turn for future context
      */
     private generateTextInternal;
     /**
@@ -367,6 +373,18 @@ export declare class NeuroLink {
             recommendations: string[];
         }>;
     };
+    /**
+     * Get conversation memory statistics (public API)
+     */
+    getConversationStats(): Promise<import("./types/conversationTypes.js").ConversationMemoryStats>;
+    /**
+     * Clear conversation history for a specific session (public API)
+     */
+    clearConversationSession(sessionId: string): Promise<boolean>;
+    /**
+     * Clear all conversation history (public API)
+     */
+    clearAllConversations(): Promise<void>;
 }
 export declare const neurolink: NeuroLink;
 export default neurolink;

package/dist/lib/neurolink.js

@@ -27,6 +27,8 @@ import { processFactoryOptions, enhanceTextGenerationOptions, validateFactoryCon
 // Enhanced error handling imports
 import { ErrorFactory, NeuroLinkError, withTimeout, withRetry, isRetriableError, logStructuredError, CircuitBreaker, } from "./utils/errorHandling.js";
 import { EventEmitter } from "events";
+import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
+import { applyConversationMemoryDefaults, getConversationMessages, storeConversationTurn, } from "./utils/conversationMemoryUtils.js";
 // Core types imported from core/types.js
 export class NeuroLink {
     mcpInitialized = false;
@@ -52,11 +54,22 @@ export class NeuroLink {
             timestamp: Date.now(),
         });
     }
-    constructor() {
+    // Conversation memory support
+    conversationMemory;
+    constructor(config) {
         // SDK always disables manual MCP config for security
         ProviderRegistry.setOptions({
             enableManualMCP: false,
         });
+        // Initialize conversation memory if enabled
+        if (config?.conversationMemory?.enabled) {
+            const memoryConfig = applyConversationMemoryDefaults(config.conversationMemory);
+            this.conversationMemory = new ConversationMemoryManager(memoryConfig);
+            logger.info("NeuroLink initialized with conversation memory", {
+                maxSessions: memoryConfig.maxSessions,
+                maxTurnsPerSession: memoryConfig.maxTurnsPerSession,
+            });
+        }
     }
     /**
      * Initialize MCP registry with enhanced error handling and resource cleanup
@@ -247,9 +260,11 @@ export class NeuroLink {
      * REDESIGNED INTERNAL GENERATION - NO CIRCULAR DEPENDENCIES
      *
      * This method implements a clean fallback chain:
-     * 1. Try MCP-enhanced generation if available
-     * 2. Fall back to direct provider generation
-     * 3. No recursive calls - each method has a specific purpose
+     * 1. Initialize conversation memory if enabled
+     * 2. Inject conversation history into prompt
+     * 3. Try MCP-enhanced generation if available
+     * 4. Fall back to direct provider generation
+     * 5. Store conversation turn for future context
      */
     async generateTextInternal(options) {
         const startTime = Date.now();
@@ -257,14 +272,21 @@ export class NeuroLink {
         logger.debug(`[${functionTag}] Starting generation`, {
             provider: options.provider || "auto",
             promptLength: options.prompt?.length || 0,
+            hasConversationMemory: !!this.conversationMemory,
         });
         try {
+            // Initialize conversation memory if enabled
+            if (this.conversationMemory) {
+                await this.conversationMemory.initialize();
+            }
             // Try MCP-enhanced generation first (if not explicitly disabled)
             if (!options.disableTools) {
                 try {
                     const mcpResult = await this.tryMCPGeneration(options);
                     if (mcpResult && mcpResult.content) {
                         logger.debug(`[${functionTag}] MCP generation successful`);
+                        // Store conversation turn
+                        await storeConversationTurn(this.conversationMemory, options, mcpResult);
                         return mcpResult;
                     }
                 }
@@ -277,6 +299,8 @@ export class NeuroLink {
             // Fall back to direct provider generation
             const directResult = await this.directProviderGeneration(options);
             logger.debug(`[${functionTag}] Direct generation successful`);
+            // Store conversation turn
+            await storeConversationTurn(this.conversationMemory, options, directResult);
             return directResult;
         }
         catch (error) {
@@ -334,6 +358,8 @@ export class NeuroLink {
             }
             // Create tool-aware system prompt
             const enhancedSystemPrompt = this.createToolAwareSystemPrompt(options.systemPrompt, availableTools);
+            // Get conversation messages for context
+            const conversationMessages = await getConversationMessages(this.conversationMemory, options);
             // Create provider and generate
             const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
             this);
@@ -345,6 +371,7 @@ export class NeuroLink {
             const result = await provider.generate({
                 ...options,
                 systemPrompt: enhancedSystemPrompt,
+                conversationMessages, // Inject conversation history
             });
             const responseTime = Date.now() - startTime;
             // Check if result is meaningful
@@ -413,6 +440,8 @@ export class NeuroLink {
         for (const providerName of tryProviders) {
             try {
                 logger.debug(`[${functionTag}] Attempting provider: ${providerName}`);
+                // Get conversation messages for context
+                const conversationMessages = await getConversationMessages(this.conversationMemory, options);
                 const provider = await AIProviderFactory.createProvider(providerName, options.model, !options.disableTools, // Pass disableTools as inverse of enableMCP
                 this);
                 // Enable tool execution for direct provider generation using BaseProvider method
@@ -420,7 +449,10 @@ export class NeuroLink {
                     customTools: this.customTools,
                     executeTool: this.executeTool.bind(this),
                 }, functionTag);
-                const result = await provider.generate(options);
+                const result = await provider.generate({
+                    ...options,
+                    conversationMessages, // Inject conversation history
+                });
                 const responseTime = Date.now() - startTime;
                 if (!result) {
                     throw new Error(`Provider ${providerName} returned null result`);
@@ -1577,6 +1609,36 @@ export class NeuroLink {
             tools,
         };
     }
+    // ============================================================================
+    // CONVERSATION MEMORY PUBLIC API
+    // ============================================================================
+    /**
+     * Get conversation memory statistics (public API)
+     */
+    async getConversationStats() {
+        if (!this.conversationMemory) {
+            throw new Error("Conversation memory is not enabled");
+        }
+        return await this.conversationMemory.getStats();
+    }
+    /**
+     * Clear conversation history for a specific session (public API)
+     */
+    async clearConversationSession(sessionId) {
+        if (!this.conversationMemory) {
+            throw new Error("Conversation memory is not enabled");
+        }
+        return await this.conversationMemory.clearSession(sessionId);
+    }
+    /**
+     * Clear all conversation history (public API)
+     */
+    async clearAllConversations() {
+        if (!this.conversationMemory) {
+            throw new Error("Conversation memory is not enabled");
+        }
+        await this.conversationMemory.clearAllSessions();
+    }
 }
 // Create default instance
 export const neurolink = new NeuroLink();

package/dist/lib/providers/amazonBedrock.js

@@ -5,6 +5,7 @@ import { logger } from "../utils/logger.js";
 import { TimeoutError, } from "../utils/timeout.js";
 import { DEFAULT_MAX_TOKENS } from "../core/constants.js";
 import { validateApiKey, createAWSAccessKeyConfig, createAWSSecretConfig, getAWSRegion, getAWSSessionToken, } from "../utils/providerConfig.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 // Configuration helpers
 const getBedrockModelId = () => {
     return (process.env.BEDROCK_MODEL ||
@@ -79,10 +80,11 @@ export class AmazonBedrockProvider extends BaseProvider {
     async executeStream(options, analysisSchema) {
         try {
             this.validateStreamOptions(options);
+            // Build message array from options
+            const messages = buildMessagesArray(options);
             const result = await streamText({
                 model: this.model,
-                prompt: options.input.text,
-                system: options.systemPrompt,
+                messages: messages,
                 maxTokens: options.maxTokens || DEFAULT_MAX_TOKENS,
                 temperature: options.temperature,
             });

package/dist/lib/providers/anthropic.js

@@ -5,6 +5,7 @@ import { logger } from "../utils/logger.js";
 import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { DEFAULT_MAX_TOKENS, DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { validateApiKey, createAnthropicConfig, getProviderModel, } from "../utils/providerConfig.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 // Configuration helpers - now using consolidated utility
 const getAnthropicApiKey = () => {
     return validateApiKey(createAnthropicConfig());
@@ -94,10 +95,11 @@ export class AnthropicProvider extends BaseProvider {
             // ✅ Get tools for streaming (same as generate method)
             const shouldUseTools = !options.disableTools && this.supportsTools();
             const tools = shouldUseTools ? await this.getAllTools() : {};
+            // Build message array from options
+            const messages = buildMessagesArray(options);
             const result = await streamText({
                 model: this.model,
-                prompt: options.input.text,
-                system: options.systemPrompt || undefined,
+                messages: messages,
                 temperature: options.temperature,
                 maxTokens: options.maxTokens || DEFAULT_MAX_TOKENS,
                 tools,

package/dist/lib/providers/azureOpenai.js

@@ -3,6 +3,7 @@ import { streamText } from "ai";
 import { BaseProvider } from "../core/baseProvider.js";
 import { validateApiKey, createAzureAPIKeyConfig, createAzureEndpointConfig, } from "../utils/providerConfig.js";
 import { logger } from "../utils/logger.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 export class AzureOpenAIProvider extends BaseProvider {
     apiKey;
     resourceName;
@@ -69,12 +70,13 @@ export class AzureOpenAIProvider extends BaseProvider {
     // executeGenerate removed - BaseProvider handles all generation with tools
     async executeStream(options, analysisSchema) {
         try {
+            // Build message array from options
+            const messages = buildMessagesArray(options);
             const stream = await streamText({
                 model: this.azureProvider(this.deployment),
-                prompt: options.input?.text || "",
+                messages: messages,
                 maxTokens: options.maxTokens || 1000,
                 temperature: options.temperature || 0.7,
-                system: options.systemPrompt,
             });
             return {
                 stream: (async function* () {

package/dist/lib/providers/googleAiStudio.js

@@ -6,6 +6,7 @@ import { logger } from "../utils/logger.js";
 import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { DEFAULT_MAX_TOKENS, DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 // Environment variable setup
 if (!process.env.GOOGLE_GENERATIVE_AI_API_KEY &&
     process.env.GOOGLE_AI_API_KEY) {
@@ -76,10 +77,11 @@ export class GoogleAIStudioProvider extends BaseProvider {
             // Get tools consistently with generate method
             const shouldUseTools = !options.disableTools && this.supportsTools();
             const tools = shouldUseTools ? await this.getAllTools() : {};
+            // Build message array from options
+            const messages = buildMessagesArray(options);
             const result = await streamText({
                 model,
-                prompt: options.input.text,
-                system: options.systemPrompt,
+                messages: messages,
                 temperature: options.temperature,
                 maxTokens: options.maxTokens || DEFAULT_MAX_TOKENS,
                 tools,

package/dist/lib/providers/googleVertex.js

@@ -6,6 +6,7 @@ import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { DEFAULT_MAX_TOKENS, DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { ModelConfigurationManager } from "../core/modelConfiguration.js";
 import { validateApiKey, createVertexProjectConfig, createGoogleAuthConfig, } from "../utils/providerConfig.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 // Cache for anthropic module to avoid repeated imports
 let _createVertexAnthropic = null;
 let _anthropicImportAttempted = false;
@@ -189,6 +190,8 @@ export class GoogleVertexProvider extends BaseProvider {
         const timeoutController = createTimeoutController(timeout, this.providerName, "stream");
         try {
             this.validateStreamOptions(options);
+            // Build message array from options
+            const messages = buildMessagesArray(options);
             logger.debug(`${functionTag}: Starting stream request`, {
                 modelName: this.modelName,
                 promptLength: options.input.text.length,
@@ -209,8 +212,7 @@ export class GoogleVertexProvider extends BaseProvider {
             // Build complete stream options with proper typing
             let streamOptions = {
                 model: model,
-                prompt: options.input.text,
-                system: options.systemPrompt,
+                messages: messages,
                 temperature: options.temperature,
                 ...(maxTokens && { maxTokens }),
                 tools,

package/dist/lib/providers/huggingFace.js

@@ -5,6 +5,7 @@ import { logger } from "../utils/logger.js";
 import { createTimeoutController, TimeoutError } from "../utils/timeout.js";
 import { DEFAULT_MAX_TOKENS } from "../core/constants.js";
 import { validateApiKey, createHuggingFaceConfig, getProviderModel, } from "../utils/providerConfig.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 // Configuration helpers - now using consolidated utility
 const getHuggingFaceApiKey = () => {
     return validateApiKey(createHuggingFaceConfig());
@@ -111,10 +112,11 @@ export class HuggingFaceProvider extends BaseProvider {
         try {
             // Enhanced tool handling for HuggingFace models
             const streamOptions = this.prepareStreamOptions(options, analysisSchema);
+            // Build message array from options
+            const messages = buildMessagesArray(options);
             const result = await streamText({
                 model: this.model,
-                prompt: streamOptions.prompt,
-                system: streamOptions.system,
+                messages: messages,
                 temperature: options.temperature,
                 maxTokens: options.maxTokens || DEFAULT_MAX_TOKENS,
                 tools: streamOptions.tools, // Tools format conversion handled by prepareStreamOptions

package/dist/lib/providers/litellm.js

@@ -6,6 +6,7 @@ import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { DEFAULT_MAX_TOKENS } from "../core/constants.js";
 import { getProviderModel } from "../utils/providerConfig.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 // Configuration helpers
 const getLiteLLMConfig = () => {
     return {
@@ -118,10 +119,11 @@ export class LiteLLMProvider extends BaseProvider {
         const timeout = this.getTimeout(options);
         const timeoutController = createTimeoutController(timeout, this.providerName, "stream");
         try {
+            // Build message array from options
+            const messages = buildMessagesArray(options);
             const result = await streamText({
                 model: this.model,
-                prompt: options.input.text,
-                system: options.systemPrompt,
+                messages: messages,
                 temperature: options.temperature,
                 maxTokens: options.maxTokens || DEFAULT_MAX_TOKENS,
                 tools: options.tools,

package/dist/lib/providers/mistral.js

@@ -6,6 +6,7 @@ import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { DEFAULT_MAX_TOKENS, DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { validateApiKey, createMistralConfig, getProviderModel, } from "../utils/providerConfig.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 // Configuration helpers - now using consolidated utility
 const getMistralApiKey = () => {
     return validateApiKey(createMistralConfig());
@@ -46,10 +47,10 @@ export class MistralProvider extends BaseProvider {
             // Get tools consistently with generate method
             const shouldUseTools = !options.disableTools && this.supportsTools();
             const tools = shouldUseTools ? await this.getAllTools() : {};
+            const messages = buildMessagesArray(options);
             const result = await streamText({
                 model: this.model,
-                prompt: options.input.text,
-                system: options.systemPrompt,
+                messages: messages,
                 temperature: options.temperature,
                 maxTokens: options.maxTokens || DEFAULT_MAX_TOKENS,
                 tools,

package/dist/lib/providers/openAI.js

@@ -7,6 +7,7 @@ import { createTimeoutController, TimeoutError, } from "../utils/timeout.js";
 import { DEFAULT_MAX_TOKENS, DEFAULT_MAX_STEPS } from "../core/constants.js";
 import { validateApiKey, createOpenAIConfig, getProviderModel, } from "../utils/providerConfig.js";
 import { streamAnalyticsCollector } from "../core/streamAnalytics.js";
+import { buildMessagesArray } from "../utils/messageBuilder.js";
 // Configuration helpers - now using consolidated utility
 const getOpenAIApiKey = () => {
     return validateApiKey(createOpenAIConfig());
@@ -77,10 +78,11 @@ export class OpenAIProvider extends BaseProvider {
             // Get tools consistently with generate method
             const shouldUseTools = !options.disableTools && this.supportsTools();
             const tools = shouldUseTools ? await this.getAllTools() : {};
+            // Build message array from options
+            const messages = buildMessagesArray(options);
             const result = await streamText({
                 model: this.model,
-                prompt: options.input.text,
-                system: options.systemPrompt,
+                messages: messages,
                 temperature: options.temperature,
                 maxTokens: options.maxTokens || DEFAULT_MAX_TOKENS,
                 tools,

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

@@ -0,0 +1,95 @@
+/**
+ * Conversation Memory Types for NeuroLink
+ * Provides type-safe conversation storage and context management
+ */
+/**
+ * Configuration for conversation memory feature
+ */
+export interface ConversationMemoryConfig {
+    /** Enable conversation memory feature */
+    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;
+}
+/**
+ * Complete memory for a conversation session
+ * ULTRA-OPTIMIZED: Direct ChatMessage[] storage - zero conversion overhead
+ */
+export interface SessionMemory {
+    /** Unique session identifier */
+    sessionId: string;
+    /** User identifier (optional) */
+    userId?: string;
+    /** Direct message storage - ready for immediate AI consumption */
+    messages: ChatMessage[];
+    /** When this session was created */
+    createdAt: number;
+    /** When this session was last active */
+    lastActivity: number;
+    /** Optional session metadata */
+    metadata?: {
+        /** User role or permissions */
+        userRole?: string;
+        /** Tags for categorizing this session */
+        tags?: string[];
+        /** Custom data specific to the organization */
+        customData?: Record<string, unknown>;
+    };
+}
+/**
+ * Statistics about conversation memory usage (simplified for pure in-memory storage)
+ */
+export interface ConversationMemoryStats {
+    /** Total number of active sessions */
+    totalSessions: number;
+    /** Total number of conversation turns across all sessions */
+    totalTurns: number;
+}
+/**
+ * Chat message format for conversation history
+ */
+export interface ChatMessage {
+    /** Role of the message sender */
+    role: "user" | "assistant" | "system";
+    /** Content of the message */
+    content: string;
+}
+/**
+ * Events emitted by conversation memory system
+ */
+export interface ConversationMemoryEvents {
+    /** Emitted when a new session is created */
+    "session:created": {
+        sessionId: string;
+        userId?: string;
+        timestamp: number;
+    };
+    /** Emitted when a conversation turn is stored */
+    "turn:stored": {
+        sessionId: string;
+        turnIndex: number;
+        timestamp: number;
+    };
+    /** Emitted when a session is cleaned up */
+    "session:cleanup": {
+        sessionId: string;
+        reason: "expired" | "limit_exceeded";
+        timestamp: number;
+    };
+    /** Emitted when context is injected */
+    "context:injected": {
+        sessionId: string;
+        turnsIncluded: number;
+        timestamp: number;
+    };
+}
+/**
+ * Error types specific to conversation memory
+ */
+export declare class ConversationMemoryError extends Error {
+    code: "STORAGE_ERROR" | "CONFIG_ERROR" | "SESSION_NOT_FOUND" | "CLEANUP_ERROR";
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: "STORAGE_ERROR" | "CONFIG_ERROR" | "SESSION_NOT_FOUND" | "CLEANUP_ERROR", details?: Record<string, unknown> | undefined);
+}

package/dist/lib/types/conversationTypes.js

@@ -0,0 +1,17 @@
+/**
+ * Conversation Memory Types for NeuroLink
+ * Provides type-safe conversation storage and context management
+ */
+/**
+ * Error types specific to conversation memory
+ */
+export class ConversationMemoryError extends Error {
+    code;
+    details;
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "ConversationMemoryError";
+    }
+}

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

@@ -2,6 +2,7 @@ import type { ZodType, ZodTypeDef } from "zod";
 import type { Tool, Schema } from "ai";
 import type { AIProviderName, AnalyticsData, EvaluationData } from "../core/types.js";
 import type { UnknownRecord, JsonValue } from "./common.js";
+import type { ChatMessage } from "./conversationTypes.js";
 /**
  * Interface for tool execution calls (AI SDK compatible)
  */
@@ -107,6 +108,7 @@ export interface StreamOptions {
         enableProgress?: boolean;
         fallbackToGenerate?: boolean;
     };
+    conversationMessages?: ChatMessage[];
 }
 /**
  * Stream function result interface - Primary output format for streaming

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

@@ -0,0 +1,22 @@
+/**
+ * Conversation Memory Utilities
+ * Handles configuration merging and conversation memory operations
+ */
+import type { ConversationMemoryConfig, ChatMessage } from "../types/conversationTypes.js";
+import type { ConversationMemoryManager } from "../core/conversationMemoryManager.js";
+import type { TextGenerationOptions, TextGenerationResult } from "../core/types.js";
+/**
+ * Apply conversation memory defaults to user configuration
+ * Merges user config with environment variables and default values
+ */
+export declare function applyConversationMemoryDefaults(userConfig?: Partial<ConversationMemoryConfig>): ConversationMemoryConfig;
+/**
+ * Get conversation history as message array (PREFERRED METHOD)
+ * Returns proper message array format for AI providers
+ */
+export declare function getConversationMessages(conversationMemory: ConversationMemoryManager | undefined, options: TextGenerationOptions): Promise<ChatMessage[]>;
+/**
+ * Store conversation turn for future context
+ * Saves user messages and AI responses for conversation memory
+ */
+export declare function storeConversationTurn(conversationMemory: ConversationMemoryManager | undefined, originalOptions: TextGenerationOptions, result: TextGenerationResult): Promise<void>;

package/dist/lib/utils/conversationMemoryUtils.js

@@ -0,0 +1,77 @@
+/**
+ * Conversation Memory Utilities
+ * Handles configuration merging and conversation memory operations
+ */
+import { getConversationMemoryDefaults } from "../config/conversationMemoryConfig.js";
+import { logger } from "./logger.js";
+/**
+ * Apply conversation memory defaults to user configuration
+ * Merges user config with environment variables and default values
+ */
+export function applyConversationMemoryDefaults(userConfig) {
+    const defaults = getConversationMemoryDefaults();
+    return {
+        enabled: userConfig?.enabled ?? defaults.enabled,
+        maxSessions: userConfig?.maxSessions ?? defaults.maxSessions,
+        maxTurnsPerSession: userConfig?.maxTurnsPerSession ?? defaults.maxTurnsPerSession,
+    };
+}
+/**
+ * Get conversation history as message array (PREFERRED METHOD)
+ * Returns proper message array format for AI providers
+ */
+export async function getConversationMessages(conversationMemory, options) {
+    if (!conversationMemory || !options.context) {
+        return [];
+    }
+    const sessionId = options.context?.sessionId;
+    if (typeof sessionId !== "string" || !sessionId) {
+        return [];
+    }
+    try {
+        const messages = conversationMemory.buildContextMessages(sessionId);
+        logger.debug("Conversation messages retrieved", {
+            sessionId,
+            messageCount: messages.length,
+        });
+        return messages;
+    }
+    catch (error) {
+        logger.warn("Failed to get conversation messages", {
+            sessionId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return [];
+    }
+}
+/**
+ * Store conversation turn for future context
+ * Saves user messages and AI responses for conversation memory
+ */
+export async function storeConversationTurn(conversationMemory, originalOptions, result) {
+    if (!conversationMemory || !originalOptions.context) {
+        return;
+    }
+    const context = originalOptions.context;
+    const sessionId = context.sessionId;
+    const userId = typeof context.userId === "string" ? context.userId : undefined;
+    if (typeof sessionId !== "string" || !sessionId) {
+        return;
+    }
+    try {
+        await conversationMemory.storeConversationTurn(sessionId, userId, originalOptions.prompt || "", result.content);
+        logger.debug("Conversation turn stored", {
+            sessionId,
+            userId,
+            promptLength: originalOptions.prompt?.length || 0,
+            responseLength: result.content.length,
+        });
+    }
+    catch (error) {
+        logger.warn("Failed to store conversation turn", {
+            sessionId,
+            userId,
+            error: error instanceof Error ? error.message : String(error),
+        });
+    }
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Message Builder Utility
+ * Centralized logic for building message arrays from TextGenerationOptions
+ */
+import type { ChatMessage } from "../types/conversationTypes.js";
+import type { TextGenerationOptions } from "../core/types.js";
+import type { StreamOptions } from "../types/streamTypes.js";
+/**
+ * Build a properly formatted message array for AI providers
+ * Combines system prompt, conversation history, and current user prompt
+ * Supports both TextGenerationOptions and StreamOptions
+ */
+export declare function buildMessagesArray(options: TextGenerationOptions | StreamOptions): ChatMessage[];