@lov3kaizen/agentsea-memory 0.5.1

package/dist/index-Bbc3COw0.d.cts

@@ -0,0 +1,748 @@
+import { EventEmitter } from 'eventemitter3';
+import { c as MemoryEntry, i as MemoryStoreInterface, S as ScoredMemory } from './core.types-lkxKv-bW.cjs';
+
+/**
+ * Structure Types
+ *
+ * Types for memory structure implementations.
+ */
+
+/**
+ * Memory level in hierarchy
+ */
+type MemoryLevel = 'working' | 'episodic' | 'semantic' | 'longTerm';
+/**
+ * Memory importance source
+ */
+type ImportanceSource = 'recency' | 'frequency' | 'explicit' | 'inferred';
+/**
+ * Working memory configuration
+ */
+interface WorkingMemoryConfig {
+    maxItems?: number;
+    maxSize?: number;
+    ttl?: number;
+    importance?: ImportanceSource;
+    onEvict?: (entry: MemoryEntry) => void;
+    attentionWindow?: number;
+    decayRate?: number;
+    relevanceThreshold?: number;
+    autoEvict?: boolean;
+}
+/**
+ * Episodic memory configuration
+ */
+interface EpisodicMemoryConfig {
+    store?: MemoryStoreInterface;
+    consolidateAfter?: number;
+    summarizeThreshold?: number;
+    retentionDays?: number;
+    episodeTimeout?: number;
+    maxEpisodeLength?: number;
+    autoSummarize?: boolean;
+    minEventsForEpisode?: number;
+    emotionTracking?: boolean;
+}
+/**
+ * Semantic memory configuration
+ */
+interface SemanticMemoryConfig {
+    store?: MemoryStoreInterface;
+    extractEntities?: boolean;
+    extractRelations?: boolean;
+    deduplication?: boolean;
+    deduplicationThreshold?: number;
+    maxConcepts?: number;
+    enableInference?: boolean;
+    conflictResolution?: 'newest' | 'highest-confidence' | 'manual' | 'merge';
+    minConfidence?: number;
+}
+/**
+ * Long-term memory configuration
+ */
+interface LongTermMemoryConfig {
+    store?: MemoryStoreInterface;
+    indexing?: 'vector' | 'keyword' | 'hybrid';
+    compression?: boolean;
+    compressionThreshold?: number;
+    consolidationThreshold?: number;
+    compressionRatio?: number;
+    minImportance?: number;
+    retentionPeriod?: number;
+    autoConsolidate?: boolean;
+    maxStorageSize?: number;
+}
+/**
+ * Hierarchical memory configuration
+ */
+interface HierarchicalMemoryConfig {
+    working?: WorkingMemoryConfig;
+    episodic?: EpisodicMemoryConfig;
+    semantic?: SemanticMemoryConfig;
+    longTerm?: LongTermMemoryConfig;
+    routing?: MemoryRoutingConfig;
+    routingStrategy?: 'importance' | 'recency' | 'type' | 'hybrid' | 'auto' | 'manual';
+    consolidationInterval?: number;
+    workingMemorySize?: number;
+    promotionThreshold?: number;
+}
+/**
+ * Memory routing configuration
+ */
+interface MemoryRoutingConfig {
+    rules?: MemoryRoutingRule[];
+    defaultLevel?: MemoryLevel;
+}
+/**
+ * Memory routing rule
+ */
+interface MemoryRoutingRule {
+    condition: (entry: MemoryEntry) => boolean;
+    target: MemoryLevel;
+    priority?: number;
+}
+
+/**
+ * WorkingMemory
+ *
+ * Short-term, context-focused memory with limited capacity.
+ * Implements a sliding window for recent context.
+ */
+
+/**
+ * Working memory events
+ */
+interface WorkingMemoryEvents {
+    overflow: (evicted: MemoryEntry[]) => void;
+    contextUpdate: (context: MemoryEntry[]) => void;
+    attention: (entry: MemoryEntry, score: number) => void;
+}
+/**
+ * Attention score for a memory entry
+ */
+interface AttentionScore {
+    entry: MemoryEntry;
+    relevance: number;
+    recency: number;
+    importance: number;
+    total: number;
+}
+/**
+ * Working memory for short-term context management
+ */
+declare class WorkingMemory extends EventEmitter<WorkingMemoryEvents> {
+    private store;
+    private config;
+    private contextWindow;
+    private attentionBuffer;
+    private currentQuery;
+    constructor(store: MemoryStoreInterface, config?: WorkingMemoryConfig);
+    /**
+     * Add an entry to working memory
+     */
+    add(entry: MemoryEntry): Promise<void>;
+    /**
+     * Get all entries in working memory
+     */
+    getContext(): MemoryEntry[];
+    /**
+     * Get entries with attention scores
+     */
+    getContextWithAttention(): AttentionScore[];
+    /**
+     * Update attention for an entry (e.g., when referenced)
+     */
+    attend(id: string): void;
+    /**
+     * Set the current query/context for relevance calculation
+     */
+    setQuery(query: string): void;
+    /**
+     * Decay attention scores
+     */
+    decay(): void;
+    /**
+     * Get the most attended entries
+     */
+    getFocused(limit?: number): MemoryEntry[];
+    /**
+     * Clear working memory
+     */
+    clear(): void;
+    /**
+     * Remove a specific entry
+     */
+    remove(id: string): boolean;
+    /**
+     * Get current size
+     */
+    get size(): number;
+    /**
+     * Check if at capacity
+     */
+    get isFull(): boolean;
+    /**
+     * Consolidate important items to long-term storage
+     */
+    consolidate(targetStore: MemoryStoreInterface): Promise<number>;
+    /**
+     * Load context from store
+     */
+    loadFromStore(options?: {
+        namespace?: string;
+        userId?: string;
+        conversationId?: string;
+        limit?: number;
+    }): Promise<void>;
+    /**
+     * Calculate relevance to current query
+     */
+    private calculateRelevance;
+    /**
+     * Evict entry with lowest attention
+     */
+    private evictLowestAttention;
+    /**
+     * Get summary of working memory state
+     */
+    getSummary(): {
+        size: number;
+        maxSize: number;
+        avgAttention: number;
+        topTypes: Record<string, number>;
+    };
+}
+/**
+ * Create working memory instance
+ */
+declare function createWorkingMemory(store: MemoryStoreInterface, config?: WorkingMemoryConfig): WorkingMemory;
+
+/**
+ * EpisodicMemory
+ *
+ * Stores autobiographical events, experiences, and interactions.
+ * Supports temporal organization and context-based retrieval.
+ */
+
+/**
+ * Episode - a coherent sequence of related events
+ */
+interface Episode {
+    id: string;
+    title?: string;
+    startTime: number;
+    endTime?: number;
+    events: MemoryEntry[];
+    summary?: string;
+    participants?: string[];
+    location?: string;
+    emotionalContext?: string;
+    metadata: Record<string, unknown>;
+}
+/**
+ * Episodic memory events
+ */
+interface EpisodicMemoryEvents {
+    episodeStart: (episode: Episode) => void;
+    episodeEnd: (episode: Episode) => void;
+    eventAdded: (event: MemoryEntry, episode: Episode) => void;
+}
+/**
+ * Episodic memory for experiences and events
+ */
+declare class EpisodicMemory extends EventEmitter<EpisodicMemoryEvents> {
+    private store;
+    private config;
+    private episodes;
+    private currentEpisode;
+    private episodeTimeout;
+    constructor(store: MemoryStoreInterface, config?: EpisodicMemoryConfig);
+    /**
+     * Record an event
+     */
+    recordEvent(entry: MemoryEntry): Promise<Episode>;
+    /**
+     * Start a new episode
+     */
+    startEpisode(metadata?: Record<string, unknown>): Episode;
+    /**
+     * End the current episode
+     */
+    endCurrentEpisode(): Promise<Episode | null>;
+    /**
+     * Recall events from a time period
+     */
+    recall(options: {
+        startTime?: number;
+        endTime?: number;
+        limit?: number;
+        conversationId?: string;
+        userId?: string;
+    }): Promise<MemoryEntry[]>;
+    /**
+     * Search episodes by content
+     */
+    searchEpisodes(query: string, limit?: number): Promise<Episode[]>;
+    /**
+     * Get episode by ID
+     */
+    getEpisode(id: string): Episode | undefined;
+    /**
+     * Get current episode
+     */
+    getCurrentEpisode(): Episode | null;
+    /**
+     * Get all episodes in a time range
+     */
+    getEpisodesByTimeRange(startTime: number, endTime: number): Episode[];
+    /**
+     * Get recent episodes
+     */
+    getRecentEpisodes(limit?: number): Episode[];
+    /**
+     * Find similar episodes
+     */
+    findSimilarEpisodes(episode: Episode, embedFn: (text: string) => Promise<number[]>, limit?: number): Promise<Array<{
+        episode: Episode;
+        similarity: number;
+    }>>;
+    /**
+     * Merge related episodes
+     */
+    mergeEpisodes(episodeIds: string[], newTitle?: string): Episode | null;
+    /**
+     * Reset episode timeout
+     */
+    private resetEpisodeTimeout;
+    /**
+     * Generate episode summary
+     */
+    private generateEpisodeSummary;
+    /**
+     * Calculate episode importance
+     */
+    private calculateEpisodeImportance;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        totalEpisodes: number;
+        currentEpisodeSize: number;
+        totalEvents: number;
+        avgEventsPerEpisode: number;
+    };
+}
+/**
+ * Create episodic memory instance
+ */
+declare function createEpisodicMemory(store: MemoryStoreInterface, config?: EpisodicMemoryConfig): EpisodicMemory;
+
+/**
+ * SemanticMemory
+ *
+ * Stores factual knowledge, concepts, and relationships.
+ * Supports knowledge graphs and concept organization.
+ */
+
+/**
+ * Concept node in the knowledge graph
+ */
+interface Concept {
+    id: string;
+    name: string;
+    description?: string;
+    category?: string;
+    attributes: Record<string, unknown>;
+    embedding?: number[];
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * Relationship between concepts
+ */
+interface Relationship {
+    id: string;
+    sourceId: string;
+    targetId: string;
+    type: string;
+    weight: number;
+    metadata: Record<string, unknown>;
+    createdAt: number;
+}
+/**
+ * Semantic memory events
+ */
+interface SemanticMemoryEvents {
+    conceptAdded: (concept: Concept) => void;
+    conceptUpdated: (concept: Concept) => void;
+    relationshipAdded: (relationship: Relationship) => void;
+    factLearned: (fact: MemoryEntry) => void;
+}
+/**
+ * Semantic memory for factual knowledge
+ */
+declare class SemanticMemory extends EventEmitter<SemanticMemoryEvents> {
+    private store;
+    private config;
+    private concepts;
+    private relationships;
+    private conceptIndex;
+    constructor(store: MemoryStoreInterface, config?: SemanticMemoryConfig);
+    /**
+     * Learn a new fact
+     */
+    learnFact(content: string, metadata?: Record<string, unknown>): Promise<MemoryEntry>;
+    /**
+     * Add or update a concept
+     */
+    addConcept(concept: Omit<Concept, 'id' | 'createdAt' | 'updatedAt'>): Concept;
+    /**
+     * Create a relationship between concepts
+     */
+    addRelationship(sourceId: string, targetId: string, type: string, metadata?: Record<string, unknown>): Relationship | null;
+    /**
+     * Get a concept by ID or name
+     */
+    getConcept(idOrName: string): Concept | undefined;
+    /**
+     * Get concepts by category
+     */
+    getConceptsByCategory(category: string): Concept[];
+    /**
+     * Get relationships for a concept
+     */
+    getRelationships(conceptId: string, direction?: 'outgoing' | 'incoming' | 'both'): Relationship[];
+    /**
+     * Get related concepts
+     */
+    getRelatedConcepts(conceptId: string, relationshipType?: string, maxDepth?: number): Array<{
+        concept: Concept;
+        path: Relationship[];
+        distance: number;
+    }>;
+    /**
+     * Query facts
+     */
+    queryFacts(query: string, limit?: number): Promise<MemoryEntry[]>;
+    /**
+     * Search facts by embedding
+     */
+    searchFacts(embedding: number[], options?: {
+        topK?: number;
+        minScore?: number;
+    }): Promise<Array<{
+        entry: MemoryEntry;
+        score: number;
+    }>>;
+    /**
+     * Find path between two concepts
+     */
+    findPath(sourceId: string, targetId: string, maxDepth?: number): Relationship[] | null;
+    /**
+     * Infer new relationships based on existing ones
+     */
+    inferRelationships(): Relationship[];
+    /**
+     * Get conflicting facts
+     */
+    findConflicts(fact: MemoryEntry): Promise<MemoryEntry[]>;
+    /**
+     * Resolve conflict between facts
+     */
+    resolveConflict(fact1: MemoryEntry, fact2: MemoryEntry): MemoryEntry;
+    /**
+     * Export knowledge graph
+     */
+    exportGraph(): {
+        concepts: Concept[];
+        relationships: Relationship[];
+    };
+    /**
+     * Import knowledge graph
+     */
+    importGraph(data: {
+        concepts: Concept[];
+        relationships: Relationship[];
+    }): void;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Get statistics
+     */
+    getStats(): {
+        conceptCount: number;
+        relationshipCount: number;
+        categoryCount: number;
+        avgRelationshipsPerConcept: number;
+    };
+}
+/**
+ * Create semantic memory instance
+ */
+declare function createSemanticMemory(store: MemoryStoreInterface, config?: SemanticMemoryConfig): SemanticMemory;
+
+/**
+ * LongTermMemory
+ *
+ * Persistent, compressed storage for important memories.
+ * Supports consolidation from working/episodic memory.
+ */
+
+/**
+ * Consolidated memory summary
+ */
+interface ConsolidatedMemory {
+    id: string;
+    summary: string;
+    sourceIds: string[];
+    sourceCount: number;
+    avgImportance: number;
+    timeRange: {
+        start: number;
+        end: number;
+    };
+    metadata: Record<string, unknown>;
+    embedding?: number[];
+    createdAt: number;
+}
+/**
+ * Long-term memory events
+ */
+interface LongTermMemoryEvents {
+    consolidated: (consolidated: ConsolidatedMemory, sources: MemoryEntry[]) => void;
+    pruned: (pruned: MemoryEntry[]) => void;
+    retrieved: (entries: MemoryEntry[]) => void;
+}
+/**
+ * Long-term memory for persistent storage
+ */
+declare class LongTermMemory extends EventEmitter<LongTermMemoryEvents> {
+    private store;
+    private config;
+    private consolidatedMemories;
+    constructor(store: MemoryStoreInterface, config?: LongTermMemoryConfig);
+    /**
+     * Store a memory in long-term storage
+     */
+    store_memory(entry: MemoryEntry): Promise<string>;
+    /**
+     * Retrieve memories by similarity
+     */
+    retrieve(embedding: number[], options?: {
+        topK?: number;
+        minScore?: number;
+        includeConsolidated?: boolean;
+    }): Promise<ScoredMemory[]>;
+    /**
+     * Query long-term memories
+     */
+    query(options: {
+        query?: string;
+        types?: string[];
+        namespace?: string;
+        userId?: string;
+        minImportance?: number;
+        startTime?: number;
+        endTime?: number;
+        limit?: number;
+    }): Promise<MemoryEntry[]>;
+    /**
+     * Consolidate old memories into summaries
+     */
+    consolidateOldMemories(options?: {
+        olderThan?: number;
+        groupBy?: 'day' | 'week' | 'topic';
+        summarizeFn?: (entries: MemoryEntry[]) => Promise<string>;
+    }): Promise<ConsolidatedMemory[]>;
+    /**
+     * Prune low-importance memories
+     */
+    prune(options?: {
+        maxAge?: number;
+        maxImportance?: number;
+        maxCount?: number;
+    }): Promise<number>;
+    /**
+     * Reinforce a memory (increase importance)
+     */
+    reinforce(id: string, amount?: number): Promise<boolean>;
+    /**
+     * Get consolidated memory by ID
+     */
+    getConsolidated(id: string): ConsolidatedMemory | undefined;
+    /**
+     * Get all consolidated memories
+     */
+    getAllConsolidated(): ConsolidatedMemory[];
+    /**
+     * Expand a consolidated memory to show original summaries
+     */
+    expandConsolidated(id: string): MemoryEntry[] | null;
+    /**
+     * Group memories by time or topic
+     */
+    private groupMemories;
+    /**
+     * Generate simple summary from entries
+     */
+    private generateSimpleSummary;
+    /**
+     * Generate unique ID
+     */
+    private generateId;
+    /**
+     * Get statistics
+     */
+    getStats(): Promise<{
+        totalMemories: number;
+        consolidatedCount: number;
+        avgImportance: number;
+        oldestMemory: number | null;
+        newestMemory: number | null;
+    }>;
+}
+/**
+ * Create long-term memory instance
+ */
+declare function createLongTermMemory(store: MemoryStoreInterface, config?: LongTermMemoryConfig): LongTermMemory;
+
+/**
+ * HierarchicalMemory
+ *
+ * Routes between working, episodic, semantic, and long-term memory.
+ * Manages memory consolidation and retrieval across all layers.
+ */
+
+/**
+ * Memory layer type
+ */
+type MemoryLayer = 'working' | 'episodic' | 'semantic' | 'longterm';
+/**
+ * Routing decision
+ */
+interface RoutingDecision {
+    layer: MemoryLayer;
+    confidence: number;
+    reason: string;
+}
+/**
+ * Hierarchical memory events
+ */
+interface HierarchicalMemoryEvents {
+    routed: (entry: MemoryEntry, layer: MemoryLayer) => void;
+    promoted: (entry: MemoryEntry, from: MemoryLayer, to: MemoryLayer) => void;
+    consolidated: (from: MemoryLayer, to: MemoryLayer, count: number) => void;
+    retrieved: (entries: MemoryEntry[], layers: MemoryLayer[]) => void;
+}
+/**
+ * Search result with layer information
+ */
+interface HierarchicalSearchResult {
+    entry: MemoryEntry;
+    score: number;
+    layer: MemoryLayer;
+}
+/**
+ * Hierarchical memory system
+ */
+declare class HierarchicalMemory extends EventEmitter<HierarchicalMemoryEvents> {
+    private workingMemory;
+    private episodicMemory;
+    private semanticMemory;
+    private longTermMemory;
+    private config;
+    private embedFn?;
+    constructor(stores: {
+        working: MemoryStoreInterface;
+        episodic: MemoryStoreInterface;
+        semantic: MemoryStoreInterface;
+        longterm: MemoryStoreInterface;
+    }, config?: HierarchicalMemoryConfig);
+    /**
+     * Set embedding function for semantic search
+     */
+    setEmbeddingFunction(fn: (text: string) => Promise<number[]>): void;
+    /**
+     * Add a memory entry with automatic routing
+     */
+    add(entry: MemoryEntry): Promise<MemoryLayer>;
+    /**
+     * Add to a specific layer
+     */
+    addToLayer(entry: MemoryEntry, layer: MemoryLayer): Promise<void>;
+    /**
+     * Search across all memory layers
+     */
+    search(query: string, options?: {
+        layers?: MemoryLayer[];
+        topK?: number;
+        minScore?: number;
+    }): Promise<HierarchicalSearchResult[]>;
+    /**
+     * Search a specific layer
+     */
+    private searchLayer;
+    /**
+     * Get context from working memory
+     */
+    getWorkingContext(): MemoryEntry[];
+    /**
+     * Promote a memory to a higher layer
+     */
+    promote(entryId: string, from: MemoryLayer, to: MemoryLayer): Promise<boolean>;
+    /**
+     * Consolidate memories from one layer to another
+     */
+    consolidate(from: MemoryLayer, to: MemoryLayer): Promise<number>;
+    /**
+     * Route a memory entry to the appropriate layer
+     */
+    route(entry: MemoryEntry): MemoryLayer;
+    /**
+     * Make routing decision
+     */
+    private makeRoutingDecision;
+    /**
+     * Calculate text similarity score
+     */
+    private calculateTextScore;
+    /**
+     * Set up event handlers between layers
+     */
+    private setupEventHandlers;
+    /**
+     * Get statistics for all layers
+     */
+    getStats(): Promise<{
+        working: ReturnType<WorkingMemory['getSummary']>;
+        episodic: ReturnType<EpisodicMemory['getStats']>;
+        semantic: ReturnType<SemanticMemory['getStats']>;
+        longterm: Awaited<ReturnType<LongTermMemory['getStats']>>;
+    }>;
+    /**
+     * Access individual memory layers
+     */
+    get layers(): {
+        working: WorkingMemory;
+        episodic: EpisodicMemory;
+        semantic: SemanticMemory;
+        longterm: LongTermMemory;
+    };
+}
+/**
+ * Create hierarchical memory system
+ */
+declare function createHierarchicalMemory(stores: {
+    working: MemoryStoreInterface;
+    episodic: MemoryStoreInterface;
+    semantic: MemoryStoreInterface;
+    longterm: MemoryStoreInterface;
+}, config?: HierarchicalMemoryConfig): HierarchicalMemory;
+
+export { type AttentionScore as A, type Concept as C, EpisodicMemory as E, type HierarchicalMemoryConfig as H, type LongTermMemoryConfig as L, type MemoryLayer as M, type Relationship as R, SemanticMemory as S, WorkingMemory as W, type WorkingMemoryConfig as a, type EpisodicMemoryConfig as b, type SemanticMemoryConfig as c, createWorkingMemory as d, createEpisodicMemory as e, createSemanticMemory as f, LongTermMemory as g, createLongTermMemory as h, HierarchicalMemory as i, createHierarchicalMemory as j, type WorkingMemoryEvents as k, type Episode as l, type EpisodicMemoryEvents as m, type SemanticMemoryEvents as n, type ConsolidatedMemory as o, type LongTermMemoryEvents as p, type RoutingDecision as q, type HierarchicalMemoryEvents as r, type HierarchicalSearchResult as s };