ai-database 2.1.3 → 2.3.0

package/dist/memory-provider.js

@@ -6,7 +6,11 @@
  * Supports automatic embedding generation on create/update.
  */
 import { cosineSimilarity, computeRRF, extractEmbeddableText, generateContentHash, } from './semantic.js';
-import { EMBEDDING_DIMENSIONS } from './constants.js';
+import { DEFAULT_EMBEDDING_DIMENSIONS, EMBEDDING_DIMENSIONS } from './constants.js';
+import { SEMANTIC_VECTORS, DEFAULT_VECTOR, BASE_VECTOR_DIMENSIONS } from './semantic-vectors.js';
+import { validateTypeName, validateEntityId, validateSearchQuery, validateEntityData, validateRelationName, validateEventPattern, validateActionType, validateArtifactUrl, validateListOptions, validateSearchOptions, validateFieldName, isDangerousField, } from './validation.js';
+import { EntityNotFoundError, EntityAlreadyExistsError } from './errors.js';
+import { logWarn } from './logger.js';
 // =============================================================================
 // Semaphore for Concurrency Control
 // =============================================================================
@@ -83,6 +87,157 @@ function generateId() {
     return crypto.randomUUID();
 }
 // =============================================================================
+// Embedding Helper Functions
+// =============================================================================
+/**
+ * Simple hash function for deterministic randomness
+ *
+ * Generates a consistent hash value for any input string, used for
+ * creating deterministic "random" variations in embedding generation.
+ *
+ * @param str - The string to hash
+ * @returns A positive integer hash value
+ *
+ * @internal
+ */
+function simpleHash(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+        const char = str.charCodeAt(i);
+        hash = (hash << 5) - hash + char;
+        hash = hash & hash; // Convert to 32-bit integer
+    }
+    return Math.abs(hash);
+}
+/**
+ * Generate a deterministic pseudo-random number from seed
+ *
+ * Uses sin function to generate predictable values that appear random
+ * but are reproducible given the same seed and index.
+ *
+ * @param seed - The seed value (typically from a hash)
+ * @param index - The position in the sequence
+ * @returns A number between 0 and 1
+ *
+ * @internal
+ */
+function seededRandom(seed, index) {
+    const x = Math.sin(seed + index) * 10000;
+    return x - Math.floor(x);
+}
+/**
+ * Tokenize text into lowercase words
+ *
+ * Splits text on whitespace and punctuation, filters empty strings,
+ * and converts all words to lowercase for consistent matching.
+ *
+ * @param text - The text to tokenize
+ * @returns Array of lowercase word tokens
+ *
+ * @internal
+ */
+function tokenizeText(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\w\s]/g, ' ')
+        .split(/\s+/)
+        .filter((w) => w.length > 0);
+}
+/**
+ * Get semantic vector for a word
+ *
+ * Looks up the word in SEMANTIC_VECTORS, or generates a deterministic
+ * fallback vector based on the word's hash if not found.
+ *
+ * @param word - The word to get a vector for
+ * @returns A 4-dimensional semantic vector
+ *
+ * @internal
+ */
+function getWordVector(word) {
+    const lower = word.toLowerCase();
+    const known = SEMANTIC_VECTORS[lower];
+    if (known) {
+        return known;
+    }
+    // Generate deterministic vector based on word hash
+    const hash = simpleHash(lower);
+    return DEFAULT_VECTOR.map((v, i) => v + seededRandom(hash, i) * 0.1);
+}
+/**
+ * Aggregate word vectors into a single base vector
+ *
+ * Sums up the semantic vectors for all words in the input,
+ * creating a combined representation of the text's meaning.
+ *
+ * @param words - Array of word tokens
+ * @returns Aggregated 4-dimensional vector (not normalized)
+ *
+ * @internal
+ */
+function aggregateWordVectors(words) {
+    const aggregated = new Array(BASE_VECTOR_DIMENSIONS).fill(0);
+    for (const word of words) {
+        const vec = getWordVector(word);
+        for (let i = 0; i < BASE_VECTOR_DIMENSIONS; i++) {
+            aggregated[i] += vec[i];
+        }
+    }
+    return aggregated;
+}
+/**
+ * Normalize a vector to unit length
+ *
+ * Divides each component by the vector's magnitude to create
+ * a unit vector (length = 1), enabling cosine similarity comparison.
+ *
+ * @param vector - The vector to normalize
+ * @returns A new unit-length vector
+ *
+ * @internal
+ */
+function normalizeVector(vector) {
+    const norm = Math.sqrt(vector.reduce((sum, v) => sum + v * v, 0));
+    return vector.map((v) => v / (norm || 1));
+}
+/**
+ * Expand base vector to full embedding dimensions
+ *
+ * Takes a 4-dimensional base vector and expands it to the target
+ * dimensions by cycling through base values and adding deterministic noise.
+ *
+ * @param normalized - Normalized base vector (4 dimensions)
+ * @param dimensions - Target number of dimensions
+ * @param textHash - Hash of original text for deterministic noise
+ * @returns Expanded vector (not normalized)
+ *
+ * @internal
+ */
+function expandToFullDimensions(normalized, dimensions, textHash) {
+    const embedding = new Array(dimensions);
+    for (let i = 0; i < dimensions; i++) {
+        const baseIndex = i % BASE_VECTOR_DIMENSIONS;
+        const base = normalized[baseIndex];
+        const noise = seededRandom(textHash, i) * 0.1 - 0.05;
+        embedding[i] = base + noise;
+    }
+    return embedding;
+}
+/**
+ * Generate embedding for empty text
+ *
+ * Creates a low-magnitude embedding for empty input,
+ * using deterministic small values based on position.
+ *
+ * @param dimensions - Number of embedding dimensions
+ * @returns A low-magnitude embedding vector
+ *
+ * @internal
+ */
+function generateEmptyEmbedding(dimensions) {
+    return Array.from({ length: dimensions }, (_, i) => seededRandom(0, i) * 0.01);
+}
+// =============================================================================
 // Verb Conjugation (Linguistic Helpers)
 // =============================================================================
 /**
@@ -196,8 +351,11 @@ function toPresent(verb) {
     if (verb.endsWith('y') && !isVowel(verb[verb.length - 2])) {
         return verb.slice(0, -1) + 'ies';
     }
-    if (verb.endsWith('s') || verb.endsWith('x') || verb.endsWith('z') ||
-        verb.endsWith('ch') || verb.endsWith('sh')) {
+    if (verb.endsWith('s') ||
+        verb.endsWith('x') ||
+        verb.endsWith('z') ||
+        verb.endsWith('ch') ||
+        verb.endsWith('sh')) {
         return verb + 'es';
     }
     return verb + 's';
@@ -255,9 +413,37 @@ export class MemoryProvider {
     semaphore;
     // Embedding configuration
     embeddingsConfig;
+    // Flag to use ai-functions for embeddings
+    useAiFunctions;
+    // Custom embedding provider (for testing or alternative services)
+    embeddingProvider;
+    // Embedding dimensions for mock provider
+    embeddingDimensions;
     constructor(options = {}) {
         this.semaphore = new Semaphore(options.concurrency ?? 10);
         this.embeddingsConfig = options.embeddings ?? {};
+        this.useAiFunctions = options.useAiFunctions ?? false;
+        if (options.embeddingProvider !== undefined) {
+            this.embeddingProvider = options.embeddingProvider;
+        }
+        this.embeddingDimensions = options.embeddingDimensions ?? DEFAULT_EMBEDDING_DIMENSIONS;
+    }
+    /**
+     * Enable or disable ai-functions for embeddings
+     */
+    setUseAiFunctions(enabled) {
+        this.useAiFunctions = enabled;
+    }
+    /**
+     * Set a custom embedding provider
+     */
+    setEmbeddingProvider(provider) {
+        if (provider !== undefined) {
+            this.embeddingProvider = provider;
+        }
+        else {
+            this.embeddingProvider = undefined;
+        }
     }
     /**
      * Set embeddings configuration
@@ -273,210 +459,28 @@ export class MemoryProvider {
      *
      * Uses semantic word vectors to create meaningful embeddings
      * where similar concepts have higher cosine similarity.
+     *
+     * The embedding process:
+     * 1. Tokenize text into words
+     * 2. Look up semantic vectors for each word
+     * 3. Aggregate word vectors into a base vector
+     * 4. Normalize the aggregated vector
+     * 5. Expand to full embedding dimensions with deterministic noise
+     * 6. Final normalization to unit vector
+     *
+     * @param text - The text to generate an embedding for
+     * @returns A normalized embedding vector
      */
     generateEmbedding(text) {
-        // Import semantic vectors for deterministic embeddings
-        const SEMANTIC_VECTORS = {
-            // AI/ML domain
-            machine: [0.9, 0.1, 0.05, 0.02],
-            learning: [0.85, 0.15, 0.08, 0.03],
-            artificial: [0.88, 0.12, 0.06, 0.04],
-            intelligence: [0.87, 0.13, 0.07, 0.05],
-            neural: [0.82, 0.18, 0.09, 0.06],
-            network: [0.75, 0.2, 0.15, 0.1],
-            deep: [0.8, 0.17, 0.1, 0.08],
-            ai: [0.92, 0.08, 0.04, 0.02],
-            ml: [0.88, 0.12, 0.06, 0.03],
-            // Programming domain
-            programming: [0.15, 0.85, 0.1, 0.05],
-            code: [0.12, 0.88, 0.12, 0.06],
-            software: [0.18, 0.82, 0.15, 0.08],
-            development: [0.2, 0.8, 0.18, 0.1],
-            typescript: [0.1, 0.9, 0.08, 0.04],
-            javascript: [0.12, 0.88, 0.1, 0.05],
-            python: [0.25, 0.75, 0.12, 0.06],
-            react: [0.08, 0.85, 0.2, 0.1],
-            vue: [0.06, 0.84, 0.18, 0.08],
-            frontend: [0.05, 0.8, 0.25, 0.12],
-            // Database domain
-            database: [0.1, 0.7, 0.08, 0.6],
-            query: [0.12, 0.65, 0.1, 0.7],
-            sql: [0.08, 0.6, 0.05, 0.75],
-            index: [0.1, 0.58, 0.08, 0.72],
-            optimization: [0.15, 0.55, 0.12, 0.68],
-            performance: [0.18, 0.5, 0.15, 0.65],
-            // DevOps domain
-            kubernetes: [0.05, 0.6, 0.8, 0.15],
-            docker: [0.08, 0.55, 0.82, 0.12],
-            container: [0.06, 0.5, 0.85, 0.1],
-            deployment: [0.1, 0.45, 0.78, 0.18],
-            devops: [0.12, 0.48, 0.75, 0.2],
-            // Food domain (distinctly different direction - high in dim 3, low elsewhere)
-            cooking: [0.05, 0.08, 0.05, 0.95],
-            recipe: [0.06, 0.07, 0.04, 0.93],
-            food: [0.04, 0.06, 0.04, 0.96],
-            pasta: [0.03, 0.05, 0.03, 0.97],
-            pizza: [0.03, 0.06, 0.04, 0.96],
-            italian: [0.04, 0.07, 0.04, 0.94],
-            garden: [0.05, 0.04, 0.03, 0.92],
-            flowers: [0.04, 0.03, 0.03, 0.91],
-            chef: [0.05, 0.1, 0.05, 0.95],
-            restaurant: [0.06, 0.08, 0.04, 0.93],
-            kitchen: [0.05, 0.09, 0.05, 0.94],
-            antonio: [0.05, 0.08, 0.04, 0.92],
-            // Research/Academic domain (similar to AI/ML)
-            researcher: [0.82, 0.2, 0.1, 0.08],
-            phd: [0.8, 0.18, 0.12, 0.1],
-            research: [0.85, 0.15, 0.1, 0.07],
-            professor: [0.78, 0.22, 0.12, 0.1],
-            academic: [0.75, 0.2, 0.15, 0.12],
-            // Location/Venue domain (for fuzzy threshold tests - need distinct clusters)
-            // "conference center downtown" cluster - high values in different dimensions
-            conference: [0.2, 0.25, 0.85, 0.2],
-            center: [0.18, 0.22, 0.88, 0.18],
-            downtown: [0.15, 0.2, 0.9, 0.15],
-            // "tech hub 123 main st" cluster - completely different direction
-            hub: [0.85, 0.15, 0.2, 0.15],
-            main: [0.12, 0.12, 0.15, 0.1],
-            st: [0.1, 0.1, 0.12, 0.08],
-            '123': [0.08, 0.08, 0.1, 0.05],
-            // GraphQL/API
-            graphql: [0.1, 0.75, 0.15, 0.55],
-            api: [0.15, 0.7, 0.2, 0.5],
-            rest: [0.12, 0.68, 0.18, 0.48],
-            queries: [0.14, 0.65, 0.12, 0.6],
-            // Testing
-            testing: [0.1, 0.78, 0.08, 0.15],
-            test: [0.08, 0.8, 0.06, 0.12],
-            unit: [0.06, 0.82, 0.05, 0.1],
-            integration: [0.12, 0.75, 0.1, 0.18],
-            // State management
-            state: [0.08, 0.82, 0.2, 0.08],
-            management: [0.15, 0.75, 0.25, 0.12],
-            hooks: [0.06, 0.88, 0.15, 0.05],
-            usestate: [0.05, 0.9, 0.12, 0.04],
-            useeffect: [0.04, 0.88, 0.1, 0.03],
-            // Related/Concept domain (for semantic similarity tests)
-            related: [0.5, 0.5, 0.5, 0.5],
-            concept: [0.55, 0.45, 0.55, 0.45],
-            similar: [0.52, 0.48, 0.52, 0.48],
-            different: [0.48, 0.52, 0.48, 0.52],
-            words: [0.45, 0.55, 0.45, 0.55],
-            semantically: [0.6, 0.4, 0.6, 0.4],
-            // Exact match domain (distinctly different vectors)
-            exact: [0.1, 0.1, 0.1, 0.9],
-            match: [0.15, 0.15, 0.1, 0.85],
-            title: [0.1, 0.2, 0.1, 0.8],
-            contains: [0.12, 0.18, 0.12, 0.78],
-            search: [0.08, 0.22, 0.08, 0.82],
-            terms: [0.05, 0.25, 0.05, 0.85],
-            // Business domain (for fuzzy forward resolution tests)
-            enterprise: [0.7, 0.3, 0.8, 0.6],
-            large: [0.65, 0.25, 0.75, 0.55],
-            corporations: [0.68, 0.28, 0.78, 0.58],
-            companies: [0.6, 0.4, 0.7, 0.5],
-            company: [0.62, 0.38, 0.72, 0.52],
-            thousands: [0.7, 0.2, 0.7, 0.5],
-            employees: [0.55, 0.35, 0.65, 0.45],
-            big: [0.68, 0.3, 0.75, 0.58],
-            small: [0.3, 0.6, 0.3, 0.4],
-            business: [0.5, 0.5, 0.6, 0.5],
-            owners: [0.4, 0.5, 0.5, 0.45],
-            consumer: [0.35, 0.55, 0.35, 0.35],
-            individual: [0.32, 0.58, 0.32, 0.32],
-            b2c: [0.3, 0.6, 0.3, 0.35],
-            // Tech professional domain
-            developer: [0.2, 0.85, 0.15, 0.1],
-            engineer: [0.25, 0.82, 0.18, 0.12],
-            engineers: [0.27, 0.8, 0.2, 0.14],
-            builds: [0.18, 0.78, 0.16, 0.08],
-            writes: [0.15, 0.75, 0.12, 0.06],
-            professional: [0.22, 0.72, 0.2, 0.15],
-            applications: [0.2, 0.78, 0.18, 0.1],
-            tech: [0.25, 0.8, 0.2, 0.12],
-            technology: [0.28, 0.78, 0.22, 0.14],
-            electronics: [0.3, 0.75, 0.25, 0.15],
-            device: [0.25, 0.82, 0.2, 0.1],
-            furniture: [0.1, 0.15, 0.2, 0.85],
-            home: [0.12, 0.18, 0.22, 0.8],
-            living: [0.1, 0.15, 0.2, 0.82],
-            goods: [0.3, 0.5, 0.35, 0.4],
-            leaders: [0.4, 0.5, 0.6, 0.4],
-            senior: [0.35, 0.55, 0.55, 0.35],
-            // Data science domain
-            data: [0.75, 0.3, 0.15, 0.55],
-            science: [0.78, 0.25, 0.12, 0.5],
-            scientist: [0.8, 0.28, 0.1, 0.52],
-            background: [0.72, 0.32, 0.14, 0.48],
-            // DevOps/cloud domain
-            cloud: [0.1, 0.55, 0.85, 0.15],
-            expertise: [0.15, 0.5, 0.8, 0.18],
-            // Support domain
-            support: [0.2, 0.45, 0.3, 0.55],
-            specialist: [0.22, 0.48, 0.32, 0.52],
-            technical: [0.25, 0.65, 0.35, 0.4],
-            issues: [0.18, 0.42, 0.28, 0.48],
-            // Security domain
-            security: [0.3, 0.6, 0.4, 0.7],
-            auth: [0.28, 0.58, 0.38, 0.72],
-            authentication: [0.32, 0.55, 0.42, 0.75],
-            identity: [0.35, 0.52, 0.45, 0.68],
-            oauth: [0.3, 0.62, 0.4, 0.7],
-            // CRM domain
-            crm: [0.45, 0.4, 0.7, 0.55],
-            sales: [0.42, 0.38, 0.68, 0.52],
-            salesforce: [0.48, 0.42, 0.72, 0.58],
-            provider: [0.5, 0.45, 0.65, 0.5],
-        };
-        const DEFAULT_VECTOR = [0.1, 0.1, 0.1, 0.1];
-        // Simple hash function
-        const simpleHash = (str) => {
-            let hash = 0;
-            for (let i = 0; i < str.length; i++) {
-                const char = str.charCodeAt(i);
-                hash = ((hash << 5) - hash) + char;
-                hash = hash & hash;
-            }
-            return Math.abs(hash);
-        };
-        // Seeded random
-        const seededRandom = (seed, index) => {
-            const x = Math.sin(seed + index) * 10000;
-            return x - Math.floor(x);
-        };
-        // Tokenize
-        const words = text
-            .toLowerCase()
-            .replace(/[^\w\s]/g, ' ')
-            .split(/\s+/)
-            .filter(w => w.length > 0);
+        const words = tokenizeText(text);
         if (words.length === 0) {
-            return Array.from({ length: EMBEDDING_DIMENSIONS }, (_, i) => seededRandom(0, i) * 0.01);
-        }
-        // Aggregate word vectors
-        const aggregated = [0, 0, 0, 0];
-        for (const word of words) {
-            const lower = word.toLowerCase();
-            const vec = SEMANTIC_VECTORS[lower] ?? DEFAULT_VECTOR.map((v, i) => v + seededRandom(simpleHash(lower), i) * 0.1);
-            for (let i = 0; i < 4; i++) {
-                aggregated[i] += vec[i];
-            }
+            return generateEmptyEmbedding(this.embeddingDimensions);
         }
-        // Normalize
-        const norm = Math.sqrt(aggregated.reduce((sum, v) => sum + v * v, 0));
-        const normalized = aggregated.map(v => v / (norm || 1));
-        // Expand to full dimensions
+        const aggregated = aggregateWordVectors(words);
+        const normalized = normalizeVector(aggregated);
         const textHash = simpleHash(text);
-        const embedding = new Array(EMBEDDING_DIMENSIONS);
-        for (let i = 0; i < EMBEDDING_DIMENSIONS; i++) {
-            const baseIndex = i % 4;
-            const base = normalized[baseIndex];
-            const noise = seededRandom(textHash, i) * 0.1 - 0.05;
-            embedding[i] = base + noise;
-        }
-        // Final normalization
-        const finalNorm = Math.sqrt(embedding.reduce((sum, v) => sum + v * v, 0));
-        return embedding.map((v) => v / (finalNorm || 1));
+        const expanded = expandToFullDimensions(normalized, this.embeddingDimensions, textHash);
+        return normalizeVector(expanded);
     }
     /**
      * Check if embeddings should be generated for a given entity type
@@ -509,6 +513,11 @@ export class MemoryProvider {
      * embeddings for entities based on their text content. The embedding
      * is stored as an artifact associated with the entity.
      *
+     * Priority for embedding generation:
+     * 1. Custom embeddingProvider if set (for testing or alternative services)
+     * 2. ai-functions if useAiFunctions is enabled
+     * 3. Deterministic mock embedding (default for testing)
+     *
      * @param type - The entity type name
      * @param id - The entity ID
      * @param data - The entity data to extract text from
@@ -523,8 +532,39 @@ export class MemoryProvider {
         const { text, fields: embeddedFields } = extractEmbeddableText(data, fields);
         if (!text.trim())
             return;
-        // Generate embedding
-        const embedding = this.generateEmbedding(text);
+        let embedding;
+        let dimensions = this.embeddingDimensions;
+        let source = 'mock';
+        // Priority: embeddingProvider > useAiFunctions > mock
+        if (this.embeddingProvider) {
+            try {
+                const result = await this.embeddingProvider.embedTexts([text]);
+                embedding = result.embeddings[0] ?? this.generateEmbedding(text);
+                dimensions = embedding.length;
+                source = 'custom-provider';
+            }
+            catch (err) {
+                logWarn('Custom embedding provider failed, falling back to mock:', err);
+                embedding = this.generateEmbedding(text);
+            }
+        }
+        else if (this.useAiFunctions) {
+            try {
+                const { embedTexts } = await import('ai-functions');
+                const result = await embedTexts([text]);
+                embedding = result.embeddings[0] ?? this.generateEmbedding(text);
+                dimensions = embedding.length;
+                source = 'ai-functions';
+            }
+            catch (err) {
+                // Fallback to mock embedding if ai-functions fails
+                logWarn('ai-functions embedTexts failed, falling back to mock:', err);
+                embedding = this.generateEmbedding(text);
+            }
+        }
+        else {
+            embedding = this.generateEmbedding(text);
+        }
         const contentHash = generateContentHash(text);
         // Store as artifact with complete metadata
         const url = `${type}/${id}`;
@@ -533,8 +573,9 @@ export class MemoryProvider {
             sourceHash: contentHash,
             metadata: {
                 fields: embeddedFields,
-                dimensions: EMBEDDING_DIMENSIONS,
+                dimensions,
                 text: text.slice(0, 200),
+                source,
             },
         });
     }
@@ -559,11 +600,15 @@ export class MemoryProvider {
         return this.entities.get(type);
     }
     async get(type, id) {
+        validateTypeName(type);
+        validateEntityId(id);
         const store = this.getTypeStore(type);
         const entity = store.get(id);
         return entity ? { ...entity, $id: id, $type: type } : null;
     }
     async list(type, options) {
+        validateTypeName(type);
+        validateListOptions(options);
         const store = this.getTypeStore(type);
         let results = [];
         for (const [id, entity] of store) {
@@ -612,9 +657,18 @@ export class MemoryProvider {
         return results;
     }
     async search(type, query, options) {
+        validateTypeName(type);
+        validateSearchQuery(query);
+        validateSearchOptions(options);
         const all = await this.list(type, options);
         const queryLower = query.toLowerCase();
-        const fields = options?.fields || ['$all'];
+        let fields = options?.fields || ['$all'];
+        // Filter out dangerous field names
+        fields = fields.filter((f) => !isDangerousField(f));
+        // If all fields were dangerous, return empty results
+        if (fields.length === 0) {
+            return [];
+        }
         const scored = [];
         for (const entity of all) {
             let searchText;
@@ -640,28 +694,111 @@ export class MemoryProvider {
     }
     /**
      * Semantic search using embedding similarity
+     *
+     * Priority for embedding and similarity operations:
+     * 1. Custom embeddingProvider if set
+     * 2. ai-functions if useAiFunctions is enabled
+     * 3. Local mock implementations (default)
      */
     async semanticSearch(type, query, options) {
         const store = this.getTypeStore(type);
         const limit = options?.limit ?? 10;
         const minScore = options?.minScore ?? 0;
         // Generate query embedding
-        const queryEmbedding = this.generateEmbedding(query);
-        const scored = [];
+        let queryEmbedding;
+        if (this.embeddingProvider) {
+            try {
+                const result = await this.embeddingProvider.embedTexts([query]);
+                queryEmbedding = result.embeddings[0] ?? this.generateEmbedding(query);
+            }
+            catch (err) {
+                logWarn('Custom embedding provider failed for query, falling back to mock:', err);
+                queryEmbedding = this.generateEmbedding(query);
+            }
+        }
+        else if (this.useAiFunctions) {
+            try {
+                const { embedTexts } = await import('ai-functions');
+                const result = await embedTexts([query]);
+                queryEmbedding = result.embeddings[0] ?? this.generateEmbedding(query);
+            }
+            catch (err) {
+                logWarn('ai-functions embedTexts failed for query, falling back to mock:', err);
+                queryEmbedding = this.generateEmbedding(query);
+            }
+        }
+        else {
+            queryEmbedding = this.generateEmbedding(query);
+        }
+        // Get similarity function
+        let similarityFn;
+        if (this.embeddingProvider?.cosineSimilarity) {
+            similarityFn = this.embeddingProvider.cosineSimilarity;
+        }
+        else if (this.useAiFunctions) {
+            try {
+                const { cosineSimilarity: aiCosineSimilarity } = await import('ai-functions');
+                similarityFn = aiCosineSimilarity;
+            }
+            catch (err) {
+                logWarn('ai-functions cosineSimilarity not available, using local:', err);
+                similarityFn = cosineSimilarity;
+            }
+        }
+        else {
+            similarityFn = cosineSimilarity;
+        }
+        // Collect embeddings and entities for potential findSimilar usage
+        const embeddings = [];
+        const entities = [];
         for (const [id, entity] of store) {
-            // Get stored embedding from artifacts
             const url = `${type}/${id}`;
             const artifact = await this.getArtifact(url, 'embedding');
             if (!artifact || !Array.isArray(artifact.content)) {
                 continue;
             }
-            const embedding = artifact.content;
-            const score = cosineSimilarity(queryEmbedding, embedding);
-            if (score >= minScore) {
-                scored.push({
-                    entity: { ...entity, $id: id, $type: type },
-                    score,
+            embeddings.push(artifact.content);
+            entities.push({ entity: { ...entity, $id: id, $type: type }, id });
+        }
+        // If using embeddingProvider with findSimilar, use it
+        if (this.embeddingProvider?.findSimilar && entities.length > 0) {
+            try {
+                const results = this.embeddingProvider.findSimilar(queryEmbedding, embeddings, entities, {
+                    topK: limit,
+                    minScore,
                 });
+                return results.map(({ item, score }) => ({
+                    ...item.entity,
+                    $score: score,
+                }));
+            }
+            catch (err) {
+                logWarn('Custom embedding provider findSimilar failed, falling back to manual scoring:', err);
+            }
+        }
+        // If using ai-functions and we have entities, try to use findSimilar
+        if (this.useAiFunctions && entities.length > 0) {
+            try {
+                const { findSimilar } = await import('ai-functions');
+                const results = findSimilar(queryEmbedding, embeddings, entities, { topK: limit, minScore });
+                return results.map(({ item, score }) => ({
+                    ...item.entity,
+                    $score: score,
+                }));
+            }
+            catch (err) {
+                // Fall through to manual scoring if findSimilar fails
+                logWarn('ai-functions findSimilar failed, falling back to manual scoring:', err);
+            }
+        }
+        // Manual scoring fallback
+        const scored = [];
+        for (let i = 0; i < entities.length; i++) {
+            const embedding = embeddings[i];
+            const { entity } = entities[i];
+            const score = similarityFn(queryEmbedding, embedding);
+            if (score >= minScore) {
+                scored.push({ entity, score });
             }
         }
         // Sort by score descending
@@ -686,15 +823,18 @@ export class MemoryProvider {
         const ftsResults = await this.search(type, query);
         const ftsRanks = new Map();
         ftsResults.forEach((entity, index) => {
-            const id = entity.$id || entity.id;
+            const id = entity['$id'] || entity['id'];
             ftsRanks.set(id, index + 1); // 1-indexed rank
         });
         // Get semantic results with their ranks and scores
         // Get more results to ensure we have enough after offset
-        const semanticResults = await this.semanticSearch(type, query, { limit: (limit + offset) * 2, minScore });
+        const semanticResults = await this.semanticSearch(type, query, {
+            limit: (limit + offset) * 2,
+            minScore,
+        });
         const semanticRanks = new Map();
         semanticResults.forEach((entity, index) => {
-            const id = entity.$id || entity.id;
+            const id = entity['$id'] || entity['id'];
             semanticRanks.set(id, { rank: index + 1, score: entity.$score });
         });
         // Combine results with RRF
@@ -724,7 +864,9 @@ export class MemoryProvider {
         // Sort by RRF score descending
         combined.sort((a, b) => b.rrfScore - a.rrfScore);
         // Apply offset and limit, then return with scoring fields
-        return combined.slice(offset, offset + limit).map(({ entity, rrfScore, ftsRank, semanticRank, semanticScore }) => ({
+        return combined
+            .slice(offset, offset + limit)
+            .map(({ entity, rrfScore, ftsRank, semanticRank, semanticScore }) => ({
             ...entity,
             $rrfScore: rrfScore,
             $ftsRank: ftsRank,
@@ -751,10 +893,15 @@ export class MemoryProvider {
         return results;
     }
     async create(type, id, data) {
+        validateTypeName(type);
+        if (id !== undefined) {
+            validateEntityId(id);
+        }
+        validateEntityData(data);
         const store = this.getTypeStore(type);
         const entityId = id || generateId();
         if (store.has(entityId)) {
-            throw new Error(`Entity already exists: ${type}/${entityId}`);
+            throw new EntityAlreadyExistsError(type, entityId, 'create');
         }
         const entity = {
             ...data,
@@ -766,15 +913,26 @@ export class MemoryProvider {
         await this.autoEmbed(type, entityId, entity);
         // Emit type-specific and global events
         const eventData = { $id: entityId, $type: type, ...entity };
-        await this.emit(`${type}.created`, eventData);
-        await this.emit('entity:created', eventData);
+        await this.emit({
+            event: `${type}.created`,
+            object: `${type}/${entityId}`,
+            objectData: eventData,
+        });
+        await this.emit({
+            event: 'entity:created',
+            object: `${type}/${entityId}`,
+            objectData: eventData,
+        });
         return { ...entity, $id: entityId, $type: type };
     }
     async update(type, id, data) {
+        validateTypeName(type);
+        validateEntityId(id);
+        validateEntityData(data);
         const store = this.getTypeStore(type);
         const existing = store.get(id);
         if (!existing) {
-            throw new Error(`Entity not found: ${type}/${id}`);
+            throw new EntityNotFoundError(type, id, 'update');
         }
         const updated = {
             ...existing,
@@ -788,11 +946,21 @@ export class MemoryProvider {
         await this.invalidateArtifacts(`${type}/${id}`);
         // Emit type-specific and global events
         const eventData = { $id: id, $type: type, ...updated };
-        await this.emit(`${type}.updated`, eventData);
-        await this.emit('entity:updated', eventData);
+        await this.emit({
+            event: `${type}.updated`,
+            object: `${type}/${id}`,
+            objectData: eventData,
+        });
+        await this.emit({
+            event: 'entity:updated',
+            object: `${type}/${id}`,
+            objectData: eventData,
+        });
         return { ...updated, $id: id, $type: type };
     }
     async delete(type, id) {
+        validateTypeName(type);
+        validateEntityId(id);
         const store = this.getTypeStore(type);
         if (!store.has(id)) {
             return false;
@@ -800,8 +968,16 @@ export class MemoryProvider {
         store.delete(id);
         // Emit type-specific and global events
         const eventData = { $id: id, $type: type };
-        await this.emit(`${type}.deleted`, eventData);
-        await this.emit('entity:deleted', eventData);
+        await this.emit({
+            event: `${type}.deleted`,
+            object: `${type}/${id}`,
+            objectData: eventData,
+        });
+        await this.emit({
+            event: 'entity:deleted',
+            object: `${type}/${id}`,
+            objectData: eventData,
+        });
         // Clean up relations
         for (const [key, targets] of this.relations) {
             if (key.startsWith(`${type}:${id}:`)) {
@@ -848,6 +1024,11 @@ export class MemoryProvider {
         return results;
     }
     async relate(fromType, fromId, relation, toType, toId, metadata) {
+        validateTypeName(fromType);
+        validateEntityId(fromId);
+        validateRelationName(relation);
+        validateTypeName(toType);
+        validateEntityId(toId);
         const key = this.relationKey(fromType, fromId, relation);
         if (!this.relations.has(key)) {
             this.relations.set(key, new Set());
@@ -903,11 +1084,11 @@ export class MemoryProvider {
                 id: generateId(),
                 actor: 'system',
                 event: eventOrType,
-                objectData: data,
                 timestamp: new Date(),
                 // Legacy fields
                 type: eventOrType,
                 data,
+                ...(data !== undefined && { objectData: data }),
             };
         }
         else {
@@ -915,16 +1096,17 @@ export class MemoryProvider {
             event = {
                 id: generateId(),
                 actor: eventOrType.actor ?? 'system',
-                actorData: eventOrType.actorData,
                 event: eventOrType.event,
-                object: eventOrType.object,
-                objectData: eventOrType.objectData,
-                result: eventOrType.result,
-                resultData: eventOrType.resultData,
-                meta: eventOrType.meta,
                 timestamp: new Date(),
-                // Legacy fields
+                // Legacy fields for backward compatibility
                 type: eventOrType.event,
+                ...(eventOrType.objectData !== undefined && { data: eventOrType.objectData }),
+                ...(eventOrType.actorData !== undefined && { actorData: eventOrType.actorData }),
+                ...(eventOrType.object !== undefined && { object: eventOrType.object }),
+                ...(eventOrType.objectData !== undefined && { objectData: eventOrType.objectData }),
+                ...(eventOrType.result !== undefined && { result: eventOrType.result }),
+                ...(eventOrType.resultData !== undefined && { resultData: eventOrType.resultData }),
+                ...(eventOrType.meta !== undefined && { meta: eventOrType.meta }),
             };
         }
         this.events.push(event);
@@ -947,9 +1129,9 @@ export class MemoryProvider {
      */
     getEventHandlers(type) {
         const handlers = [];
-        for (const [pattern, patternHandlers] of this.eventHandlers) {
+        for (const [pattern, patternHandlers] of [...this.eventHandlers]) {
             if (this.matchesPattern(type, pattern)) {
-                handlers.push(...patternHandlers);
+                handlers.push(...[...patternHandlers]);
             }
         }
         return handlers;
@@ -985,6 +1167,7 @@ export class MemoryProvider {
         return false;
     }
     on(pattern, handler) {
+        validateEventPattern(pattern);
         if (!this.eventHandlers.has(pattern)) {
             this.eventHandlers.set(pattern, []);
         }
@@ -1024,10 +1207,11 @@ export class MemoryProvider {
         return results;
     }
     async replayEvents(options) {
+        const eventPattern = options.event ?? options.type;
         const events = await this.listEvents({
-            event: options.event ?? options.type,
-            actor: options.actor,
-            since: options.since,
+            ...(eventPattern !== undefined && { event: eventPattern }),
+            ...(options.actor !== undefined && { actor: options.actor }),
+            ...(options.since !== undefined && { since: options.since }),
         });
         for (const event of events) {
             await this.semaphore.run(() => Promise.resolve(options.handler(event)));
@@ -1061,33 +1245,39 @@ export class MemoryProvider {
     async createAction(data) {
         // Get base verb from action or legacy type
         const baseVerb = data.action ?? data.type ?? 'process';
+        // Validate action type
+        validateActionType(baseVerb);
         // Auto-conjugate verb forms
         const conjugated = conjugateVerb(baseVerb);
+        const objectData = data.objectData ?? data.data;
         const action = {
             id: generateId(),
             actor: data.actor ?? 'system',
-            actorData: data.actorData,
             act: conjugated.act,
             action: conjugated.action,
             activity: conjugated.activity,
-            object: data.object,
-            objectData: data.objectData ?? data.data,
             status: 'pending',
             progress: 0,
-            total: data.total,
-            meta: data.meta,
             createdAt: new Date(),
             // Legacy fields
             type: baseVerb,
             data: data.data,
+            ...(data.actorData !== undefined && { actorData: data.actorData }),
+            ...(data.object !== undefined && { object: data.object }),
+            ...(objectData !== undefined && { objectData }),
+            ...(data.total !== undefined && { total: data.total }),
+            ...(data.meta !== undefined && { meta: data.meta }),
         };
         this.actions.set(action.id, action);
         await this.emit({
             actor: action.actor,
-            actorData: action.actorData,
             event: 'Action.created',
             object: action.id,
-            objectData: { action: action.action, object: action.object },
+            objectData: {
+                action: action.action,
+                ...(action.object !== undefined && { object: action.object }),
+            },
+            ...(action.actorData !== undefined && { actorData: action.actorData }),
         });
         return action;
     }
@@ -1097,7 +1287,7 @@ export class MemoryProvider {
     async updateAction(id, updates) {
         const action = this.actions.get(id);
         if (!action) {
-            throw new Error(`Action not found: ${id}`);
+            throw new EntityNotFoundError('Action', id, 'updateAction');
         }
         Object.assign(action, updates);
         if (updates.status === 'active' && !action.startedAt) {
@@ -1116,8 +1306,8 @@ export class MemoryProvider {
                 event: 'Action.completed',
                 object: action.id,
                 objectData: { action: action.action },
-                result: action.object,
-                resultData: action.result,
+                ...(action.object !== undefined && { result: action.object }),
+                ...(action.result !== undefined && { resultData: action.result }),
             });
         }
         if (updates.status === 'failed') {
@@ -1170,15 +1360,15 @@ export class MemoryProvider {
     async retryAction(id) {
         const action = this.actions.get(id);
         if (!action) {
-            throw new Error(`Action not found: ${id}`);
+            throw new EntityNotFoundError('Action', id, 'retryAction');
         }
         if (action.status !== 'failed') {
             throw new Error(`Can only retry failed actions: ${id}`);
         }
         action.status = 'pending';
-        action.error = undefined;
-        action.startedAt = undefined;
-        action.completedAt = undefined;
+        delete action.error;
+        delete action.startedAt;
+        delete action.completedAt;
         await this.emit({
             actor: action.actor,
             event: 'Action.retried',
@@ -1190,9 +1380,11 @@ export class MemoryProvider {
     async cancelAction(id) {
         const action = this.actions.get(id);
         if (!action) {
-            throw new Error(`Action not found: ${id}`);
+            throw new EntityNotFoundError('Action', id, 'cancelAction');
         }
-        if (action.status === 'completed' || action.status === 'failed' || action.status === 'cancelled') {
+        if (action.status === 'completed' ||
+            action.status === 'failed' ||
+            action.status === 'cancelled') {
             throw new Error(`Cannot cancel finished action: ${id}`);
         }
         action.status = 'cancelled';
@@ -1226,13 +1418,14 @@ export class MemoryProvider {
         return this.artifacts.get(this.artifactKey(url, type)) ?? null;
     }
     async setArtifact(url, type, data) {
+        validateArtifactUrl(url);
         const artifact = {
             url,
             type,
             sourceHash: data.sourceHash,
             content: data.content,
-            metadata: data.metadata,
             createdAt: new Date(),
+            ...(data.metadata !== undefined && { metadata: data.metadata }),
         };
         this.artifacts.set(this.artifactKey(url, type), artifact);
     }
@@ -1292,6 +1485,19 @@ export class MemoryProvider {
     async mapWithConcurrency(items, fn) {
         return this.semaphore.map(items, fn);
     }
+    // ===========================================================================
+    // Transactions
+    // ===========================================================================
+    /**
+     * Begin a new transaction.
+     *
+     * All writes (create, update, delete, relate) are buffered in memory.
+     * On commit(), they are applied to the provider atomically.
+     * On rollback(), all buffered writes are discarded.
+     */
+    async beginTransaction() {
+        return new MemoryTransaction(this);
+    }
     /**
      * Clear all data (useful for testing)
      */
@@ -1332,6 +1538,135 @@ export class MemoryProvider {
         };
     }
 }
+/**
+ * In-memory transaction that buffers writes and applies them on commit.
+ *
+ * - get() checks the write buffer first, then falls through to the provider.
+ * - create/update/delete/relate are buffered.
+ * - commit() replays all buffered operations against the real provider.
+ * - rollback() discards the buffer.
+ */
+export class MemoryTransaction {
+    provider;
+    ops = [];
+    committed = false;
+    rolledBack = false;
+    /** Buffered creates/updates: type -> id -> data */
+    buffer = new Map();
+    /** Buffered deletes: type -> Set<id> */
+    deletions = new Map();
+    /** Counter for generating temporary IDs */
+    tempIdCounter = 0;
+    constructor(provider) {
+        this.provider = provider;
+    }
+    assertActive() {
+        if (this.committed)
+            throw new Error('Transaction already committed');
+        if (this.rolledBack)
+            throw new Error('Transaction already rolled back');
+    }
+    getBuffer(type) {
+        if (!this.buffer.has(type)) {
+            this.buffer.set(type, new Map());
+        }
+        return this.buffer.get(type);
+    }
+    async get(type, id) {
+        this.assertActive();
+        // Check if deleted in this transaction
+        if (this.deletions.get(type)?.has(id))
+            return null;
+        // Check buffer first
+        const buf = this.buffer.get(type);
+        if (buf?.has(id)) {
+            return { ...buf.get(id), $id: id, $type: type };
+        }
+        // Fall through to provider
+        return this.provider.get(type, id);
+    }
+    async create(type, id, data) {
+        this.assertActive();
+        const entityId = id || `txn-temp-${++this.tempIdCounter}`;
+        const entity = {
+            ...data,
+            createdAt: new Date().toISOString(),
+            updatedAt: new Date().toISOString(),
+        };
+        this.getBuffer(type).set(entityId, entity);
+        const result = { ...entity, $id: entityId, $type: type };
+        this.ops.push({ kind: 'create', type, id: entityId, data, result });
+        return result;
+    }
+    async update(type, id, data) {
+        this.assertActive();
+        // Get current state (from buffer or provider)
+        const existing = await this.get(type, id);
+        if (!existing)
+            throw new Error(`update ${type}/${id}: Entity not found`);
+        const { $id: _id, $type: _type, ...rest } = existing;
+        const updated = { ...rest, ...data, updatedAt: new Date().toISOString() };
+        this.getBuffer(type).set(id, updated);
+        const result = { ...updated, $id: id, $type: type };
+        this.ops.push({ kind: 'update', type, id, data, result });
+        return result;
+    }
+    async delete(type, id) {
+        this.assertActive();
+        // Check existence
+        const existing = await this.get(type, id);
+        if (!existing)
+            return false;
+        // Remove from buffer if present
+        this.buffer.get(type)?.delete(id);
+        // Mark as deleted
+        if (!this.deletions.has(type))
+            this.deletions.set(type, new Set());
+        this.deletions.get(type).add(id);
+        this.ops.push({ kind: 'delete', type, id });
+        return true;
+    }
+    async relate(fromType, fromId, relation, toType, toId, metadata) {
+        this.assertActive();
+        this.ops.push({
+            kind: 'relate',
+            fromType,
+            fromId,
+            relation,
+            toType,
+            toId,
+            ...(metadata != null ? { metadata } : {}),
+        });
+    }
+    async commit() {
+        this.assertActive();
+        this.committed = true;
+        // Replay all operations against the real provider
+        for (const op of this.ops) {
+            switch (op.kind) {
+                case 'create':
+                    await this.provider.create(op.type, op.id, op.data);
+                    break;
+                case 'update':
+                    await this.provider.update(op.type, op.id, op.data);
+                    break;
+                case 'delete':
+                    await this.provider.delete(op.type, op.id);
+                    break;
+                case 'relate':
+                    await this.provider.relate(op.fromType, op.fromId, op.relation, op.toType, op.toId, op.metadata);
+                    break;
+            }
+        }
+    }
+    async rollback() {
+        this.assertActive();
+        this.rolledBack = true;
+        this.ops = [];
+        this.buffer.clear();
+        this.deletions.clear();
+    }
+}
 /**
  * Create an in-memory provider
  */