crewly 1.5.18 → 1.5.20

package/dist/backend/backend/src/services/memory/embedding-provider.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Embedding Provider Abstraction (#155)
+ *
+ * Decouples embedding logic from specific APIs. Supports:
+ * - Cloud: Gemini (default), OpenAI, Voyage
+ * - Local: Ollama (for air-gapped/high-security environments)
+ *
+ * Provider selection via environment variables:
+ * - GEMINI_API_KEY → GeminiEmbeddingProvider
+ * - OPENAI_API_KEY → OpenAIEmbeddingProvider
+ * - OLLAMA_HOST → OllamaEmbeddingProvider
+ *
+ * @see https://github.com/stevehuang0115/crewly/issues/155
+ * @module services/memory/embedding-provider
+ */
+/**
+ * Abstract interface for embedding providers.
+ * All providers must implement the embed() method.
+ */
+export interface EmbeddingProvider {
+    /** Provider name for logging */
+    readonly name: string;
+    /** Embedding vector dimensions */
+    readonly dimensions: number;
+    /**
+     * Generate an embedding vector for the given text.
+     *
+     * @param text - Text to embed
+     * @returns Embedding vector, or null on failure
+     */
+    embed(text: string): Promise<number[] | null>;
+}
+/**
+ * Gemini embedding provider (default cloud provider).
+ */
+export declare class GeminiEmbeddingProvider implements EmbeddingProvider {
+    readonly name = "gemini";
+    readonly dimensions = 768;
+    private readonly apiKey;
+    private readonly logger;
+    constructor(apiKey: string);
+    embed(text: string): Promise<number[] | null>;
+}
+/**
+ * OpenAI embedding provider.
+ * Uses the text-embedding-3-small model by default.
+ */
+export declare class OpenAIEmbeddingProvider implements EmbeddingProvider {
+    readonly name = "openai";
+    readonly dimensions = 1536;
+    private readonly apiKey;
+    private readonly model;
+    private readonly logger;
+    constructor(apiKey: string, model?: string);
+    embed(text: string): Promise<number[] | null>;
+}
+/**
+ * Ollama local embedding provider.
+ * Runs entirely on-device for air-gapped environments.
+ */
+export declare class OllamaEmbeddingProvider implements EmbeddingProvider {
+    readonly name = "ollama";
+    readonly dimensions = 768;
+    private readonly host;
+    private readonly model;
+    private readonly logger;
+    constructor(host?: string, model?: string);
+    embed(text: string): Promise<number[] | null>;
+}
+/**
+ * Create the best available embedding provider based on environment config.
+ *
+ * Priority: GEMINI_API_KEY > OPENAI_API_KEY > OLLAMA_HOST > null
+ *
+ * @returns EmbeddingProvider instance, or null if none configured
+ */
+export declare function createEmbeddingProvider(): EmbeddingProvider | null;
+//# sourceMappingURL=embedding-provider.d.ts.map

package/dist/backend/backend/src/services/memory/embedding-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-provider.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/embedding-provider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,gCAAgC;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,kCAAkC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC;CAC9C;AAED;;GAEG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAChE,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,UAAU,OAAO;IAC1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,MAAM,EAAE,MAAM;IAKpB,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;CA2CnD;AAED;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAChE,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,UAAU,QAAQ;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,MAAM,EAAE,MAAM,EAAE,KAAK,SAA2B;IAMtD,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;CA6BnD;AAED;;;GAGG;AACH,qBAAa,uBAAwB,YAAW,iBAAiB;IAChE,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,UAAU,OAAO;IAC1B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;gBAE7B,IAAI,SAA2B,EAAE,KAAK,SAAqB;IAMjE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;CA0BnD;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,IAAI,iBAAiB,GAAG,IAAI,CAiBlE"}

package/dist/backend/backend/src/services/memory/embedding-provider.js

@@ -0,0 +1,185 @@
+/**
+ * Embedding Provider Abstraction (#155)
+ *
+ * Decouples embedding logic from specific APIs. Supports:
+ * - Cloud: Gemini (default), OpenAI, Voyage
+ * - Local: Ollama (for air-gapped/high-security environments)
+ *
+ * Provider selection via environment variables:
+ * - GEMINI_API_KEY → GeminiEmbeddingProvider
+ * - OPENAI_API_KEY → OpenAIEmbeddingProvider
+ * - OLLAMA_HOST → OllamaEmbeddingProvider
+ *
+ * @see https://github.com/stevehuang0115/crewly/issues/155
+ * @module services/memory/embedding-provider
+ */
+import { LoggerService } from '../core/logger.service.js';
+import { EMBEDDING_CONSTANTS } from '../../constants.js';
+/**
+ * Gemini embedding provider (default cloud provider).
+ */
+export class GeminiEmbeddingProvider {
+    name = 'gemini';
+    dimensions = 768;
+    apiKey;
+    logger;
+    constructor(apiKey) {
+        this.apiKey = apiKey;
+        this.logger = LoggerService.getInstance().createComponentLogger('GeminiEmbedding');
+    }
+    async embed(text) {
+        try {
+            const url = `${EMBEDDING_CONSTANTS.GEMINI_ENDPOINT}/${EMBEDDING_CONSTANTS.GEMINI_MODEL}:embedContent?key=${this.apiKey}`;
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), EMBEDDING_CONSTANTS.TIMEOUT_MS);
+            try {
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({
+                        model: `models/${EMBEDDING_CONSTANTS.GEMINI_MODEL}`,
+                        content: { parts: [{ text }] },
+                    }),
+                    signal: controller.signal,
+                });
+                if (!response.ok) {
+                    // #214: Log specific guidance for common error codes
+                    const hint = response.status === 404
+                        ? 'Model may be deprecated — check Gemini embedding model availability'
+                        : response.status === 401 || response.status === 403
+                            ? 'Check your GEMINI_API_KEY — it may be invalid or lack permissions'
+                            : '';
+                    this.logger.warn('Gemini embedding API error, falling back to keyword search', {
+                        status: response.status,
+                        model: EMBEDDING_CONSTANTS.GEMINI_MODEL,
+                        hint,
+                    });
+                    return null;
+                }
+                const data = (await response.json());
+                return data.embedding?.values ?? null;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch (error) {
+            this.logger.warn('Gemini embedding API call failed, falling back to keyword search', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return null;
+        }
+    }
+}
+/**
+ * OpenAI embedding provider.
+ * Uses the text-embedding-3-small model by default.
+ */
+export class OpenAIEmbeddingProvider {
+    name = 'openai';
+    dimensions = 1536;
+    apiKey;
+    model;
+    logger;
+    constructor(apiKey, model = 'text-embedding-3-small') {
+        this.apiKey = apiKey;
+        this.model = model;
+        this.logger = LoggerService.getInstance().createComponentLogger('OpenAIEmbedding');
+    }
+    async embed(text) {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 30000);
+            try {
+                const response = await fetch('https://api.openai.com/v1/embeddings', {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'Authorization': `Bearer ${this.apiKey}`,
+                    },
+                    body: JSON.stringify({ input: text, model: this.model }),
+                    signal: controller.signal,
+                });
+                if (!response.ok)
+                    return null;
+                const data = (await response.json());
+                return data.data?.[0]?.embedding ?? null;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch (error) {
+            this.logger.warn('Embedding request failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+}
+/**
+ * Ollama local embedding provider.
+ * Runs entirely on-device for air-gapped environments.
+ */
+export class OllamaEmbeddingProvider {
+    name = 'ollama';
+    dimensions = 768; // depends on model
+    host;
+    model;
+    logger;
+    constructor(host = 'http://localhost:11434', model = 'nomic-embed-text') {
+        this.host = host;
+        this.model = model;
+        this.logger = LoggerService.getInstance().createComponentLogger('OllamaEmbedding');
+    }
+    async embed(text) {
+        try {
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), 30000);
+            try {
+                const response = await fetch(`${this.host}/api/embeddings`, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: JSON.stringify({ model: this.model, prompt: text }),
+                    signal: controller.signal,
+                });
+                if (!response.ok)
+                    return null;
+                const data = (await response.json());
+                return data.embedding ?? null;
+            }
+            finally {
+                clearTimeout(timeout);
+            }
+        }
+        catch (error) {
+            this.logger.warn('Embedding request failed', {
+                error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+        }
+    }
+}
+/**
+ * Create the best available embedding provider based on environment config.
+ *
+ * Priority: GEMINI_API_KEY > OPENAI_API_KEY > OLLAMA_HOST > null
+ *
+ * @returns EmbeddingProvider instance, or null if none configured
+ */
+export function createEmbeddingProvider() {
+    const geminiKey = process.env.GEMINI_API_KEY;
+    if (geminiKey) {
+        return new GeminiEmbeddingProvider(geminiKey);
+    }
+    const openaiKey = process.env.OPENAI_API_KEY;
+    if (openaiKey) {
+        return new OpenAIEmbeddingProvider(openaiKey);
+    }
+    const ollamaHost = process.env.OLLAMA_HOST;
+    if (ollamaHost) {
+        return new OllamaEmbeddingProvider(ollamaHost);
+    }
+    return null;
+}
+//# sourceMappingURL=embedding-provider.js.map

package/dist/backend/backend/src/services/memory/embedding-provider.js.map

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

package/dist/backend/backend/src/services/memory/vector-store.service.d.ts

@@ -0,0 +1,331 @@
+/**
+ * Vector Store Service — v2
+ *
+ * Local, on-device vector storage using SQLite (better-sqlite3) with optional
+ * sqlite-vec extension for native KNN search. Falls back gracefully to
+ * JavaScript cosine similarity when the extension is unavailable.
+ *
+ * v2 improvements over v1:
+ * - Binary BLOB storage (Float32Array) instead of JSON TEXT (~4× smaller, faster)
+ * - Optional sqlite-vec integration for native SQL-based KNN search (cosine metric)
+ * - Dimension validation ensures all vectors in a scope share the same width
+ * - Prepared statement caching for repeated operations
+ * - Input sanitization (NaN, Infinity rejection)
+ * - Batch upsert with transaction wrapping
+ * - Automatic schema migration from v1 (JSON TEXT) databases
+ *
+ * Storage locations:
+ * - Global scope: ~/.crewly/vector-store.db
+ * - Project scope: {projectPath}/.crewly/vector-store.db
+ *
+ * @module services/memory/vector-store.service
+ */
+/** Reset the sqlite-vec loader state (for testing). */
+export declare function resetSqliteVecLoader(): void;
+/** Constants for the vector store */
+export declare const VECTOR_STORE_CONSTANTS: {
+    /** SQLite database filename */
+    readonly DB_FILENAME: "vector-store.db";
+    /** Default number of results for similarity search */
+    readonly DEFAULT_SEARCH_LIMIT: 10;
+    /** Minimum cosine similarity threshold for search results */
+    readonly DEFAULT_SIMILARITY_THRESHOLD: 0.1;
+    /** Maximum metadata JSON size (bytes) */
+    readonly MAX_METADATA_SIZE: 65536;
+    /** Current schema version */
+    readonly SCHEMA_VERSION: 2;
+    /** Maximum supported embedding dimensions */
+    readonly MAX_DIMENSIONS: 4096;
+    /** Maximum items in a single batch upsert */
+    readonly MAX_BATCH_SIZE: 500;
+};
+/**
+ * A stored embedding record with metadata.
+ */
+export interface VectorRecord {
+    /** Unique identifier (typically document ID) */
+    id: string;
+    /** The embedding vector as a Float64 array */
+    embedding: number[];
+    /** Optional metadata associated with the embedding */
+    metadata: Record<string, unknown>;
+    /** ISO timestamp of when the embedding was stored */
+    createdAt: string;
+    /** ISO timestamp of last update */
+    updatedAt: string;
+}
+/**
+ * A search result with cosine similarity score.
+ */
+export interface VectorSearchResult {
+    /** Unique identifier */
+    id: string;
+    /** Cosine similarity score (higher is more similar) */
+    score: number;
+    /** Associated metadata */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Convert a number array to a Float32Array Buffer for efficient BLOB storage.
+ *
+ * @param embedding - The embedding vector
+ * @returns Buffer containing the Float32Array binary data
+ */
+export declare function embeddingToBlob(embedding: number[]): Buffer;
+/**
+ * Convert a BLOB Buffer back to a number array.
+ *
+ * @param blob - Buffer containing Float32Array binary data
+ * @returns The embedding as a number array
+ */
+export declare function blobToEmbedding(blob: Buffer): number[];
+/**
+ * Compute cosine similarity between two vectors.
+ *
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Cosine similarity in range [-1, 1], or 0 if vectors are incompatible
+ */
+export declare function cosineSimilarity(a: number[], b: number[]): number;
+/**
+ * Validate an embedding vector for storage. Rejects empty arrays, values
+ * that are not finite numbers (NaN, Infinity), and dimensions exceeding
+ * the maximum.
+ *
+ * @param embedding - The embedding to validate
+ * @throws Error if the embedding is invalid
+ */
+export declare function validateEmbedding(embedding: number[]): void;
+/**
+ * VectorStoreService provides local SQLite-based vector storage with optional
+ * native KNN search via the sqlite-vec extension.
+ *
+ * When sqlite-vec is available, search uses a `vec0` virtual table with cosine
+ * distance metric for hardware-accelerated nearest-neighbor queries. When it is
+ * not available, search falls back to JavaScript cosine similarity (fully
+ * portable, no native extension required).
+ *
+ * Each scope (global / project) gets its own database file so project data
+ * stays isolated and portable.
+ *
+ * @example
+ * ```typescript
+ * const store = VectorStoreService.getInstance();
+ * store.upsert('doc-123', embedding, { title: 'My Doc' }, 'global');
+ * const results = store.search(queryEmbedding, 'global');
+ * console.log(store.isVecEnabled('global')); // true if sqlite-vec loaded
+ * ```
+ */
+export declare class VectorStoreService {
+    private static instance;
+    private readonly logger;
+    /** Cache of open database connections by resolved db path */
+    private readonly databases;
+    private constructor();
+    /**
+     * Get the singleton instance.
+     *
+     * @returns VectorStoreService instance
+     */
+    static getInstance(): VectorStoreService;
+    /**
+     * Reset the singleton and close all open databases (for testing).
+     */
+    static resetInstance(): void;
+    /**
+     * Resolve the database file path for a given scope.
+     *
+     * @param scope - 'global' or 'project'
+     * @param projectPath - Required when scope is 'project'
+     * @returns Absolute path to the SQLite database file
+     * @throws Error if projectPath is missing for project scope
+     */
+    private dbPath;
+    /**
+     * Check whether the sqlite-vec native KNN search is available for a scope.
+     *
+     * @param scope - Storage scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns true if vec0 virtual table is active
+     */
+    isVecEnabled(scope: 'global' | 'project', projectPath?: string): boolean;
+    /**
+     * Get (or prepare + cache) a statement for the given database state.
+     *
+     * @param state - Database state to prepare on
+     * @param key - Unique cache key
+     * @param sql - SQL to prepare if not yet cached
+     * @returns A prepared Statement
+     */
+    private getStmt;
+    /**
+     * Open or retrieve a cached database connection. Creates the parent
+     * directory, schema, and vec0 table (if sqlite-vec is available) on first
+     * access. Handles automatic migration from v1 databases.
+     *
+     * @param scope - Document scope
+     * @param projectPath - Project path for project-scoped databases
+     * @returns Internal DatabaseState
+     */
+    private getDbState;
+    /**
+     * Migrate database schema to v2.
+     * - Creates vec_config table for tracking schema version and dimensions
+     * - Adds dimensions column if missing
+     * - Converts JSON TEXT embeddings to BLOB if needed
+     * - Creates vec0 virtual table if sqlite-vec is available and dimensions are known
+     *
+     * @param db - The database to migrate
+     * @param vecEnabled - Whether sqlite-vec extension is loaded
+     */
+    private migrateSchema;
+    /**
+     * Create the vec0 virtual table if it doesn't already exist and dimensions
+     * are known. Returns true if the table is ready for use.
+     *
+     * @param db - The database
+     * @param dimensions - Explicit dimensions; if omitted, reads from vec_config
+     * @returns true if vec0 table exists and is ready
+     */
+    private ensureVecTable;
+    /**
+     * Copy all existing embeddings matching the target dimensions into the vec0
+     * virtual table.
+     *
+     * @param db - The database
+     * @param dimensions - Target embedding dimensions
+     */
+    private backfillVecTable;
+    /**
+     * Read the stored embedding dimensions from the vec_config table.
+     *
+     * @param db - The database
+     * @returns Stored dimensions, or null if not yet determined
+     */
+    private getStoredDimensions;
+    /**
+     * Close all open database connections and clear caches.
+     */
+    closeAll(): void;
+    /**
+     * Store or update an embedding for a document.
+     *
+     * @param id - Document identifier
+     * @param embedding - The embedding vector (array of numbers)
+     * @param metadata - Optional metadata to associate with the embedding
+     * @param scope - Storage scope ('global' or 'project')
+     * @param projectPath - Required when scope is 'project'
+     * @throws Error if id is empty, embedding is invalid, metadata exceeds size,
+     *         or dimensions don't match previously stored embeddings
+     */
+    upsert(id: string, embedding: number[], metadata: Record<string, unknown>, scope: 'global' | 'project', projectPath?: string): void;
+    /**
+     * Sync a single embedding to the vec0 virtual table.
+     * Uses CAST(? AS INTEGER) for rowid because sqlite-vec's vec0 virtual
+     * table does not accept JS number params directly for primary keys.
+     *
+     * @param state - Database state
+     * @param id - Document identifier
+     * @param blob - Embedding as a Float32Array buffer
+     */
+    private syncToVec;
+    /**
+     * Batch upsert multiple embeddings in a single transaction. Significantly
+     * faster than individual upserts for bulk imports.
+     *
+     * @param items - Array of { id, embedding, metadata } objects
+     * @param scope - Storage scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns Count of succeeded and failed inserts
+     * @throws Error if batch size exceeds MAX_BATCH_SIZE
+     */
+    batchUpsert(items: Array<{
+        id: string;
+        embedding: number[];
+        metadata: Record<string, unknown>;
+    }>, scope: 'global' | 'project', projectPath?: string): {
+        succeeded: number;
+        failed: number;
+    };
+    /**
+     * Retrieve a stored embedding by document ID.
+     *
+     * @param id - Document identifier
+     * @param scope - Storage scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns The vector record, or null if not found
+     */
+    get(id: string, scope: 'global' | 'project', projectPath?: string): VectorRecord | null;
+    /**
+     * Delete an embedding by document ID.
+     *
+     * @param id - Document identifier
+     * @param scope - Storage scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns True if a record was deleted, false if not found
+     */
+    delete(id: string, scope: 'global' | 'project', projectPath?: string): boolean;
+    /**
+     * Check whether an embedding exists for a given document ID.
+     *
+     * @param id - Document identifier
+     * @param scope - Storage scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns True if the embedding exists
+     */
+    has(id: string, scope: 'global' | 'project', projectPath?: string): boolean;
+    /**
+     * Return the total number of stored embeddings.
+     *
+     * @param scope - Storage scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns Count of stored embeddings
+     */
+    count(scope: 'global' | 'project', projectPath?: string): number;
+    /**
+     * Search for the most similar embeddings. Uses native vec0 KNN search when
+     * sqlite-vec is available, otherwise falls back to JavaScript cosine
+     * similarity.
+     *
+     * @param queryEmbedding - The query embedding vector
+     * @param scope - Storage scope
+     * @param projectPath - Required when scope is 'project'
+     * @param limit - Maximum number of results (default 10)
+     * @param threshold - Minimum similarity threshold (default 0.1)
+     * @returns Matching records sorted by descending similarity
+     */
+    search(queryEmbedding: number[], scope: 'global' | 'project', projectPath?: string, limit?: number, threshold?: number): VectorSearchResult[];
+    /**
+     * Native KNN search using sqlite-vec's vec0 virtual table with cosine
+     * distance metric. Results are converted from cosine distance (0 = identical,
+     * 1 = orthogonal) to cosine similarity (1 = identical, 0 = orthogonal).
+     *
+     * @param state - Database state
+     * @param queryEmbedding - The query vector
+     * @param limit - Max results
+     * @param threshold - Minimum cosine similarity
+     * @returns Sorted search results
+     */
+    private vecSearch;
+    /**
+     * JavaScript fallback search using cosine similarity on BLOB embeddings.
+     * Used when sqlite-vec is not available.
+     *
+     * @param state - Database state
+     * @param queryEmbedding - The query vector
+     * @param limit - Max results
+     * @param threshold - Minimum cosine similarity
+     * @returns Sorted search results
+     */
+    private jsFallbackSearch;
+    /**
+     * Delete all embeddings from the store. Also resets the stored dimension
+     * constraint so that subsequent inserts may use a different embedding width.
+     *
+     * @param scope - Storage scope
+     * @param projectPath - Required when scope is 'project'
+     * @returns Number of records deleted
+     */
+    clear(scope: 'global' | 'project', projectPath?: string): number;
+}
+//# sourceMappingURL=vector-store.service.d.ts.map

package/dist/backend/backend/src/services/memory/vector-store.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vector-store.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/memory/vector-store.service.ts"],"names":[],"mappings":"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"}