maskweaver 0.7.0

package/dist/memory/indexer.js

@@ -0,0 +1,162 @@
+/**
+ * File Indexer - Process markdown files into searchable chunks
+ *
+ * Read file → Parse sections → Chunk → Hash → Embed → Store
+ */
+import { readFile } from 'fs/promises';
+import { chunkText } from './chunking.js';
+import { initDatabase, upsertChunk, deleteChunksByPath, getChunksByPath } from './store/sqlite.js';
+import { getDbPath } from './core.js';
+const HEADER_REGEX = /^(#{1,6})\s+(.+)$/;
+/**
+ * Parse markdown into sections.
+ */
+export function parseMarkdownSections(content) {
+    const lines = content.split('\n');
+    const sections = [];
+    let currentSection = null;
+    let currentLines = [];
+    let sectionStartLine = 1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const lineNumber = i + 1;
+        const headerMatch = line.match(HEADER_REGEX);
+        if (headerMatch) {
+            // Save previous section
+            if (currentSection !== null || currentLines.length > 0) {
+                sections.push({
+                    header: currentSection?.header || '',
+                    content: currentLines.join('\n'),
+                    level: currentSection?.level || 0,
+                    startLine: sectionStartLine,
+                    endLine: lineNumber - 1
+                });
+            }
+            // Start new section
+            currentSection = {
+                header: headerMatch[2],
+                content: '',
+                level: headerMatch[1].length,
+                startLine: lineNumber,
+                endLine: lineNumber
+            };
+            currentLines = [line];
+            sectionStartLine = lineNumber;
+        }
+        else {
+            currentLines.push(line);
+        }
+    }
+    // Save last section
+    if (currentLines.length > 0) {
+        sections.push({
+            header: currentSection?.header || '',
+            content: currentLines.join('\n'),
+            level: currentSection?.level || 0,
+            startLine: sectionStartLine,
+            endLine: lines.length
+        });
+    }
+    return sections;
+}
+/**
+ * Classify source from file path.
+ */
+export function classifySource(filePath) {
+    const normalized = filePath.replace(/\\/g, '/').toLowerCase();
+    const fileName = normalized.split('/').pop() || '';
+    if (fileName === 'memory.md')
+        return 'memory';
+    if (fileName === 'masks.md')
+        return 'masks';
+    if (fileName === 'retrospect.md')
+        return 'retrospect';
+    if (fileName === 'user.md')
+        return 'user';
+    if (normalized.includes('/daily/') || normalized.includes('\\daily\\'))
+        return 'daily';
+    return 'memory';
+}
+// ============================================================================
+// File Processing
+// ============================================================================
+/**
+ * Process markdown file into chunks.
+ */
+async function processFile(filePath) {
+    const content = await readFile(filePath, 'utf-8');
+    return chunkText(content, filePath);
+}
+// ============================================================================
+// Indexing
+// ============================================================================
+/**
+ * Index a single file.
+ * Only re-embeds chunks that changed (based on hash).
+ */
+export async function indexFile(filePath, getEmbedding, basePath) {
+    console.log(`[Indexer] Processing: ${filePath}`);
+    // Initialize database
+    initDatabase(getDbPath(basePath));
+    // Process file
+    const chunks = await processFile(filePath);
+    console.log(`[Indexer] Generated ${chunks.length} chunks`);
+    // Get existing chunks for hash comparison
+    const existingChunks = getChunksByPath(filePath);
+    const existingHashes = new Set(existingChunks.map(c => c.hash));
+    // Process only changed chunks
+    let newCount = 0;
+    let skippedCount = 0;
+    for (const chunk of chunks) {
+        if (existingHashes.has(chunk.hash)) {
+            skippedCount++;
+            continue;
+        }
+        // New or changed chunk - compute embedding
+        const embedding = await getEmbedding(chunk.text);
+        upsertChunk(chunk, embedding);
+        newCount++;
+    }
+    console.log(`[Indexer] Completed: ${newCount} new, ${skippedCount} unchanged`);
+}
+/**
+ * Reindex file (delete all chunks and reindex).
+ */
+export async function reindexFile(filePath, getEmbedding, basePath) {
+    console.log(`[Indexer] Reindexing: ${filePath}`);
+    initDatabase(getDbPath(basePath));
+    // Delete existing chunks
+    deleteChunksByPath(filePath);
+    // Process and index all chunks
+    const chunks = await processFile(filePath);
+    for (const chunk of chunks) {
+        const embedding = await getEmbedding(chunk.text);
+        upsertChunk(chunk, embedding);
+    }
+    console.log(`[Indexer] Reindexed ${chunks.length} chunks`);
+}
+/**
+ * Index all memory files in directory.
+ */
+export async function indexAllMemoryFiles(baseDir, getEmbedding, basePath) {
+    console.log(`[Indexer] Scanning directory: ${baseDir}`);
+    initDatabase(getDbPath(basePath || baseDir));
+    // Main memory files
+    const mainFiles = ['MEMORY.md', 'MASKS.md', 'RETROSPECT.md', 'USER.md'];
+    let totalFiles = 0;
+    for (const fileName of mainFiles) {
+        const filePath = `${baseDir}/${fileName}`;
+        try {
+            await indexFile(filePath, getEmbedding, basePath || baseDir);
+            totalFiles++;
+        }
+        catch (error) {
+            // File doesn't exist or not readable
+            console.log(`[Indexer] Skipping ${fileName}: ${error}`);
+        }
+    }
+    // TODO: Scan daily directory
+    // This requires glob or fs.readdir
+    console.log(`[Indexer] Completed indexing ${totalFiles} files`);
+}
+//# sourceMappingURL=indexer.js.map

