@hashgraphonline/conversational-agent 0.1.204 → 0.1.206

package/dist/cjs/langchain-agent.d.ts

@@ -4,6 +4,7 @@ export declare class LangChainAgent extends BaseAgent {
     private executor;
     private systemMessage;
     private mcpManager?;
+    private smartMemory;
     boot(): Promise<void>;
     chat(message: string, context?: ConversationContext): Promise<ChatResponse>;
     shutdown(): Promise<void>;

package/dist/cjs/mcp/ContentProcessor.d.ts

@@ -0,0 +1,37 @@
+import { ContentStorage } from '../memory/ContentStorage';
+import { Logger } from '@hashgraphonline/standards-sdk';
+
+export interface MCPResponseContent {
+    content: unknown;
+    type: 'text' | 'image' | 'resource' | 'text[]' | 'image[]';
+    sizeBytes: number;
+    mimeType?: string;
+}
+export interface ProcessedResponse {
+    content: unknown;
+    wasProcessed: boolean;
+    referenceCreated?: boolean;
+    referenceId?: string;
+    originalSize?: number;
+    errors?: string[];
+}
+export interface ContentAnalysis {
+    shouldProcess: boolean;
+    contents: MCPResponseContent[];
+    totalSize: number;
+    largestContentSize: number;
+}
+export declare class MCPContentProcessor {
+    private contentStorage;
+    private logger;
+    constructor(contentStorage: ContentStorage, logger: Logger);
+    analyzeResponse(response: unknown): ContentAnalysis;
+    processResponse(response: unknown, serverName: string, toolName: string): Promise<ProcessedResponse>;
+    private extractContentFromResponse;
+    private createReferencedResponse;
+    private createLightweightReference;
+    private replaceContentInResponse;
+    private detectMimeType;
+    private mapMimeTypeToContentType;
+    private deepClone;
+}

package/dist/cjs/mcp/MCPClientManager.d.ts

@@ -1,5 +1,6 @@
 import { MCPServerConfig, MCPToolInfo, MCPConnectionStatus } from './types';
 import { Logger } from '@hashgraphonline/standards-sdk';
+import { ContentStorage } from '../memory/ContentStorage';
 
 /**
  * Manages connections to MCP servers and tool discovery
@@ -8,7 +9,8 @@ export declare class MCPClientManager {
     private clients;
     private tools;
     private logger;
-    constructor(logger: Logger);
+    private contentProcessor?;
+    constructor(logger: Logger, contentStorage?: ContentStorage);
     /**
      * Connect to an MCP server and discover its tools
      */
@@ -37,4 +39,20 @@ export declare class MCPClientManager {
      * Get list of connected server names
      */
     getConnectedServers(): string[];
+    /**
+     * Enable content processing with content storage
+     */
+    enableContentProcessing(contentStorage: ContentStorage): void;
+    /**
+     * Disable content processing
+     */
+    disableContentProcessing(): void;
+    /**
+     * Check if content processing is enabled
+     */
+    isContentProcessingEnabled(): boolean;
+    /**
+     * Analyze a response without processing it (for testing/debugging)
+     */
+    analyzeResponseContent(response: unknown): unknown;
 }

package/dist/cjs/memory/ContentStorage.d.ts

@@ -0,0 +1,205 @@
+import { BaseMessage } from '@langchain/core/messages';
+import { ReferenceId, ContentReference, ContentMetadata, ReferenceResolutionResult, ContentReferenceConfig, ContentReferenceStore, ContentReferenceStats, ContentType, ContentSource } from '../types/content-reference';
+
+/**
+ * Search options for message queries
+ */
+interface SearchOptions {
+    /** Whether to perform case-sensitive search */
+    caseSensitive?: boolean;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Whether to use regex pattern matching */
+    useRegex?: boolean;
+}
+/**
+ * Result of storing messages
+ */
+interface StoreResult {
+    /** Number of messages successfully stored */
+    stored: number;
+    /** Number of old messages dropped to make room */
+    dropped: number;
+}
+/**
+ * Storage statistics
+ */
+export interface StorageStats {
+    /** Total number of messages currently stored */
+    totalMessages: number;
+    /** Maximum storage capacity */
+    maxStorageLimit: number;
+    /** Percentage of storage used */
+    usagePercentage: number;
+    /** Timestamp of oldest message */
+    oldestMessageTime: Date | undefined;
+    /** Timestamp of newest message */
+    newestMessageTime: Date | undefined;
+}
+/**
+ * Content storage for managing pruned conversation messages and large content references
+ * Provides searchable storage with time-based querying and automatic cleanup.
+ *
+ * Extended to support reference-based storage for large content to optimize context window usage.
+ */
+export declare class ContentStorage implements ContentReferenceStore {
+    private messages;
+    private maxStorage;
+    private idCounter;
+    private contentStore;
+    private referenceConfig;
+    private cleanupTimer?;
+    private referenceStats;
+    static readonly DEFAULT_MAX_STORAGE = 1000;
+    constructor(maxStorage?: number, referenceConfig?: Partial<ContentReferenceConfig>);
+    /**
+     * Store messages in the content storage
+     * Automatically drops oldest messages if storage limit is exceeded
+     * @param messages - Messages to store
+     * @returns Result indicating how many messages were stored and dropped
+     */
+    storeMessages(messages: BaseMessage[]): StoreResult;
+    /**
+     * Get the most recent messages from storage
+     * @param count - Number of recent messages to retrieve
+     * @returns Array of recent messages in chronological order
+     */
+    getRecentMessages(count: number): BaseMessage[];
+    /**
+     * Search for messages containing specific text or patterns
+     * @param query - Search term or regex pattern
+     * @param options - Search configuration options
+     * @returns Array of matching messages
+     */
+    searchMessages(query: string, options?: SearchOptions): BaseMessage[];
+    /**
+     * Get messages from a specific time range
+     * @param startTime - Start of time range (inclusive)
+     * @param endTime - End of time range (inclusive)
+     * @returns Array of messages within the time range
+     */
+    getMessagesFromTimeRange(startTime: Date, endTime: Date): BaseMessage[];
+    /**
+     * Get storage statistics and usage information
+     * @returns Current storage statistics
+     */
+    getStorageStats(): StorageStats;
+    /**
+     * Clear all stored messages
+     */
+    clear(): void;
+    /**
+     * Get total number of stored messages
+     * @returns Number of messages currently in storage
+     */
+    getTotalStoredMessages(): number;
+    /**
+     * Update the maximum storage limit
+     * @param newLimit - New maximum storage limit
+     */
+    updateStorageLimit(newLimit: number): void;
+    /**
+     * Get messages by message type
+     * @param messageType - Type of messages to retrieve ('human', 'ai', 'system', etc.)
+     * @param limit - Maximum number of messages to return
+     * @returns Array of messages of the specified type
+     */
+    getMessagesByType(messageType: string, limit?: number): BaseMessage[];
+    /**
+     * Get the current storage configuration
+     * @returns Storage configuration object
+     */
+    getConfig(): {
+        maxStorage: number;
+        currentUsage: number;
+        utilizationPercentage: number;
+    };
+    /**
+     * Generate a unique ID for stored messages
+     * @returns Unique string identifier
+     */
+    private generateId;
+    /**
+     * Get messages stored within the last N minutes
+     * @param minutes - Number of minutes to look back
+     * @returns Array of messages from the last N minutes
+     */
+    getRecentMessagesByTime(minutes: number): BaseMessage[];
+    /**
+     * Export messages to a JSON-serializable format
+     * @returns Serializable representation of stored messages
+     */
+    exportMessages(): {
+        content: import('@langchain/core/messages').MessageContent;
+        type: import('@langchain/core/messages').MessageType;
+        storedAt: string;
+        id: string;
+    }[];
+    /**
+     * Determine if content should be stored as a reference based on size
+     */
+    shouldUseReference(content: Buffer | string): boolean;
+    /**
+     * Store content and return a reference if it exceeds the size threshold
+     * Otherwise returns null to indicate direct content should be used
+     */
+    storeContentIfLarge(content: Buffer | string, metadata: {
+        contentType?: ContentType;
+        mimeType?: string;
+        source: ContentSource;
+        mcpToolName?: string;
+        fileName?: string;
+        tags?: string[];
+        customMetadata?: Record<string, unknown>;
+    }): Promise<ContentReference | null>;
+    /**
+     * Store content and return a reference (implements ContentReferenceStore)
+     */
+    storeContent(content: Buffer, metadata: Omit<ContentMetadata, 'createdAt' | 'lastAccessedAt' | 'accessCount'>): Promise<ContentReference>;
+    /**
+     * Resolve a reference to its content (implements ContentReferenceStore)
+     */
+    resolveReference(referenceId: ReferenceId): Promise<ReferenceResolutionResult>;
+    /**
+     * Check if a reference exists and is valid
+     */
+    hasReference(referenceId: ReferenceId): Promise<boolean>;
+    /**
+     * Mark a reference for cleanup
+     */
+    cleanupReference(referenceId: ReferenceId): Promise<boolean>;
+    /**
+     * Get current reference storage statistics (implements ContentReferenceStore)
+     */
+    getStats(): Promise<ContentReferenceStats>;
+    /**
+     * Update reference configuration
+     */
+    updateConfig(config: Partial<ContentReferenceConfig>): Promise<void>;
+    /**
+     * Perform cleanup based on current policies (implements ContentReferenceStore)
+     */
+    performCleanup(): Promise<{
+        cleanedUp: number;
+        errors: string[];
+    }>;
+    /**
+     * Get reference configuration for debugging
+     */
+    getReferenceConfig(): ContentReferenceConfig;
+    private enforceReferenceStorageLimits;
+    private calculateExpirationTime;
+    private getCleanupPolicy;
+    private detectContentType;
+    private createContentPreview;
+    private updateStatsAfterStore;
+    private updateReferenceStorageStats;
+    private recordPerformanceMetric;
+    private calculateAverage;
+    private startReferenceCleanupTimer;
+    /**
+     * Clean up resources (enhanced to include reference cleanup)
+     */
+    dispose(): Promise<void>;
+}
+export {};

package/dist/cjs/memory/MemoryWindow.d.ts

@@ -0,0 +1,114 @@
+import { BaseMessage } from '@langchain/core/messages';
+import { TokenCounter } from './TokenCounter';
+
+/**
+ * Result of adding a message to the memory window
+ */
+export interface AddMessageResult {
+    /** Whether the message was successfully added */
+    added: boolean;
+    /** Messages that were pruned to make room */
+    prunedMessages: BaseMessage[];
+    /** Current token count after operation */
+    currentTokenCount: number;
+    /** Remaining token capacity */
+    remainingCapacity: number;
+}
+/**
+ * Memory window that manages conversation history with token-based size limits
+ * Automatically prunes old messages to stay within token limits while preserving conversational context
+ */
+export declare class MemoryWindow {
+    private messages;
+    private maxTokens;
+    private reserveTokens;
+    private tokenCounter;
+    private systemPrompt;
+    private systemPromptTokens;
+    static readonly DEFAULT_MAX_TOKENS = 8000;
+    static readonly DEFAULT_RESERVE_TOKENS = 1000;
+    static readonly PRUNING_BATCH_SIZE = 2;
+    constructor(maxTokens?: number, reserveTokens?: number, tokenCounter?: TokenCounter);
+    /**
+     * Add a message to the memory window, pruning old messages if necessary
+     * @param message - The message to add
+     * @returns Result of the add operation including any pruned messages
+     */
+    addMessage(message: BaseMessage): AddMessageResult;
+    /**
+     * Prune old messages to fit within token limits
+     * Removes messages in pairs to maintain conversational flow
+     * @returns Array of pruned messages
+     */
+    pruneToFit(): BaseMessage[];
+    /**
+     * Get current token count including system prompt and messages
+     * @returns Current token count
+     */
+    getCurrentTokenCount(): number;
+    /**
+     * Get remaining token capacity before hitting the reserve limit
+     * @returns Remaining tokens that can be used
+     */
+    getRemainingTokenCapacity(): number;
+    /**
+     * Check if a message can be added without exceeding limits
+     * @param message - The message to check
+     * @returns True if message can be added within reserve limits
+     */
+    canAddMessage(message: BaseMessage): boolean;
+    /**
+     * Get all messages in the memory window
+     * @returns Copy of current messages array
+     */
+    getMessages(): BaseMessage[];
+    /**
+     * Clear all messages from the memory window
+     */
+    clear(): void;
+    /**
+     * Set the system prompt and update token calculations
+     * @param systemPrompt - The system prompt text
+     */
+    setSystemPrompt(systemPrompt: string): void;
+    /**
+     * Get the current system prompt
+     * @returns Current system prompt
+     */
+    getSystemPrompt(): string;
+    /**
+     * Get current configuration
+     * @returns Memory window configuration
+     */
+    getConfig(): {
+        maxTokens: number;
+        reserveTokens: number;
+        currentTokens: number;
+        messageCount: number;
+        systemPromptTokens: number;
+    };
+    /**
+     * Update token limits
+     * @param maxTokens - New maximum token limit
+     * @param reserveTokens - New reserve token amount
+     */
+    updateLimits(maxTokens: number, reserveTokens?: number): void;
+    /**
+     * Get statistics about the memory window
+     * @returns Memory usage statistics
+     */
+    getStats(): {
+        totalMessages: number;
+        currentTokens: number;
+        maxTokens: number;
+        reserveTokens: number;
+        systemPromptTokens: number;
+        usagePercentage: number;
+        remainingCapacity: number;
+        canAcceptMore: boolean;
+    };
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}

package/dist/cjs/memory/ReferenceIdGenerator.d.ts

@@ -0,0 +1,45 @@
+import { ReferenceId } from '../types/content-reference';
+
+/**
+ * Content-based reference ID generator using SHA-256 (HCS-1 style)
+ *
+ * Generates deterministic reference IDs based on content hashing.
+ * Same content always produces the same reference ID.
+ */
+export declare class ReferenceIdGenerator {
+    /**
+     * Generate a content-based reference ID using SHA-256 hashing
+     *
+     * @param content The content to generate a reference ID for
+     * @returns Deterministic reference ID based on content hash
+     */
+    static generateId(content: Buffer): ReferenceId;
+    /**
+     * Validate that a string is a properly formatted reference ID
+     *
+     * @param id The ID to validate
+     * @returns true if the ID is valid format
+     */
+    static isValidReferenceId(id: string): id is ReferenceId;
+    /**
+     * Extract reference ID from ref:// format
+     *
+     * @param input Input string that may contain a reference ID
+     * @returns Extracted reference ID or null if not found
+     */
+    static extractReferenceId(input: string): ReferenceId | null;
+    /**
+     * Format a reference ID in the standard ref:// format
+     *
+     * @param referenceId The reference ID to format
+     * @returns Formatted reference string
+     */
+    static formatReference(referenceId: ReferenceId): string;
+    /**
+     * Generate a test reference ID (for testing purposes only)
+     *
+     * @param testSeed A test seed to generate a fake but valid ID format
+     * @returns A valid format reference ID for testing
+     */
+    static generateTestId(testSeed: string): ReferenceId;
+}

package/dist/cjs/memory/SmartMemoryManager.d.ts

@@ -0,0 +1,201 @@
+import { BaseMessage } from '@langchain/core/messages';
+
+/**
+ * Configuration for SmartMemoryManager
+ */
+export interface SmartMemoryConfig {
+    /** Maximum tokens for active memory window */
+    maxTokens?: number;
+    /** Reserve tokens for response generation */
+    reserveTokens?: number;
+    /** Model name for token counting */
+    modelName?: string;
+    /** Maximum messages to store in content storage */
+    storageLimit?: number;
+}
+/**
+ * Search options for history search
+ */
+export interface SearchOptions {
+    /** Whether to perform case-sensitive search */
+    caseSensitive?: boolean;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Whether to use regex pattern matching */
+    useRegex?: boolean;
+}
+/**
+ * Memory statistics for active memory window
+ */
+export interface MemoryStats {
+    /** Total active messages in memory window */
+    totalActiveMessages: number;
+    /** Current token count including system prompt */
+    currentTokenCount: number;
+    /** Maximum token capacity */
+    maxTokens: number;
+    /** Remaining token capacity */
+    remainingCapacity: number;
+    /** System prompt token count */
+    systemPromptTokens: number;
+    /** Memory usage percentage */
+    usagePercentage: number;
+}
+/**
+ * Smart memory manager that combines active memory window with long-term storage
+ * Provides context-aware memory management with automatic pruning and searchable history
+ */
+export declare class SmartMemoryManager {
+    private memoryWindow;
+    private contentStorage;
+    private tokenCounter;
+    private config;
+    private static readonly DEFAULT_CONFIG;
+    constructor(config?: SmartMemoryConfig);
+    /**
+     * Add a message to the active memory window
+     * Automatically handles pruning and storage of displaced messages
+     * @param message - Message to add
+     */
+    addMessage(message: BaseMessage): void;
+    /**
+     * Get all active messages from the memory window
+     * @returns Array of active messages in chronological order
+     */
+    getMessages(): BaseMessage[];
+    /**
+     * Clear active memory window
+     * @param clearStorage - Whether to also clear the content storage (default: false)
+     */
+    clear(clearStorage?: boolean): void;
+    /**
+     * Set the system prompt for the memory window
+     * @param systemPrompt - System prompt text
+     */
+    setSystemPrompt(systemPrompt: string): void;
+    /**
+     * Get the current system prompt
+     * @returns Current system prompt text
+     */
+    getSystemPrompt(): string;
+    /**
+     * Search through stored message history
+     * @param query - Search term or pattern
+     * @param options - Search configuration
+     * @returns Array of matching messages from history
+     */
+    searchHistory(query: string, options?: SearchOptions): BaseMessage[];
+    /**
+     * Get recent messages from storage history
+     * @param count - Number of recent messages to retrieve
+     * @returns Array of recent messages from storage
+     */
+    getRecentHistory(count: number): BaseMessage[];
+    /**
+     * Check if a message can be added without exceeding limits
+     * @param message - Message to test
+     * @returns True if message can be added
+     */
+    canAddMessage(message: BaseMessage): boolean;
+    /**
+     * Get statistics about the active memory window
+     * @returns Memory usage statistics
+     */
+    getMemoryStats(): MemoryStats;
+    /**
+     * Get statistics about the content storage
+     * @returns Storage usage statistics
+     */
+    getStorageStats(): import('./ContentStorage').StorageStats;
+    /**
+     * Get combined statistics for both active memory and storage
+     * @returns Combined memory and storage statistics
+     */
+    getOverallStats(): {
+        activeMemory: MemoryStats;
+        storage: import('./ContentStorage').StorageStats;
+        totalMessagesManaged: number;
+        activeMemoryUtilization: number;
+        storageUtilization: number;
+    };
+    /**
+     * Update the configuration and apply changes
+     * @param newConfig - New configuration options
+     */
+    updateConfig(newConfig: Partial<SmartMemoryConfig>): void;
+    /**
+     * Get current configuration
+     * @returns Current configuration settings
+     */
+    getConfig(): Required<SmartMemoryConfig>;
+    /**
+     * Get messages from storage within a time range
+     * @param startTime - Start of time range
+     * @param endTime - End of time range
+     * @returns Messages within the specified time range
+     */
+    getHistoryFromTimeRange(startTime: Date, endTime: Date): BaseMessage[];
+    /**
+     * Get messages from storage by message type
+     * @param messageType - Type of messages to retrieve ('human', 'ai', 'system', etc.)
+     * @param limit - Maximum number of messages to return
+     * @returns Messages of the specified type
+     */
+    getHistoryByType(messageType: string, limit?: number): BaseMessage[];
+    /**
+     * Get recent messages from storage within the last N minutes
+     * @param minutes - Number of minutes to look back
+     * @returns Messages from the last N minutes
+     */
+    getRecentHistoryByTime(minutes: number): BaseMessage[];
+    /**
+     * Export the current state for persistence or analysis
+     * @returns Serializable representation of memory state
+     */
+    exportState(): {
+        config: Required<SmartMemoryConfig>;
+        activeMessages: {
+            content: import('@langchain/core/messages').MessageContent;
+            type: import('@langchain/core/messages').MessageType;
+        }[];
+        systemPrompt: string;
+        memoryStats: MemoryStats;
+        storageStats: import('./ContentStorage').StorageStats;
+        storedMessages: {
+            content: import('@langchain/core/messages').MessageContent;
+            type: import('@langchain/core/messages').MessageType;
+            storedAt: string;
+            id: string;
+        }[];
+    };
+    /**
+     * Get a summary of conversation context for external use
+     * Useful for providing context to other systems or for logging
+     * @param includeStoredContext - Whether to include recent stored messages
+     * @returns Context summary object
+     */
+    getContextSummary(includeStoredContext?: boolean): {
+        activeMessageCount: number;
+        systemPrompt: string;
+        recentMessages: BaseMessage[];
+        memoryUtilization: number;
+        hasStoredHistory: boolean;
+    } | {
+        recentStoredMessages: BaseMessage[];
+        storageStats: import('./ContentStorage').StorageStats;
+        activeMessageCount: number;
+        systemPrompt: string;
+        recentMessages: BaseMessage[];
+        memoryUtilization: number;
+        hasStoredHistory: boolean;
+    };
+    /**
+     * Perform maintenance operations
+     * Optimizes storage and cleans up resources
+     */
+    performMaintenance(): void;
+    /**
+     * Clean up resources and dispose of components
+     */
+    dispose(): void;
+}