aether-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,880 @@
+/**
+ * Represents a relationship between memory events.
+ */
+interface EventRelation {
+    /** The type of relationship */
+    type: 'follows' | 'references' | 'causes' | 'related_to';
+    /** The ID of the target event */
+    targetEventId: string;
+    /** Optional metadata about the relationship */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Core data model for a memory event.
+ * All memories are stored as structured events, ensuring temporal
+ * and relational context is preserved.
+ */
+interface MemoryEvent {
+    /** Unique identifier for the memory event (ULID for sortability) */
+    id: string;
+    /** ISO 8601 timestamp of when the event occurred */
+    timestamp: string;
+    /** Entity that performed the action (e.g., 'user123', 'system', 'assistant') */
+    actor: string;
+    /** Type of action or event (e.g., 'selected', 'purchased', 'responded') */
+    action: string;
+    /** Natural language description of the event */
+    content: string;
+    /** Structured metadata providing context */
+    context: Record<string, unknown>;
+    /** Vector embedding for semantic search (added by the system) */
+    embedding?: number[];
+    /** Optional relations to other events */
+    relations?: EventRelation[];
+}
+/**
+ * Input for creating a new memory event.
+ * Most fields are optional and will be auto-populated.
+ */
+interface MemoryEventInput {
+    /** Entity that performed the action */
+    actor?: string;
+    /** Type of action or event */
+    action?: string;
+    /** Natural language description of the event (required) */
+    content: string;
+    /** Structured metadata providing context */
+    context?: Record<string, unknown>;
+    /** Optional relations to other events */
+    relations?: EventRelation[];
+}
+/**
+ * A memory event with an associated relevance score.
+ * Used in retrieval results.
+ */
+interface ScoredMemoryEvent extends MemoryEvent {
+    /** Relevance score (0-1, higher is more relevant) */
+    score: number;
+}
+
+/**
+ * Time range for filtering events.
+ */
+interface TimeRange {
+    /** Start of the time range (ISO 8601) */
+    start: string;
+    /** End of the time range (ISO 8601) */
+    end: string;
+}
+/**
+ * Retrieval strategy type.
+ */
+type RetrievalType = 'semantic' | 'temporal' | 'relational' | 'hybrid';
+/**
+ * Options for retrieving memories.
+ */
+interface RetrievalOptions {
+    /** Filter by actor */
+    actor?: string;
+    /** Filter by time range */
+    timeRange?: TimeRange;
+    /** Maximum number of results to return */
+    limit?: number;
+    /** Type of retrieval strategy to use */
+    retrievalType?: RetrievalType;
+    /** Filter by specific context fields */
+    contextFilters?: Record<string, unknown>;
+    /** Include embedding vectors in results */
+    includeEmbeddings?: boolean;
+    /** Minimum similarity threshold for semantic search (0-1) */
+    threshold?: number;
+}
+/**
+ * Options for advanced multi-modal search.
+ */
+interface AdvancedSearchOptions {
+    /** Semantic search configuration */
+    semantic?: {
+        /** Query text for semantic similarity */
+        query: string;
+        /** Weight for this retrieval mode (0-1) */
+        weight?: number;
+    };
+    /** Temporal search configuration */
+    temporal?: {
+        /** Actor to retrieve history for */
+        actor: string;
+        /** How many recent events to consider */
+        recency?: number;
+        /** Weight for this retrieval mode (0-1) */
+        weight?: number;
+    };
+    /** Relational search configuration */
+    relational?: {
+        /** Context keys to match */
+        contextKeys: string[];
+        /** Values to match */
+        values: unknown[];
+        /** Weight for this retrieval mode (0-1) */
+        weight?: number;
+    };
+    /** Maximum number of results */
+    limit?: number;
+    /** How to combine results from different strategies */
+    combineStrategy?: 'union' | 'intersection' | 'weighted';
+}
+/**
+ * Options for querying by actor.
+ */
+interface TemporalQueryOptions {
+    /** Maximum number of results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+    /** Sort order by timestamp */
+    order?: 'asc' | 'desc';
+}
+/**
+ * General query options.
+ */
+interface QueryOptions {
+    /** Maximum number of results */
+    limit?: number;
+    /** Offset for pagination */
+    offset?: number;
+}
+/**
+ * Options for vector similarity search.
+ */
+interface VectorSearchOptions {
+    /** Maximum number of results */
+    limit?: number;
+    /** Minimum similarity threshold (0-1) */
+    threshold?: number;
+    /** Additional filters to apply */
+    filters?: Record<string, unknown>;
+}
+
+/**
+ * Abstract interface for storage adapters.
+ * Implementations can use any backing store (in-memory, PostgreSQL, Neo4j, etc.)
+ */
+interface StorageAdapter {
+    /** Unique identifier for this adapter type */
+    readonly name: string;
+    /**
+     * Initialize the adapter (create tables, indexes, etc.)
+     * Called once before any other operations.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Store a single memory event.
+     * @param event The event to store (must include id and embedding if applicable)
+     * @returns The stored event
+     */
+    store(event: MemoryEvent): Promise<MemoryEvent>;
+    /**
+     * Store multiple memory events in a batch.
+     * @param events The events to store
+     * @returns The stored events
+     */
+    storeBatch(events: MemoryEvent[]): Promise<MemoryEvent[]>;
+    /**
+     * Retrieve an event by its ID.
+     * @param id The event ID
+     * @returns The event or null if not found
+     */
+    getById(id: string): Promise<MemoryEvent | null>;
+    /**
+     * Retrieve multiple events by their IDs.
+     * @param ids The event IDs
+     * @returns The found events (may be fewer than requested)
+     */
+    getByIds(ids: string[]): Promise<MemoryEvent[]>;
+    /**
+     * Query events by actor (for temporal retrieval).
+     * @param actor The actor identifier
+     * @param options Query options (limit, offset, order)
+     * @returns Events for the actor, ordered by timestamp
+     */
+    queryByActor(actor: string, options?: TemporalQueryOptions): Promise<MemoryEvent[]>;
+    /**
+     * Query events by context fields (for relational retrieval).
+     * @param filters Key-value pairs to match in event context
+     * @param options Query options
+     * @returns Matching events
+     */
+    queryByContext(filters: Record<string, unknown>, options?: QueryOptions): Promise<MemoryEvent[]>;
+    /**
+     * Query events within a time range.
+     * @param range The time range (start/end ISO 8601)
+     * @param options Query options
+     * @returns Events within the range
+     */
+    queryByTimeRange(range: TimeRange, options?: QueryOptions): Promise<MemoryEvent[]>;
+    /**
+     * Search for events by vector similarity (for semantic retrieval).
+     * @param vector The query embedding vector
+     * @param options Search options (limit, threshold, filters)
+     * @returns Scored events, ordered by similarity (highest first)
+     */
+    searchByVector(vector: number[], options?: VectorSearchOptions): Promise<ScoredMemoryEvent[]>;
+    /**
+     * Delete an event by ID.
+     * @param id The event ID to delete
+     * @returns True if deleted, false if not found
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Delete multiple events by IDs.
+     * @param ids The event IDs to delete
+     * @returns Number of events deleted
+     */
+    deleteBatch(ids: string[]): Promise<number>;
+    /**
+     * Delete all events. Use with caution!
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the count of stored events.
+     * @param filters Optional filters to count specific events
+     * @returns The event count
+     */
+    count(filters?: Record<string, unknown>): Promise<number>;
+    /**
+     * Get all unique actors.
+     * @returns Array of actor identifiers
+     */
+    getActors(): Promise<string[]>;
+    /**
+     * Close connections and cleanup resources.
+     */
+    close(): Promise<void>;
+}
+
+/**
+ * Abstract interface for embedding providers.
+ * Implementations can use any embedding service (VoyageAI, OpenAI, local models, etc.)
+ */
+interface EmbeddingProvider {
+    /** Unique identifier for this provider */
+    readonly name: string;
+    /** Number of dimensions in the embedding vectors */
+    readonly dimensions: number;
+    /**
+     * Generate an embedding vector for a single text.
+     * @param text The text to embed
+     * @returns The embedding vector
+     */
+    embed(text: string): Promise<number[]>;
+    /**
+     * Generate embedding vectors for multiple texts.
+     * More efficient than calling embed() multiple times.
+     * @param texts The texts to embed
+     * @returns Array of embedding vectors (same order as input)
+     */
+    embedBatch(texts: string[]): Promise<number[][]>;
+    /**
+     * Calculate the similarity between two embedding vectors.
+     * @param a First embedding vector
+     * @param b Second embedding vector
+     * @returns Similarity score (typically 0-1 for normalized vectors)
+     */
+    similarity(a: number[], b: number[]): number;
+}
+
+/**
+ * Configuration for the storage layer.
+ */
+interface StorageConfig {
+    /** The storage adapter instance */
+    adapter: StorageAdapter;
+}
+/**
+ * Configuration for the embedding provider.
+ */
+interface EmbeddingConfig {
+    /** The embedding provider instance */
+    provider: EmbeddingProvider;
+    /** Model to use (provider-specific) */
+    model?: string;
+    /** Embedding dimensions (auto-detected from provider if not specified) */
+    dimensions?: number;
+    /** Batch size for embedding multiple texts */
+    batchSize?: number;
+}
+/**
+ * Configuration for retrieval behavior.
+ */
+interface RetrievalConfig {
+    /** Default maximum number of results */
+    defaultLimit?: number;
+    /** Default retrieval type */
+    defaultType?: RetrievalType;
+    /** Weights for hybrid retrieval (must sum to 1) */
+    hybridWeights?: {
+        semantic: number;
+        temporal: number;
+        relational: number;
+    };
+    /** Reranker configuration */
+    reranker?: RerankerConfig;
+}
+/**
+ * Configuration for result reranking.
+ */
+interface RerankerConfig {
+    /** Whether reranking is enabled */
+    enabled: boolean;
+    /** Model to use for reranking (if applicable) */
+    model?: string;
+    /** Number of results to rerank */
+    topK?: number;
+}
+/**
+ * Logging configuration.
+ */
+interface LoggingConfig {
+    /** Log level */
+    level: 'debug' | 'info' | 'warn' | 'error';
+    /** Where to send logs */
+    destination?: 'console' | 'file' | 'custom';
+    /** Custom log handler */
+    handler?: (level: string, message: string, data?: unknown) => void;
+}
+/**
+ * Main configuration for Aether.
+ */
+interface AetherConfig {
+    /** Storage configuration */
+    storage: StorageConfig;
+    /** Embedding configuration */
+    embeddings: EmbeddingConfig;
+    /** Retrieval configuration (optional) */
+    retrieval?: RetrievalConfig;
+    /** Logging configuration (optional) */
+    logging?: LoggingConfig;
+}
+/**
+ * Statistics about the memory store.
+ */
+interface MemoryStats {
+    /** Total number of events stored */
+    totalEvents: number;
+    /** Number of unique actors */
+    uniqueActors: number;
+    /** Timestamp of oldest event */
+    oldestEvent?: string;
+    /** Timestamp of newest event */
+    newestEvent?: string;
+    /** Name of the storage adapter */
+    storageAdapter: string;
+    /** Name of the embedding provider */
+    embeddingProvider: string;
+}
+
+/**
+ * Type for unsubscribe function returned by subscribe.
+ */
+type Unsubscribe = () => void;
+/**
+ * Event listener callback type.
+ */
+type EventListener = (event: MemoryEvent) => void;
+/**
+ * Aether - Event-driven memory framework for LLM/AI agents.
+ *
+ * Provides a simple, intuitive API for recording and retrieving memories,
+ * moving beyond the limitations of pure vector-based RAG.
+ *
+ * @example
+ * ```typescript
+ * const aether = new Aether({
+ *   storage: { adapter: new InMemoryStorageAdapter() },
+ *   embeddings: { provider: new VoyageProvider({ apiKey: '...' }) },
+ * });
+ *
+ * // Add a memory
+ * await aether.add('User selected product XYZ', { productId: 'xyz' });
+ *
+ * // Retrieve relevant memories
+ * const memories = await aether.retrieve('What did the user look at?');
+ * ```
+ */
+declare class Aether {
+    private readonly storage;
+    private readonly embeddings;
+    private readonly retrieval;
+    private readonly config;
+    private readonly listeners;
+    private initialized;
+    constructor(config: AetherConfig);
+    /**
+     * Initialize the memory system.
+     * Called automatically on first operation if not called explicitly.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Add a memory event.
+     *
+     * @example Simple string input
+     * ```typescript
+     * await aether.add('User clicked the buy button');
+     * ```
+     *
+     * @example With context
+     * ```typescript
+     * await aether.add('User added item to cart', { cartId: '123', itemId: 'xyz' });
+     * ```
+     *
+     * @example Structured input
+     * ```typescript
+     * await aether.add({
+     *   actor: 'user123',
+     *   action: 'purchase',
+     *   content: 'Purchased premium subscription',
+     *   context: { planId: 'premium', amount: 99.99 }
+     * });
+     * ```
+     */
+    add(content: string, context?: Record<string, unknown>): Promise<MemoryEvent>;
+    add(event: MemoryEventInput): Promise<MemoryEvent>;
+    /**
+     * Add multiple memory events in a batch.
+     * More efficient than calling add() multiple times.
+     */
+    addBatch(events: MemoryEventInput[]): Promise<MemoryEvent[]>;
+    /**
+     * Retrieve relevant memories based on a query.
+     * Uses multi-modal retrieval (semantic, temporal, relational).
+     *
+     * @example Basic retrieval
+     * ```typescript
+     * const memories = await aether.retrieve('What products did the user view?');
+     * ```
+     *
+     * @example With options
+     * ```typescript
+     * const memories = await aether.retrieve('recent actions', {
+     *   actor: 'user123',
+     *   retrievalType: 'temporal',
+     *   limit: 10
+     * });
+     * ```
+     */
+    retrieve(query: string, options?: RetrievalOptions): Promise<MemoryEvent[]>;
+    /**
+     * Get the history of events for a specific actor.
+     * Events are returned in reverse chronological order (most recent first).
+     */
+    getHistory(actor: string, limit?: number): Promise<MemoryEvent[]>;
+    /**
+     * Get a specific event by ID.
+     */
+    get(id: string): Promise<MemoryEvent | null>;
+    /**
+     * Delete a specific event by ID.
+     */
+    delete(id: string): Promise<boolean>;
+    /**
+     * Advanced multi-modal search with fine-grained control.
+     */
+    search(options: AdvancedSearchOptions): Promise<MemoryEvent[]>;
+    /**
+     * Get events related to a specific event.
+     * Follows the relations defined on the event.
+     */
+    getRelated(eventId: string, depth?: number): Promise<MemoryEvent[]>;
+    /**
+     * Subscribe to new memory events.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback: EventListener): Unsubscribe;
+    /**
+     * Get statistics about the memory store.
+     */
+    stats(): Promise<MemoryStats>;
+    /**
+     * Close the memory system and release resources.
+     */
+    close(): Promise<void>;
+    /**
+     * Clear all stored memories.
+     * Use with caution!
+     */
+    clear(): Promise<void>;
+    /**
+     * Infer an action type from content.
+     */
+    private inferAction;
+    /**
+     * Notify all listeners of a new event.
+     */
+    private notifyListeners;
+}
+
+/**
+ * In-memory storage adapter for development and testing.
+ * Uses Maps for O(1) lookups and maintains indexes for efficient queries.
+ */
+declare class InMemoryStorageAdapter implements StorageAdapter {
+    readonly name = "in-memory";
+    /** Primary storage: id -> event */
+    private events;
+    /** Actor index: actor -> Set<event ids> */
+    private actorIndex;
+    /** Context index: context key -> value -> Set<event ids> */
+    private contextIndex;
+    /** Timestamp index: sorted list of [timestamp, id] for range queries */
+    private timestampIndex;
+    initialize(): Promise<void>;
+    store(event: MemoryEvent): Promise<MemoryEvent>;
+    storeBatch(events: MemoryEvent[]): Promise<MemoryEvent[]>;
+    getById(id: string): Promise<MemoryEvent | null>;
+    getByIds(ids: string[]): Promise<MemoryEvent[]>;
+    queryByActor(actor: string, options?: TemporalQueryOptions): Promise<MemoryEvent[]>;
+    queryByContext(filters: Record<string, unknown>, options?: QueryOptions): Promise<MemoryEvent[]>;
+    queryByTimeRange(range: TimeRange, options?: QueryOptions): Promise<MemoryEvent[]>;
+    searchByVector(vector: number[], options?: VectorSearchOptions): Promise<ScoredMemoryEvent[]>;
+    delete(id: string): Promise<boolean>;
+    deleteBatch(ids: string[]): Promise<number>;
+    clear(): Promise<void>;
+    count(filters?: Record<string, unknown>): Promise<number>;
+    getActors(): Promise<string[]>;
+    close(): Promise<void>;
+    /**
+     * Binary search to find insertion point for a timestamp.
+     */
+    private binarySearchInsert;
+}
+
+/**
+ * Mock embedding provider for testing and development.
+ * Generates deterministic pseudo-random embeddings based on text hash.
+ */
+declare class MockEmbeddingProvider implements EmbeddingProvider {
+    readonly name = "mock";
+    readonly dimensions: number;
+    constructor(dimensions?: number);
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    similarity(a: number[], b: number[]): number;
+    /**
+     * Generate a deterministic vector from text hash.
+     * Same text always produces the same vector.
+     */
+    private hashToVector;
+    /**
+     * Simple string hash function.
+     */
+    private simpleHash;
+}
+
+/**
+ * VoyageAI provider configuration.
+ */
+interface VoyageProviderConfig {
+    /** VoyageAI API key */
+    apiKey: string;
+    /** Model to use (default: 'voyage-2') */
+    model?: VoyageModel;
+    /** Base URL (default: 'https://api.voyageai.com/v1') */
+    baseUrl?: string;
+    /** Maximum texts per batch (default: 128) */
+    batchSize?: number;
+    /** Request timeout in ms (default: 30000) */
+    timeout?: number;
+    /** Maximum retries on failure (default: 3) */
+    maxRetries?: number;
+}
+/**
+ * Available VoyageAI models with their dimensions.
+ */
+type VoyageModel = 'voyage-3' | 'voyage-3-lite' | 'voyage-code-3' | 'voyage-finance-2' | 'voyage-law-2' | 'voyage-code-2' | 'voyage-2' | 'voyage-large-2' | 'voyage-large-2-instruct';
+/**
+ * VoyageAI embedding provider.
+ * Uses VoyageAI's API for generating high-quality embeddings.
+ */
+declare class VoyageProvider implements EmbeddingProvider {
+    readonly name = "voyage";
+    readonly dimensions: number;
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly batchSize;
+    private readonly timeout;
+    private readonly maxRetries;
+    constructor(config: VoyageProviderConfig);
+    embed(text: string): Promise<number[]>;
+    embedBatch(texts: string[]): Promise<number[][]>;
+    similarity(a: number[], b: number[]): number;
+    /**
+     * Embed a batch of texts with retry logic.
+     */
+    private embedWithRetry;
+    /**
+     * Call the VoyageAI API.
+     */
+    private callApi;
+    private sleep;
+}
+
+/**
+ * Context passed to retrieval strategies.
+ */
+interface RetrievalContext {
+    /** The storage adapter for querying events */
+    storage: StorageAdapter;
+    /** The embedding provider for vectorizing queries */
+    embeddings: EmbeddingProvider;
+}
+/**
+ * Interface for retrieval strategies.
+ * Each strategy implements a different approach to finding relevant memories.
+ */
+interface RetrievalStrategy {
+    /** The type of retrieval this strategy implements */
+    readonly type: RetrievalType;
+    /**
+     * Retrieve relevant memories using this strategy.
+     * @param query The search query
+     * @param context Storage and embedding context
+     * @param options Retrieval options
+     * @returns Scored memory events
+     */
+    retrieve(query: string, context: RetrievalContext, options: RetrievalOptions): Promise<ScoredMemoryEvent[]>;
+}
+
+/**
+ * The retrieval engine orchestrates multi-modal memory retrieval.
+ * It manages different strategies and combines their results.
+ */
+declare class RetrievalEngine {
+    private readonly storage;
+    private readonly embeddings;
+    private readonly config;
+    private readonly strategies;
+    constructor(storage: StorageAdapter, embeddings: EmbeddingProvider, config?: RetrievalConfig);
+    /**
+     * Retrieve relevant memories based on a query.
+     * @param query The search query
+     * @param options Retrieval options
+     * @returns Array of relevant memory events
+     */
+    retrieve(query: string, options?: RetrievalOptions): Promise<MemoryEvent[]>;
+    /**
+     * Get a specific retrieval strategy.
+     */
+    getStrategy(type: RetrievalType): RetrievalStrategy | undefined;
+    /**
+     * Register a custom retrieval strategy.
+     */
+    registerStrategy(type: string, strategy: RetrievalStrategy): void;
+    /**
+     * Rerank results (placeholder - can be extended with cross-encoder models).
+     */
+    private rerank;
+}
+
+/**
+ * Semantic retrieval strategy.
+ * Finds memories that are semantically similar to the query using vector search.
+ */
+declare class SemanticStrategy implements RetrievalStrategy {
+    readonly type: "semantic";
+    retrieve(query: string, context: RetrievalContext, options: RetrievalOptions): Promise<ScoredMemoryEvent[]>;
+}
+
+/**
+ * Temporal retrieval strategy.
+ * Retrieves recent memories for an actor, scoring by recency.
+ */
+declare class TemporalStrategy implements RetrievalStrategy {
+    readonly type: "temporal";
+    /** Decay rate for recency scoring (higher = faster decay) */
+    private readonly decayRate;
+    constructor(decayRate?: number);
+    retrieve(_query: string, context: RetrievalContext, options: RetrievalOptions): Promise<ScoredMemoryEvent[]>;
+}
+
+/**
+ * Interface for entity extraction from text.
+ * Implement this to create custom entity extractors (regex, NLP, LLM-based, etc.)
+ */
+interface EntityExtractor {
+    /**
+     * Extract entities from query text.
+     * @param query The query text to extract entities from
+     * @returns Object with entity key-value pairs (e.g., { userId: '123', productId: 'abc' })
+     */
+    extract(query: string): Record<string, unknown> | Promise<Record<string, unknown>>;
+}
+/**
+ * Configuration for pattern-based entity extraction.
+ */
+interface EntityPattern {
+    /** The context key to store the extracted value under */
+    key: string;
+    /** Regex pattern with a capture group for the value */
+    pattern: RegExp;
+}
+/**
+ * Default entity patterns for common use cases.
+ * These can be extended or replaced entirely.
+ */
+declare const DEFAULT_ENTITY_PATTERNS: EntityPattern[];
+/**
+ * Pattern-based entity extractor.
+ * Uses regex patterns to extract entities from text.
+ */
+declare class PatternEntityExtractor implements EntityExtractor {
+    private patterns;
+    constructor(patterns?: EntityPattern[]);
+    /**
+     * Add a new pattern.
+     */
+    addPattern(key: string, pattern: RegExp): void;
+    /**
+     * Add multiple patterns at once.
+     */
+    addPatterns(patterns: EntityPattern[]): void;
+    /**
+     * Remove a pattern by key.
+     */
+    removePattern(key: string): void;
+    /**
+     * Clear all patterns.
+     */
+    clearPatterns(): void;
+    /**
+     * Get current patterns.
+     */
+    getPatterns(): EntityPattern[];
+    extract(query: string): Record<string, unknown>;
+}
+/**
+ * Composite entity extractor that combines multiple extractors.
+ * Useful for combining pattern-based extraction with LLM-based extraction.
+ */
+declare class CompositeEntityExtractor implements EntityExtractor {
+    private extractors;
+    constructor(extractors?: EntityExtractor[]);
+    addExtractor(extractor: EntityExtractor): void;
+    extract(query: string): Promise<Record<string, unknown>>;
+}
+/**
+ * Configuration for the RelationalStrategy.
+ */
+interface RelationalStrategyConfig {
+    /** Custom entity extractor (defaults to PatternEntityExtractor) */
+    entityExtractor?: EntityExtractor;
+    /** Custom patterns for PatternEntityExtractor (ignored if entityExtractor is provided) */
+    patterns?: EntityPattern[];
+    /** Whether to include default patterns when providing custom patterns */
+    includeDefaultPatterns?: boolean;
+}
+/**
+ * Relational retrieval strategy.
+ * Finds memories related to specific entities mentioned in the query.
+ *
+ * Entity extraction is pluggable - you can:
+ * 1. Use the default pattern-based extractor
+ * 2. Provide custom regex patterns
+ * 3. Implement a custom EntityExtractor (e.g., using NLP or LLM)
+ *
+ * @example Default usage
+ * ```typescript
+ * const strategy = new RelationalStrategy();
+ * ```
+ *
+ * @example Custom patterns
+ * ```typescript
+ * const strategy = new RelationalStrategy({
+ *   patterns: [
+ *     { key: 'sku', pattern: /SKU[:\s]+([A-Z0-9-]+)/i },
+ *     { key: 'barcode', pattern: /barcode[:\s]+(\d+)/i },
+ *   ],
+ *   includeDefaultPatterns: true, // Also include default patterns
+ * });
+ * ```
+ *
+ * @example Custom extractor
+ * ```typescript
+ * class LLMEntityExtractor implements EntityExtractor {
+ *   async extract(query: string): Promise<Record<string, unknown>> {
+ *     // Call LLM to extract entities
+ *     const entities = await llm.extractEntities(query);
+ *     return entities;
+ *   }
+ * }
+ *
+ * const strategy = new RelationalStrategy({
+ *   entityExtractor: new LLMEntityExtractor(),
+ * });
+ * ```
+ */
+declare class RelationalStrategy implements RetrievalStrategy {
+    readonly type: "relational";
+    private entityExtractor;
+    constructor(config?: RelationalStrategyConfig);
+    /**
+     * Get the entity extractor (for testing or modification).
+     */
+    getEntityExtractor(): EntityExtractor;
+    retrieve(query: string, context: RetrievalContext, options: RetrievalOptions): Promise<ScoredMemoryEvent[]>;
+    /**
+     * Build filters from explicit context filters or by extracting entities from query.
+     */
+    private buildFilters;
+}
+
+/**
+ * Weights for combining different retrieval strategies.
+ */
+interface HybridWeights {
+    semantic: number;
+    temporal: number;
+    relational: number;
+}
+/**
+ * Hybrid retrieval strategy.
+ * Combines semantic, temporal, and relational strategies with configurable weights.
+ */
+declare class HybridStrategy implements RetrievalStrategy {
+    readonly type: "hybrid";
+    private readonly semanticStrategy;
+    private readonly temporalStrategy;
+    private readonly relationalStrategy;
+    private readonly weights;
+    constructor(weights?: Partial<HybridWeights>);
+    retrieve(query: string, context: RetrievalContext, options: RetrievalOptions): Promise<ScoredMemoryEvent[]>;
+}
+
+/**
+ * Generate a unique, sortable ID using ULID.
+ * ULIDs are lexicographically sortable by creation time.
+ */
+declare function generateId(): string;
+/**
+ * Get the timestamp from a ULID.
+ * @param id The ULID
+ * @returns The timestamp in milliseconds
+ */
+declare function getTimestampFromId(id: string): number;
+
+/**
+ * Normalize a vector to unit length.
+ */
+declare function normalize(v: number[]): number[];
+/**
+ * Calculate cosine similarity between two vectors.
+ * Returns a value between -1 and 1 (1 = identical, 0 = orthogonal, -1 = opposite).
+ * For normalized vectors, this is equivalent to the dot product.
+ */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Calculate Euclidean distance between two vectors.
+ */
+declare function euclideanDistance(a: number[], b: number[]): number;
+
+export { type AdvancedSearchOptions, Aether, type AetherConfig, CompositeEntityExtractor, DEFAULT_ENTITY_PATTERNS, type EmbeddingConfig, type EmbeddingProvider, type EntityExtractor, type EntityPattern, type EventListener, type EventRelation, HybridStrategy, type HybridWeights, InMemoryStorageAdapter, type LoggingConfig, type MemoryEvent, type MemoryEventInput, type MemoryStats, MockEmbeddingProvider, PatternEntityExtractor, type QueryOptions, RelationalStrategy, type RelationalStrategyConfig, type RerankerConfig, type RetrievalConfig, type RetrievalContext, RetrievalEngine, type RetrievalOptions, type RetrievalStrategy, type RetrievalType, type ScoredMemoryEvent, SemanticStrategy, type StorageAdapter, type StorageConfig, type TemporalQueryOptions, TemporalStrategy, type TimeRange, type Unsubscribe, type VectorSearchOptions, type VoyageModel, VoyageProvider, type VoyageProviderConfig, cosineSimilarity, euclideanDistance, generateId, getTimestampFromId, normalize };