package/dist/memory/indexer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexer.js","sourceRoot":"","sources":["../../src/memory/indexer.ts"],"names":[],"mappings":"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"}

package/dist/memory/providers/examples.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Embedding Provider Usage Examples
+ *
+ * Practical examples showing how to use the provider system.
+ */
+declare function example1_autoSelection(): Promise<void>;
+declare function example2_manualSelection(): Promise<void>;
+declare function example3_codeEmbedding(): Promise<void>;
+declare function example4_asymmetricSearch(): Promise<void>;
+declare function example5_customPriority(): Promise<void>;
+declare function example6_production(): Promise<void>;
+declare function example7_batchProcessing(): Promise<void>;
+declare function example8_errorHandling(): Promise<void>;
+declare function example9_healthMonitoring(): Promise<void>;
+declare function example10_testing(): Promise<void>;
+export { example1_autoSelection, example2_manualSelection, example3_codeEmbedding, example4_asymmetricSearch, example5_customPriority, example6_production, example7_batchProcessing, example8_errorHandling, example9_healthMonitoring, example10_testing };
+//# sourceMappingURL=examples.d.ts.map

package/dist/memory/providers/examples.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples.d.ts","sourceRoot":"","sources":["../../../src/memory/providers/examples.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAcH,iBAAe,sBAAsB,kBAkBpC;AAMD,iBAAe,wBAAwB,kBAyBtC;AAMD,iBAAe,sBAAsB,kBAuBpC;AAMD,iBAAe,yBAAyB,kBAiDvC;AAMD,iBAAe,uBAAuB,kBAcrC;AAMD,iBAAe,mBAAmB,kBAmCjC;AAMD,iBAAe,wBAAwB,kBAmBtC;AAMD,iBAAe,sBAAsB,kBAepC;AAMD,iBAAe,yBAAyB,kBAsBvC;AAMD,iBAAe,iBAAiB,kBAc/B;AAmCD,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,sBAAsB,EACtB,yBAAyB,EACzB,iBAAiB,EAClB,CAAC"}

package/dist/memory/providers/examples.js

