ai-database 2.0.1 → 2.1.1

package/dist/memory-provider.js

@@ -3,7 +3,10 @@
  *
  * Simple provider implementation for testing and development.
  * Includes concurrency control via Semaphore for rate limiting.
+ * Supports automatic embedding generation on create/update.
  */
+import { cosineSimilarity, computeRRF, extractEmbeddableText, generateContentHash, } from './semantic.js';
+import { EMBEDDING_DIMENSIONS } from './constants.js';
 // =============================================================================
 // Semaphore for Concurrency Control
 // =============================================================================
@@ -67,6 +70,15 @@ export class Semaphore {
 // =============================================================================
 // Generate ID
 // =============================================================================
+/**
+ * Generate a unique ID for a new entity
+ *
+ * Uses crypto.randomUUID() to generate a UUID v4 identifier.
+ *
+ * @returns A new UUID string
+ *
+ * @internal
+ */
 function generateId() {
     return crypto.randomUUID();
 }
@@ -116,11 +128,36 @@ function conjugateVerb(verb) {
         activity: toGerund(base),
     };
 }
-/** Check if character is a vowel */
+/**
+ * Check if a character is a vowel (a, e, i, o, u)
+ *
+ * @param char - The character to check
+ * @returns True if the character is a vowel
+ *
+ * @internal
+ */
 function isVowel(char) {
     return char ? 'aeiou'.includes(char.toLowerCase()) : false;
 }
