maskweaver 0.9.4 → 0.9.5

package/dist/memory/indexer.js

@@ -1,16 +1,8 @@
-/**
- * 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 = [];
@@ -22,7 +14,6 @@ export function parseMarkdownSections(content) {
         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 || '',
@@ -32,7 +23,6 @@ export function parseMarkdownSections(content) {
                     endLine: lineNumber - 1
                 });
             }
-            // Start new section
             currentSection = {
                 header: headerMatch[2],
                 content: '',
@@ -47,7 +37,6 @@ export function parseMarkdownSections(content) {
             currentLines.push(line);
         }
     }
-    // Save last section
     if (currentLines.length > 0) {
         sections.push({
             header: currentSection?.header || '',
@@ -59,9 +48,6 @@ export function parseMarkdownSections(content) {
     }
     return sections;
 }
-/**
- * Classify source from file path.
- */
 export function classifySource(filePath) {
     const normalized = filePath.replace(/\\/g, '/').toLowerCase();
     const fileName = normalized.split('/').pop() || '';
@@ -77,34 +63,17 @@ export function classifySource(filePath) {
         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
     await 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) {
@@ -112,22 +81,16 @@ export async function indexFile(filePath, getEmbedding, basePath) {
             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}`);
     await 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);
@@ -135,13 +98,9 @@ export async function reindexFile(filePath, getEmbedding, basePath) {
     }
     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}`);
     await 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) {
@@ -151,11 +110,8 @@ export async function indexAllMemoryFiles(baseDir, getEmbedding, basePath) {
             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`);
 }

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

@@ -1,8 +1,3 @@
-/**
- * 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>;

package/dist/memory/providers/examples.js

@@ -1,20 +1,10 @@
-/**
- * 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"
@@ -22,18 +12,13 @@ async function example1_autoSelection() {
     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}`);
@@ -46,9 +31,6 @@ async function example2_manualSelection() {
     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({
@@ -57,22 +39,17 @@ async function example3_codeEmbedding() {
         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({
@@ -80,17 +57,13 @@ async function example4_asymmetricSearch() {
         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);
@@ -100,14 +73,12 @@ async function example4_asymmetricSearch() {
         [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 }))
@@ -117,47 +88,35 @@ async function example4_asymmetricSearch() {
     });
     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
+        { type: "ollama" },
+        { type: "openai", dimensions: 512 },
+        { type: "text-only" }
     ];
     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"
@@ -168,13 +127,9 @@ async function example6_production() {
     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);
@@ -182,16 +137,12 @@ async function example7_batchProcessing() {
     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!
+            dimensions: 999
         });
         await provider.embed(["test"]);
     }
@@ -200,9 +151,6 @@ async function example8_errorHandling() {
         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 = [
@@ -222,12 +170,8 @@ async function example9_healthMonitoring() {
         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}`);
@@ -237,9 +181,6 @@ async function example10_testing() {
     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,
@@ -263,7 +204,6 @@ async function runExamples() {
         console.log("─".repeat(80) + "\n");
     }
 }
-// Run if executed directly
 if (import.meta.url === `file://${process.argv[1]}`) {
     runExamples().catch(console.error);
 }

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

@@ -1,48 +1,4 @@
-/**
- * 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[];

package/dist/memory/providers/factory.js

@@ -1,23 +1,8 @@
-/**
- * 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":
@@ -34,29 +19,8 @@ export function createProvider(config) {
             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);
@@ -72,20 +36,10 @@ export async function selectBestProvider(configs) {
             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 [
         {

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

@@ -1,29 +1,3 @@
-/**
- * Embedding Providers Module
- *
- * Clean public API following the Dependency Inversion Principle.
- * Clients depend on abstractions (IEmbeddingProvider), not implementations.
- *
- * @example Basic usage
- * ```typescript
- * import { createProvider } from "./providers";
- *
- * const provider = createProvider({
- *   type: "voyage",
- *   model: "voyage-code-3"
- * });
- *
- * const embeddings = await provider.embed(["hello world"]);
- * ```
- *
- * @example Auto-selection with graceful degradation
- * ```typescript
- * import { selectBestProvider, getDefaultConfigs } from "./providers";
- *
- * const provider = await selectBestProvider(getDefaultConfigs());
- * // Will try providers in order and fallback to text-only if needed
- * ```
- */
 export type { Embedding, ProviderType, HealthCheckResult, ProviderConfig, IEmbeddingProvider } from "./types.js";
 export { OllamaProvider } from "./ollama.js";
 export { OpenAIProvider } from "./openai.js";

package/dist/memory/providers/index.js

@@ -1,34 +1,6 @@
-/**
- * Embedding Providers Module
- *
- * Clean public API following the Dependency Inversion Principle.
- * Clients depend on abstractions (IEmbeddingProvider), not implementations.
- *
- * @example Basic usage
- * ```typescript
- * import { createProvider } from "./providers";
- *
- * const provider = createProvider({
- *   type: "voyage",
- *   model: "voyage-code-3"
- * });
- *
- * const embeddings = await provider.embed(["hello world"]);
- * ```
- *
- * @example Auto-selection with graceful degradation
- * ```typescript
- * import { selectBestProvider, getDefaultConfigs } from "./providers";
- *
- * const provider = await selectBestProvider(getDefaultConfigs());
- * // Will try providers in order and fallback to text-only if needed
- * ```
- */
-// Concrete implementations (export for advanced use cases)
 export { OllamaProvider } from "./ollama.js";
 export { OpenAIProvider } from "./openai.js";
 export { VoyageProvider } from "./voyage.js";
 export { OpenRouterProvider } from "./openrouter.js";
 export { TextOnlyProvider } from "./text-only.js";
-// Factory functions (recommended API)
 export { createProvider, selectBestProvider, getDefaultConfigs } from "./factory.js";

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

@@ -1,9 +1,3 @@
-/**
- * Ollama Embedding Provider
- *
- * Local-first embedding using Ollama's API.
- * Prioritizes privacy and zero-cost operation.
- */
 import type { Embedding, HealthCheckResult, IEmbeddingProvider, ProviderConfig } from "./types.js";
 export declare class OllamaProvider implements IEmbeddingProvider {
     readonly name = "Ollama";

package/dist/memory/providers/ollama.js

@@ -1,9 +1,3 @@
-/**
- * Ollama Embedding Provider
- *
- * Local-first embedding using Ollama's API.
- * Prioritizes privacy and zero-cost operation.
- */
 export class OllamaProvider {
     name = "Ollama";
     type = "ollama";
@@ -13,7 +7,7 @@ export class OllamaProvider {
     constructor(config) {
         this.baseUrl = config.baseUrl || "http://localhost:11434";
         this.model = config.model || "nomic-embed-text";
-        this.dimensions = config.dimensions || 768; // nomic-embed-text default
+        this.dimensions = config.dimensions || 768;
     }
     async healthCheck() {
         try {
@@ -46,7 +40,6 @@ export class OllamaProvider {
     }
     async embed(texts) {
         const embeddings = [];
-        // Ollama API processes one text at a time
         for (const text of texts) {
             const response = await fetch(`${this.baseUrl}/api/embeddings`, {
                 method: "POST",

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

@@ -1,9 +1,3 @@
-/**
- * OpenAI Embedding Provider
- *
- * Industry-standard embeddings with flexible dimensionality.
- * Supports text-embedding-3-small and text-embedding-3-large models.
- */
 import type { Embedding, HealthCheckResult, IEmbeddingProvider, ProviderConfig } from "./types.js";
 export declare class OpenAIProvider implements IEmbeddingProvider {
     readonly name = "OpenAI";

package/dist/memory/providers/openai.js

@@ -1,9 +1,3 @@
-/**
- * OpenAI Embedding Provider
- *
- * Industry-standard embeddings with flexible dimensionality.
- * Supports text-embedding-3-small and text-embedding-3-large models.
- */
 const VALID_DIMENSIONS = [256, 512, 1536, 3072];
 export class OpenAIProvider {
     name = "OpenAI";
@@ -25,7 +19,7 @@ export class OpenAIProvider {
     }
     validateDimensions(dim) {
         if (!dim)
-            return 1536; // Default for text-embedding-3-small
+            return 1536;
         if (!VALID_DIMENSIONS.includes(dim)) {
             throw new Error(`Invalid dimensions ${dim}. Must be one of: ${VALID_DIMENSIONS.join(", ")}`);
         }
@@ -33,7 +27,6 @@ export class OpenAIProvider {
     }
     async healthCheck() {
         try {
-            // Lightweight check: list models endpoint
             const response = await fetch(`${this.baseUrl}/models`, {
                 headers: {
                     "Authorization": `Bearer ${this.apiKey}`,

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

@@ -1,9 +1,3 @@
-/**
- * OpenRouter Embedding Provider
- *
- * Multi-model gateway supporting various embedding providers.
- * Requires HTTP-Referer and X-Title headers for API tracking.
- */
 import type { Embedding, HealthCheckResult, IEmbeddingProvider, ProviderConfig } from "./types.js";
 export declare class OpenRouterProvider implements IEmbeddingProvider {
     readonly name = "OpenRouter";

package/dist/memory/providers/openrouter.js

@@ -1,9 +1,3 @@
-/**
- * OpenRouter Embedding Provider
- *
- * Multi-model gateway supporting various embedding providers.
- * Requires HTTP-Referer and X-Title headers for API tracking.
- */
 export class OpenRouterProvider {
     name = "OpenRouter";
     type = "openrouter";
@@ -22,13 +16,11 @@ export class OpenRouterProvider {
         this.model = config.model || "openai/text-embedding-3-small";
         this.baseUrl = config.baseUrl || "https://openrouter.ai/api/v1";
         this.dimensions = config.dimensions || 1536;
-        // OpenRouter requires these headers for tracking
         this.referer = process.env.OPENROUTER_REFERER || "https://maskweaver.dev";
         this.title = process.env.OPENROUTER_TITLE || "MaskWeaver";
     }
     async healthCheck() {
         try {
-            // Check API key validity
             const response = await fetch(`${this.baseUrl}/auth/key`, {
                 headers: {
                     "Authorization": `Bearer ${this.apiKey}`,