@@ -0,0 +1,271 @@
+/**
+ * Embedding Provider Usage Examples
+ *
+ * Practical examples showing how to use the provider system.
+ */
+import { createProvider, selectBestProvider, getDefaultConfigs } from "./index.js";
+// ============================================================================
+// Example 1: Auto-selection (Recommended)
+// ============================================================================
+async function example1_autoSelection() {
+    console.log("Example 1: Auto-selection with graceful degradation\n");
+    // Let the system choose the best available provider
+    const provider = await selectBestProvider(getDefaultConfigs());
+    console.log(`✓ Selected: ${provider.name}`);
+    console.log(`  Type: ${provider.type}`);
+    console.log(`  Dimensions: ${provider.dimensions}\n`);
+    // Use it!
+    const embeddings = await provider.embed([
+        "Hello, world!",
+        "TypeScript is awesome"
+    ]);
+    console.log(`Generated ${embeddings.length} embeddings`);
+    console.log(`Each embedding has ${embeddings[0].length} dimensions\n`);
+}
+// ============================================================================
+// Example 2: Manual Provider Selection
+// ============================================================================
+async function example2_manualSelection() {
+    console.log("Example 2: Manual provider selection\n");
+    // For local development - privacy-first
+    const localProvider = createProvider({
+        type: "ollama",
+        model: "nomic-embed-text"
+    });
+    console.log(`Using: ${localProvider.name}`);
+    // Check health before using
+    const health = await localProvider.healthCheck();
+    if (!health.ok) {
+        console.error(`❌ ${health.reason}`);
+        if (health.hint) {
+            console.log(`💡 Hint: ${health.hint}`);
+        }
+        return;
+    }
+    console.log("✓ Provider is healthy\n");
+    const embeddings = await localProvider.embed(["Test document"]);
+    console.log(`Generated embedding with ${embeddings[0].length} dimensions\n`);
+}
+// ============================================================================
+// Example 3: Code-Specialized Embedding
+// ============================================================================
+async function example3_codeEmbedding() {
+    console.log("Example 3: Code-specialized embedding with Voyage\n");
+    const codeProvider = createProvider({
+        type: "voyage",
+        model: "voyage-code-3",
+        dimensions: 1024,
+        apiKey: process.env.VOYAGE_API_KEY
+    });
+    // Code snippets
+    const codeSnippets = [
+        "function fibonacci(n: number): number { return n < 2 ? n : fibonacci(n-1) + fibonacci(n-2); }",
+        "const factorial = (n: number): number => n <= 1 ? 1 : n * factorial(n - 1);",
+        "class Stack<T> { private items: T[] = []; push(item: T) { this.items.push(item); } }"
+    ];
+    // Use code-specific embedding
+    if (codeProvider.embedCode) {
+        const embeddings = await codeProvider.embedCode(codeSnippets);
+        console.log(`Generated ${embeddings.length} code embeddings`);
+        console.log(`Optimized for code similarity search\n`);
+    }
+}
+// ============================================================================
+// Example 4: Asymmetric Search (Query vs Document)
+// ============================================================================
+async function example4_asymmetricSearch() {
+    console.log("Example 4: Asymmetric search with Voyage\n");
+    const provider = createProvider({
+        type: "voyage",
+        model: "voyage-4-lite",
+        apiKey: process.env.VOYAGE_API_KEY
+    });
+    // Documents (what you're searching through)
+    const documents = [
+        "TypeScript is a strongly typed programming language that builds on JavaScript.",
+        "Python is an interpreted, high-level programming language with dynamic semantics.",
+        "Rust is a systems programming language focused on safety and performance."
+    ];
+    // Query (what the user is searching for)
+    const query = "What is a type-safe language?";
+    // Embed documents
+    const docEmbeddings = await provider.embed(documents);
+    // Embed query (optimized differently)
+    let queryEmbedding;
+    if (provider.embedQuery) {
+        queryEmbedding = await provider.embedQuery(query);
+        console.log("✓ Used query-optimized embedding");
+    }
+    else {
+        [queryEmbedding] = await provider.embed([query]);
+        console.log("✓ Used standard embedding");
+    }
+    // Compute cosine similarity (simplified)
+    const similarities = docEmbeddings.map((docEmb) => {
+        const dotProduct = docEmb.reduce((sum, val, i) => sum + val * queryEmbedding[i], 0);
+        const magnitude1 = Math.sqrt(docEmb.reduce((sum, val) => sum + val * val, 0));
+        const magnitude2 = Math.sqrt(queryEmbedding.reduce((sum, val) => sum + val * val, 0));
+        return dotProduct / (magnitude1 * magnitude2);
+    });
+    // Show results
+    console.log("\nSearch results:");
+    similarities
+        .map((sim, i) => ({ doc: documents[i], similarity: sim }))
+        .sort((a, b) => b.similarity - a.similarity)
+        .forEach((result, i) => {
+        console.log(`${i + 1}. [${result.similarity.toFixed(3)}] ${result.doc}`);
+    });
+    console.log();
+}
+// ============================================================================
+// Example 5: Custom Priority Order
+// ============================================================================
+async function example5_customPriority() {
+    console.log("Example 5: Custom priority order\n");
+    // Try local first, then cloud
+    const customConfigs = [
+        { type: "ollama" }, // Free, local
+        { type: "openai", dimensions: 512 }, // Cheap, small dimensions
+        { type: "text-only" } // Ultimate fallback
+    ];
+    const provider = await selectBestProvider(customConfigs);
+    console.log(`Selected: ${provider.name}`);
+    console.log(`Strategy: Try local → Try cheap cloud → Fallback\n`);
+}
+// ============================================================================
+// Example 6: Production Configuration
+// ============================================================================
+async function example6_production() {
+    console.log("Example 6: Production-ready configuration\n");
+    // Production setup with redundancy
+    const productionConfigs = [
+        // Primary: High-quality embeddings
+        {
+            type: "openai",
+            model: "text-embedding-3-large",
+            dimensions: 3072
+        },
+        // Fallback 1: Smaller but still good
+        {
+            type: "openai",
+            model: "text-embedding-3-small",
+            dimensions: 1536
+        },
+        // Fallback 2: Alternative provider
+        {
+            type: "voyage",
+            model: "voyage-4-lite",
+            dimensions: 1024
+        },
+        // Fallback 3: Multi-provider gateway
+        {
+            type: "openrouter",
+            model: "openai/text-embedding-3-small"
+        }
+    ];
+    const provider = await selectBestProvider(productionConfigs);
+    console.log(`✓ Production provider: ${provider.name}`);
+    console.log(`  Dimensions: ${provider.dimensions}`);
+    console.log(`  Type: ${provider.type}\n`);
+}
+// ============================================================================
+// Example 7: Batch Processing
+// ============================================================================
+async function example7_batchProcessing() {
+    console.log("Example 7: Efficient batch processing\n");
+    const provider = await selectBestProvider(getDefaultConfigs());
+    // Efficient: Single API call
+    const startTime = Date.now();
+    const texts = Array.from({ length: 100 }, (_, i) => `Document number ${i + 1} with some content`);
+    const embeddings = await provider.embed(texts);
+    const duration = Date.now() - startTime;
+    console.log(`✓ Embedded ${embeddings.length} documents in ${duration}ms`);
+    console.log(`  Average: ${(duration / embeddings.length).toFixed(2)}ms per document\n`);
+}
+// ============================================================================
+// Example 8: Error Handling
+// ============================================================================
+async function example8_errorHandling() {
+    console.log("Example 8: Proper error handling\n");
+    try {
+        // Invalid configuration
+        const provider = createProvider({
+            type: "openai",
+            dimensions: 999 // Invalid dimension!
+        });
+        await provider.embed(["test"]);
+    }
+    catch (error) {
+        console.error("❌ Caught error:", error instanceof Error ? error.message : error);
+        console.log("✓ Errors are clear and actionable\n");
+    }
+}
+// ============================================================================
+// Example 9: Health Monitoring
+// ============================================================================
+async function example9_healthMonitoring() {
+    console.log("Example 9: Health monitoring\n");
+    const providers = [
+        createProvider({ type: "ollama" }),
+        createProvider({ type: "text-only" })
+    ];
+    for (const provider of providers) {
+        const health = await provider.healthCheck();
+        console.log(`${provider.name}:`);
+        console.log(`  Status: ${health.ok ? "✓ Healthy" : "✗ Unhealthy"}`);
+        if (health.reason) {
+            console.log(`  Reason: ${health.reason}`);
+        }
+        if (health.hint) {
+            console.log(`  Hint: ${health.hint}`);
+        }
+        console.log();
+    }
+}
+// ============================================================================
+// Example 10: Testing Setup
+// ============================================================================
+async function example10_testing() {
+    console.log("Example 10: Testing setup\n");
+    // Use text-only provider for fast tests
+    const testProvider = createProvider({ type: "text-only" });
+    console.log("Test provider setup:");
+    console.log(`  Name: ${testProvider.name}`);
+    console.log(`  No API calls: ✓`);
+    console.log(`  Always available: ✓`);
+    console.log(`  Fast: ✓`);
+    const embeddings = await testProvider.embed(["test1", "test2", "test3"]);
+    console.log(`  Generated ${embeddings.length} mock embeddings\n`);
+}
+// ============================================================================
+// Run Examples
+// ============================================================================
+async function runExamples() {
+    const examples = [
+        example1_autoSelection,
+        example2_manualSelection,
+        example3_codeEmbedding,
+        example4_asymmetricSearch,
+        example5_customPriority,
+        example6_production,
+        example7_batchProcessing,
+        example8_errorHandling,
+        example9_healthMonitoring,
+        example10_testing
+    ];
+    for (const example of examples) {
+        try {
+            await example();
+        }
+        catch (error) {
+            console.error(`Error in ${example.name}:`, error);
+        }
+        console.log("─".repeat(80) + "\n");
+    }
+}
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runExamples().catch(console.error);
+}
+export { example1_autoSelection, example2_manualSelection, example3_codeEmbedding, example4_asymmetricSearch, example5_customPriority, example6_production, example7_batchProcessing, example8_errorHandling, example9_healthMonitoring, example10_testing };
+//# sourceMappingURL=examples.js.map

