@mzhub/mem-ts 0.1.0

package/dist/index.d.mts

@@ -0,0 +1,1206 @@
+export { b as MemoryMiddlewareOptions, M as MemoryOS, a as MemoryOSConfig, c as createMemoryMiddleware, d as digestAfterResponse, w as withMemory } from './index-Ci5Q9G9H.mjs';
+import { f as MemoryOperation, M as MemoryFact, E as ExtractionResult, H as HydrateOptions, d as HydratedContext, S as Session, F as FactFilter, C as ConversationExchange } from './types-G9qmfSeZ.mjs';
+export { a as CompletionOptions, b as CompletionResult, h as MemoryOSEvents, c as MemoryOSOptions, g as Message, P as ProviderConfig, e as ProviderName } from './types-G9qmfSeZ.mjs';
+import { B as BaseAdapter } from './BaseAdapter-BoRh1T7O.mjs';
+export { InMemoryAdapter, JSONFileAdapter, JSONFileAdapterConfig, MongoDBAdapter, MongoDBAdapterConfig, PostgresAdapter, PostgresAdapterConfig, UpstashRedisAdapter, UpstashRedisAdapterConfig } from './adapters/index.mjs';
+export { AnthropicProvider, CerebrasProvider, GeminiProvider, GroqProvider, OpenAIProvider, createProvider, getAvailableProviders } from './providers/index.mjs';
+import { B as BaseProvider } from './BaseProvider-edMh_R9t.mjs';
+
+interface ConflictResolutionResult {
+    /** Operations to apply after conflict resolution */
+    resolvedOperations: MemoryOperation[];
+    /** Conflicts that were detected and resolved */
+    conflicts: Array<{
+        existingFact: MemoryFact;
+        newOperation: MemoryOperation;
+        resolution: "replace" | "keep_both" | "merge" | "ignore";
+    }>;
+}
+type ConflictStrategy = "latest" | "keep_both" | "merge";
+/**
+ * Resolves conflicts between new operations and existing facts.
+ * Implements the conflict resolution logic for the memory graph.
+ */
+declare class ConflictResolver {
+    private strategy;
+    constructor(strategy?: ConflictStrategy);
+    /**
+     * Resolve conflicts between new operations and existing facts
+     */
+    resolve(userId: string, operations: MemoryOperation[], adapter: BaseAdapter): Promise<ConflictResolutionResult>;
+    /**
+     * Check if a predicate should allow multiple values
+     * (e.g., USES_TECH can have multiple values, but LOCATION should not)
+     */
+    isMultiValuePredicate(predicate: string): boolean;
+}
+
+interface ExtractorWorkerConfig {
+    /** Minimum confidence threshold for facts (0-1) */
+    minConfidence?: number;
+    /** Conflict resolution strategy */
+    conflictStrategy?: ConflictStrategy;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * The "Slow Brain" - Background worker that extracts facts from conversations.
+ * Runs asynchronously after responses are sent to users.
+ */
+declare class ExtractorWorker {
+    private provider;
+    private adapter;
+    private conflictResolver;
+    private minConfidence;
+    private debug;
+    private queue;
+    private processing;
+    constructor(provider: BaseProvider, adapter: BaseAdapter, config?: ExtractorWorkerConfig);
+    /**
+     * Queue a conversation exchange for background extraction.
+     * This method returns immediately (non-blocking).
+     */
+    enqueue(userId: string, sessionId: string, userMessage: string, assistantResponse: string): void;
+    /**
+     * Process the extraction queue
+     */
+    private processQueue;
+    /**
+     * Process a single extraction task
+     */
+    private processTask;
+    /**
+     * Apply memory operations to the storage adapter
+     */
+    private applyOperations;
+    /**
+     * Extract facts immediately (synchronous, for testing)
+     */
+    extractNow(userId: string, sessionId: string, userMessage: string, assistantResponse: string): Promise<ExtractionResult>;
+    /**
+     * Get the current queue length
+     */
+    getQueueLength(): number;
+    /**
+     * Check if the worker is currently processing
+     */
+    isProcessing(): boolean;
+    /**
+     * Wait for all queued tasks to complete
+     */
+    drain(): Promise<void>;
+    /**
+     * Get effective importance for an operation.
+     * Auto-escalates safety-critical predicates (allergies, medical, boundaries).
+     */
+    private getEffectiveImportance;
+}
+
+interface ContextHydratorConfig {
+    /** Maximum number of facts to include in context */
+    maxFacts?: number;
+    /** Maximum number of recent messages to include */
+    maxHistory?: number;
+    /** Format style for compiled prompt */
+    formatStyle?: "natural" | "structured" | "minimal";
+    /** Minimum confidence threshold for facts (0-1) */
+    minConfidence?: number;
+    /** Wrap context in safety tags to prevent injection */
+    safeMode?: boolean;
+}
+/**
+ * The "Fast Brain" - Builds compiled context for LLM injection.
+ * Runs synchronously before each LLM call.
+ */
+declare class ContextHydrator {
+    private adapter;
+    private config;
+    constructor(adapter: BaseAdapter, config?: ContextHydratorConfig);
+    /**
+     * Hydrate context for a user based on their message.
+     *
+     * Uses the "Amygdala pattern":
+     * 1. CRITICAL facts (importance >= 9) are ALWAYS included
+     * 2. Remaining budget filled with recent, high-confidence facts
+     */
+    hydrate(userId: string, _message: string, options?: HydrateOptions): Promise<HydratedContext>;
+    /**
+     * Record fact access for Hebbian learning (strengthens frequently used facts)
+     */
+    private recordAccess;
+    /**
+     * Compile facts and history into a prompt string
+     */
+    private compilePrompt;
+    /**
+     * Natural language format (default)
+     */
+    private compileNatural;
+    /**
+     * Structured format (for debugging or specific use cases)
+     */
+    private compileStructured;
+    /**
+     * Minimal format (just facts, no history)
+     */
+    private compileMinimal;
+    /**
+     * Convert a fact to natural language
+     */
+    private factToNaturalLanguage;
+    /**
+     * Group facts by subject
+     */
+    private groupFactsBySubject;
+    /**
+     * Truncate text to a maximum length
+     */
+    private truncate;
+}
+
+/**
+ * Configuration for semantic cache
+ */
+interface SemanticCacheConfig {
+    /** Maximum cache size per user */
+    maxSize?: number;
+    /** TTL in milliseconds (default: 5 minutes) */
+    ttlMs?: number;
+    /** Similarity threshold for cache hit (0-1) */
+    similarityThreshold?: number;
+}
+/**
+ * In-memory semantic cache for reducing redundant hydrations.
+ * Uses simple string similarity for matching - can be extended with embeddings.
+ */
+declare class SemanticCache {
+    private cache;
+    private config;
+    private stats;
+    constructor(config?: SemanticCacheConfig);
+    /**
+     * Try to get a cached context for a query
+     */
+    get(userId: string, query: string): HydratedContext | null;
+    /**
+     * Store a context in the cache
+     */
+    set(userId: string, query: string, context: HydratedContext): void;
+    /**
+     * Invalidate cache for a user (call after digest)
+     */
+    invalidate(userId: string): void;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        hits: number;
+        misses: number;
+        evictions: number;
+        hitRate: number;
+    };
+    /**
+     * Calculate simple string similarity using Jaccard index on word tokens
+     */
+    private calculateSimilarity;
+}
+
+/**
+ * Token economics utilities for mem-ts.
+ * Provides token estimation, compression, and analytics.
+ */
+/**
+ * Token usage statistics
+ */
+interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    estimatedCost?: number;
+}
+/**
+ * Token analytics over time
+ */
+interface TokenAnalytics {
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCalls: number;
+    averageInputTokens: number;
+    averageOutputTokens: number;
+    tokensSavedByCache: number;
+    tokensSavedByCompression: number;
+    estimatedSavings: number;
+}
+/**
+ * Pricing per 1M tokens (approximate, as of late 2024)
+ */
+declare const TOKEN_PRICING: Record<string, {
+    input: number;
+    output: number;
+}>;
+/**
+ * Estimate token count for a string.
+ * Uses a simple heuristic: ~4 characters per token for English text.
+ * For more accurate counts, use tiktoken or similar.
+ */
+declare function estimateTokens(text: string): number;
+/**
+ * Estimate cost for a given token usage
+ */
+declare function estimateCost(usage: {
+    inputTokens: number;
+    outputTokens: number;
+}, model: string): number;
+/**
+ * Token analytics tracker
+ */
+declare class TokenTracker {
+    private usages;
+    private tokensSavedByCache;
+    private tokensSavedByCompression;
+    private model;
+    constructor(model?: string);
+    /**
+     * Record a token usage
+     */
+    record(usage: {
+        inputTokens: number;
+        outputTokens: number;
+    }): void;
+    /**
+     * Record tokens saved by cache hit
+     */
+    recordCacheSavings(tokens: number): void;
+    /**
+     * Record tokens saved by compression
+     */
+    recordCompressionSavings(originalTokens: number, compressedTokens: number): void;
+    /**
+     * Get analytics summary
+     */
+    getAnalytics(): TokenAnalytics;
+    /**
+     * Reset analytics
+     */
+    reset(): void;
+}
+/**
+ * Compress conversation history by summarizing older messages.
+ * Returns a compressed conversation array.
+ */
+declare function compressConversation(messages: Array<{
+    role: string;
+    content: string;
+}>, options?: {
+    keepRecent?: number;
+    maxSummaryTokens?: number;
+}): {
+    messages: Array<{
+        role: string;
+        content: string;
+    }>;
+    originalTokens: number;
+    compressedTokens: number;
+};
+
+/**
+ * Event types for MemoryOS
+ */
+interface MemoryEvents {
+    "fact:created": {
+        fact: MemoryFact;
+        userId: string;
+    };
+    "fact:updated": {
+        fact: MemoryFact;
+        oldFact: MemoryFact;
+        userId: string;
+    };
+    "fact:deleted": {
+        fact: MemoryFact;
+        reason?: string;
+        userId: string;
+    };
+    "session:start": {
+        session: Session;
+    };
+    "session:end": {
+        session: Session;
+    };
+    "extraction:start": {
+        userId: string;
+        sessionId: string;
+    };
+    "extraction:complete": {
+        result: ExtractionResult;
+        userId: string;
+        sessionId: string;
+    };
+    "hydration:start": {
+        userId: string;
+        message: string;
+    };
+    "hydration:complete": {
+        userId: string;
+        factsCount: number;
+        fromCache: boolean;
+    };
+    "cache:hit": {
+        userId: string;
+        query: string;
+    };
+    "cache:miss": {
+        userId: string;
+        query: string;
+    };
+    error: {
+        error: Error;
+        context?: string;
+    };
+}
+type EventHandler<T> = (data: T) => void;
+/**
+ * Simple event emitter for MemoryOS events.
+ * Provides type-safe event handling.
+ */
+declare class MemoryEventEmitter {
+    private handlers;
+    /**
+     * Subscribe to an event
+     */
+    on<K extends keyof MemoryEvents>(event: K, handler: EventHandler<MemoryEvents[K]>): () => void;
+    /**
+     * Subscribe to an event once
+     */
+    once<K extends keyof MemoryEvents>(event: K, handler: EventHandler<MemoryEvents[K]>): () => void;
+    /**
+     * Emit an event
+     */
+    emit<K extends keyof MemoryEvents>(event: K, data: MemoryEvents[K]): void;
+    /**
+     * Remove all handlers for an event
+     */
+    off<K extends keyof MemoryEvents>(event: K): void;
+    /**
+     * Remove all handlers
+     */
+    removeAllListeners(): void;
+    /**
+     * Get handler count for an event
+     */
+    listenerCount<K extends keyof MemoryEvents>(event: K): number;
+}
+
+/**
+ * Security utilities for mem-ts.
+ * Protects against prompt injection and data poisoning.
+ */
+interface SecurityConfig {
+    /** Enable prompt injection detection */
+    detectInjection?: boolean;
+    /** Block facts that contain injection patterns */
+    blockInjectedFacts?: boolean;
+    /** Detect PII in facts */
+    detectPii?: boolean;
+    /** Redact PII before storing */
+    redactPii?: boolean;
+    /** Custom patterns to block */
+    customBlockPatterns?: RegExp[];
+}
+interface SecurityCheckResult {
+    safe: boolean;
+    issues: Array<{
+        type: "injection" | "pii" | "custom";
+        description: string;
+        location?: string;
+    }>;
+    sanitized?: string;
+}
+/**
+ * Security scanner for memory content
+ */
+declare class SecurityScanner {
+    private config;
+    constructor(config?: SecurityConfig);
+    /**
+     * Scan text for security issues
+     */
+    scan(text: string): SecurityCheckResult;
+    /**
+     * Check if a fact is safe to store
+     */
+    isSafeToStore(fact: {
+        subject: string;
+        predicate: string;
+        object: string;
+    }): SecurityCheckResult;
+}
+/**
+ * Wrap memory context in XML tags to instruct the LLM to treat it as data.
+ * This is a mitigation against prompt injection via memory.
+ */
+declare function wrapContextSafely(context: string): string;
+/**
+ * Sanitize a string for safe storage
+ */
+declare function sanitizeForStorage(text: string): string;
+
+/**
+ * Budget management for mem-ts.
+ * Prevents runaway costs from infinite loops or abuse.
+ */
+interface BudgetConfig {
+    /** Maximum tokens per user per day for background processing */
+    maxTokensPerUserPerDay?: number;
+    /** Maximum extraction calls per user per day */
+    maxExtractionsPerUserPerDay?: number;
+    /** Maximum facts per user (to prevent storage abuse) */
+    maxFactsPerUser?: number;
+    /** Maximum conversations stored per user */
+    maxConversationsPerUser?: number;
+    /** Cooldown between extractions in ms (prevents rapid-fire) */
+    extractionCooldownMs?: number;
+}
+/**
+ * Budget manager to prevent runaway costs and abuse.
+ */
+declare class BudgetManager {
+    private config;
+    private userBudgets;
+    constructor(config?: BudgetConfig);
+    private getToday;
+    private getUserState;
+    /**
+     * Check if a user can perform an extraction
+     */
+    canExtract(userId: string): {
+        allowed: boolean;
+        reason?: string;
+    };
+    /**
+     * Check if a user has token budget remaining
+     */
+    canUseTokens(userId: string, estimatedTokens: number): {
+        allowed: boolean;
+        reason?: string;
+    };
+    /**
+     * Record an extraction
+     */
+    recordExtraction(userId: string): void;
+    /**
+     * Record token usage
+     */
+    recordTokens(userId: string, tokens: number): void;
+    /**
+     * Get remaining budget for a user
+     */
+    getRemainingBudget(userId: string): {
+        tokensRemaining: number;
+        extractionsRemaining: number;
+    };
+    /**
+     * Get max facts allowed per user
+     */
+    getMaxFactsPerUser(): number;
+    /**
+     * Get max conversations allowed per user
+     */
+    getMaxConversationsPerUser(): number;
+    /**
+     * Reset a user's budget (for testing or admin override)
+     */
+    resetUserBudget(userId: string): void;
+    /**
+     * Get current usage stats for a user
+     */
+    getUsageStats(userId: string): {
+        tokensUsedToday: number;
+        extractionsToday: number;
+        tokensRemaining: number;
+        extractionsRemaining: number;
+    };
+}
+
+/**
+ * Memory decay utilities for mem-ts.
+ * Prevents the "stalker effect" by forgetting irrelevant facts over time.
+ */
+
+interface DecayConfig {
+    /** Enable automatic decay */
+    enabled?: boolean;
+    /** Default TTL for facts in days (null = never expire) */
+    defaultTtlDays?: number | null;
+    /** TTL for low-weight facts (confidence < 0.5) in days */
+    lowWeightTtlDays?: number;
+    /** Predicates that should never decay (e.g., NAME, ALLERGY) */
+    permanentPredicates?: string[];
+    /** Predicates that should decay quickly (e.g., WEARING, CURRENT_MOOD) */
+    ephemeralPredicates?: string[];
+    /** TTL for ephemeral predicates in hours */
+    ephemeralTtlHours?: number;
+    /** Minimum reinforcement count to become "permanent" */
+    reinforcementThreshold?: number;
+}
+interface FactWithDecay extends MemoryFact {
+    /** Number of times this fact has been reinforced (mentioned again) */
+    reinforcementCount?: number;
+    /** Last time the fact was reinforced */
+    lastReinforcedAt?: Date;
+    /** Calculated decay weight (0-1, where 0 = should be deleted) */
+    decayWeight?: number;
+    /** Calculated expiry time */
+    expiresAt?: Date | null;
+}
+/**
+ * Decay manager for memory facts
+ */
+declare class DecayManager {
+    private config;
+    constructor(config?: DecayConfig);
+    /**
+     * Calculate decay weight for a fact (0-1, where 0 = should be deleted)
+     */
+    calculateDecayWeight(fact: FactWithDecay): number;
+    /**
+     * Calculate expiry date for a fact
+     */
+    calculateExpiryDate(fact: FactWithDecay): Date | null;
+    /**
+     * Check if a fact should be pruned
+     */
+    shouldPrune(fact: FactWithDecay): boolean;
+    /**
+     * Filter facts by decay weight threshold
+     */
+    filterByWeight(facts: FactWithDecay[], minWeight?: number): FactWithDecay[];
+    /**
+     * Get facts that should be pruned
+     */
+    getFactsToPrune(facts: FactWithDecay[]): FactWithDecay[];
+    /**
+     * Check if a predicate is permanent (never decays)
+     */
+    isPermanent(predicate: string): boolean;
+    /**
+     * Check if a predicate is ephemeral (decays quickly)
+     */
+    isEphemeral(predicate: string): boolean;
+    /**
+     * Add a predicate to permanent list
+     */
+    addPermanentPredicate(predicate: string): void;
+    /**
+     * Add a predicate to ephemeral list
+     */
+    addEphemeralPredicate(predicate: string): void;
+}
+
+/**
+ * Auto-summarization manager for mem-ts.
+ * Triggers conversation summarization after a threshold of messages.
+ */
+
+interface AutoSummarizeConfig {
+    /** Enable auto-summarization */
+    enabled?: boolean;
+    /** Number of messages before triggering summarization */
+    threshold?: number;
+    /** Maximum summary length in characters */
+    maxSummaryLength?: number;
+}
+/**
+ * Auto-summarization manager
+ */
+declare class AutoSummarizer {
+    private adapter;
+    private provider;
+    private config;
+    private messageCounters;
+    constructor(adapter: BaseAdapter, provider: BaseProvider | null, config?: AutoSummarizeConfig);
+    /**
+     * Record a message and check if summarization should trigger
+     */
+    recordMessage(userId: string, sessionId: string): Promise<boolean>;
+    /**
+     * Summarize a session's conversation history
+     */
+    summarizeSession(userId: string, sessionId: string): Promise<string | null>;
+    /**
+     * Get current message count for a session
+     */
+    getMessageCount(userId: string, sessionId: string): number;
+    /**
+     * Reset message counter for a session
+     */
+    resetCounter(userId: string, sessionId: string): void;
+    /**
+     * Force summarization regardless of count
+     */
+    forceSummarize(userId: string, sessionId: string): Promise<string | null>;
+}
+
+/**
+ * Tiered storage adapter for mem-ts.
+ * Manages automatic data flow between hot, warm, and cold storage tiers.
+ */
+
+interface TieredAdapterConfig {
+    /** Hot storage (fast, limited) - e.g., Redis, in-memory */
+    hotAdapter: BaseAdapter;
+    /** Cold storage (slow, unlimited) - e.g., Postgres, MongoDB */
+    coldAdapter: BaseAdapter;
+    /** Maximum facts to keep in hot storage per user */
+    hotFactLimit?: number;
+    /** Maximum conversations to keep in hot storage per user */
+    hotConversationLimit?: number;
+    /** Automatically promote frequently accessed facts to hot */
+    autoPromote?: boolean;
+    /** Automatically demote old facts to cold */
+    autoDemote?: boolean;
+}
+/**
+ * Tiered storage adapter that manages hot (fast) and cold (persistent) storage.
+ *
+ * Hot tier: Recent/frequently accessed data for fast retrieval
+ * Cold tier: Long-term persistent storage
+ *
+ * Read path: Hot first, fall back to cold, promote on access
+ * Write path: Write to both (hot for speed, cold for durability)
+ */
+declare class TieredAdapter extends BaseAdapter {
+    private hot;
+    private cold;
+    private config;
+    constructor(config: TieredAdapterConfig);
+    initialize(): Promise<void>;
+    close(): Promise<void>;
+    getFacts(userId: string, filter?: FactFilter): Promise<MemoryFact[]>;
+    getFactById(userId: string, factId: string): Promise<MemoryFact | null>;
+    upsertFact(userId: string, fact: Omit<MemoryFact, "id" | "createdAt" | "updatedAt">): Promise<MemoryFact>;
+    updateFact(userId: string, factId: string, updates: Partial<MemoryFact>): Promise<MemoryFact>;
+    deleteFact(userId: string, factId: string, reason?: string): Promise<void>;
+    hardDeleteFact(userId: string, factId: string): Promise<void>;
+    getConversationHistory(userId: string, limit?: number, sessionId?: string): Promise<ConversationExchange[]>;
+    saveConversation(userId: string, exchange: Omit<ConversationExchange, "id">): Promise<ConversationExchange>;
+    getSessions(userId: string, limit?: number): Promise<Session[]>;
+    getSession(userId: string, sessionId: string): Promise<Session | null>;
+    createSession(userId: string): Promise<Session>;
+    endSession(userId: string, sessionId: string, summary?: string): Promise<Session>;
+    private promoteFactsToHot;
+    private demoteOldFacts;
+    private demoteOldConversations;
+    /**
+     * Manually promote a fact to hot storage
+     */
+    promoteToHot(userId: string, factId: string): Promise<void>;
+    /**
+     * Manually demote a fact from hot storage
+     */
+    demoteFromHot(userId: string, factId: string): Promise<void>;
+    /**
+     * Sync all facts from cold to hot for a user (cache warming)
+     */
+    warmCache(userId: string): Promise<void>;
+    /**
+     * Get storage statistics
+     */
+    getStorageStats(userId: string): Promise<{
+        hotFacts: number;
+        coldFacts: number;
+        hotConversations: number;
+        coldConversations: number;
+    }>;
+}
+
+/**
+ * Embeddings support for mem-ts.
+ * Provides vector embeddings for semantic search.
+ */
+interface EmbeddingConfig {
+    /** Embedding provider */
+    provider: "openai" | "cohere" | "local";
+    /** API key (for cloud providers) */
+    apiKey?: string;
+    /** Model to use */
+    model?: string;
+    /** Embedding dimensions */
+    dimensions?: number;
+}
+interface EmbeddingResult {
+    /** The embedding vector */
+    vector: number[];
+    /** Token count */
+    tokens: number;
+}
+/**
+ * Embedding provider interface
+ */
+declare abstract class BaseEmbeddingProvider {
+    protected config: EmbeddingConfig;
+    constructor(config: EmbeddingConfig);
+    abstract embed(text: string): Promise<EmbeddingResult>;
+    abstract embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    abstract getDimensions(): number;
+}
+/**
+ * OpenAI embedding provider
+ */
+declare class OpenAIEmbeddingProvider extends BaseEmbeddingProvider {
+    private model;
+    private dimensions;
+    constructor(config: EmbeddingConfig);
+    embed(text: string): Promise<EmbeddingResult>;
+    embedBatch(texts: string[]): Promise<EmbeddingResult[]>;
+    getDimensions(): number;
+}
+/**
+ * Calculate cosine similarity between two vectors
+ */
+declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Find top-k most similar vectors
+ */
+declare function findTopK(query: number[], candidates: Array<{
+    id: string;
+    vector: number[];
+}>, k: number): Array<{
+    id: string;
+    similarity: number;
+}>;
+/**
+ * In-memory vector store for simple use cases
+ */
+declare class InMemoryVectorStore {
+    private vectors;
+    /**
+     * Store a vector for a user
+     */
+    store(userId: string, id: string, vector: number[]): void;
+    /**
+     * Search for similar vectors
+     */
+    search(userId: string, query: number[], k?: number): Array<{
+        id: string;
+        similarity: number;
+    }>;
+    /**
+     * Delete a vector
+     */
+    delete(userId: string, id: string): void;
+    /**
+     * Clear all vectors for a user
+     */
+    clear(userId: string): void;
+    /**
+     * Get vector count for a user
+     */
+    count(userId: string): number;
+}
+/**
+ * Create an embedding provider
+ */
+declare function createEmbeddingProvider(config: EmbeddingConfig): BaseEmbeddingProvider;
+
+/**
+ * Deep Sleep Worker - "Sleep Synthesis" for pattern recognition.
+ *
+ * Runs on a schedule (not per-message) to find higher-level patterns
+ * across multiple conversations over time.
+ *
+ * Biological analogy: During sleep, the brain consolidates memories
+ * and connects dots between experiences that happened days apart.
+ */
+
+interface DeepSleepConfig {
+    /** Hours to look back for recent facts (default: 24) */
+    lookbackHours?: number;
+    /** Minimum facts needed to trigger synthesis (default: 3) */
+    minFactsForSynthesis?: number;
+    /** Maximum new insights to generate (default: 5) */
+    maxInsights?: number;
+    /** Minimum confidence for synthesized insights (default: 0.7) */
+    minInsightConfidence?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Deep Sleep Worker - Scheduled batch synthesis for pattern recognition.
+ *
+ * Call `runSynthesisCycle(userId)` on a schedule (e.g., nightly cron).
+ */
+declare class DeepSleepWorker {
+    private provider;
+    private adapter;
+    private config;
+    constructor(provider: BaseProvider, adapter: BaseAdapter, config?: DeepSleepConfig);
+    /**
+     * Run a synthesis cycle for a user.
+     * Meant to be called on a schedule (e.g., nightly).
+     */
+    runSynthesisCycle(userId: string): Promise<MemoryOperation[]>;
+    /**
+     * Run synthesis for all active users.
+     * Call this from a cron job for batch processing.
+     */
+    runGlobalCycle(userIds: string[]): Promise<Map<string, MemoryOperation[]>>;
+    private buildPrompt;
+}
+
+/**
+ * Memory Consolidation Worker
+ *
+ * Implements the three-stage memory model:
+ * - Short-term: Just learned, may not persist (< 1 hour, < 2 accesses)
+ * - Working: Being actively used (1-24 hours, 2-5 accesses)
+ * - Long-term: Consolidated through reinforcement (> 24 hours, > 5 accesses)
+ *
+ * Facts progress through stages based on time and access patterns.
+ */
+
+interface ConsolidationConfig {
+    /** Hours before short-term can become working (default: 1) */
+    shortTermHours?: number;
+    /** Hours before working can become long-term (default: 24) */
+    workingHours?: number;
+    /** Access count to promote short-term → working (default: 2) */
+    workingAccessThreshold?: number;
+    /** Access count to promote working → long-term (default: 5) */
+    longTermAccessThreshold?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+type MemoryStage = "short-term" | "working" | "long-term";
+/**
+ * Manages memory consolidation through the three-stage model.
+ */
+declare class ConsolidationWorker {
+    private adapter;
+    private config;
+    constructor(adapter: BaseAdapter, config?: ConsolidationConfig);
+    /**
+     * Determine what stage a fact should be in based on age and access.
+     */
+    determineStage(fact: MemoryFact): MemoryStage;
+    /**
+     * Run consolidation for a user's facts.
+     * Promotes facts through stages based on age and access patterns.
+     */
+    consolidate(userId: string): Promise<{
+        promoted: number;
+        demoted: number;
+        unchanged: number;
+    }>;
+    /**
+     * Get facts filtered by memory stage.
+     */
+    getFactsByStage(userId: string, stage: MemoryStage): Promise<MemoryFact[]>;
+    /**
+     * Automatically prune short-term facts that haven't been accessed.
+     * Call this periodically to clean up ephemeral memories.
+     */
+    pruneShortTerm(userId: string, maxAgeHours?: number): Promise<number>;
+}
+
+/**
+ * Contradiction Detection
+ *
+ * Detects when new facts conflict with existing facts in real-time.
+ * Can be used to:
+ * 1. Automatically resolve conflicts
+ * 2. Flag for user clarification
+ * 3. Emit events for logging/debugging
+ */
+
+interface ContradictionConfig {
+    /** Whether to auto-resolve contradictions (default: true) */
+    autoResolve?: boolean;
+    /** Use LLM to detect semantic contradictions (default: false) */
+    useLLM?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+interface Contradiction {
+    /** The new fact attempting to be stored */
+    newFact: MemoryOperation;
+    /** The existing fact it conflicts with */
+    existingFact: MemoryFact;
+    /** Type of contradiction */
+    type: "direct" | "semantic" | "temporal";
+    /** Confidence that this is a real contradiction (0-1) */
+    confidence: number;
+    /** Description of the contradiction */
+    description: string;
+}
+interface ContradictionResult {
+    /** Whether contradictions were found */
+    hasContradictions: boolean;
+    /** List of detected contradictions */
+    contradictions: Contradiction[];
+    /** Suggested resolution */
+    resolution?: "replace" | "keep" | "merge" | "clarify";
+}
+/**
+ * Detects contradictions between new and existing facts.
+ */
+declare class ContradictionDetector {
+    private adapter;
+    private provider?;
+    private config;
+    constructor(adapter: BaseAdapter, provider?: BaseProvider, config?: ContradictionConfig);
+    /**
+     * Check if a new operation contradicts existing facts.
+     */
+    check(userId: string, operation: MemoryOperation): Promise<ContradictionResult>;
+    /**
+     * Analyze if two facts are truly contradictory.
+     */
+    private analyzeContradiction;
+    /**
+     * Use LLM to detect semantic contradictions.
+     */
+    private checkSemanticContradiction;
+    /**
+     * Check multiple operations at once.
+     */
+    checkBatch(userId: string, operations: MemoryOperation[]): Promise<Map<number, ContradictionResult>>;
+}
+
+/**
+ * Association Engine - Knowledge Graph Links
+ *
+ * Creates and manages links between related facts.
+ * Enables richer context by connecting:
+ * - "likes hiking" → "likes outdoors"
+ * - "works at Google" → "is an engineer"
+ */
+
+interface AssociationConfig {
+    /** Minimum similarity score to auto-link (default: 0.7) */
+    similarityThreshold?: number;
+    /** Maximum associations per fact (default: 5) */
+    maxAssociations?: number;
+    /** Use LLM to find semantic relationships (default: false) */
+    useLLM?: boolean;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+interface Association {
+    /** Source fact ID */
+    fromFactId: string;
+    /** Target fact ID */
+    toFactId: string;
+    /** Type of relationship */
+    relationship: "similar" | "implies" | "contradicts" | "related" | "causes";
+    /** Strength of association (0-1) */
+    strength: number;
+}
+/**
+ * Manages associations (links) between facts.
+ */
+declare class AssociationEngine {
+    private adapter;
+    private provider?;
+    private config;
+    constructor(adapter: BaseAdapter, provider?: BaseProvider, config?: AssociationConfig);
+    /**
+     * Manually link two facts together.
+     */
+    linkFacts(userId: string, factIdA: string, factIdB: string, relationship?: Association["relationship"]): Promise<void>;
+    /**
+     * Find all facts related to a given fact.
+     */
+    findRelated(userId: string, factId: string): Promise<MemoryFact[]>;
+    /**
+     * Automatically find and link similar facts using embeddings.
+     */
+    autoLink(userId: string): Promise<number>;
+    /**
+     * Use LLM to find deeper relationships between facts.
+     */
+    findSemanticRelationships(userId: string): Promise<Association[]>;
+    /**
+     * Get the full knowledge graph for a user.
+     */
+    getGraph(userId: string): Promise<{
+        nodes: MemoryFact[];
+        edges: Array<{
+            from: string;
+            to: string;
+        }>;
+    }>;
+}
+
+/**
+ * Predictive Engine - Behavioral Pattern Detection
+ *
+ * Detects temporal and behavioral patterns in user interactions:
+ * - "User usually asks about X on Mondays"
+ * - "User tends to discuss work topics in mornings"
+ * - "User often follows up on topic Y after topic X"
+ */
+
+interface PredictionConfig {
+    /** Minimum occurrences to consider a pattern (default: 3) */
+    minOccurrences?: number;
+    /** Days to look back for patterns (default: 30) */
+    lookbackDays?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+interface BehaviorPattern {
+    /** Type of pattern */
+    type: "temporal" | "sequential" | "topical";
+    /** Description of the pattern */
+    description: string;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Supporting evidence */
+    occurrences: number;
+    /** Day of week (0-6) for temporal patterns */
+    dayOfWeek?: number;
+    /** Hour of day (0-23) for temporal patterns */
+    hourOfDay?: number;
+    /** Topic/predicate involved */
+    topic?: string;
+}
+interface Prediction {
+    /** What we predict the user might do/ask */
+    prediction: string;
+    /** Based on which pattern */
+    basedOn: BehaviorPattern;
+    /** Confidence score (0-1) */
+    confidence: number;
+    /** Suggested proactive action */
+    suggestedAction?: string;
+}
+/**
+ * Analyzes user behavior to detect patterns and make predictions.
+ */
+declare class PredictiveEngine {
+    private adapter;
+    private provider?;
+    private config;
+    constructor(adapter: BaseAdapter, provider?: BaseProvider, config?: PredictionConfig);
+    /**
+     * Analyze a user's behavior patterns.
+     */
+    analyzePatterns(userId: string): Promise<BehaviorPattern[]>;
+    /**
+     * Analyze when user tends to interact.
+     */
+    private analyzeTemporalPatterns;
+    /**
+     * Analyze what topics user engages with most.
+     */
+    private analyzeTopicPatterns;
+    /**
+     * Get predictions for what user might need/ask next.
+     */
+    getPredictions(userId: string, _currentContext?: string): Promise<Prediction[]>;
+    /**
+     * Use LLM for deeper behavioral analysis.
+     */
+    analyzeWithLLM(userId: string): Promise<BehaviorPattern[]>;
+}
+
+/**
+ * Hierarchical Memory Manager (HMM)
+ *
+ * Implements the 4-level Memory Pyramid:
+ *
+ * Level 4: Core Beliefs (BIOS)
+ *   - Always loaded, never forgotten
+ *   - Allergies, identity, safety rules
+ *
+ * Level 3: Patterns (Wisdom)
+ *   - Synthesized from multiple Level 2 facts
+ *   - "User is health-conscious" instead of 50 food facts
+ *
+ * Level 2: Facts (Knowledge)
+ *   - The standard discrete facts
+ *   - Subject-Predicate-Object triples
+ *
+ * Level 1: Raw Logs (Stream)
+ *   - Ephemeral conversation buffer
+ *   - Auto-flushed after extraction
+ *
+ * This is an OPTIONAL wrapper - you can use mem-ts without HMM.
+ */
+
+type MemoryLevel = "raw_log" | "fact" | "pattern" | "core_belief";
+interface HierarchicalConfig {
+    /** Enable HMM mode (default: false for backwards compatibility) */
+    enabled?: boolean;
+    /** Maximum raw logs to keep before flushing (default: 20) */
+    maxRawLogs?: number;
+    /** Minimum facts needed to synthesize a pattern (default: 3) */
+    minFactsForPattern?: number;
+    /** Hours before promoting patterns to core beliefs (default: 168 = 1 week) */
+    coreBeliefHours?: number;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+/**
+ * Hierarchical Memory Manager - Optional HMM mode for mem-ts
+ */
+declare class HierarchicalMemory {
+    private adapter;
+    private provider?;
+    private config;
+    constructor(adapter: BaseAdapter, provider?: BaseProvider, config?: HierarchicalConfig);
+    /**
+     * Get facts by memory level.
+     */
+    getByLevel(userId: string, level: MemoryLevel): Promise<MemoryFact[]>;
+    /**
+     * Hierarchical retrieval - top-down query.
+     * 1. Always load core beliefs
+     * 2. Check patterns for context
+     * 3. Load specific facts only if needed
+     */
+    hydrateHierarchical(userId: string, maxFacts?: number): Promise<{
+        coreBeliefs: MemoryFact[];
+        patterns: MemoryFact[];
+        facts: MemoryFact[];
+        totalTokens: number;
+    }>;
+    /**
+     * Compile hierarchical context into a prompt.
+     */
+    compileHierarchicalPrompt(coreBeliefs: MemoryFact[], patterns: MemoryFact[], facts: MemoryFact[]): string;
+    /**
+     * Promote fact to core_belief level.
+     */
+    promoteToCore(userId: string, factId: string, reason?: string): Promise<void>;
+    /**
+     * Synthesize patterns from facts using LLM.
+     * This is the "Deep Sleep" compression step.
+     */
+    synthesizePatterns(userId: string): Promise<{
+        patternsCreated: number;
+        promotions: number;
+        factsCompressed: number;
+    }>;
+    /**
+     * Flush raw logs - extract facts and delete.
+     */
+    flushRawLogs(userId: string): Promise<number>;
+    /**
+     * Get compression statistics - shows efficiency of HMM.
+     */
+    getCompressionStats(userId: string): Promise<{
+        rawLogs: number;
+        facts: number;
+        patterns: number;
+        coreBeliefs: number;
+        compressionRatio: number;
+    }>;
+}
+
+export { type Association, type AssociationConfig, AssociationEngine, type AutoSummarizeConfig, AutoSummarizer, BaseAdapter, BaseProvider, type BehaviorPattern, type BudgetConfig, BudgetManager, ConflictResolver, type ConflictStrategy, type ConsolidationConfig, ConsolidationWorker, ContextHydrator, type Contradiction, type ContradictionConfig, ContradictionDetector, type ContradictionResult, ConversationExchange, type DecayConfig, DecayManager, type DeepSleepConfig, DeepSleepWorker, type EmbeddingConfig, type EmbeddingResult, ExtractionResult, ExtractorWorker, FactFilter, type FactWithDecay, type HierarchicalConfig, HierarchicalMemory, HydrateOptions, HydratedContext, InMemoryVectorStore, MemoryEventEmitter, type MemoryEvents, MemoryFact, type MemoryLevel, MemoryOperation, OpenAIEmbeddingProvider, type Prediction, type PredictionConfig, PredictiveEngine, type SecurityCheckResult, type SecurityConfig, SecurityScanner, SemanticCache, type SemanticCacheConfig, Session, TOKEN_PRICING, TieredAdapter, type TieredAdapterConfig, type TokenAnalytics, TokenTracker, type TokenUsage, compressConversation, cosineSimilarity, createEmbeddingProvider, estimateCost, estimateTokens, findTopK, sanitizeForStorage, wrapContextSafely };