@lov3kaizen/agentsea-memory 0.5.1

package/dist/index-Bczz1Eyk.d.ts

@@ -0,0 +1,637 @@
+import { j as MemoryType, i as MemoryStoreInterface, c as MemoryEntry } from './core.types-lkxKv-bW.js';
+import { EventEmitter } from 'eventemitter3';
+
+/**
+ * Debug Types
+ *
+ * Types for memory debugging and inspection.
+ */
+
+/**
+ * Warning thresholds for inspector
+ */
+interface WarningThresholds {
+    lowImportance?: number;
+    highEntryCount?: number;
+    oldAge?: number;
+}
+/**
+ * Inspector configuration
+ */
+interface InspectorConfig {
+    includeEmbeddings?: boolean;
+    samplingRate?: number;
+    maxEntriesForAnalysis?: number;
+    warningThresholds?: WarningThresholds;
+}
+/**
+ * Timeline configuration
+ */
+interface TimelineConfig {
+    timeRange?: {
+        start: number;
+        end: number;
+    };
+    groupBy?: 'hour' | 'day' | 'week' | 'month';
+    showTypes?: boolean;
+    showNamespaces?: boolean;
+    maxEvents?: number;
+    autoTrack?: boolean;
+    segmentSize?: 'hour' | 'day' | 'week';
+}
+/**
+ * Retrieval debug options
+ */
+interface RetrievalDebugOptions {
+    query: string;
+    expectedMemories?: string[];
+    context?: Record<string, unknown>;
+    verbose?: boolean;
+    candidateMultiplier?: number;
+    limit?: number;
+    types?: string[];
+    namespace?: string;
+    minScore?: number;
+}
+/**
+ * Export format
+ */
+type ExportFormat$1 = 'json' | 'csv' | 'jsonl' | 'training';
+/**
+ * Export options
+ */
+interface ExportOptions {
+    format?: ExportFormat$1;
+    includeEmbeddings?: boolean;
+    includeMetadata?: boolean;
+    filter?: {
+        types?: MemoryType[];
+        namespaces?: string[];
+        timeRange?: {
+            start?: number;
+            end?: number;
+        };
+    };
+    namespace?: string;
+    types?: string[];
+    startTime?: number;
+    endTime?: number;
+    ids?: string[];
+    pretty?: boolean;
+}
+
+/**
+ * Inspector
+ *
+ * Memory inspection and analysis tools.
+ */
+
+/**
+ * Memory statistics
+ */
+interface MemoryStats {
+    totalEntries: number;
+    totalSize: number;
+    avgContentLength: number;
+    avgImportance: number;
+    avgAccessCount: number;
+    typeDistribution: Record<string, number>;
+    namespaceDistribution: Record<string, number>;
+    timeRange: {
+        oldest: number;
+        newest: number;
+    } | null;
+    entriesWithEmbeddings: number;
+    expiredEntries: number;
+}
+/**
+ * Memory health report
+ */
+interface HealthReport {
+    score: number;
+    issues: HealthIssue[];
+    recommendations: string[];
+}
+/**
+ * Health issue
+ */
+interface HealthIssue {
+    type: 'warning' | 'error' | 'info';
+    message: string;
+    affectedEntries?: number;
+    suggestion?: string;
+}
+/**
+ * Inspection result
+ */
+interface InspectionResult {
+    entry: MemoryEntry;
+    analysis: {
+        contentLength: number;
+        wordCount: number;
+        hasEmbedding: boolean;
+        embeddingDimensions?: number;
+        metadataKeys: string[];
+        age: number;
+        accessRate: number;
+        isExpired: boolean;
+        importancePercentile?: number;
+    };
+}
+/**
+ * Memory inspector
+ */
+declare class Inspector {
+    private store;
+    private config;
+    constructor(store: MemoryStoreInterface, config?: InspectorConfig);
+    /**
+     * Get comprehensive memory statistics
+     */
+    getStats(): Promise<MemoryStats>;
+    /**
+     * Inspect a specific entry
+     */
+    inspect(id: string): Promise<InspectionResult | null>;
+    /**
+     * Get memory health report
+     */
+    getHealthReport(): Promise<HealthReport>;
+    /**
+     * Find duplicate entries
+     */
+    findDuplicates(threshold?: number): Promise<Array<[MemoryEntry, MemoryEntry]>>;
+    /**
+     * Find orphaned entries (no parent, but has parentId)
+     */
+    findOrphans(): Promise<MemoryEntry[]>;
+    /**
+     * Find low-value entries
+     */
+    findLowValueEntries(options?: {
+        maxImportance?: number;
+        maxAccessCount?: number;
+        minAge?: number;
+    }): Promise<MemoryEntry[]>;
+    /**
+     * Get entry distribution over time
+     */
+    getTimeDistribution(bucketSize?: 'hour' | 'day' | 'week' | 'month'): Promise<Map<string, number>>;
+    /**
+     * Calculate similarity between two entries
+     */
+    private calculateSimilarity;
+    /**
+     * Cosine similarity
+     */
+    private cosineSimilarity;
+    /**
+     * Text similarity (Jaccard)
+     */
+    private textSimilarity;
+}
+/**
+ * Create inspector instance
+ */
+declare function createInspector(store: MemoryStoreInterface, config?: InspectorConfig): Inspector;
+
+/**
+ * Timeline
+ *
+ * Memory timeline visualization and analysis.
+ */
+
+/**
+ * Timeline event
+ */
+interface TimelineEvent {
+    id: string;
+    type: 'add' | 'update' | 'delete' | 'access' | 'consolidate';
+    entryId: string;
+    timestamp: number;
+    details?: Record<string, unknown>;
+}
+/**
+ * Timeline segment
+ */
+interface TimelineSegment {
+    start: number;
+    end: number;
+    entries: MemoryEntry[];
+    events: TimelineEvent[];
+    summary?: string;
+}
+/**
+ * Timeline marker
+ */
+interface TimelineMarker {
+    timestamp: number;
+    label: string;
+    type: 'milestone' | 'annotation' | 'warning';
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Memory timeline
+ */
+declare class Timeline {
+    private store;
+    private config;
+    private events;
+    private markers;
+    constructor(store: MemoryStoreInterface, config?: TimelineConfig);
+    /**
+     * Record a timeline event
+     */
+    recordEvent(event: Omit<TimelineEvent, 'id'>): void;
+    /**
+     * Add a marker to the timeline
+     */
+    addMarker(marker: Omit<TimelineMarker, 'timestamp'> & {
+        timestamp?: number;
+    }): void;
+    /**
+     * Get timeline segments
+     */
+    getSegments(startTime: number, endTime: number): Promise<TimelineSegment[]>;
+    /**
+     * Get timeline for a specific entry
+     */
+    getEntryTimeline(entryId: string): Promise<{
+        entry: MemoryEntry | null;
+        events: TimelineEvent[];
+        createdAt: number;
+        lastModified: number;
+        accessHistory: number[];
+    }>;
+    /**
+     * Get activity heatmap data
+     */
+    getActivityHeatmap(startTime: number, endTime: number, bucketSize?: 'hour' | 'day'): Promise<Map<string, {
+        entries: number;
+        events: number;
+    }>>;
+    /**
+     * Get markers in time range
+     */
+    getMarkers(startTime: number, endTime: number): TimelineMarker[];
+    /**
+     * Get recent activity summary
+     */
+    getRecentActivity(windowMs?: number): {
+        newEntries: number;
+        updatedEntries: number;
+        deletedEntries: number;
+        totalAccesses: number;
+        topAccessed: Array<{
+            entryId: string;
+            accessCount: number;
+        }>;
+    };
+    /**
+     * Get memory growth over time
+     */
+    getGrowthChart(startTime: number, endTime: number, bucketSize?: 'hour' | 'day' | 'week'): Promise<Array<{
+        time: string;
+        cumulativeCount: number;
+        newCount: number;
+    }>>;
+    /**
+     * Find gaps in timeline (periods with no activity)
+     */
+    findGaps(startTime: number, endTime: number, minGapSize?: number): Promise<Array<{
+        start: number;
+        end: number;
+        durationMs: number;
+    }>>;
+    /**
+     * Clear events
+     */
+    clearEvents(): void;
+    /**
+     * Clear markers
+     */
+    clearMarkers(): void;
+    /**
+     * Export timeline data
+     */
+    exportData(): {
+        events: TimelineEvent[];
+        markers: TimelineMarker[];
+        exportedAt: number;
+    };
+    /**
+     * Import timeline data
+     */
+    importData(data: {
+        events: TimelineEvent[];
+        markers: TimelineMarker[];
+    }): void;
+    /**
+     * Get segment size in milliseconds
+     */
+    private getSegmentSizeMs;
+    /**
+     * Get bucket key for timestamp
+     */
+    private getBucketKey;
+}
+/**
+ * Create timeline instance
+ */
+declare function createTimeline(store: MemoryStoreInterface, config?: TimelineConfig): Timeline;
+
+/**
+ * Debugger
+ *
+ * Memory debugging and tracing tools.
+ */
+
+/**
+ * Debug trace entry
+ */
+interface DebugTrace {
+    id: string;
+    operation: string;
+    timestamp: number;
+    duration: number;
+    input: unknown;
+    output: unknown;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Retrieval debug info
+ */
+interface RetrievalDebugInfo {
+    query: string;
+    totalCandidates: number;
+    returnedCount: number;
+    strategyUsed: string;
+    filteringSteps: Array<{
+        name: string;
+        inputCount: number;
+        outputCount: number;
+        durationMs: number;
+    }>;
+    scoringDetails: Array<{
+        entryId: string;
+        scores: Record<string, number>;
+        finalScore: number;
+    }>;
+    timing: {
+        total: number;
+        embedding?: number;
+        search?: number;
+        filtering?: number;
+        ranking?: number;
+    };
+}
+/**
+ * Breakpoint
+ */
+interface Breakpoint {
+    id: string;
+    condition: (entry: MemoryEntry, operation: string) => boolean;
+    enabled: boolean;
+    hitCount: number;
+}
+/**
+ * Debug events
+ */
+interface DebuggerEvents {
+    trace: (trace: DebugTrace) => void;
+    breakpointHit: (breakpoint: Breakpoint, entry: MemoryEntry, operation: string) => void;
+    warning: (message: string, data?: unknown) => void;
+}
+/**
+ * Memory debugger
+ */
+declare class Debugger extends EventEmitter<DebuggerEvents> {
+    private store;
+    private traces;
+    private breakpoints;
+    private enabled;
+    private maxTraces;
+    constructor(store: MemoryStoreInterface);
+    /**
+     * Enable debugging
+     */
+    enable(): void;
+    /**
+     * Disable debugging
+     */
+    disable(): void;
+    /**
+     * Check if debugging is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Trace an operation
+     */
+    trace(operation: string, input: unknown, output: unknown, durationMs: number, metadata?: Record<string, unknown>): void;
+    /**
+     * Wrap a function with tracing
+     */
+    wrapWithTrace<T extends (...args: unknown[]) => Promise<unknown>>(operation: string, fn: T): T;
+    /**
+     * Add a breakpoint
+     */
+    addBreakpoint(condition: (entry: MemoryEntry, operation: string) => boolean, id?: string): string;
+    /**
+     * Remove a breakpoint
+     */
+    removeBreakpoint(id: string): boolean;
+    /**
+     * Enable/disable a breakpoint
+     */
+    toggleBreakpoint(id: string, enabled: boolean): boolean;
+    /**
+     * Check breakpoints for an entry/operation
+     */
+    checkBreakpoints(entry: MemoryEntry, operation: string): void;
+    /**
+     * Debug a retrieval operation
+     */
+    debugRetrieval(query: string, embedFn: (text: string) => Promise<number[]>, options?: RetrievalDebugOptions): Promise<RetrievalDebugInfo>;
+    /**
+     * Get recent traces
+     */
+    getTraces(options?: {
+        operation?: string;
+        limit?: number;
+        startTime?: number;
+        endTime?: number;
+    }): DebugTrace[];
+    /**
+     * Get operation statistics
+     */
+    getOperationStats(): Map<string, {
+        count: number;
+        avgDuration: number;
+        maxDuration: number;
+        minDuration: number;
+    }>;
+    /**
+     * Get all breakpoints
+     */
+    getBreakpoints(): Breakpoint[];
+    /**
+     * Clear traces
+     */
+    clearTraces(): void;
+    /**
+     * Clear all breakpoints
+     */
+    clearBreakpoints(): void;
+    /**
+     * Create a snapshot of current debug state
+     */
+    createSnapshot(): {
+        traces: DebugTrace[];
+        breakpoints: Array<{
+            id: string;
+            enabled: boolean;
+            hitCount: number;
+        }>;
+        stats: Map<string, {
+            count: number;
+            avgDuration: number;
+            maxDuration: number;
+            minDuration: number;
+        }>;
+        timestamp: number;
+    };
+}
+/**
+ * Create debugger instance
+ */
+declare function createDebugger(store: MemoryStoreInterface): Debugger;
+
+/**
+ * Exporter
+ *
+ * Export and import memory data in various formats.
+ */
+
+/**
+ * Export format
+ */
+type ExportFormat = 'json' | 'jsonl' | 'csv' | 'training';
+/**
+ * Export result
+ */
+interface ExportResult {
+    data: string;
+    format: ExportFormat;
+    entryCount: number;
+    exportedAt: number;
+    checksum: string;
+}
+/**
+ * Import result
+ */
+interface ImportResult {
+    imported: number;
+    skipped: number;
+    errors: Array<{
+        entry: unknown;
+        error: string;
+    }>;
+}
+/**
+ * Memory exporter
+ */
+declare class Exporter {
+    private store;
+    constructor(store: MemoryStoreInterface);
+    /**
+     * Export memories to string
+     */
+    export(options?: ExportOptions): Promise<ExportResult>;
+    /**
+     * Export to JSON file content
+     */
+    private toJSON;
+    /**
+     * Export to JSON Lines format
+     */
+    private toJSONL;
+    /**
+     * Export to CSV format
+     */
+    private toCSV;
+    /**
+     * Escape CSV value
+     */
+    private escapeCSV;
+    /**
+     * Import memories from string
+     */
+    import(data: string, format?: ExportFormat, options?: {
+        overwrite?: boolean;
+        namespace?: string;
+        validateOnly?: boolean;
+    }): Promise<ImportResult>;
+    /**
+     * Parse JSON export
+     */
+    private fromJSON;
+    /**
+     * Parse JSONL export
+     */
+    private fromJSONL;
+    /**
+     * Parse CSV export
+     */
+    private fromCSV;
+    /**
+     * Parse a CSV line
+     */
+    private parseCSVLine;
+    /**
+     * Validate entry
+     */
+    private validateEntry;
+    /**
+     * Calculate simple checksum
+     */
+    private calculateChecksum;
+    /**
+     * Create backup
+     */
+    createBackup(name?: string): Promise<{
+        name: string;
+        data: ExportResult;
+        createdAt: number;
+    }>;
+    /**
+     * Restore from backup
+     */
+    restoreBackup(backup: {
+        data: ExportResult;
+    }, options?: {
+        clearExisting?: boolean;
+    }): Promise<ImportResult>;
+    /**
+     * Get export size estimate
+     */
+    estimateExportSize(options?: ExportOptions): Promise<{
+        entryCount: number;
+        estimatedSizeBytes: number;
+        withEmbeddingsBytes?: number;
+    }>;
+    /**
+     * Diff two exports
+     */
+    diffExports(export1: ExportResult, export2: ExportResult): {
+        added: string[];
+        removed: string[];
+        modified: string[];
+        unchanged: string[];
+    };
+}
+/**
+ * Create exporter instance
+ */
+declare function createExporter(store: MemoryStoreInterface): Exporter;
+
+export { type Breakpoint as B, Debugger as D, type ExportOptions as E, type HealthReport as H, type InspectorConfig as I, type MemoryStats as M, type RetrievalDebugOptions as R, type TimelineConfig as T, Inspector as a, Timeline as b, createInspector as c, createTimeline as d, createDebugger as e, Exporter as f, createExporter as g, type HealthIssue as h, type InspectionResult as i, type TimelineEvent as j, type TimelineSegment as k, type TimelineMarker as l, type DebugTrace as m, type RetrievalDebugInfo as n, type DebuggerEvents as o, type ExportFormat as p, type ExportResult as q, type ImportResult as r };