package/dist/memory/providers/examples.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"examples.js","sourceRoot":"","sources":["../../../src/memory/providers/examples.ts"],"names":[],"mappings":"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"}

package/dist/memory/providers/factory.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Provider Factory with Graceful Degradation
+ *
+ * "Make the right things easy and the wrong things hard."
+ *
+ * This factory implements:
+ * 1. Strategy Pattern - swappable providers
+ * 2. Factory Pattern - centralized creation
+ * 3. Graceful Degradation - automatic fallback to working providers
+ */
+import type { IEmbeddingProvider, ProviderConfig } from "./types.js";
+/**
+ * Create a provider from configuration
+ *
+ * @throws Error if provider type is invalid or required credentials are missing
+ */
+export declare function createProvider(config: ProviderConfig): IEmbeddingProvider;
+/**
+ * Select the best working provider from a list
+ *
+ * Implements graceful degradation:
+ * - Tries each provider in order
+ * - Returns first healthy provider
+ * - Falls back to text-only if all fail
+ *
+ * @param configs - Array of provider configurations in priority order
+ * @returns The first healthy provider or text-only fallback
+ *
+ * @example
+ * ```typescript
+ * const provider = await selectBestProvider([
+ *   { type: "voyage", model: "voyage-code-3" },
+ *   { type: "ollama" },
+ *   { type: "openai" }
+ * ]);
+ * ```
+ */
+export declare function selectBestProvider(configs: ProviderConfig[]): Promise<IEmbeddingProvider>;
+/**
+ * Get default provider configurations
+ *
+ * Priority order:
+ * 1. Voyage (code-specialized)
+ * 2. Ollama (local, free)
+ * 3. OpenAI (reliable)
+ * 4. OpenRouter (fallback)
+ */
+export declare function getDefaultConfigs(): ProviderConfig[];
+//# sourceMappingURL=factory.d.ts.map

