@lov3kaizen/agentsea-memory 0.5.1

package/dist/index-Dy8UjRFz.d.cts

@@ -0,0 +1,565 @@
+import { S as ScoredMemory, c as MemoryEntry, i as MemoryStoreInterface } from './core.types-lkxKv-bW.cjs';
+
+/**
+ * Retrieval Types
+ *
+ * Types for memory retrieval strategies.
+ */
+
+/**
+ * Semantic retrieval configuration
+ */
+interface SemanticRetrievalConfig {
+    topK?: number;
+    minScore?: number;
+    reranking?: boolean;
+    rerankModel?: string;
+    maxCandidates?: number;
+    rerankFn?: (query: string, results: ScoredMemory[]) => Promise<ScoredMemory[]>;
+}
+/**
+ * Keyword retrieval configuration
+ */
+interface KeywordRetrievalConfig {
+    analyzer?: 'english' | 'standard' | 'simple';
+    fuzziness?: number;
+    boost?: Record<string, number>;
+}
+/**
+ * Hybrid retrieval configuration
+ */
+interface HybridRetrievalConfig {
+    semanticWeight?: number;
+    keywordWeight?: number;
+    topK?: number;
+    minScore?: number;
+    fusionMethod?: 'rrf' | 'weighted-sum' | 'max' | 'reciprocal-rank';
+    semantic?: {
+        weight: number;
+        config?: SemanticRetrievalConfig;
+    };
+    keyword?: {
+        weight: number;
+        config?: KeywordRetrievalConfig;
+    };
+    fusion?: 'reciprocal-rank' | 'weighted-sum' | 'max';
+}
+/**
+ * Temporal decay function
+ */
+type TemporalDecayFunction = 'exponential' | 'linear' | 'step' | 'logarithmic' | 'custom';
+/**
+ * Temporal retrieval configuration
+ */
+interface TemporalRetrievalConfig {
+    decayFunction?: TemporalDecayFunction;
+    halfLife?: number;
+    customDecay?: (ageMs: number) => number;
+    boost?: {
+        recent?: number;
+        medium?: number;
+        old?: number;
+    };
+    recentThreshold?: number;
+    mediumThreshold?: number;
+    recencyWeight?: number;
+    importanceWeight?: number;
+    accessWeight?: number;
+    decayHalfLife?: number;
+    topK?: number;
+}
+/**
+ * Reranker interface
+ */
+interface RerankerInterface {
+    readonly name: string;
+    rerank(query: string, candidates: ScoredMemory[], topK: number): Promise<ScoredMemory[]>;
+}
+/**
+ * Retrieval pipeline stage
+ */
+interface RetrievalPipelineStage {
+    stage: string;
+    retriever?: {
+        retrieve(query: string, context: RetrievalPipelineContext): Promise<ScoredMemory[]>;
+    };
+    filter?: (memory: MemoryEntry) => boolean;
+    reranker?: RerankerInterface;
+    transform?: (memories: ScoredMemory[]) => ScoredMemory[];
+    topK?: number;
+}
+/**
+ * Retrieval pipeline configuration
+ */
+interface RetrievalPipelineConfig {
+    stages: RetrievalPipelineStage[];
+    fallback?: 'previous-stage' | 'empty' | 'error';
+}
+/**
+ * Retrieval pipeline context
+ */
+interface RetrievalPipelineContext {
+    query: string;
+    embedding?: number[];
+    filters?: Record<string, unknown>;
+    limit?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Retrieval result
+ */
+interface RetrievalResult {
+    memories: MemoryEntry[];
+    scores: number[];
+    totalCandidates: number;
+    retrievalTimeMs: number;
+    strategy: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Retrieval result with debug info
+ */
+interface RetrievalResultWithDebug {
+    results: ScoredMemory[];
+    debug?: {
+        queryEmbedding?: number[];
+        stages?: Array<{
+            name: string;
+            inputCount: number;
+            outputCount: number;
+            durationMs: number;
+        }>;
+        totalDurationMs: number;
+    };
+}
+
+/**
+ * SemanticRetrieval
+ *
+ * Vector-based semantic search retrieval strategy.
+ */
+
+/**
+ * Embedding function type
+ */
+type EmbeddingFunction = (text: string) => Promise<number[]>;
+/**
+ * Semantic retrieval options
+ */
+interface SemanticRetrievalOptions {
+    query: string;
+    topK?: number;
+    minScore?: number;
+    namespace?: string;
+    filter?: Record<string, unknown>;
+    includeEmbeddings?: boolean;
+}
+/**
+ * Semantic retrieval strategy using vector embeddings
+ */
+declare class SemanticRetrieval {
+    private store;
+    private embedFn;
+    private config;
+    constructor(store: MemoryStoreInterface, embedFn: EmbeddingFunction, config?: SemanticRetrievalConfig);
+    /**
+     * Retrieve memories semantically similar to the query
+     */
+    retrieve(options: SemanticRetrievalOptions): Promise<RetrievalResult>;
+    /**
+     * Retrieve with context - includes surrounding memories
+     */
+    retrieveWithContext(options: SemanticRetrievalOptions, contextWindow?: number): Promise<RetrievalResult & {
+        contextMemories: MemoryEntry[][];
+    }>;
+    /**
+     * Get memories surrounding a given memory by timestamp
+     */
+    private getSurroundingMemories;
+    /**
+     * Rerank results using provided rerank function
+     */
+    private rerank;
+    /**
+     * Find memories similar to a given memory
+     */
+    findSimilar(memory: MemoryEntry, options?: Partial<SemanticRetrievalOptions>): Promise<ScoredMemory[]>;
+    /**
+     * Cluster memories by semantic similarity
+     */
+    cluster(memories: MemoryEntry[], numClusters?: number): Promise<Map<number, MemoryEntry[]>>;
+    /**
+     * Calculate cosine similarity between two vectors
+     */
+    private cosineSimilarity;
+    /**
+     * Calculate average embedding
+     */
+    private averageEmbedding;
+    /**
+     * Random sample without replacement
+     */
+    private randomSample;
+    /**
+     * Update configuration
+     */
+    configure(config: Partial<SemanticRetrievalConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): SemanticRetrievalConfig;
+}
+/**
+ * Create a semantic retrieval instance
+ */
+declare function createSemanticRetrieval(store: MemoryStoreInterface, embedFn: EmbeddingFunction, config?: SemanticRetrievalConfig): SemanticRetrieval;
+
+/**
+ * HybridRetrieval
+ *
+ * Combines semantic search with keyword matching for better recall.
+ */
+
+/**
+ * Hybrid retrieval options
+ */
+interface HybridRetrievalOptions {
+    query: string;
+    topK?: number;
+    minScore?: number;
+    namespace?: string;
+    filter?: Record<string, unknown>;
+    semanticWeight?: number;
+    keywordWeight?: number;
+}
+/**
+ * Hybrid retrieval strategy combining semantic and keyword search
+ */
+declare class HybridRetrieval {
+    private store;
+    private semanticRetrieval;
+    private config;
+    constructor(store: MemoryStoreInterface, embedFn: EmbeddingFunction, config?: HybridRetrievalConfig);
+    /**
+     * Retrieve memories using hybrid search
+     */
+    retrieve(options: HybridRetrievalOptions): Promise<RetrievalResult>;
+    /**
+     * Keyword-based search using text matching
+     */
+    private keywordSearch;
+    /**
+     * Tokenize text into terms
+     */
+    private tokenize;
+    /**
+     * Calculate BM25-like keyword score
+     */
+    private calculateKeywordScore;
+    /**
+     * Fuse semantic and keyword results
+     */
+    private fuseResults;
+    /**
+     * Reciprocal Rank Fusion (RRF)
+     */
+    private reciprocalRankFusion;
+    /**
+     * Weighted score fusion
+     */
+    private weightedFusion;
+    /**
+     * Retrieve with explanation of why each result matched
+     */
+    retrieveWithExplanation(options: HybridRetrievalOptions): Promise<RetrievalResult & {
+        explanations: string[];
+    }>;
+    /**
+     * Update configuration
+     */
+    configure(config: Partial<HybridRetrievalConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): HybridRetrievalConfig;
+}
+/**
+ * Create a hybrid retrieval instance
+ */
+declare function createHybridRetrieval(store: MemoryStoreInterface, embedFn: EmbeddingFunction, config?: HybridRetrievalConfig): HybridRetrieval;
+
+/**
+ * TemporalRetrieval
+ *
+ * Time-based memory retrieval with recency weighting and temporal patterns.
+ */
+
+/**
+ * Temporal retrieval options
+ */
+interface TemporalRetrievalOptions {
+    startTime?: number;
+    endTime?: number;
+    topK?: number;
+    recencyWeight?: number;
+    importanceWeight?: number;
+    accessWeight?: number;
+    namespace?: string;
+    types?: string[];
+    filter?: Record<string, unknown>;
+}
+/**
+ * Time window definition
+ */
+interface TimeWindow {
+    start: number;
+    end: number;
+    label?: string;
+}
+/**
+ * Temporal pattern
+ */
+interface TemporalPattern {
+    type: 'daily' | 'weekly' | 'monthly' | 'custom';
+    interval: number;
+    peakHours?: number[];
+    peakDays?: number[];
+}
+/**
+ * Temporal retrieval strategy with time-based scoring
+ */
+declare class TemporalRetrieval {
+    private store;
+    private config;
+    constructor(store: MemoryStoreInterface, config?: TemporalRetrievalConfig);
+    /**
+     * Retrieve memories with temporal scoring
+     */
+    retrieve(options: TemporalRetrievalOptions): Promise<RetrievalResult>;
+    /**
+     * Retrieve memories from specific time windows
+     */
+    retrieveFromWindows(windows: TimeWindow[], options?: Partial<TemporalRetrievalOptions>): Promise<Map<string, RetrievalResult>>;
+    /**
+     * Get memories from relative time periods
+     */
+    retrieveRecent(period: 'hour' | 'day' | 'week' | 'month', options?: Partial<TemporalRetrievalOptions>): Promise<RetrievalResult>;
+    /**
+     * Get trending memories (high access in recent time)
+     */
+    retrieveTrending(windowMs?: number, options?: Partial<TemporalRetrievalOptions>): Promise<RetrievalResult>;
+    /**
+     * Get memories matching a temporal pattern
+     */
+    retrieveByPattern(pattern: TemporalPattern, lookbackPeriods?: number, options?: Partial<TemporalRetrievalOptions>): Promise<RetrievalResult>;
+    /**
+     * Get timeline of memories
+     */
+    getTimeline(options: {
+        startTime: number;
+        endTime: number;
+        bucketSize: 'hour' | 'day' | 'week';
+        namespace?: string;
+    }): Promise<Map<string, MemoryEntry[]>>;
+    /**
+     * Calculate temporal score for a memory
+     */
+    private calculateTemporalScore;
+    /**
+     * Calculate decay based on configured function
+     */
+    private calculateDecay;
+    /**
+     * Apply metadata filter to entries
+     */
+    private applyFilter;
+    /**
+     * Deduplicate entries by ID
+     */
+    private deduplicateEntries;
+    /**
+     * Update configuration
+     */
+    configure(config: Partial<TemporalRetrievalConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): TemporalRetrievalConfig;
+}
+/**
+ * Create a temporal retrieval instance
+ */
+declare function createTemporalRetrieval(store: MemoryStoreInterface, config?: TemporalRetrievalConfig): TemporalRetrieval;
+/**
+ * Helper to create common time windows
+ */
+declare const TimeWindows: {
+    lastHour: () => TimeWindow;
+    lastDay: () => TimeWindow;
+    lastWeek: () => TimeWindow;
+    lastMonth: () => TimeWindow;
+    today: () => TimeWindow;
+    yesterday: () => TimeWindow;
+    custom: (startDate: Date, endDate: Date, label?: string) => TimeWindow;
+};
+
+/**
+ * RetrievalPipeline
+ *
+ * Chains multiple retrieval strategies together with configurable stages.
+ */
+
+/**
+ * Pipeline stage function type
+ */
+type PipelineStage = (input: PipelineContext, config: StageConfig) => Promise<PipelineContext>;
+/**
+ * Stage configuration
+ */
+interface StageConfig {
+    name: string;
+    enabled?: boolean;
+    params?: Record<string, unknown>;
+}
+/**
+ * Pipeline context passed between stages
+ */
+interface PipelineContext {
+    query: string;
+    candidates: ScoredMemory[];
+    metadata: Record<string, unknown>;
+    timing: Record<string, number>;
+}
+/**
+ * Pipeline configuration
+ */
+interface PipelineConfig {
+    stages: StageConfig[];
+    maxCandidates?: number;
+    minScore?: number;
+    timeout?: number;
+}
+/**
+ * Built-in stage types
+ */
+type BuiltInStage = 'filter' | 'boost' | 'rerank' | 'dedupe' | 'diversify' | 'truncate' | 'enrich';
+/**
+ * Retrieval pipeline for chaining retrieval strategies
+ */
+declare class RetrievalPipeline {
+    private stages;
+    private config;
+    constructor(config?: PipelineConfig);
+    /**
+     * Register built-in stages
+     */
+    private registerBuiltInStages;
+    /**
+     * Register a custom stage
+     */
+    register(name: string, stage: PipelineStage): void;
+    /**
+     * Execute the pipeline
+     */
+    execute(query: string, initialCandidates: ScoredMemory[]): Promise<RetrievalResult>;
+    /**
+     * Execute promise with timeout
+     */
+    private executeWithTimeout;
+    /**
+     * Get dedupe key for an entry
+     */
+    private getDedupeKey;
+    /**
+     * Add a stage to the pipeline
+     */
+    addStage(config: StageConfig): this;
+    /**
+     * Remove a stage from the pipeline
+     */
+    removeStage(name: string): this;
+    /**
+     * Update pipeline configuration
+     */
+    configure(config: Partial<PipelineConfig>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): PipelineConfig;
+    /**
+     * Get registered stage names
+     */
+    getStageNames(): string[];
+}
+/**
+ * Pipeline builder for fluent API
+ */
+declare class PipelineBuilder {
+    private stages;
+    private maxCandidates;
+    private minScore;
+    private timeout;
+    private customStages;
+    /**
+     * Add a filter stage
+     */
+    filter(filters: Record<string, unknown>): this;
+    /**
+     * Add a boost stage
+     */
+    boost(boosts: Array<{
+        field: string;
+        value: unknown;
+        factor: number;
+    }>): this;
+    /**
+     * Add a rerank stage
+     */
+    rerank(weights: Record<string, number>): this;
+    /**
+     * Add a dedupe stage
+     */
+    dedupe(field?: string, similarity?: number): this;
+    /**
+     * Add a diversify stage
+     */
+    diversify(field?: string, maxPerCategory?: number): this;
+    /**
+     * Add a truncate stage
+     */
+    truncate(limit: number): this;
+    /**
+     * Add an enrich stage
+     */
+    enrich(enrichFn: (entry: MemoryEntry) => Promise<Record<string, unknown>>): this;
+    /**
+     * Add a custom stage
+     */
+    custom(name: string, stage: PipelineStage, params?: Record<string, unknown>): this;
+    /**
+     * Set maximum candidates
+     */
+    withMaxCandidates(max: number): this;
+    /**
+     * Set minimum score
+     */
+    withMinScore(min: number): this;
+    /**
+     * Set timeout
+     */
+    withTimeout(ms: number): this;
+    /**
+     * Build the pipeline
+     */
+    build(): RetrievalPipeline;
+}
+/**
+ * Create a pipeline builder
+ */
+declare function createPipelineBuilder(): PipelineBuilder;
+/**
+ * Create a retrieval pipeline
+ */
+declare function createRetrievalPipeline(config?: PipelineConfig): RetrievalPipeline;
+
+export { type BuiltInStage as B, type EmbeddingFunction as E, type HybridRetrievalConfig as H, PipelineBuilder as P, type RetrievalPipelineConfig as R, type SemanticRetrievalConfig as S, type TemporalRetrievalConfig as T, type RetrievalResultWithDebug as a, SemanticRetrieval as b, createSemanticRetrieval as c, HybridRetrieval as d, createHybridRetrieval as e, TemporalRetrieval as f, createTemporalRetrieval as g, TimeWindows as h, RetrievalPipeline as i, createRetrievalPipeline as j, createPipelineBuilder as k, type SemanticRetrievalOptions as l, type HybridRetrievalOptions as m, type TemporalRetrievalOptions as n, type TimeWindow as o, type TemporalPattern as p, type PipelineStage as q, type StageConfig as r, type PipelineContext as s, type PipelineConfig as t };