-/** Check if we should double the final consonant */
+/**
+ * Check if we should double the final consonant when adding a suffix
+ *
+ * English spelling rules require doubling the final consonant in certain
+ * cases when adding suffixes like -ing or -ed. This applies to short words
+ * ending in consonant-vowel-consonant patterns.
+ *
+ * @param verb - The verb to check
+ * @returns True if the final consonant should be doubled
+ *
+ * @example
+ * ```ts
+ * shouldDoubleConsonant('run')  // => true  (running)
+ * shouldDoubleConsonant('play') // => false (playing)
+ * shouldDoubleConsonant('fix')  // => false (fixing - x is excluded)
+ * ```
+ *
+ * @internal
+ */
 function shouldDoubleConsonant(verb) {
     if (verb.length < 2)
         return false;
@@ -135,7 +172,26 @@ function shouldDoubleConsonant(verb) {
         return true;
     return false;
 }
-/** Convert verb to present 3rd person (create → creates) */
+/**
+ * Convert a verb to present tense third person singular form
+ *
+ * Applies English conjugation rules for third person singular:
+ * - Verbs ending in consonant + y: change y to ies (try → tries)
+ * - Verbs ending in s, x, z, ch, sh: add es (push → pushes)
+ * - Other verbs: add s (run → runs)
+ *
+ * @param verb - The base form of the verb
+ * @returns The third person singular present tense form
+ *
+ * @example
+ * ```ts
+ * toPresent('create')  // => 'creates'
+ * toPresent('push')    // => 'pushes'
+ * toPresent('try')     // => 'tries'
+ * ```
+ *
+ * @internal
+ */
 function toPresent(verb) {
     if (verb.endsWith('y') && !isVowel(verb[verb.length - 2])) {
         return verb.slice(0, -1) + 'ies';
@@ -146,7 +202,27 @@ function toPresent(verb) {
     }
     return verb + 's';
 }
-/** Convert verb to gerund (create → creating) */
+/**
+ * Convert a verb to gerund/present participle form (-ing)
+ *
+ * Applies English spelling rules for adding -ing:
+ * - Verbs ending in ie: change ie to ying (die → dying)
+ * - Verbs ending in e (not ee): drop e, add ing (create → creating)
+ * - Verbs requiring consonant doubling: double + ing (run → running)
+ * - Other verbs: add ing (play → playing)
+ *
+ * @param verb - The base form of the verb
+ * @returns The gerund/present participle form
+ *
+ * @example
+ * ```ts
+ * toGerund('create')  // => 'creating'
+ * toGerund('run')     // => 'running'
+ * toGerund('die')     // => 'dying'
+ * ```
+ *
+ * @internal
+ */
 function toGerund(verb) {
     if (verb.endsWith('ie'))
         return verb.slice(0, -2) + 'ying';
@@ -177,12 +253,305 @@ export class MemoryProvider {
     artifacts = new Map();
     // Concurrency control
     semaphore;
+    // Embedding configuration
+    embeddingsConfig;
     constructor(options = {}) {
         this.semaphore = new Semaphore(options.concurrency ?? 10);
+        this.embeddingsConfig = options.embeddings ?? {};
+    }
+    /**
+     * Set embeddings configuration
+     */
+    setEmbeddingsConfig(config) {
+        this.embeddingsConfig = config;
+    }
+    // ===========================================================================
+    // Embedding Generation
+    // ===========================================================================
+    /**
+     * Generate embedding for text (deterministic for testing)
+     *
+     * Uses semantic word vectors to create meaningful embeddings
+     * where similar concepts have higher cosine similarity.
+     */
+    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);
+        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];
+            }
+        }
+        // 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 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));
+    }
+    /**
+     * Check if embeddings should be generated for a given entity type
+     *
+     * Consults the embeddings configuration to determine:
+     * - If embeddings are disabled for this type (config === false)
+     * - If specific fields are configured for embedding
+     * - If auto-detection of text fields should be used (default)
+     *
+     * @param type - The entity type name
+     * @returns Object with enabled flag and optional field list
+     *
+     * @internal
+     */
+    shouldEmbed(type) {
+        const config = this.embeddingsConfig[type];
+        if (config === false) {
+            return { enabled: false };
+        }
+        if (config && config.fields) {
+            return { enabled: true, fields: config.fields };
+        }
+        // Default: embed all text fields (auto-detect)
+        return { enabled: true };
+    }
+    /**
+     * Auto-generate and store an embedding for an entity
+     *
+     * Called during create/update operations to automatically generate
+     * embeddings for entities based on their text content. The embedding
+     * is stored as an artifact associated with the entity.
+     *
+     * @param type - The entity type name
+     * @param id - The entity ID
+     * @param data - The entity data to extract text from
+     *
+     * @internal
+     */
+    async autoEmbed(type, id, data) {
+        const { enabled, fields } = this.shouldEmbed(type);
+        if (!enabled)
+            return;
+        // Extract embeddable text
+        const { text, fields: embeddedFields } = extractEmbeddableText(data, fields);
+        if (!text.trim())
+            return;
+        // Generate embedding
+        const embedding = this.generateEmbedding(text);
+        const contentHash = generateContentHash(text);
+        // Store as artifact with complete metadata
+        const url = `${type}/${id}`;
+        await this.setArtifact(url, 'embedding', {
+            content: embedding,
+            sourceHash: contentHash,
+            metadata: {
+                fields: embeddedFields,
+                dimensions: EMBEDDING_DIMENSIONS,
+                text: text.slice(0, 200),
+            },
+        });
     }
     // ===========================================================================
     // Things (Records)
     // ===========================================================================