package/dist/memory/providers/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../../../src/memory/providers/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAOrE;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,kBAAkB,CAoBzE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EAAE,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAqC7B;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAqBpD"}

package/dist/memory/providers/factory.js

@@ -0,0 +1,111 @@
+/**
+ * Provider Factory with Graceful Degradation
+ *
+ * "Make the right things easy and the wrong things hard."
+ *
+ * This factory implements:
+ * 1. Strategy Pattern - swappable providers
+ * 2. Factory Pattern - centralized creation
+ * 3. Graceful Degradation - automatic fallback to working providers
+ */
+import { OllamaProvider } from "./ollama.js";
+import { OpenAIProvider } from "./openai.js";
+import { VoyageProvider } from "./voyage.js";
+import { OpenRouterProvider } from "./openrouter.js";
+import { TextOnlyProvider } from "./text-only.js";
+/**
+ * Create a provider from configuration
+ *
+ * @throws Error if provider type is invalid or required credentials are missing
+ */
+export function createProvider(config) {
+    switch (config.type) {
+        case "ollama":
+            return new OllamaProvider(config);
+        case "openai":
+            return new OpenAIProvider(config);
+        case "voyage":
+            return new VoyageProvider(config);
+        case "openrouter":
+            return new OpenRouterProvider(config);
+        case "text-only":
+            return new TextOnlyProvider(config);
+        default:
+            throw new Error(`Unknown provider type: ${config.type}`);
+    }
+}
+/**
+ * Select the best working provider from a list
+ *
+ * Implements graceful degradation:
+ * - Tries each provider in order
+ * - Returns first healthy provider
+ * - Falls back to text-only if all fail
+ *
+ * @param configs - Array of provider configurations in priority order
+ * @returns The first healthy provider or text-only fallback
+ *
+ * @example
+ * ```typescript
+ * const provider = await selectBestProvider([
+ *   { type: "voyage", model: "voyage-code-3" },
+ *   { type: "ollama" },
+ *   { type: "openai" }
+ * ]);
+ * ```
+ */
+export async function selectBestProvider(configs) {
+    const results = [];
+    // Try each provider
+    for (const config of configs) {
+        try {
+            const provider = createProvider(config);
+            const health = await provider.healthCheck();
+            results.push({ provider, health });
+            if (health.ok) {
+                console.log(`✓ Selected provider: ${provider.name}`);
+                return provider;
+            }
+            console.warn(`✗ ${provider.name} unavailable: ${health.reason}${health.hint ? `\n  Hint: ${health.hint}` : ""}`);
+        }
+        catch (error) {
+            console.warn(`✗ Failed to initialize ${config.type}:`, error instanceof Error ? error.message : error);
+        }
+    }
+    // Fallback to text-only
+    console.warn("⚠️  All embedding providers failed. Falling back to text-only mode.");
+    console.warn("   Semantic search will be limited to keyword matching.");
+    return new TextOnlyProvider({ type: "text-only" });
+}
+/**
+ * Get default provider configurations
+ *
+ * Priority order:
+ * 1. Voyage (code-specialized)
+ * 2. Ollama (local, free)
+ * 3. OpenAI (reliable)
+ * 4. OpenRouter (fallback)
+ */
+export function getDefaultConfigs() {
+    return [
+        {
+            type: "voyage",
+            model: "voyage-code-3",
+            dimensions: 1024
+        },
+        {
+            type: "ollama",
+            model: "nomic-embed-text"
+        },
+        {
+            type: "openai",
+            model: "text-embedding-3-small",
+            dimensions: 1536
+        },
+        {
+            type: "openrouter",
+            model: "openai/text-embedding-3-small"
+        }
+    ];
+}
+//# sourceMappingURL=factory.js.map

