@hashgraphonline/conversational-agent/dist/cjs/memory/ContentStorage.d.ts

Hashgraph Online conversational AI agent implementing HCS-10 communication, HCS-2 registries, and content inscription on Hedera

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 {};