+    /**
+     * Get or create the storage map for an entity type
+     *
+     * Lazily creates the type-specific storage map if it doesn't exist.
+     * This ensures each entity type has its own namespace for ID collisions.
+     *
+     * @param type - The entity type name
+     * @returns The Map storing entities of this type (id -> entity data)
+     *
+     * @internal
+     */
     getTypeStore(type) {
         if (!this.entities.has(type)) {
             this.entities.set(type, new Map());
@@ -269,6 +638,118 @@ export class MemoryProvider {
         scored.sort((a, b) => b.score - a.score);
         return scored.map((s) => s.entity);
     }
+    /**
+     * Semantic search using embedding similarity
+     */
+    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 = [];
+        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,
+                });
+            }
+        }
+        // Sort by score descending
+        scored.sort((a, b) => b.score - a.score);
+        // Apply limit and add $score
+        return scored.slice(0, limit).map(({ entity, score }) => ({
+            ...entity,
+            $score: score,
+        }));
+    }
+    /**
+     * Hybrid search combining FTS and semantic with RRF scoring
+     */
+    async hybridSearch(type, query, options) {
+        const limit = options?.limit ?? 10;
+        const offset = options?.offset ?? 0;
+        const rrfK = options?.rrfK ?? 60;
+        const ftsWeight = options?.ftsWeight ?? 0.5;
+        const semanticWeight = options?.semanticWeight ?? 0.5;
+        const minScore = options?.minScore ?? 0;
+        // Get FTS results with their ranks
+        const ftsResults = await this.search(type, query);
+        const ftsRanks = new Map();
+        ftsResults.forEach((entity, index) => {
+            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 semanticRanks = new Map();
+        semanticResults.forEach((entity, index) => {
+            const id = entity.$id || entity.id;
+            semanticRanks.set(id, { rank: index + 1, score: entity.$score });
+        });
+        // Combine results with RRF
+        const allIds = new Set([...ftsRanks.keys(), ...semanticRanks.keys()]);
+        const combined = [];
+        const store = this.getTypeStore(type);
+        for (const id of allIds) {
+            const entity = store.get(id);
+            if (!entity)
+                continue;
+            const ftsRank = ftsRanks.get(id) ?? Infinity;
+            const semantic = semanticRanks.get(id) ?? { rank: Infinity, score: 0 };
+            const semanticRank = semantic.rank;
+            const semanticScore = semantic.score;
+            // Skip if semantic score is below threshold (when we have a semantic result)
+            if (semanticRanks.has(id) && semanticScore < minScore)
+                continue;
+            const rrfScore = computeRRF(ftsRank, semanticRank, rrfK, ftsWeight, semanticWeight);
+            combined.push({
+                entity: { ...entity, $id: id, $type: type },
+                rrfScore,
+                ftsRank,
+                semanticRank,
+                semanticScore,
+            });
+        }
+        // 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 }) => ({
+            ...entity,
+            $rrfScore: rrfScore,
+            $ftsRank: ftsRank,
+            $semanticRank: semanticRank,
+            $score: semanticScore,
+        }));
+    }
+    /**
+     * Get all embeddings for a type
+     */
+    async getAllEmbeddings(type) {
+        const store = this.getTypeStore(type);
+        const results = [];
+        for (const [id] of store) {
+            const url = `${type}/${id}`;
+            const artifact = await this.getArtifact(url, 'embedding');
+            if (artifact && Array.isArray(artifact.content)) {
+                results.push({
+                    id,
+                    embedding: artifact.content,
+                });
+            }
+        }
+        return results;
+    }
     async create(type, id, data) {
         const store = this.getTypeStore(type);
         const entityId = id || generateId();
@@ -281,8 +762,12 @@ export class MemoryProvider {
             updatedAt: new Date().toISOString(),
         };
         store.set(entityId, entity);
-        // Emit event
-        await this.emit(`${type}.created`, { $id: entityId, $type: type, ...entity });
+        // Auto-generate embedding
+        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);
         return { ...entity, $id: entityId, $type: type };
     }
     async update(type, id, data) {
@@ -297,10 +782,14 @@ export class MemoryProvider {
             updatedAt: new Date().toISOString(),
         };
         store.set(id, updated);
-        // Emit event
-        await this.emit(`${type}.updated`, { $id: id, $type: type, ...updated });
-        // Invalidate artifacts when data changes
+        // Re-generate embedding with updated data
+        await this.autoEmbed(type, id, updated);
+        // Invalidate non-embedding artifacts when data changes
         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);
         return { ...updated, $id: id, $type: type };
     }
     async delete(type, id) {
@@ -309,8 +798,10 @@ export class MemoryProvider {
             return false;
         }
         store.delete(id);
-        // Emit event
-        await this.emit(`${type}.deleted`, { $id: id, $type: type });
+        // Emit type-specific and global events
+        const eventData = { $id: id, $type: type };
+        await this.emit(`${type}.deleted`, eventData);
+        await this.emit('entity:deleted', eventData);
         // Clean up relations
         for (const [key, targets] of this.relations) {
             if (key.startsWith(`${type}:${id}:`)) {
@@ -325,6 +816,19 @@ export class MemoryProvider {
     // ===========================================================================
     // Relationships
     // ===========================================================================
+    /**
+     * Generate a unique key for storing relationships
+     *
+     * Creates a composite key from source entity type, ID, and relation name
+     * that serves as the key in the relations Map.
+     *
+     * @param fromType - The source entity type
+     * @param fromId - The source entity ID
+     * @param relation - The relationship name
+     * @returns Composite key in format "type:id:relation"
+     *
+     * @internal
+     */
     relationKey(fromType, fromId, relation) {
         return `${fromType}:${fromId}:${relation}`;
     }
@@ -343,17 +847,19 @@ export class MemoryProvider {
         }
         return results;
     }
-    async relate(fromType, fromId, relation, toType, toId) {
+    async relate(fromType, fromId, relation, toType, toId, metadata) {
         const key = this.relationKey(fromType, fromId, relation);
         if (!this.relations.has(key)) {
             this.relations.set(key, new Set());
         }
         this.relations.get(key).add(`${toType}:${toId}`);
-        // Emit event
+        // Emit event with metadata
         await this.emit('Relation.created', {
             from: `${fromType}/${fromId}`,
             type: relation,
             to: `${toType}/${toId}`,
+            matchMode: metadata?.matchMode,
+            similarity: metadata?.similarity,
         });
     }
     async unrelate(fromType, fromId, relation, toType, toId) {
@@ -427,6 +933,18 @@ export class MemoryProvider {
         await this.semaphore.map(handlers, (handler) => Promise.resolve(handler(event)));
         return event;
     }
+    /**
+     * Get all event handlers matching an event type
+     *
+     * Collects handlers from all registered patterns that match the given
+     * event type. Supports exact matches, wildcards (*), and prefix/suffix
+     * patterns (*.created, Post.*).
+     *
+     * @param type - The event type to match handlers for
+     * @returns Array of matching event handlers
+     *
+     * @internal
+     */
     getEventHandlers(type) {
         const handlers = [];
         for (const [pattern, patternHandlers] of this.eventHandlers) {
@@ -436,6 +954,21 @@ export class MemoryProvider {
         }
         return handlers;
     }
+    /**
+     * Check if an event type matches a subscription pattern
+     *
+     * Supports several pattern formats:
+     * - Exact match: 'Post.created' matches 'Post.created'
+     * - Global wildcard: '*' matches everything
+     * - Prefix wildcard: 'Post.*' matches 'Post.created', 'Post.updated', etc.
+     * - Suffix wildcard: '*.created' matches 'Post.created', 'User.created', etc.
+     *
+     * @param type - The event type to check
+     * @param pattern - The subscription pattern to match against
+     * @returns True if the type matches the pattern
+     *
+     * @internal
+     */
     matchesPattern(type, pattern) {
         if (pattern === type)
             return true;
@@ -674,6 +1207,18 @@ export class MemoryProvider {
     // ===========================================================================
     // Artifacts
     // ===========================================================================
+    /**
+     * Generate a unique key for storing artifacts
+     *
+     * Creates a composite key from URL and artifact type for storage
+     * in the artifacts Map.
+     *
+     * @param url - The entity URL (e.g., 'Post/123')
+     * @param type - The artifact type (e.g., 'embedding')
+     * @returns Composite key in format "url:type"
+     *
+     * @internal
+     */
     artifactKey(url, type) {
         return `${url}:${type}`;
     }
@@ -704,6 +1249,17 @@ export class MemoryProvider {
             }
         }
     }
+    /**
+     * Invalidate cached artifacts for an entity (except embeddings)
+     *
+     * Called when entity data changes to ensure stale computed content
+     * (like cached transformations) is regenerated. Embeddings are preserved
+     * as they're regenerated separately via autoEmbed.
+     *
+     * @param url - The entity URL whose artifacts should be invalidated
+     *
+     * @internal
+     */
     async invalidateArtifacts(url) {
         // Keep embedding artifact but mark others for regeneration
         for (const [key, artifact] of this.artifacts) {