package/dist/memory/providers/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../../src/memory/providers/factory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAElD;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAsB;IACnD,QAAQ,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,KAAK,QAAQ;YACX,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QAEpC,KAAK,QAAQ;YACX,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QAEpC,KAAK,QAAQ;YACX,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC;QAEpC,KAAK,YAAY;YACf,OAAO,IAAI,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAExC,KAAK,WAAW;YACd,OAAO,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAEtC;YACE,MAAM,IAAI,KAAK,CAAC,0BAA2B,MAAyB,CAAC,IAAI,EAAE,CAAC,CAAC;IACjF,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAyB;IAEzB,MAAM,OAAO,GAGR,EAAE,CAAC;IAER,oBAAoB;IACpB,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;YACxC,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC;YAE5C,OAAO,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC;YAEnC,IAAI,MAAM,CAAC,EAAE,EAAE,CAAC;gBACd,OAAO,CAAC,GAAG,CAAC,wBAAwB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;gBACrD,OAAO,QAAQ,CAAC;YAClB,CAAC;YAED,OAAO,CAAC,IAAI,CACV,KAAK,QAAQ,CAAC,IAAI,iBAAiB,MAAM,CAAC,MAAM,GAC9C,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,aAAa,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAC7C,EAAE,CACH,CAAC;QACJ,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,CAAC,IAAI,CACV,0BAA0B,MAAM,CAAC,IAAI,GAAG,EACxC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAC/C,CAAC;QACJ,CAAC;IACH,CAAC;IAED,wBAAwB;IACxB,OAAO,CAAC,IAAI,CAAC,qEAAqE,CAAC,CAAC;IACpF,OAAO,CAAC,IAAI,CAAC,yDAAyD,CAAC,CAAC;IAExE,OAAO,IAAI,gBAAgB,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC;AACrD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL;YACE,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,eAAe;YACtB,UAAU,EAAE,IAAI;SACjB;QACD;YACE,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,kBAAkB;SAC1B;QACD;YACE,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,wBAAwB;YAC/B,UAAU,EAAE,IAAI;SACjB;QACD;YACE,IAAI,EAAE,YAAY;YAClB,KAAK,EAAE,+BAA+B;SACvC;KACF,CAAC;AACJ,CAAC"}