maskweaver 0.9.3 → 0.9.5

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

@@ -1,11 +1,3 @@
-/**
- * Voyage AI Embedding Provider
- *
- * Specialized embeddings with code-specific models (voyage-code-3).
- * Supports asymmetric search with input_type distinction.
- *
- * Key feature: embedCode() method for superior code understanding.
- */
 import type { Embedding, HealthCheckResult, IEmbeddingProvider, ProviderConfig } from "./types.js";
 export declare class VoyageProvider implements IEmbeddingProvider {
     readonly name = "Voyage AI";
@@ -17,22 +9,8 @@ export declare class VoyageProvider implements IEmbeddingProvider {
     constructor(config: ProviderConfig);
     private validateDimensions;
     healthCheck(): Promise<HealthCheckResult>;
-    /**
-     * General-purpose embedding (documents)
-     */
     embed(texts: string[]): Promise<Embedding[]>;
-    /**
-     * Code-optimized embedding
-     * Use voyage-code-3 model for best results
-     */
     embedCode(texts: string[]): Promise<Embedding[]>;
-    /**
-     * Query-optimized embedding
-     * For asymmetric search (query vs document)
-     */
     embedQuery(text: string): Promise<Embedding>;
-    /**
-     * Core embedding method with input_type specification
-     */
     private embedWithType;
 }

package/dist/memory/providers/voyage.js

@@ -1,11 +1,3 @@
-/**
- * Voyage AI Embedding Provider
- *
- * Specialized embeddings with code-specific models (voyage-code-3).
- * Supports asymmetric search with input_type distinction.
- *
- * Key feature: embedCode() method for superior code understanding.
- */
 const VALID_DIMENSIONS = [256, 512, 1024, 2048];
 const CODE_MODELS = ["voyage-code-3"];
 const GENERAL_MODELS = ["voyage-4-lite", "voyage-4-large"];
@@ -28,7 +20,7 @@ export class VoyageProvider {
     }
     validateDimensions(dim) {
         if (!dim)
-            return 1024; // Default for voyage-4-lite
+            return 1024;
         if (!VALID_DIMENSIONS.includes(dim)) {
             throw new Error(`Invalid dimensions ${dim}. Must be one of: ${VALID_DIMENSIONS.join(", ")}`);
         }
@@ -36,7 +28,6 @@ export class VoyageProvider {
     }
     async healthCheck() {
         try {
-            // Test with a minimal embedding request
             const response = await fetch(`${this.baseUrl}/embeddings`, {
                 method: "POST",
                 headers: {
@@ -74,16 +65,9 @@ export class VoyageProvider {
             };
         }
     }
-    /**
-     * General-purpose embedding (documents)
-     */
     async embed(texts) {
         return this.embedWithType(texts, "document");
     }
-    /**
-     * Code-optimized embedding
-     * Use voyage-code-3 model for best results
-     */
     async embedCode(texts) {
         const isCodeModel = CODE_MODELS.includes(this.model);
         if (!isCodeModel) {
@@ -91,17 +75,10 @@ export class VoyageProvider {
         }
         return this.embedWithType(texts, "document");
     }
-    /**
-     * Query-optimized embedding
-     * For asymmetric search (query vs document)
-     */
     async embedQuery(text) {
         const [embedding] = await this.embedWithType([text], "query");
         return embedding;
     }
-    /**
-     * Core embedding method with input_type specification
-     */
     async embedWithType(texts, inputType) {
         const response = await fetch(`${this.baseUrl}/embeddings`, {
             method: "POST",

package/dist/memory/search/hybrid.d.ts

@@ -1,15 +1,3 @@
-/**
- * Hybrid Search - Combine vector and text search
- *
- * Simple weighted combination of vector similarity and FTS scores.
- * Gracefully degrades to text-only when no embedding is available.
- */
 import type { SearchResult } from '../core.js';
 import type { SearchOptions } from '../store/sqlite.js';
-/**
- * Hybrid search combining vector and text search.
- *
- * If queryEmbedding is empty/missing, automatically falls back
- * to text-only search with adjusted scoring.
- */
 export declare function hybridSearch(query: string, queryEmbedding: number[], options?: SearchOptions): SearchResult[];

package/dist/memory/search/hybrid.js

@@ -1,42 +1,23 @@
-/**
- * Hybrid Search - Combine vector and text search
- *
- * Simple weighted combination of vector similarity and FTS scores.
- * Gracefully degrades to text-only when no embedding is available.
- */
 import { getDatabase } from '../store/sqlite.js';
 const DEFAULT_VECTOR_WEIGHT = 0.7;
 const DEFAULT_TEXT_WEIGHT = 0.3;
 const DEFAULT_MIN_SCORE = 0.35;
 const DEFAULT_MAX_RESULTS = 6;
-/**
- * Hybrid search combining vector and text search.
- *
- * If queryEmbedding is empty/missing, automatically falls back
- * to text-only search with adjusted scoring.
- */
 export function hybridSearch(query, queryEmbedding, options = {}) {
     const { limit = DEFAULT_MAX_RESULTS, minScore = DEFAULT_MIN_SCORE, vectorWeight = DEFAULT_VECTOR_WEIGHT, textWeight = DEFAULT_TEXT_WEIGHT, sourceFilter, } = options;
     const db = getDatabase();
-    // SQLite not available - return empty results (graceful degradation)
     if (!db) {
         return [];
     }
-    // Get more candidates for reranking
     const candidateLimit = limit * 3;
-    // Determine if we can do vector search
     const hasEmbedding = queryEmbedding && queryEmbedding.length > 0;
-    // Run vector search only if we have a real embedding
     const vectorResults = hasEmbedding
         ? db.searchByVector(queryEmbedding, candidateLimit, sourceFilter)
         : [];
-    // Always try text search
     const textResults = db.searchByText(query, candidateLimit);
-    // If both are empty, nothing to merge
     if (vectorResults.length === 0 && textResults.length === 0) {
         return [];
     }
-    // Merge results
     const scoreMap = new Map();
     for (const result of vectorResults) {
         scoreMap.set(result.chunk.id, {
@@ -58,14 +39,12 @@ export function hybridSearch(query, queryEmbedding, options = {}) {
             });
         }
     }
-    // Calculate combined scores
-    // When in text-only mode, use text score directly (don't penalize via vectorWeight)
     const effectiveMinScore = hasEmbedding ? minScore : minScore * textWeight;
     const results = Array.from(scoreMap.values())
         .map(({ chunk, vectorScore, textScore }) => {
         const combinedScore = hasEmbedding
             ? vectorScore * vectorWeight + textScore * textWeight
-            : textScore; // Pure text mode — use raw text score
+            : textScore;
         return {
             chunk,
             score: combinedScore,

package/dist/memory/store/sqlite.d.ts

@@ -1,21 +1,5 @@
-/**
- * SQLite Storage - Persistent chunk and embedding storage
- *
- * Uses better-sqlite3 for Node.js compatibility.
- * WAL mode for concurrent access.
- *
- * NOTE: better-sqlite3 is an optional dependency.
- * This module uses dynamic import to avoid errors when not installed.
- */
 import { type Chunk, type SearchResult } from '../core.js';
-/**
- * Check if SQLite is available without throwing.
- * Returns true if SQLite can be loaded, false otherwise.
- */
 export declare function isSqliteAvailable(): boolean;
-/**
- * Get the reason SQLite is unavailable.
- */
 export declare function getSqliteUnavailableReason(): string;
 export interface SearchOptions {
     limit?: number;
@@ -29,62 +13,19 @@ export declare class MemoryDatabase {
     private statements;
     private ftsAvailable;
     private constructor();
-    /**
-     * Create a new MemoryDatabase instance.
-     * Uses async factory pattern because better-sqlite3 is dynamically imported.
-     * Returns null if SQLite is not available (graceful degradation).
-     */
     static create(dbPath: string): Promise<MemoryDatabase | null>;
-    /**
-     * Initialize database schema.
-     */
     private initSchema;
-    /**
-     * Prepare SQL statements for reuse.
-     */
     private prepareStatements;
-    /**
-     * Insert or update chunk.
-     *
-     * If embedding is empty (e.g., text-only mode), the chunk is stored
-     * but the embedding row is skipped. This allows text search to work
-     * while vector search gracefully returns no results for these chunks.
-     */
     upsertChunk(chunk: Chunk, embedding: number[]): number;
-    /**
-     * Bulk insert chunks in transaction.
-     */
     upsertChunks(chunks: Array<{
         chunk: Chunk;
         embedding: number[];
     }>): number[];
-    /**
-     * Delete chunks by path.
-     */
     deleteChunksByPath(path: string): number;
-    /**
-     * Check if chunk changed.
-     */
     isChunkChanged(path: string, hash: string): boolean;
-    /**
-     * Get chunks by path.
-     */
     getChunksByPath(path: string): Chunk[];
-    /**
-     * Vector similarity search.
-     *
-     * Returns empty results if queryEmbedding is empty (e.g., text-only mode).
-     * Skips stored embeddings with dimension mismatches instead of crashing.
-     */
     searchByVector(queryEmbedding: number[], limit?: number, sourceFilter?: Chunk['source'][]): SearchResult[];
-    /**
-     * Full-text search using FTS5.
-     * Returns empty results if FTS is not available.
-     */
     searchByText(query: string, limit?: number): SearchResult[];
-    /**
-     * Normalize FTS query.
-     */
     private normalizeFtsQuery;
     recordMaskUsage(maskName: string, taskDescription?: string, effectivenessScore?: number): void;
     getMaskStats(): Array<{
@@ -103,21 +44,8 @@ export declare class MemoryDatabase {
     optimize(): void;
     close(): void;
 }
-/**
- * Initialize the database.
- * Returns null if SQLite is not available (graceful degradation).
- */
 export declare function initDatabase(dbPath: string): Promise<MemoryDatabase | null>;
-/**
- * Get the database instance.
- * Returns null if SQLite is not available or not initialized.
- * Use this for optional memory features.
- */
 export declare function getDatabase(): MemoryDatabase | null;
-/**
- * Try to get the database instance, returning null if not initialized.
- * Use this when database access is optional (e.g., in intake stage).
- */
 export declare function tryGetDatabase(): MemoryDatabase | null;
 export declare function upsertChunk(chunk: Chunk, embedding: number[]): number;
 export declare function searchByVector(embedding: number[], limit?: number): SearchResult[];

package/dist/memory/store/sqlite.js

@@ -1,47 +1,24 @@
-/**
- * SQLite Storage - Persistent chunk and embedding storage
- *
- * Uses better-sqlite3 for Node.js compatibility.
- * WAL mode for concurrent access.
- *
- * NOTE: better-sqlite3 is an optional dependency.
- * This module uses dynamic import to avoid errors when not installed.
- */
 import { existsSync, mkdirSync } from 'fs';
 import { dirname } from 'path';
 import { cosineSimilarityFloat32, embeddingToBlob, blobToEmbedding, toFloat32Array, } from '../core.js';
-// Dynamic import for better-sqlite3 or bun:sqlite
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
 let DatabaseConstructor = null;
 let isBun = false;
 let sqliteUnavailable = false;
 let sqliteUnavailableReason = '';
-// Check if running in Bun at module level
-// @ts-ignore
 const IS_BUN = typeof Bun !== 'undefined';
-/**
- * Check if SQLite is available without throwing.
- * Returns true if SQLite can be loaded, false otherwise.
- */
 export function isSqliteAvailable() {
     return !sqliteUnavailable;
 }
-/**
- * Get the reason SQLite is unavailable.
- */
 export function getSqliteUnavailableReason() {
     return sqliteUnavailableReason;
 }
 async function loadDatabase() {
     if (DatabaseConstructor)
         return DatabaseConstructor;
-    // If we already know SQLite is unavailable, return null immediately
     if (sqliteUnavailable)
         return null;
-    // In Bun environment, use bun:sqlite exclusively
     if (IS_BUN) {
         try {
-            // @ts-ignore
             const { Database } = await import('bun:sqlite');
             DatabaseConstructor = Database;
             isBun = true;
@@ -54,8 +31,6 @@ async function loadDatabase() {
             return null;
         }
     }
-    // In Node.js environment, use better-sqlite3
-    // Use Function constructor to avoid Bun's static analysis of import()
     try {
         const dynamicImport = new Function('specifier', 'return import(specifier)');
         const module = await dynamicImport('better-sqlite3');
@@ -72,35 +47,23 @@ async function loadDatabase() {
         return null;
     }
 }
-// ============================================================================
-// Database Class
-// ============================================================================
 export class MemoryDatabase {
-    db; // Database.Database type
+    db;
     statements = new Map();
     ftsAvailable = false;
     constructor(db) {
         this.db = db;
     }
-    /**
-     * Create a new MemoryDatabase instance.
-     * Uses async factory pattern because better-sqlite3 is dynamically imported.
-     * Returns null if SQLite is not available (graceful degradation).
-     */
     static async create(dbPath) {
         const DatabaseClass = await loadDatabase();
-        // SQLite not available - graceful degradation
         if (!DatabaseClass) {
             return null;
         }
-        // Ensure directory exists
         const dir = dirname(dbPath);
         if (!existsSync(dir)) {
             mkdirSync(dir, { recursive: true });
         }
-        // Open database
         const db = new DatabaseClass(dbPath);
-        // Enable WAL mode for concurrency
         if (isBun) {
             db.exec('PRAGMA journal_mode = WAL');
             db.exec('PRAGMA synchronous = NORMAL');
@@ -108,19 +71,14 @@ export class MemoryDatabase {
         else {
             db.pragma('journal_mode = WAL');
             db.pragma('synchronous = NORMAL');
-            db.pragma('cache_size = -64000'); // 64MB
+            db.pragma('cache_size = -64000');
             db.pragma('temp_store = MEMORY');
         }
         const instance = new MemoryDatabase(db);
-        // Initialize schema
         instance.initSchema();
-        // Prepare statements
         instance.prepareStatements();
         return instance;
     }
-    /**
-     * Initialize database schema.
-     */
     initSchema() {
         this.db.exec(`
       -- Chunks table
@@ -158,7 +116,6 @@ export class MemoryDatabase {
       CREATE INDEX IF NOT EXISTS idx_chunks_hash ON chunks(hash);
       CREATE INDEX IF NOT EXISTS idx_mask_usage_name ON mask_usage(mask_name);
     `);
-        // FTS5 virtual table
         this.ftsAvailable = false;
         try {
             this.db.exec(`
@@ -172,10 +129,8 @@ export class MemoryDatabase {
             this.ftsAvailable = true;
         }
         catch (error) {
-            // FTS5 not supported by this SQLite build
             console.warn('[Memory DB] FTS5 not available. Text search will be disabled:', error);
         }
-        // FTS triggers — only if FTS table was created successfully
         if (this.ftsAvailable) {
             try {
                 this.db.exec(`
@@ -202,9 +157,6 @@ export class MemoryDatabase {
             }
         }
     }
-    /**
-     * Prepare SQL statements for reuse.
-     */
     prepareStatements() {
         this.statements.set('upsertChunk', this.db.prepare(`
       INSERT INTO chunks (path, start_line, end_line, text, hash, source)
@@ -236,7 +188,6 @@ export class MemoryDatabase {
       FROM chunks c
       JOIN embeddings e ON c.id = e.chunk_id
     `));
-        // FTS statement — only prepare if FTS table exists
         if (this.ftsAvailable) {
             this.statements.set('searchFts', this.db.prepare(`
         SELECT rowid, text, rank
@@ -264,23 +215,12 @@ export class MemoryDatabase {
       ORDER BY usage_count DESC
     `));
     }
-    // ==========================================================================
-    // CRUD Operations
-    // ==========================================================================
-    /**
-     * Insert or update chunk.
-     *
-     * If embedding is empty (e.g., text-only mode), the chunk is stored
-     * but the embedding row is skipped. This allows text search to work
-     * while vector search gracefully returns no results for these chunks.
-     */
     upsertChunk(chunk, embedding) {
         const stmt = this.statements.get('upsertChunk');
         const result = stmt.get(chunk.path, chunk.startLine, chunk.endLine, chunk.text, chunk.hash, chunk.source);
         if (!result?.id) {
             throw new Error('[Memory DB] Failed to upsert chunk');
         }
-        // Only save embedding if it has actual content
         if (embedding && embedding.length > 0) {
             const embStmt = this.statements.get('upsertEmbedding');
             const embeddingBlob = embeddingToBlob(embedding);
@@ -288,9 +228,6 @@ export class MemoryDatabase {
         }
         return result.id;
     }
-    /**
-     * Bulk insert chunks in transaction.
-     */
     upsertChunks(chunks) {
         const ids = [];
         const transaction = this.db.transaction(() => {
@@ -302,25 +239,16 @@ export class MemoryDatabase {
         transaction();
         return ids;
     }
-    /**
-     * Delete chunks by path.
-     */
     deleteChunksByPath(path) {
         const stmt = this.statements.get('deleteChunksByPath');
         const result = stmt.run(path);
         return result.changes;
     }
-    /**
-     * Check if chunk changed.
-     */
     isChunkChanged(path, hash) {
         const stmt = this.statements.get('checkChunkByHash');
         const result = stmt.get(path, hash);
         return result === undefined;
     }
-    /**
-     * Get chunks by path.
-     */
     getChunksByPath(path) {
         const stmt = this.statements.get('getChunksByPath');
         const rows = stmt.all(path);
@@ -335,34 +263,19 @@ export class MemoryDatabase {
             createdAt: row.created_at,
         }));
     }
-    // ==========================================================================
-    // Search Operations
-    // ==========================================================================
-    /**
-     * Vector similarity search.
-     *
-     * Returns empty results if queryEmbedding is empty (e.g., text-only mode).
-     * Skips stored embeddings with dimension mismatches instead of crashing.
-     */
     searchByVector(queryEmbedding, limit = 6, sourceFilter) {
-        // Empty embedding = text-only mode. Skip vector search entirely.
         if (!queryEmbedding || queryEmbedding.length === 0) {
             return [];
         }
         const queryVec = toFloat32Array(queryEmbedding);
-        // Get all embeddings
         const stmt = this.statements.get('getAllEmbeddings');
         let rows = stmt.all();
-        // Filter by source if specified
         if (sourceFilter && sourceFilter.length > 0) {
             rows = rows.filter(row => sourceFilter.includes(row.source));
         }
-        // Calculate similarities and sort
-        // cosineSimilarityFloat32 returns 0 on dimension mismatch (no throw)
         const scored = [];
         for (const row of rows) {
             const embeddingVec = blobToEmbedding(row.embedding);
-            // Skip rows with empty or invalid embeddings
             if (embeddingVec.length === 0) {
                 continue;
             }
@@ -386,10 +299,6 @@ export class MemoryDatabase {
             .sort((a, b) => b.score - a.score)
             .slice(0, limit);
     }
-    /**
-     * Full-text search using FTS5.
-     * Returns empty results if FTS is not available.
-     */
     searchByText(query, limit = 6) {
         if (!this.ftsAvailable) {
             return [];
@@ -408,7 +317,6 @@ export class MemoryDatabase {
                 const chunk = chunkStmt.get(fts.rowid);
                 if (!chunk)
                     continue;
-                // Normalize BM25 score to 0-1 range
                 const normalizedScore = Math.min(1, Math.max(0, -fts.rank / 10));
                 results.push({
                     chunk: {
@@ -432,9 +340,6 @@ export class MemoryDatabase {
             return [];
         }
     }
-    /**
-     * Normalize FTS query.
-     */
     normalizeFtsQuery(query) {
         const tokens = query
             .replace(/[^\w\s가-힣]/g, ' ')
@@ -444,9 +349,6 @@ export class MemoryDatabase {
             return '';
         return tokens.map(t => `${t}*`).join(' OR ');
     }
-    // ==========================================================================
-    // Mask Usage
-    // ==========================================================================
     recordMaskUsage(maskName, taskDescription, effectivenessScore) {
         const stmt = this.statements.get('insertMaskUsage');
         stmt.run(maskName, taskDescription ?? null, effectivenessScore ?? null);
@@ -455,9 +357,6 @@ export class MemoryDatabase {
         const stmt = this.statements.get('getMaskStats');
         return stmt.all();
     }
-    // ==========================================================================
-    // Utilities
-    // ==========================================================================
     getStats() {
         const chunkCount = this.db.prepare('SELECT COUNT(*) as count FROM chunks').get().count;
         const embeddingCount = this.db.prepare('SELECT COUNT(*) as count FROM embeddings').get().count;
@@ -491,14 +390,7 @@ export class MemoryDatabase {
         this.db.close();
     }
 }
-// ============================================================================
-// Singleton Instance
-// ============================================================================
 let defaultInstance = null;
-/**
- * Initialize the database.
- * Returns null if SQLite is not available (graceful degradation).
- */
 export async function initDatabase(dbPath) {
     if (defaultInstance) {
         defaultInstance.close();
@@ -506,30 +398,15 @@ export async function initDatabase(dbPath) {
     defaultInstance = await MemoryDatabase.create(dbPath);
     return defaultInstance;
 }
-/**
- * Get the database instance.
- * Returns null if SQLite is not available or not initialized.
- * Use this for optional memory features.
- */
 export function getDatabase() {
     if (!defaultInstance && !isSqliteAvailable()) {
-        // SQLite not available - return null instead of throwing
         return null;
     }
     return defaultInstance;
 }
-/**
- * Try to get the database instance, returning null if not initialized.
- * Use this when database access is optional (e.g., in intake stage).
- */
 export function tryGetDatabase() {
     return defaultInstance;
 }
-// ============================================================================
-// Convenience Functions
-// These throw errors if SQLite is not available. Use getDatabase() directly
-// for optional access with null checks.
-// ============================================================================
 export function upsertChunk(chunk, embedding) {
     const db = getDatabase();
     if (!db)
@@ -539,13 +416,13 @@ export function upsertChunk(chunk, embedding) {
 export function searchByVector(embedding, limit) {
     const db = getDatabase();
     if (!db)
-        return []; // Graceful degradation - return empty results
+        return [];
     return db.searchByVector(embedding, limit);
 }
 export function searchByText(query, limit) {
     const db = getDatabase();
     if (!db)
-        return []; // Graceful degradation - return empty results
+        return [];
     return db.searchByText(query, limit);
 }
 export function deleteChunksByPath(path) {