/**
 * Token Economics Module
 *
 * Tracks token usage and savings for memory operations.
 * Provides ROI metrics for the memory system.
 *
 * Key metrics:
 * - Discovery tokens: Input tokens used to create memories
 * - Read tokens: Tokens when retrieving memories
 * - Savings: Discovery - Read tokens (compression benefit)
 *
 * @module @aitytech/agentkits-memory/search
 */
/**
 * Token economics statistics
 */
export interface TokenStats {
    /** Total discovery tokens (input that created memories) */
    totalDiscoveryTokens: number;
    /** Total read tokens (output when retrieved) */
    totalReadTokens: number;
    /** Total tokens saved (discovery - read) */
    totalSavings: number;
    /** Savings as percentage */
    savingsPercent: number;
    /** Number of observations/memories */
    totalObservations: number;
    /** Average tokens per observation */
    avgTokensPerObservation: number;
    /** Token efficiency score (0-100) */
    efficiencyScore: number;
}
/**
 * Per-entry token metrics
 */
export interface EntryTokenMetrics {
    /** Entry ID */
    entryId: string;
    /** Tokens used to create this entry */
    discoveryTokens: number;
    /** Tokens when retrieved */
    readTokens: number;
    /** Savings for this entry */
    savings: number;
    /** Number of times accessed */
    accessCount: number;
    /** Value score (savings * accessCount) */
    valueScore: number;
}
/**
 * Session token summary
 */
export interface SessionTokenSummary {
    /** Session ID */
    sessionId: string;
    /** Tokens input during session */
    inputTokens: number;
    /** Tokens saved by memory recall */
    savedTokens: number;
    /** Number of memories created */
    memoriesCreated: number;
    /** Number of memories recalled */
    memoriesRecalled: number;
    /** Net efficiency */
    netEfficiency: number;
}
/**
 * Token economics configuration
 */
export interface TokenEconomicsConfig {
    /** Characters per token estimate (default: 4) */
    charsPerToken: number;
    /** Include metadata in token count (default: false) */
    includeMetadata: boolean;
    /** Track per-entry metrics (default: true) */
    trackPerEntry: boolean;
}
/**
 * Token Economics Tracker
 *
 * Provides detailed token usage metrics for the memory system.
 * Helps users understand the ROI of persistent memory.
 */
export declare class TokenEconomicsTracker {
    private config;
    private entryMetrics;
    private sessionMetrics;
    private totalDiscoveryTokens;
    private totalReadTokens;
    private totalObservations;
    constructor(config?: Partial<TokenEconomicsConfig>);
    /**
     * Estimate token count for text
     */
    estimateTokens(text: string): number;
    /**
     * Record memory creation (discovery tokens)
     */
    recordCreation(entryId: string, content: string, metadata?: Record<string, unknown>): void;
    /**
     * Record memory retrieval (read tokens)
     */
    recordRetrieval(entryId: string, content: string, sessionId?: string): void;
    /**
     * Record session input tokens
     */
    recordSessionInput(sessionId: string, inputTokens: number): void;
    /**
     * Get aggregate statistics
     */
    getStats(): TokenStats;
    /**
     * Get per-entry metrics
     */
    getEntryMetrics(entryId?: string): EntryTokenMetrics[];
    /**
     * Get top entries by value score
     */
    getTopValueEntries(limit?: number): EntryTokenMetrics[];
    /**
     * Get low-value entries (candidates for archival)
     */
    getLowValueEntries(limit?: number): EntryTokenMetrics[];
    /**
     * Get session summary
     */
    getSessionSummary(sessionId: string): SessionTokenSummary | undefined;
    /**
     * Get all session summaries
     */
    getAllSessionSummaries(): SessionTokenSummary[];
    /**
     * Reset all metrics
     */
    reset(): void;
    /**
     * Export metrics as JSON
     */
    export(): {
        stats: TokenStats;
        entries: EntryTokenMetrics[];
        sessions: SessionTokenSummary[];
    };
    /**
     * Import metrics from JSON
     */
    import(data: {
        entries?: EntryTokenMetrics[];
        sessions?: SessionTokenSummary[];
    }): void;
    /**
     * Format stats for display
     */
    formatStats(): string;
}
/**
 * Create a token economics tracker
 */
export declare function createTokenEconomicsTracker(config?: Partial<TokenEconomicsConfig>): TokenEconomicsTracker;
export default TokenEconomicsTracker;
//# sourceMappingURL=token-economics.d.ts.map