@soulcraft/brainy 2.10.0 → 2.11.0

package/dist/brainyData.js

@@ -12,6 +12,7 @@ import { enforceNodeVersion } from './utils/nodeVersionCheck.js';
 import { createNamespacedMetadata, updateNamespacedMetadata, markDeleted, markRestored, isDeleted, getUserMetadata } from './utils/metadataNamespace.js';
 import { PeriodicCleanup } from './utils/periodicCleanup.js';
 import { NounType, VerbType } from './types/graphTypes.js';
+import { validateNounType } from './utils/typeValidation.js';
 import { createServerSearchAugmentations } from './augmentations/serverSearchAugmentations.js';
 import { augmentationPipeline } from './augmentationPipeline.js';
 import { prodLog } from './utils/logger.js';
@@ -127,7 +128,7 @@ export class BrainyData {
         this.operationalMode = null;
         this.domainDetector = null;
         // Enforce Node.js version requirement for ONNX stability
-        if (typeof process !== 'undefined' && process.version) {
+        if (typeof process !== 'undefined' && process.version && !process.env.BRAINY_SKIP_VERSION_CHECK) {
             enforceNodeVersion();
         }
         // Store raw config for processing in init()
@@ -1248,1317 +1249,1023 @@ export class BrainyData {
             throw new Error(`Failed to connect to remote server: ${error}`);
         }
     }
+    // REMOVED: addItem() - Use addNoun() instead (cleaner 2.0 API)
+    // REMOVED: addToBoth() - Remote server functionality moved to post-2.0.0
     /**
-     * Add data to the database with intelligent processing
-     *
-     * @param vectorOrData Vector or data to add
-     * @param metadata Optional metadata to associate with the data
-     * @param options Additional options for processing
-     * @returns The ID of the added data
-     *
-     * @example
-     * // Auto mode - intelligently decides processing
-     * await brainy.add("Customer feedback: Great product!")
-     *
-     * @example
-     * // Explicit literal mode for sensitive data
-     * await brainy.add("API_KEY=secret123", null, { process: 'literal' })
-     *
-     * @example
-     * // Force neural processing
-     * await brainy.add("John works at Acme Corp", null, { process: 'neural' })
+     * Add a vector to the remote server
+     * @param id ID of the vector to add
+     * @param vector Vector to add
+     * @param metadata Optional metadata to associate with the vector
+     * @returns True if successful, false otherwise
+     * @private
+     */
+    async addToRemote(id, vector, metadata) {
+        if (!this.isConnectedToRemoteServer()) {
+            return false;
+        }
+        try {
+            // TODO: Remote server operations (post-2.0.0 feature)
+            // if (!this.serverSearchConduit || !this.serverConnection) {
+            //   throw new Error(
+            //     'Server search conduit or connection is not initialized'
+            //   )
+            // }
+            // TODO: Add to remote server
+            // const addResult = await this.serverSearchConduit.addToBoth(
+            //   this.serverConnection.connectionId,
+            //   vector,
+            //   metadata
+            // )
+            throw new Error('Remote server functionality not yet implemented in Brainy 2.0.0');
+            // TODO: Handle remote add result (post-2.0.0 feature)
+            // if (!addResult.success) {
+            //   throw new Error(`Remote add failed: ${addResult.error}`)
+            // }
+            return true;
+        }
+        catch (error) {
+            console.error('Failed to add to remote server:', error);
+            throw new Error(`Failed to add to remote server: ${error}`);
+        }
+    }
+    /**
+     * Add multiple vectors or data items to the database
+     * @param items Array of items to add
+     * @param options Additional options
+     * @returns Array of IDs for the added items
+     */
+    /**
+     * Add multiple nouns in batch with required types
+     * @param items Array of nouns to add (all must have types)
+     * @param options Batch processing options
+     * @returns Array of generated IDs
      */
-    async add(vectorOrData, metadata, options = {}) {
+    async addNouns(items, options = {}) {
         await this.ensureInitialized();
         // Check if database is in read-only mode
         this.checkReadOnly();
-        // Validate input is not null or undefined
-        if (vectorOrData === null || vectorOrData === undefined) {
-            throw new Error('Input cannot be null or undefined');
+        // Validate all types upfront for better error handling
+        const invalidItems = [];
+        items.forEach((item, index) => {
+            if (!item.nounType || typeof item.nounType !== 'string') {
+                invalidItems.push(index);
+            }
+            else {
+                // Validate the type is valid
+                try {
+                    validateNounType(item.nounType);
+                }
+                catch (error) {
+                    invalidItems.push(index);
+                }
+            }
+        });
+        if (invalidItems.length > 0) {
+            throw new Error(`Type validation failed for ${invalidItems.length} items at indices: ${invalidItems.slice(0, 5).join(', ')}${invalidItems.length > 5 ? '...' : ''}\n` +
+                'All items must have valid noun types.\n' +
+                'Example: { vectorOrData: "data", nounType: NounType.Content, metadata: {...} }');
         }
+        // Default concurrency to 4 if not specified
+        const concurrency = options.concurrency || 4;
+        // Default batch size to 50 if not specified
+        const batchSize = options.batchSize || 50;
         try {
-            let vector;
-            // First validate if input is an array but contains non-numeric values
-            if (Array.isArray(vectorOrData)) {
-                for (let i = 0; i < vectorOrData.length; i++) {
-                    if (typeof vectorOrData[i] !== 'number') {
-                        throw new Error('Vector contains non-numeric values');
+            // Process items in batches to control concurrency and memory usage
+            const ids = [];
+            const itemsToProcess = [...items]; // Create a copy to avoid modifying the original array
+            while (itemsToProcess.length > 0) {
+                // Take up to 'batchSize' items to process in a batch
+                const batch = itemsToProcess.splice(0, batchSize);
+                // Separate items that are already vectors from those that need embedding
+                const vectorItems = [];
+                const textItems = [];
+                // Categorize items
+                batch.forEach((item, index) => {
+                    if (Array.isArray(item.vectorOrData) &&
+                        item.vectorOrData.every((val) => typeof val === 'number') &&
+                        !options.forceEmbed) {
+                        // Item is already a vector
+                        vectorItems.push({
+                            vectorOrData: item.vectorOrData,
+                            nounType: item.nounType,
+                            metadata: item.metadata,
+                            index
+                        });
+                    }
+                    else if (typeof item.vectorOrData === 'string') {
+                        // Item is text that needs embedding
+                        textItems.push({
+                            text: item.vectorOrData,
+                            nounType: item.nounType,
+                            metadata: item.metadata,
+                            index
+                        });
+                    }
+                    else {
+                        // For now, treat other types as text
+                        // In a more complete implementation, we might handle other types differently
+                        const textRepresentation = String(item.vectorOrData);
+                        textItems.push({
+                            text: textRepresentation,
+                            nounType: item.nounType,
+                            metadata: item.metadata,
+                            index
+                        });
                     }
+                });
+                // Process vector items (already embedded)
+                const vectorPromises = vectorItems.map((item) => this.addNoun(item.vectorOrData, item.nounType, item.metadata));
+                // Process text items in a single batch embedding operation
+                let textPromises = [];
+                if (textItems.length > 0) {
+                    // Extract just the text for batch embedding
+                    const texts = textItems.map((item) => item.text);
+                    // Perform batch embedding
+                    const embeddings = await batchEmbed(texts);
+                    // Add each item with its embedding
+                    textPromises = textItems.map((item, i) => this.addNoun(embeddings[i], item.nounType, item.metadata));
                 }
+                // Combine all promises
+                const batchResults = await Promise.all([
+                    ...vectorPromises,
+                    ...textPromises
+                ]);
+                // Add the results to our ids array
+                ids.push(...batchResults);
             }
+            return ids;
+        }
+        catch (error) {
+            console.error('Failed to add batch of items:', error);
+            throw new Error(`Failed to add batch of items: ${error}`);
+        }
+    }
+    /**
+     * Add multiple vectors or data items to both local and remote databases
+     * @param items Array of items to add (with required types)
+     * @param options Additional options
+     * @returns Array of IDs for the added items
+     */
+    async addBatchToBoth(items, options = {}) {
+        // Check if connected to a remote server
+        if (!this.isConnectedToRemoteServer()) {
+            throw new Error('Not connected to a remote server. Call connectToRemoteServer() first.');
+        }
+        // Add to local with addToRemote option
+        return this.addNouns(items, { ...options, addToRemote: true });
+    }
+    /**
+     * Filter search results by service
+     * @param results Search results to filter
+     * @param service Service to filter by
+     * @returns Filtered search results
+     * @private
+     */
+    filterResultsByService(results, service) {
+        if (!service)
+            return results;
+        return results.filter((result) => {
+            if (!result.metadata || typeof result.metadata !== 'object')
+                return false;
+            if (!('createdBy' in result.metadata))
+                return false;
+            const createdBy = result.metadata.createdBy;
+            if (!createdBy)
+                return false;
+            return createdBy.augmentation === service;
+        });
+    }
+    /**
+     * Search for similar vectors within specific noun types
+     * @param queryVectorOrData Query vector or data to search for
+     * @param k Number of results to return
+     * @param nounTypes Array of noun types to search within, or null to search all
+     * @param options Additional options
+     * @returns Array of search results
+     */
+    /**
+     * @deprecated Use search() with nounTypes option instead
+     * @example
+     * // Old way (deprecated)
+     * await brain.searchByNounTypes(query, 10, ['type1', 'type2'])
+     * // New way
+     * await brain.search(query, { limit: 10, nounTypes: ['type1', 'type2'] })
+     */
+    async searchByNounTypes(queryVectorOrData, k = 10, nounTypes = null, options = {}) {
+        // Helper function to filter results by service
+        const filterByService = (metadata) => {
+            if (!options.service)
+                return true; // No filter, include all
+            // Check if metadata has createdBy field with matching service
+            if (!metadata || typeof metadata !== 'object')
+                return false;
+            if (!('createdBy' in metadata))
+                return false;
+            const createdBy = metadata.createdBy;
+            if (!createdBy)
+                return false;
+            return createdBy.augmentation === options.service;
+        };
+        if (!this.isInitialized) {
+            throw new Error('BrainyData must be initialized before searching. Call init() first.');
+        }
+        // Check if database is in write-only mode
+        this.checkWriteOnly();
+        try {
+            let queryVector;
             // Check if input is already a vector
-            if (Array.isArray(vectorOrData) && !options.forceEmbed) {
-                // Input is already a vector (and we've validated it contains only numbers)
-                vector = vectorOrData;
+            if (Array.isArray(queryVectorOrData) &&
+                queryVectorOrData.every((item) => typeof item === 'number') &&
+                !options.forceEmbed) {
+                // Input is already a vector
+                queryVector = queryVectorOrData;
             }
             else {
                 // Input needs to be vectorized
                 try {
-                    // Check if input is a JSON object and process it specially
-                    if (typeof vectorOrData === 'object' &&
-                        vectorOrData !== null &&
-                        !Array.isArray(vectorOrData)) {
-                        // Process JSON object for better vectorization
-                        const preparedText = prepareJsonForVectorization(vectorOrData, {
-                            // Prioritize common name/title fields if they exist
-                            priorityFields: [
-                                'name',
-                                'title',
-                                'company',
-                                'organization',
-                                'description',
-                                'summary'
-                            ]
-                        });
-                        vector = await this.embeddingFunction(preparedText);
-                        // IMPORTANT: When an object is passed as data and no metadata is provided,
-                        // use the object AS the metadata too. This is expected behavior for the API.
-                        // Users can pass either:
-                        // 1. addNoun(string, metadata) - vectorize string, store metadata
-                        // 2. addNoun(object) - vectorize object text, store object as metadata
-                        // 3. addNoun(object, metadata) - vectorize object text, store provided metadata
-                        if (!metadata) {
-                            metadata = vectorOrData;
-                        }
-                        // Track field names for this JSON document
-                        const service = this.getServiceName(options);
-                        if (this.storage) {
-                            await this.storage.trackFieldNames(vectorOrData, service);
-                        }
-                    }
-                    else {
-                        // Use standard embedding for non-JSON data
-                        vector = await this.embeddingFunction(vectorOrData);
-                    }
+                    queryVector = await this.embeddingFunction(queryVectorOrData);
                 }
                 catch (embedError) {
-                    throw new Error(`Failed to vectorize data: ${embedError}`);
+                    throw new Error(`Failed to vectorize query data: ${embedError}`);
                 }
             }
-            // Check if vector is defined
-            if (!vector) {
-                throw new Error('Vector is undefined or null');
+            // Check if query vector is defined
+            if (!queryVector) {
+                throw new Error('Query vector is undefined or null');
             }
-            // Validate vector dimensions
-            if (vector.length !== this._dimensions) {
-                throw new Error(`Vector dimension mismatch: expected ${this._dimensions}, got ${vector.length}`);
+            // Check if query vector dimensions match the expected dimensions
+            if (queryVector.length !== this._dimensions) {
+                throw new Error(`Query vector dimension mismatch: expected ${this._dimensions}, got ${queryVector.length}`);
             }
-            // Use ID from options if it exists, otherwise from metadata, otherwise generate a new UUID
-            const id = options.id ||
-                (metadata && typeof metadata === 'object' && 'id' in metadata
-                    ? metadata.id
-                    : uuidv4());
-            // Check for existing noun (both write-only and normal modes)
-            let existingNoun;
-            if (options.id) {
-                try {
-                    if (this.writeOnly) {
-                        // In write-only mode, check storage directly
-                        existingNoun =
-                            (await this.storage.getNoun(options.id)) ?? undefined;
+            // If no noun types specified, search all nouns
+            if (!nounTypes || nounTypes.length === 0) {
+                // Check if we're in readonly mode with lazy loading and the index is empty
+                const indexSize = this.index.getNouns().size;
+                if (this.readOnly && this.lazyLoadInReadOnlyMode && indexSize === 0) {
+                    if (this.loggingConfig?.verbose) {
+                        console.log('Lazy loading mode: Index is empty, loading nodes for search...');
                     }
-                    else {
-                        // In normal mode, check index first, then storage
-                        existingNoun = this.index.getNouns().get(options.id);
-                        if (!existingNoun) {
-                            existingNoun =
-                                (await this.storage.getNoun(options.id)) ?? undefined;
+                    // In lazy loading mode, we need to load some nodes to search
+                    // Instead of loading all nodes, we'll load a subset of nodes
+                    // Load a limited number of nodes from storage using pagination
+                    const result = await this.storage.getNouns({
+                        pagination: { offset: 0, limit: k * 10 } // Get 10x more nodes than needed
+                    });
+                    const limitedNouns = result.items;
+                    // Add these nodes to the index
+                    for (const node of limitedNouns) {
+                        // Check if the vector dimensions match the expected dimensions
+                        if (node.vector.length !== this._dimensions) {
+                            console.warn(`Skipping node ${node.id} due to dimension mismatch: expected ${this._dimensions}, got ${node.vector.length}`);
+                            continue;
                         }
+                        // Add to index
+                        await this.index.addItem({
+                            id: node.id,
+                            vector: node.vector
+                        });
                     }
-                    if (existingNoun) {
-                        // Check if existing noun is a placeholder
-                        const existingMetadata = await this.storage.getMetadata(options.id);
-                        const isPlaceholder = existingMetadata &&
-                            typeof existingMetadata === 'object' &&
-                            existingMetadata.isPlaceholder;
-                        if (isPlaceholder) {
-                            // Replace placeholder with real data
-                            if (this.loggingConfig?.verbose) {
-                                console.log(`Replacing placeholder noun ${options.id} with real data`);
-                            }
+                    if (this.loggingConfig?.verbose) {
+                        console.log(`Lazy loading mode: Added ${limitedNouns.length} nodes to index for search`);
+                    }
+                }
+                // Create filter function for HNSW search with metadata index optimization
+                const hasMetadataFilter = options.metadata && Object.keys(options.metadata).length > 0;
+                const hasServiceFilter = !!options.service;
+                let filterFunction;
+                let preFilteredIds;
+                // Use metadata index for pre-filtering if available
+                if (hasMetadataFilter && this.metadataIndex) {
+                    try {
+                        // Ensure metadata index is up to date
+                        await this.metadataIndex?.flush?.();
+                        // Get candidate IDs from metadata index
+                        const candidateIds = await this.metadataIndex?.getIdsForFilter?.(options.metadata) || [];
+                        if (candidateIds.length > 0) {
+                            preFilteredIds = new Set(candidateIds);
+                            // Create a simple filter function that just checks the pre-filtered set
+                            filterFunction = async (id) => {
+                                if (!preFilteredIds.has(id))
+                                    return false;
+                                // Still apply service filter if needed
+                                if (hasServiceFilter) {
+                                    const metadata = await this.storage.getMetadata(id);
+                                    const noun = this.index.getNouns().get(id);
+                                    if (!noun || !metadata)
+                                        return false;
+                                    const result = { id, score: 0, vector: noun.vector, metadata };
+                                    return this.filterResultsByService([result], options.service).length > 0;
+                                }
+                                return true;
+                            };
                         }
                         else {
-                            // Real noun already exists, update it
-                            if (this.loggingConfig?.verbose) {
-                                console.log(`Updating existing noun ${options.id}`);
-                            }
+                            // No items match the metadata criteria, return empty results immediately
+                            return [];
                         }
                     }
+                    catch (indexError) {
+                        console.warn('Metadata index error, falling back to full filtering:', indexError);
+                        // Fall back to full metadata filtering below
+                    }
                 }
-                catch (storageError) {
-                    // Item doesn't exist, continue with add operation
-                }
-            }
-            let noun;
-            // In write-only mode, skip index operations since index is not loaded
-            if (this.writeOnly) {
-                // Create noun object directly without adding to index
-                noun = {
-                    id,
-                    vector,
-                    connections: new Map(),
-                    level: 0, // Default level for new nodes
-                    metadata: undefined // Will be set separately
-                };
-            }
-            else {
-                // Normal mode: Add to HNSW index first
-                await this.hnswIndex.addItem({ id, vector, metadata });
-                // Get the noun from the HNSW index
-                const indexNoun = this.hnswIndex.getNouns().get(id);
-                if (!indexNoun) {
-                    throw new Error(`Failed to retrieve newly created noun with ID ${id}`);
-                }
-                noun = indexNoun;
-            }
-            // Save noun to storage using augmentation system
-            await this.augmentations.execute('saveNoun', { noun, options }, async () => {
-                await this.storage.saveNoun(noun);
-                const service = this.getServiceName(options);
-                await this.storage.incrementStatistic('noun', service);
-            });
-            // Save metadata if provided and not empty
-            if (metadata !== undefined) {
-                // Skip saving if metadata is an empty object
-                if (metadata &&
-                    typeof metadata === 'object' &&
-                    Object.keys(metadata).length === 0) {
-                    // Don't save empty metadata
-                    // Explicitly save null to ensure no metadata is stored
-                    await this.storage.saveMetadata(id, null);
-                }
-                else {
-                    // Validate noun type if metadata is for a GraphNoun
-                    if (metadata && typeof metadata === 'object' && 'noun' in metadata) {
-                        const nounType = metadata.noun;
-                        // Check if the noun type is valid
-                        const isValidNounType = Object.values(NounType).includes(nounType);
-                        if (!isValidNounType) {
-                            console.warn(`Invalid noun type: ${nounType}. Falling back to GraphNoun.`);
-                            metadata.noun = NounType.Concept;
-                        }
-                        // Ensure createdBy field is populated for GraphNoun
-                        const service = options.service || this.getCurrentAugmentation();
-                        const graphNoun = metadata;
-                        // Only set createdBy if it doesn't exist or is being explicitly updated
-                        if (!graphNoun.createdBy || options.service) {
-                            graphNoun.createdBy = getAugmentationVersion(service);
-                        }
-                        // Update timestamps
-                        const now = new Date();
-                        const timestamp = {
-                            seconds: Math.floor(now.getTime() / 1000),
-                            nanoseconds: (now.getTime() % 1000) * 1000000
-                        };
-                        // Set createdAt if it doesn't exist
-                        if (!graphNoun.createdAt) {
-                            graphNoun.createdAt = timestamp;
+                // Fallback to full metadata filtering if index wasn't used
+                if (!filterFunction && (hasMetadataFilter || hasServiceFilter)) {
+                    filterFunction = async (id) => {
+                        // Get metadata for filtering
+                        let metadata = await this.storage.getMetadata(id);
+                        if (metadata === null) {
+                            metadata = {};
                         }
-                        // Always update updatedAt
-                        graphNoun.updatedAt = timestamp;
-                    }
-                    // Create properly namespaced metadata for new items
-                    let metadataToSave = createNamespacedMetadata(metadata);
-                    // Add domain metadata if distributed mode is enabled
-                    if (this.domainDetector) {
-                        // First check if domain is already in metadata
-                        if (metadataToSave.domain) {
-                            // Domain already specified, keep it
-                            const domainInfo = this.domainDetector.detectDomain(metadataToSave);
-                            if (domainInfo.domainMetadata) {
-                                ;
-                                metadataToSave.domainMetadata =
-                                    domainInfo.domainMetadata;
+                        // Apply metadata filter
+                        if (hasMetadataFilter) {
+                            const matches = matchesMetadataFilter(metadata, options.metadata);
+                            if (!matches) {
+                                return false;
                             }
                         }
-                        else {
-                            // Try to detect domain from the data
-                            const dataToAnalyze = Array.isArray(vectorOrData)
-                                ? metadata
-                                : vectorOrData;
-                            const domainInfo = this.domainDetector.detectDomain(dataToAnalyze);
-                            if (domainInfo.domain) {
-                                ;
-                                metadataToSave.domain = domainInfo.domain;
-                                if (domainInfo.domainMetadata) {
-                                    ;
-                                    metadataToSave.domainMetadata =
-                                        domainInfo.domainMetadata;
-                                }
+                        // Apply service filter
+                        if (hasServiceFilter) {
+                            const noun = this.index.getNouns().get(id);
+                            if (!noun)
+                                return false;
+                            const result = { id, score: 0, vector: noun.vector, metadata };
+                            if (!this.filterResultsByService([result], options.service).length) {
+                                return false;
                             }
                         }
+                        return true;
+                    };
+                }
+                // When using offset, we need to fetch more results and then slice
+                const offset = options.offset || 0;
+                const totalNeeded = k + offset;
+                // Search in the index with filter
+                const results = await this.index.search(queryVector, totalNeeded, filterFunction);
+                // Skip the offset number of results
+                const paginatedResults = results.slice(offset, offset + k);
+                // Get metadata for each result
+                const searchResults = [];
+                for (const [id, score] of paginatedResults) {
+                    const noun = this.index.getNouns().get(id);
+                    if (!noun) {
+                        continue;
                     }
-                    // Add partition information if distributed mode is enabled
-                    if (this.partitioner) {
-                        const partition = this.partitioner.getPartition(id);
-                        metadataToSave.partition = partition;
-                    }
-                    await this.storage.saveMetadata(id, metadataToSave);
-                    // Update metadata index (write-only mode should build indices!)
-                    if (this.index && !this.frozen) {
-                        await this.metadataIndex?.addToIndex?.(id, metadataToSave);
-                    }
-                    // Track metadata statistics
-                    const metadataService = this.getServiceName(options);
-                    await this.storage.incrementStatistic('metadata', metadataService);
-                    // Track content type if it's a GraphNoun
-                    if (metadataToSave &&
-                        typeof metadataToSave === 'object' &&
-                        'noun' in metadataToSave) {
-                        this.metrics.trackContentType(metadataToSave.noun);
+                    let metadata = await this.storage.getMetadata(id);
+                    // Initialize metadata to an empty object if it's null
+                    if (metadata === null) {
+                        metadata = {};
                     }
-                    // Track update timestamp (handled by metrics augmentation)
+                    // Preserve original metadata without overwriting user's custom fields
+                    // The search result already has Brainy's UUID in the main 'id' field
+                    searchResults.push({
+                        id,
+                        score: 1 - score, // Convert distance to similarity (higher = more similar)
+                        vector: noun.vector,
+                        metadata: metadata
+                    });
                 }
+                return searchResults;
             }
-            // Update HNSW index size with actual index size
-            const indexSize = this.index.size();
-            await this.storage.updateHnswIndexSize(indexSize);
-            // Update health metrics if in distributed mode
-            if (this.monitoring) {
-                const vectorCount = await this.getNounCount();
-                this.monitoring.updateVectorCount(vectorCount);
-            }
-            // If addToRemote is true and we're connected to a remote server, add to remote as well
-            if (options.addToRemote && this.isConnectedToRemoteServer()) {
-                try {
-                    await this.addToRemote(id, vector, metadata);
+            else {
+                // Get nouns for each noun type in parallel
+                const nounPromises = nounTypes.map((nounType) => this.storage.getNounsByNounType(nounType));
+                const nounArrays = await Promise.all(nounPromises);
+                // Combine all nouns
+                const nouns = [];
+                for (const nounArray of nounArrays) {
+                    nouns.push(...nounArray);
                 }
-                catch (remoteError) {
-                    console.warn(`Failed to add to remote server: ${remoteError}. Continuing with local add.`);
+                // Calculate distances for each noun
+                const results = [];
+                for (const noun of nouns) {
+                    const distance = this.index.getDistanceFunction()(queryVector, noun.vector);
+                    results.push([noun.id, distance]);
                 }
-            }
-            // Invalidate search cache since data has changed
-            this.cache?.invalidateOnDataChange('add');
-            // Determine processing mode
-            const processingMode = options.process || 'auto';
-            let shouldProcessNeurally = false;
-            if (processingMode === 'neural') {
-                shouldProcessNeurally = true;
-            }
-            else if (processingMode === 'auto') {
-                // Auto-detect whether to use neural processing
-                shouldProcessNeurally = this.shouldAutoProcessNeurally(vectorOrData, metadata);
-            }
-            // 'literal' mode means no neural processing
-            // 🧠 AI Processing (Neural Import) - Based on processing mode
-            if (shouldProcessNeurally) {
-                try {
-                    // Execute augmentation pipeline for data processing
-                    // Note: Augmentations will be called via this.augmentations.execute during the actual add operation
-                    // This replaces the legacy SENSE pipeline
-                    if (this.loggingConfig?.verbose) {
-                        console.log(`🧠 AI processing completed for data: ${id}`);
+                // Sort by distance (ascending)
+                results.sort((a, b) => a[1] - b[1]);
+                // Apply offset and take k results
+                const offset = options.offset || 0;
+                const topResults = results.slice(offset, offset + k);
+                // Get metadata for each result
+                const searchResults = [];
+                for (const [id, score] of topResults) {
+                    const noun = nouns.find((n) => n.id === id);
+                    if (!noun) {
+                        continue;
                     }
+                    let metadata = await this.storage.getMetadata(id);
+                    // Initialize metadata to an empty object if it's null
+                    if (metadata === null) {
+                        metadata = {};
+                    }
+                    // Preserve original metadata without overwriting user's custom fields
+                    // The search result already has Brainy's UUID in the main 'id' field
+                    searchResults.push({
+                        id,
+                        score: 1 - score, // Convert distance to similarity (higher = more similar)
+                        vector: noun.vector,
+                        metadata: metadata
+                    });
                 }
-                catch (processingError) {
-                    // Don't fail the add operation if processing fails
-                    console.warn(`🧠 AI processing failed for ${id}:`, processingError);
-                }
+                // Results are already filtered, just return them
+                return searchResults;
             }
-            return id;
         }
         catch (error) {
-            console.error('Failed to add vector:', error);
-            // Track error in health monitor
-            if (this.monitoring) {
-                this.monitoring.recordRequest(0, true);
-            }
-            throw new Error(`Failed to add vector: ${error}`);
+            console.error('Failed to search vectors by noun types:', error);
+            throw new Error(`Failed to search vectors by noun types: ${error}`);
         }
     }
-    // REMOVED: addItem() - Use addNoun() instead (cleaner 2.0 API)
-    // REMOVED: addToBoth() - Remote server functionality moved to post-2.0.0
     /**
-     * Add a vector to the remote server
-     * @param id ID of the vector to add
-     * @param vector Vector to add
-     * @param metadata Optional metadata to associate with the vector
-     * @returns True if successful, false otherwise
-     * @private
+     * Search for similar vectors
+     * @param queryVectorOrData Query vector or data to search for
+     * @param k Number of results to return
+     * @param options Additional options
+     * @returns Array of search results
      */
-    async addToRemote(id, vector, metadata) {
-        if (!this.isConnectedToRemoteServer()) {
-            return false;
+    /**
+     * 🔍 SIMPLE VECTOR SEARCH - Clean wrapper around find() for pure vector search
+     *
+     * @param queryVectorOrData Vector or text to search for
+     * @param k Number of results to return
+     * @param options Simple search options (metadata filters only)
+     * @returns Vector search results
+     */
+    /**
+     * 🔍 Simple Vector Similarity Search - Clean wrapper around find()
+     *
+     * search(query) = find({like: query}) - Pure vector similarity search
+     *
+     * @param queryVectorOrData - Query string, vector, or object to search with
+     * @param options - Search options for filtering and pagination
+     * @returns Array of search results with scores and metadata
+     *
+     * @example
+     * // Simple vector search
+     * await brain.search('machine learning')
+     *
+     * // With filters and pagination
+     * await brain.search('AI', {
+     *   limit: 20,
+     *   metadata: { type: 'article' },
+     *   nounTypes: ['document']
+     * })
+     */
+    async search(queryVectorOrData, options = {}) {
+        // Build metadata filter from options
+        const metadataFilter = { ...options.metadata };
+        // Add noun type filtering
+        if (options.nounTypes && options.nounTypes.length > 0) {
+            metadataFilter.nounType = { in: options.nounTypes };
         }
-        try {
-            // TODO: Remote server operations (post-2.0.0 feature)
-            // if (!this.serverSearchConduit || !this.serverConnection) {
-            //   throw new Error(
-            //     'Server search conduit or connection is not initialized'
-            //   )
-            // }
-            // TODO: Add to remote server
-            // const addResult = await this.serverSearchConduit.addToBoth(
-            //   this.serverConnection.connectionId,
-            //   vector,
-            //   metadata
-            // )
-            throw new Error('Remote server functionality not yet implemented in Brainy 2.0.0');
-            // TODO: Handle remote add result (post-2.0.0 feature)
-            // if (!addResult.success) {
-            //   throw new Error(`Remote add failed: ${addResult.error}`)
-            // }
-            return true;
+        // Add item ID filtering
+        if (options.itemIds && options.itemIds.length > 0) {
+            metadataFilter.id = { in: options.itemIds };
         }
-        catch (error) {
-            console.error('Failed to add to remote server:', error);
-            throw new Error(`Failed to add to remote server: ${error}`);
+        // Build simple TripleQuery for vector similarity
+        const tripleQuery = {
+            like: queryVectorOrData
+        };
+        // Add metadata filter if we have conditions
+        if (Object.keys(metadataFilter).length > 0) {
+            tripleQuery.where = metadataFilter;
+        }
+        // Extract find() options
+        const findOptions = {
+            limit: options.limit,
+            offset: options.offset,
+            cursor: options.cursor,
+            excludeDeleted: options.excludeDeleted,
+            timeout: options.timeout
+        };
+        // Call find() with structured query - this is the key simplification!
+        let results = await this.find(tripleQuery, findOptions);
+        // Apply threshold filtering if specified
+        if (options.threshold !== undefined) {
+            results = results.filter(r => (r.fusionScore || r.score || 0) >= options.threshold);
         }
+        // Convert to SearchResult format
+        return results.map(r => ({
+            ...r,
+            score: r.fusionScore || r.score || 0
+        }));
+        return results;
     }
     /**
-     * Add multiple vectors or data items to the database
-     * @param items Array of items to add
-     * @param options Additional options
-     * @returns Array of IDs for the added items
+     * Helper method to encode cursor for pagination
+     * @internal
      */
+    encodeCursor(data) {
+        return Buffer.from(JSON.stringify(data)).toString('base64');
+    }
     /**
-     * Add multiple nouns in batch
-     * @param items Array of nouns to add
-     * @param options Batch processing options
-     * @returns Array of generated IDs
+     * Helper method to decode cursor for pagination
+     * @internal
      */
-    async addNouns(items, options = {}) {
-        await this.ensureInitialized();
-        // Check if database is in read-only mode
-        this.checkReadOnly();
-        // Default concurrency to 4 if not specified
-        const concurrency = options.concurrency || 4;
-        // Default batch size to 50 if not specified
-        const batchSize = options.batchSize || 50;
+    decodeCursor(cursor) {
         try {
-            // Process items in batches to control concurrency and memory usage
-            const ids = [];
-            const itemsToProcess = [...items]; // Create a copy to avoid modifying the original array
-            while (itemsToProcess.length > 0) {
-                // Take up to 'batchSize' items to process in a batch
-                const batch = itemsToProcess.splice(0, batchSize);
-                // Separate items that are already vectors from those that need embedding
-                const vectorItems = [];
-                const textItems = [];
-                // Categorize items
-                batch.forEach((item, index) => {
-                    if (Array.isArray(item.vectorOrData) &&
-                        item.vectorOrData.every((val) => typeof val === 'number') &&
-                        !options.forceEmbed) {
-                        // Item is already a vector
-                        vectorItems.push({
-                            vectorOrData: item.vectorOrData,
-                            metadata: item.metadata,
-                            index
-                        });
-                    }
-                    else if (typeof item.vectorOrData === 'string') {
-                        // Item is text that needs embedding
-                        textItems.push({
-                            text: item.vectorOrData,
-                            metadata: item.metadata,
-                            index
-                        });
-                    }
-                    else {
-                        // For now, treat other types as text
-                        // In a more complete implementation, we might handle other types differently
-                        const textRepresentation = String(item.vectorOrData);
-                        textItems.push({
-                            text: textRepresentation,
-                            metadata: item.metadata,
-                            index
-                        });
-                    }
-                });
-                // Process vector items (already embedded)
-                const vectorPromises = vectorItems.map((item) => this.addNoun(item.vectorOrData, item.metadata));
-                // Process text items in a single batch embedding operation
-                let textPromises = [];
-                if (textItems.length > 0) {
-                    // Extract just the text for batch embedding
-                    const texts = textItems.map((item) => item.text);
-                    // Perform batch embedding
-                    const embeddings = await batchEmbed(texts);
-                    // Add each item with its embedding
-                    textPromises = textItems.map((item, i) => this.addNoun(embeddings[i], item.metadata));
-                }
-                // Combine all promises
-                const batchResults = await Promise.all([
-                    ...vectorPromises,
-                    ...textPromises
-                ]);
-                // Add the results to our ids array
-                ids.push(...batchResults);
-            }
-            return ids;
+            return JSON.parse(Buffer.from(cursor, 'base64').toString());
         }
-        catch (error) {
-            console.error('Failed to add batch of items:', error);
-            throw new Error(`Failed to add batch of items: ${error}`);
+        catch {
+            return { offset: 0, timestamp: 0 };
         }
     }
     /**
-     * Add multiple vectors or data items to both local and remote databases
-     * @param items Array of items to add
-     * @param options Additional options
-     * @returns Array of IDs for the added items
+     * Internal method for direct HNSW vector search
+     * Used by TripleIntelligence to avoid circular dependencies
+     * Note: For pure metadata filtering, use metadataIndex.getIdsForFilter() directly - it's O(log n)!
+     * This method is for vector similarity search with optional metadata filtering during search
+     * @internal
      */
-    async addBatchToBoth(items, options = {}) {
-        // Check if connected to a remote server
-        if (!this.isConnectedToRemoteServer()) {
-            throw new Error('Not connected to a remote server. Call connectToRemoteServer() first.');
+    async _internalVectorSearch(queryVectorOrData, k = 10, options = {}) {
+        // Generate query vector
+        const queryVector = Array.isArray(queryVectorOrData) &&
+            typeof queryVectorOrData[0] === 'number' ?
+            queryVectorOrData :
+            await this.embed(queryVectorOrData);
+        // Apply metadata filter if provided
+        let filterFunction;
+        if (options.metadata) {
+            const matchingIdsArray = await this.metadataIndex?.getIdsForFilter(options.metadata) || [];
+            const matchingIds = new Set(matchingIdsArray);
+            filterFunction = async (id) => matchingIds.has(id);
         }
-        // Add to local with addToRemote option
-        return this.addNouns(items, { ...options, addToRemote: true });
+        // Direct HNSW search
+        const results = await this.index.search(queryVector, k, filterFunction);
+        // Get metadata for results
+        const searchResults = [];
+        for (const [id, similarity] of results) {
+            const metadata = await this.getNoun(id);
+            searchResults.push({
+                id,
+                score: similarity,
+                vector: [],
+                metadata: metadata?.metadata || {}
+            });
+        }
+        return searchResults;
     }
     /**
-     * Filter search results by service
-     * @param results Search results to filter
-     * @param service Service to filter by
-     * @returns Filtered search results
-     * @private
+     * 🎯 LEGACY: Original search implementation (kept for complex cases)
+     * This is the original search method, now used as fallback for edge cases
      */
-    filterResultsByService(results, service) {
-        if (!service)
-            return results;
-        return results.filter((result) => {
-            if (!result.metadata || typeof result.metadata !== 'object')
-                return false;
-            if (!('createdBy' in result.metadata))
-                return false;
-            const createdBy = result.metadata.createdBy;
-            if (!createdBy)
-                return false;
-            return createdBy.augmentation === service;
+    async _legacySearch(queryVectorOrData, k = 10, options = {}) {
+        const startTime = Date.now();
+        // Validate input is not null or undefined
+        if (queryVectorOrData === null || queryVectorOrData === undefined) {
+            throw new Error('Query cannot be null or undefined');
+        }
+        // Validate k parameter first, before any other logic
+        if (k <= 0 || typeof k !== 'number' || isNaN(k)) {
+            throw new Error('Parameter k must be a positive number');
+        }
+        if (!this.isInitialized) {
+            throw new Error('BrainyData must be initialized before searching. Call init() first.');
+        }
+        // Check if database is in write-only mode
+        this.checkWriteOnly();
+        // If searching for verbs directly
+        if (options.searchVerbs) {
+            const verbResults = await this.searchVerbs(queryVectorOrData, k, {
+                forceEmbed: options.forceEmbed,
+                verbTypes: options.verbTypes
+            });
+            // Convert verb results to SearchResult format
+            return verbResults.map((verb) => ({
+                id: verb.id,
+                score: verb.similarity,
+                vector: verb.embedding || [],
+                metadata: {
+                    verb: verb.verb,
+                    source: verb.source,
+                    target: verb.target,
+                    ...verb.data
+                }
+            }));
+        }
+        // If searching for nouns connected by verbs
+        if (options.searchConnectedNouns) {
+            return this.searchNounsByVerbs(queryVectorOrData, k, {
+                forceEmbed: options.forceEmbed,
+                verbTypes: options.verbTypes,
+                direction: options.verbDirection
+            });
+        }
+        // If a specific search mode is specified, use the appropriate search method
+        if (options.searchMode === 'local') {
+            return this.searchLocal(queryVectorOrData, k, options);
+        }
+        else if (options.searchMode === 'remote') {
+            return this.searchRemote(queryVectorOrData, k, options);
+        }
+        else if (options.searchMode === 'combined') {
+            return this.searchCombined(queryVectorOrData, k, options);
+        }
+        // Generate deduplication key for concurrent request handling
+        const dedupeKey = RequestDeduplicator.getSearchKey(typeof queryVectorOrData === 'string' ? queryVectorOrData : JSON.stringify(queryVectorOrData), k, options);
+        // Use augmentation system for search (includes deduplication, batching, and caching)
+        return this.augmentations.execute('search', { query: queryVectorOrData, k, options, dedupeKey }, async () => {
+            // Default behavior (backward compatible): search locally
+            try {
+                // BEST OF BOTH: Automatically exclude soft-deleted items (Neural Intelligence improvement)
+                // BUT only when there's already metadata filtering happening
+                let metadataFilter = options.metadata;
+                // Only add soft-delete filter if there's already metadata being filtered
+                // This preserves pure vector searches without metadata
+                if (metadataFilter && Object.keys(metadataFilter).length > 0) {
+                    // If no explicit deleted filter is provided, exclude soft-deleted items
+                    // Use namespaced field for O(1) performance
+                    if (!metadataFilter['_brainy.deleted'] && !metadataFilter.anyOf) {
+                        metadataFilter = {
+                            ...metadataFilter,
+                            ['_brainy.deleted']: false // O(1) positive match instead of notEquals
+                        };
+                    }
+                }
+                const hasMetadataFilter = metadataFilter && Object.keys(metadataFilter).length > 0;
+                // Check cache first (transparent to user) - but skip cache if we have metadata filters
+                if (!hasMetadataFilter) {
+                    const cacheKey = this.cache?.getCacheKey(queryVectorOrData, k, options);
+                    const cachedResults = this.cache?.get(cacheKey);
+                    if (cachedResults) {
+                        // Track cache hit in health monitor
+                        if (this.monitoring) {
+                            const latency = Date.now() - startTime;
+                            this.monitoring.recordRequest(latency, false);
+                            this.monitoring.recordCacheAccess(true);
+                        }
+                        return cachedResults;
+                    }
+                }
+                // Cache miss - perform actual search
+                const results = await this.searchLocal(queryVectorOrData, k, {
+                    ...options,
+                    metadata: metadataFilter
+                });
+                // Cache results for future queries (unless explicitly disabled or has metadata filter)
+                if (!options.skipCache && !hasMetadataFilter) {
+                    const cacheKey = this.cache?.getCacheKey(queryVectorOrData, k, options);
+                    this.cache?.set(cacheKey, results);
+                }
+                // Track successful search in health monitor
+                if (this.monitoring) {
+                    const latency = Date.now() - startTime;
+                    this.monitoring.recordRequest(latency, false);
+                    this.monitoring.recordCacheAccess(false);
+                }
+                return results;
+            }
+            catch (error) {
+                // Track error in health monitor
+                if (this.monitoring) {
+                    const latency = Date.now() - startTime;
+                    this.monitoring.recordRequest(latency, true);
+                }
+                throw error;
+            }
         });
     }
     /**
-     * Search for similar vectors within specific noun types
+     * Search with cursor-based pagination for better performance on large datasets
      * @param queryVectorOrData Query vector or data to search for
      * @param k Number of results to return
-     * @param nounTypes Array of noun types to search within, or null to search all
-     * @param options Additional options
-     * @returns Array of search results
+     * @param options Additional options including cursor for pagination
+     * @returns Paginated search results with cursor for next page
      */
     /**
-     * @deprecated Use search() with nounTypes option instead
+     * @deprecated Use search() with cursor option instead
      * @example
      * // Old way (deprecated)
-     * await brain.searchByNounTypes(query, 10, ['type1', 'type2'])
+     * await brain.searchWithCursor(query, 10, { cursor: 'abc123' })
      * // New way
-     * await brain.search(query, { limit: 10, nounTypes: ['type1', 'type2'] })
+     * await brain.search(query, { limit: 10, cursor: 'abc123' })
      */
-    async searchByNounTypes(queryVectorOrData, k = 10, nounTypes = null, options = {}) {
-        // Helper function to filter results by service
-        const filterByService = (metadata) => {
-            if (!options.service)
-                return true; // No filter, include all
-            // Check if metadata has createdBy field with matching service
-            if (!metadata || typeof metadata !== 'object')
-                return false;
-            if (!('createdBy' in metadata))
-                return false;
-            const createdBy = metadata.createdBy;
-            if (!createdBy)
-                return false;
-            return createdBy.augmentation === options.service;
-        };
-        if (!this.isInitialized) {
-            throw new Error('BrainyData must be initialized before searching. Call init() first.');
-        }
-        // Check if database is in write-only mode
-        this.checkWriteOnly();
-        try {
-            let queryVector;
-            // Check if input is already a vector
-            if (Array.isArray(queryVectorOrData) &&
-                queryVectorOrData.every((item) => typeof item === 'number') &&
-                !options.forceEmbed) {
-                // Input is already a vector
-                queryVector = queryVectorOrData;
+    async searchWithCursor(queryVectorOrData, k = 10, options = {}) {
+        // For cursor-based search, we need to fetch more results and filter
+        const searchK = options.cursor ? k + 20 : k; // Get extra results for filtering
+        // Perform regular search
+        const { cursor, ...searchOptions } = options;
+        const allResults = await this.search(queryVectorOrData, {
+            limit: searchK,
+            nounTypes: searchOptions.nounTypes,
+            metadata: searchOptions.filter
+        });
+        let results = allResults;
+        let startIndex = 0;
+        // If cursor provided, find starting position
+        if (options.cursor) {
+            startIndex = allResults.findIndex((r) => r.id === options.cursor.lastId &&
+                Math.abs(r.score - options.cursor.lastScore) < 0.0001);
+            if (startIndex >= 0) {
+                startIndex += 1; // Start after the cursor position
+                results = allResults.slice(startIndex, startIndex + k);
             }
             else {
-                // Input needs to be vectorized
-                try {
-                    queryVector = await this.embeddingFunction(queryVectorOrData);
-                }
-                catch (embedError) {
-                    throw new Error(`Failed to vectorize query data: ${embedError}`);
-                }
-            }
-            // Check if query vector is defined
-            if (!queryVector) {
-                throw new Error('Query vector is undefined or null');
-            }
-            // Check if query vector dimensions match the expected dimensions
-            if (queryVector.length !== this._dimensions) {
-                throw new Error(`Query vector dimension mismatch: expected ${this._dimensions}, got ${queryVector.length}`);
-            }
-            // If no noun types specified, search all nouns
-            if (!nounTypes || nounTypes.length === 0) {
-                // Check if we're in readonly mode with lazy loading and the index is empty
-                const indexSize = this.index.getNouns().size;
-                if (this.readOnly && this.lazyLoadInReadOnlyMode && indexSize === 0) {
-                    if (this.loggingConfig?.verbose) {
-                        console.log('Lazy loading mode: Index is empty, loading nodes for search...');
-                    }
-                    // In lazy loading mode, we need to load some nodes to search
-                    // Instead of loading all nodes, we'll load a subset of nodes
-                    // Load a limited number of nodes from storage using pagination
-                    const result = await this.storage.getNouns({
-                        pagination: { offset: 0, limit: k * 10 } // Get 10x more nodes than needed
-                    });
-                    const limitedNouns = result.items;
-                    // Add these nodes to the index
-                    for (const node of limitedNouns) {
-                        // Check if the vector dimensions match the expected dimensions
-                        if (node.vector.length !== this._dimensions) {
-                            console.warn(`Skipping node ${node.id} due to dimension mismatch: expected ${this._dimensions}, got ${node.vector.length}`);
-                            continue;
-                        }
-                        // Add to index
-                        await this.index.addItem({
-                            id: node.id,
-                            vector: node.vector
-                        });
-                    }
-                    if (this.loggingConfig?.verbose) {
-                        console.log(`Lazy loading mode: Added ${limitedNouns.length} nodes to index for search`);
-                    }
-                }
-                // Create filter function for HNSW search with metadata index optimization
-                const hasMetadataFilter = options.metadata && Object.keys(options.metadata).length > 0;
-                const hasServiceFilter = !!options.service;
-                let filterFunction;
-                let preFilteredIds;
-                // Use metadata index for pre-filtering if available
-                if (hasMetadataFilter && this.metadataIndex) {
-                    try {
-                        // Ensure metadata index is up to date
-                        await this.metadataIndex?.flush?.();
-                        // Get candidate IDs from metadata index
-                        const candidateIds = await this.metadataIndex?.getIdsForFilter?.(options.metadata) || [];
-                        if (candidateIds.length > 0) {
-                            preFilteredIds = new Set(candidateIds);
-                            // Create a simple filter function that just checks the pre-filtered set
-                            filterFunction = async (id) => {
-                                if (!preFilteredIds.has(id))
-                                    return false;
-                                // Still apply service filter if needed
-                                if (hasServiceFilter) {
-                                    const metadata = await this.storage.getMetadata(id);
-                                    const noun = this.index.getNouns().get(id);
-                                    if (!noun || !metadata)
-                                        return false;
-                                    const result = { id, score: 0, vector: noun.vector, metadata };
-                                    return this.filterResultsByService([result], options.service).length > 0;
-                                }
-                                return true;
-                            };
-                        }
-                        else {
-                            // No items match the metadata criteria, return empty results immediately
-                            return [];
-                        }
-                    }
-                    catch (indexError) {
-                        console.warn('Metadata index error, falling back to full filtering:', indexError);
-                        // Fall back to full metadata filtering below
-                    }
-                }
-                // Fallback to full metadata filtering if index wasn't used
-                if (!filterFunction && (hasMetadataFilter || hasServiceFilter)) {
-                    filterFunction = async (id) => {
-                        // Get metadata for filtering
-                        let metadata = await this.storage.getMetadata(id);
-                        if (metadata === null) {
-                            metadata = {};
-                        }
-                        // Apply metadata filter
-                        if (hasMetadataFilter) {
-                            const matches = matchesMetadataFilter(metadata, options.metadata);
-                            if (!matches) {
-                                return false;
-                            }
-                        }
-                        // Apply service filter
-                        if (hasServiceFilter) {
-                            const noun = this.index.getNouns().get(id);
-                            if (!noun)
-                                return false;
-                            const result = { id, score: 0, vector: noun.vector, metadata };
-                            if (!this.filterResultsByService([result], options.service).length) {
-                                return false;
-                            }
-                        }
-                        return true;
-                    };
-                }
-                // When using offset, we need to fetch more results and then slice
-                const offset = options.offset || 0;
-                const totalNeeded = k + offset;
-                // Search in the index with filter
-                const results = await this.index.search(queryVector, totalNeeded, filterFunction);
-                // Skip the offset number of results
-                const paginatedResults = results.slice(offset, offset + k);
-                // Get metadata for each result
-                const searchResults = [];
-                for (const [id, score] of paginatedResults) {
-                    const noun = this.index.getNouns().get(id);
-                    if (!noun) {
-                        continue;
-                    }
-                    let metadata = await this.storage.getMetadata(id);
-                    // Initialize metadata to an empty object if it's null
-                    if (metadata === null) {
-                        metadata = {};
-                    }
-                    // Preserve original metadata without overwriting user's custom fields
-                    // The search result already has Brainy's UUID in the main 'id' field
-                    searchResults.push({
-                        id,
-                        score: 1 - score, // Convert distance to similarity (higher = more similar)
-                        vector: noun.vector,
-                        metadata: metadata
-                    });
-                }
-                return searchResults;
-            }
-            else {
-                // Get nouns for each noun type in parallel
-                const nounPromises = nounTypes.map((nounType) => this.storage.getNounsByNounType(nounType));
-                const nounArrays = await Promise.all(nounPromises);
-                // Combine all nouns
-                const nouns = [];
-                for (const nounArray of nounArrays) {
-                    nouns.push(...nounArray);
-                }
-                // Calculate distances for each noun
-                const results = [];
-                for (const noun of nouns) {
-                    const distance = this.index.getDistanceFunction()(queryVector, noun.vector);
-                    results.push([noun.id, distance]);
-                }
-                // Sort by distance (ascending)
-                results.sort((a, b) => a[1] - b[1]);
-                // Apply offset and take k results
-                const offset = options.offset || 0;
-                const topResults = results.slice(offset, offset + k);
-                // Get metadata for each result
-                const searchResults = [];
-                for (const [id, score] of topResults) {
-                    const noun = nouns.find((n) => n.id === id);
-                    if (!noun) {
-                        continue;
-                    }
-                    let metadata = await this.storage.getMetadata(id);
-                    // Initialize metadata to an empty object if it's null
-                    if (metadata === null) {
-                        metadata = {};
-                    }
-                    // Preserve original metadata without overwriting user's custom fields
-                    // The search result already has Brainy's UUID in the main 'id' field
-                    searchResults.push({
-                        id,
-                        score: 1 - score, // Convert distance to similarity (higher = more similar)
-                        vector: noun.vector,
-                        metadata: metadata
-                    });
-                }
-                // Results are already filtered, just return them
-                return searchResults;
+                // Cursor not found, might be stale - return from beginning
+                results = allResults.slice(0, k);
+                startIndex = 0;
             }
         }
-        catch (error) {
-            console.error('Failed to search vectors by noun types:', error);
-            throw new Error(`Failed to search vectors by noun types: ${error}`);
+        else {
+            results = allResults.slice(0, k);
+        }
+        // Create cursor for next page
+        let nextCursor;
+        const hasMoreResults = startIndex + results.length < allResults.length ||
+            allResults.length >= searchK;
+        if (results.length > 0 && hasMoreResults) {
+            const lastResult = results[results.length - 1];
+            nextCursor = {
+                lastId: lastResult.id,
+                lastScore: lastResult.score,
+                position: startIndex + results.length
+            };
         }
+        return {
+            results,
+            cursor: nextCursor,
+            hasMore: !!nextCursor,
+            totalEstimate: allResults.length > searchK ? undefined : allResults.length
+        };
     }
     /**
-     * Search for similar vectors
+     * Search the local database for similar vectors
      * @param queryVectorOrData Query vector or data to search for
      * @param k Number of results to return
      * @param options Additional options
      * @returns Array of search results
      */
-    /**
-     * 🔍 SIMPLE VECTOR SEARCH - Clean wrapper around find() for pure vector search
-     *
-     * @param queryVectorOrData Vector or text to search for
-     * @param k Number of results to return
-     * @param options Simple search options (metadata filters only)
-     * @returns Vector search results
-     */
-    /**
-     * 🔍 Simple Vector Similarity Search - Clean wrapper around find()
-     *
-     * search(query) = find({like: query}) - Pure vector similarity search
-     *
-     * @param queryVectorOrData - Query string, vector, or object to search with
-     * @param options - Search options for filtering and pagination
-     * @returns Array of search results with scores and metadata
-     *
-     * @example
-     * // Simple vector search
-     * await brain.search('machine learning')
-     *
-     * // With filters and pagination
-     * await brain.search('AI', {
-     *   limit: 20,
-     *   metadata: { type: 'article' },
-     *   nounTypes: ['document']
-     * })
-     */
-    async search(queryVectorOrData, options = {}) {
-        // Build metadata filter from options
-        const metadataFilter = { ...options.metadata };
-        // Add noun type filtering
-        if (options.nounTypes && options.nounTypes.length > 0) {
-            metadataFilter.nounType = { in: options.nounTypes };
-        }
-        // Add item ID filtering
-        if (options.itemIds && options.itemIds.length > 0) {
-            metadataFilter.id = { in: options.itemIds };
+    async searchLocal(queryVectorOrData, k = 10, options = {}) {
+        if (!this.isInitialized) {
+            throw new Error('BrainyData must be initialized before searching. Call init() first.');
         }
-        // Build simple TripleQuery for vector similarity
-        const tripleQuery = {
-            like: queryVectorOrData
-        };
-        // Add metadata filter if we have conditions
-        if (Object.keys(metadataFilter).length > 0) {
-            tripleQuery.where = metadataFilter;
+        // Check if database is in write-only mode
+        this.checkWriteOnly();
+        // Process the query input for vectorization
+        let queryToUse = queryVectorOrData;
+        // Handle string queries
+        if (typeof queryVectorOrData === 'string' && !options.forceEmbed) {
+            queryToUse = await this.embed(queryVectorOrData);
+            options.forceEmbed = false; // Already embedded, don't force again
         }
-        // Extract find() options
-        const findOptions = {
-            limit: options.limit,
-            offset: options.offset,
-            cursor: options.cursor,
-            excludeDeleted: options.excludeDeleted,
-            timeout: options.timeout
-        };
-        // Call find() with structured query - this is the key simplification!
-        let results = await this.find(tripleQuery, findOptions);
-        // Apply threshold filtering if specified
-        if (options.threshold !== undefined) {
-            results = results.filter(r => (r.fusionScore || r.score || 0) >= options.threshold);
+        // Handle JSON object queries with special processing
+        else if (typeof queryVectorOrData === 'object' &&
+            queryVectorOrData !== null &&
+            !Array.isArray(queryVectorOrData) &&
+            !options.forceEmbed) {
+            // If searching within a specific field
+            if (options.searchField) {
+                // Extract text from the specific field
+                const fieldText = extractFieldFromJson(queryVectorOrData, options.searchField);
+                if (fieldText) {
+                    queryToUse = await this.embeddingFunction(fieldText);
+                    options.forceEmbed = false; // Already embedded, don't force again
+                }
+            }
+            // Otherwise process the entire object with priority fields
+            else {
+                const preparedText = prepareJsonForVectorization(queryVectorOrData, {
+                    priorityFields: options.priorityFields || [
+                        'name',
+                        'title',
+                        'company',
+                        'organization',
+                        'description',
+                        'summary'
+                    ]
+                });
+                queryToUse = await this.embeddingFunction(preparedText);
+                options.forceEmbed = false; // Already embedded, don't force again
+            }
         }
-        // Convert to SearchResult format
-        return results.map(r => ({
-            ...r,
-            score: r.fusionScore || r.score || 0
-        }));
-        return results;
+        // If noun types are specified, use searchByNounTypes
+        let searchResults;
+        if (options.nounTypes && options.nounTypes.length > 0) {
+            searchResults = await this.searchByNounTypes(queryToUse, k, options.nounTypes, {
+                forceEmbed: options.forceEmbed,
+                service: options.service,
+                metadata: options.metadata,
+                offset: options.offset
+            });
+        }
+        else {
+            // Otherwise, search all GraphNouns
+            searchResults = await this.searchByNounTypes(queryToUse, k, null, {
+                forceEmbed: options.forceEmbed,
+                service: options.service,
+                metadata: options.metadata,
+                offset: options.offset
+            });
+        }
+        // Filter out placeholder nouns and deleted items from search results
+        searchResults = searchResults.filter((result) => {
+            if (result.metadata && typeof result.metadata === 'object') {
+                const metadata = result.metadata;
+                // Exclude deleted items from search results (soft delete)
+                // Check namespaced field
+                if (metadata._brainy?.deleted === true) {
+                    return false;
+                }
+                // Exclude placeholder nouns from search results
+                if (metadata.isPlaceholder) {
+                    return false;
+                }
+                // Apply domain filter if specified
+                if (options.filter?.domain) {
+                    if (metadata.domain !== options.filter.domain) {
+                        return false;
+                    }
+                }
+            }
+            return true;
+        });
+        // If includeVerbs is true, retrieve associated GraphVerbs for each result
+        if (options.includeVerbs && this.storage) {
+            for (const result of searchResults) {
+                try {
+                    // Get outgoing verbs for this noun
+                    const outgoingVerbs = await this.storage.getVerbsBySource(result.id);
+                    // Get incoming verbs for this noun
+                    const incomingVerbs = await this.storage.getVerbsByTarget(result.id);
+                    // Combine all verbs
+                    const allVerbs = [...outgoingVerbs, ...incomingVerbs];
+                    // Add verbs to the result metadata
+                    if (!result.metadata) {
+                        result.metadata = {};
+                    }
+                    // Add the verbs to the metadata
+                    ;
+                    result.metadata.associatedVerbs = allVerbs;
+                }
+                catch (error) {
+                    console.warn(`Failed to retrieve verbs for noun ${result.id}:`, error);
+                }
+            }
+        }
+        return searchResults;
     }
     /**
-     * Helper method to encode cursor for pagination
-     * @internal
+     * Find entities similar to a given entity ID
+     * @param id ID of the entity to find similar entities for
+     * @param options Additional options
+     * @returns Array of search results with similarity scores
      */
-    encodeCursor(data) {
-        return Buffer.from(JSON.stringify(data)).toString('base64');
+    async findSimilar(id, options = {}) {
+        await this.ensureInitialized();
+        // Get the entity by ID
+        const entity = await this.getNoun(id);
+        if (!entity) {
+            throw new Error(`Entity with ID ${id} not found`);
+        }
+        // If relationType is specified, directly get related entities by that type
+        if (options.relationType) {
+            // Get all verbs (relationships) from the source entity
+            const outgoingVerbs = await this.storage.getVerbsBySource(id);
+            // Filter to only include verbs of the specified type
+            const verbsOfType = outgoingVerbs.filter((verb) => verb.type === options.relationType);
+            // Get the target IDs
+            const targetIds = verbsOfType.map((verb) => verb.target);
+            // Get the actual entities for these IDs
+            const results = [];
+            for (const targetId of targetIds) {
+                // Skip undefined targetIds
+                if (typeof targetId !== 'string')
+                    continue;
+                const targetEntity = await this.getNoun(targetId);
+                if (targetEntity) {
+                    results.push({
+                        id: targetId,
+                        score: 1.0, // Default similarity score
+                        vector: targetEntity.vector,
+                        metadata: targetEntity.metadata
+                    });
+                }
+            }
+            // Return the results, limited to the requested number
+            return results.slice(0, options.limit || 10);
+        }
+        // If no relationType is specified, use the original vector similarity search
+        const k = (options.limit || 10) + 1; // Add 1 to account for the original entity
+        const searchResults = await this.search(entity.vector, {
+            limit: k,
+            excludeDeleted: false,
+            nounTypes: options.nounTypes
+        });
+        // Filter out the original entity and limit to the requested number
+        return searchResults
+            .filter((result) => result.id !== id)
+            .slice(0, options.limit || 10);
     }
     /**
-     * Helper method to decode cursor for pagination
-     * @internal
+     * Get a vector by ID
      */
-    decodeCursor(cursor) {
+    // Legacy get() method removed - use getNoun() instead
+    /**
+     * Check if a document with the given ID exists
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param id The ID to check for existence
+     * @returns Promise<boolean> True if the document exists, false otherwise
+     */
+    async has(id) {
+        if (id === null || id === undefined) {
+            throw new Error('ID cannot be null or undefined');
+        }
+        await this.ensureInitialized();
+        // This is a direct storage operation - check if allowed in write-only mode
+        if (this.writeOnly && !this.allowDirectReads) {
+            throw new Error('Cannot perform has() operation: database is in write-only mode. Enable allowDirectReads for direct storage operations.');
+        }
         try {
-            return JSON.parse(Buffer.from(cursor, 'base64').toString());
+            // Always query storage directly for existence check
+            const noun = await this.storage.getNoun(id);
+            return noun !== null;
         }
-        catch {
-            return { offset: 0, timestamp: 0 };
+        catch (error) {
+            // If storage lookup fails, the item doesn't exist
+            return false;
         }
     }
     /**
-     * Internal method for direct HNSW vector search
-     * Used by TripleIntelligence to avoid circular dependencies
-     * Note: For pure metadata filtering, use metadataIndex.getIdsForFilter() directly - it's O(log n)!
-     * This method is for vector similarity search with optional metadata filtering during search
-     * @internal
+     * Check if a document with the given ID exists (alias for has)
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param id The ID to check for existence
+     * @returns Promise<boolean> True if the document exists, false otherwise
      */
-    async _internalVectorSearch(queryVectorOrData, k = 10, options = {}) {
-        // Generate query vector
-        const queryVector = Array.isArray(queryVectorOrData) &&
-            typeof queryVectorOrData[0] === 'number' ?
-            queryVectorOrData :
-            await this.embed(queryVectorOrData);
-        // Apply metadata filter if provided
-        let filterFunction;
-        if (options.metadata) {
-            const matchingIdsArray = await this.metadataIndex?.getIdsForFilter(options.metadata) || [];
-            const matchingIds = new Set(matchingIdsArray);
-            filterFunction = async (id) => matchingIds.has(id);
-        }
-        // Direct HNSW search
-        const results = await this.index.search(queryVector, k, filterFunction);
-        // Get metadata for results
-        const searchResults = [];
-        for (const [id, similarity] of results) {
-            const metadata = await this.getNoun(id);
-            searchResults.push({
-                id,
-                score: similarity,
-                vector: [],
-                metadata: metadata?.metadata || {}
-            });
-        }
-        return searchResults;
-    }
     /**
-     * 🎯 LEGACY: Original search implementation (kept for complex cases)
-     * This is the original search method, now used as fallback for edge cases
+     * Check if a noun exists
+     * @param id The noun ID
+     * @returns True if exists
      */
-    async _legacySearch(queryVectorOrData, k = 10, options = {}) {
-        const startTime = Date.now();
-        // Validate input is not null or undefined
-        if (queryVectorOrData === null || queryVectorOrData === undefined) {
-            throw new Error('Query cannot be null or undefined');
-        }
-        // Validate k parameter first, before any other logic
-        if (k <= 0 || typeof k !== 'number' || isNaN(k)) {
-            throw new Error('Parameter k must be a positive number');
-        }
-        if (!this.isInitialized) {
-            throw new Error('BrainyData must be initialized before searching. Call init() first.');
-        }
-        // Check if database is in write-only mode
-        this.checkWriteOnly();
-        // If searching for verbs directly
-        if (options.searchVerbs) {
-            const verbResults = await this.searchVerbs(queryVectorOrData, k, {
-                forceEmbed: options.forceEmbed,
-                verbTypes: options.verbTypes
-            });
-            // Convert verb results to SearchResult format
-            return verbResults.map((verb) => ({
-                id: verb.id,
-                score: verb.similarity,
-                vector: verb.embedding || [],
-                metadata: {
-                    verb: verb.verb,
-                    source: verb.source,
-                    target: verb.target,
-                    ...verb.data
-                }
-            }));
-        }
-        // If searching for nouns connected by verbs
-        if (options.searchConnectedNouns) {
-            return this.searchNounsByVerbs(queryVectorOrData, k, {
-                forceEmbed: options.forceEmbed,
-                verbTypes: options.verbTypes,
-                direction: options.verbDirection
-            });
-        }
-        // If a specific search mode is specified, use the appropriate search method
-        if (options.searchMode === 'local') {
-            return this.searchLocal(queryVectorOrData, k, options);
-        }
-        else if (options.searchMode === 'remote') {
-            return this.searchRemote(queryVectorOrData, k, options);
-        }
-        else if (options.searchMode === 'combined') {
-            return this.searchCombined(queryVectorOrData, k, options);
-        }
-        // Generate deduplication key for concurrent request handling
-        const dedupeKey = RequestDeduplicator.getSearchKey(typeof queryVectorOrData === 'string' ? queryVectorOrData : JSON.stringify(queryVectorOrData), k, options);
-        // Use augmentation system for search (includes deduplication, batching, and caching)
-        return this.augmentations.execute('search', { query: queryVectorOrData, k, options, dedupeKey }, async () => {
-            // Default behavior (backward compatible): search locally
-            try {
-                // BEST OF BOTH: Automatically exclude soft-deleted items (Neural Intelligence improvement)
-                // BUT only when there's already metadata filtering happening
-                let metadataFilter = options.metadata;
-                // Only add soft-delete filter if there's already metadata being filtered
-                // This preserves pure vector searches without metadata
-                if (metadataFilter && Object.keys(metadataFilter).length > 0) {
-                    // If no explicit deleted filter is provided, exclude soft-deleted items
-                    // Use namespaced field for O(1) performance
-                    if (!metadataFilter['_brainy.deleted'] && !metadataFilter.anyOf) {
-                        metadataFilter = {
-                            ...metadataFilter,
-                            ['_brainy.deleted']: false // O(1) positive match instead of notEquals
-                        };
-                    }
-                }
-                const hasMetadataFilter = metadataFilter && Object.keys(metadataFilter).length > 0;
-                // Check cache first (transparent to user) - but skip cache if we have metadata filters
-                if (!hasMetadataFilter) {
-                    const cacheKey = this.cache?.getCacheKey(queryVectorOrData, k, options);
-                    const cachedResults = this.cache?.get(cacheKey);
-                    if (cachedResults) {
-                        // Track cache hit in health monitor
-                        if (this.monitoring) {
-                            const latency = Date.now() - startTime;
-                            this.monitoring.recordRequest(latency, false);
-                            this.monitoring.recordCacheAccess(true);
-                        }
-                        return cachedResults;
-                    }
-                }
-                // Cache miss - perform actual search
-                const results = await this.searchLocal(queryVectorOrData, k, {
-                    ...options,
-                    metadata: metadataFilter
-                });
-                // Cache results for future queries (unless explicitly disabled or has metadata filter)
-                if (!options.skipCache && !hasMetadataFilter) {
-                    const cacheKey = this.cache?.getCacheKey(queryVectorOrData, k, options);
-                    this.cache?.set(cacheKey, results);
-                }
-                // Track successful search in health monitor
-                if (this.monitoring) {
-                    const latency = Date.now() - startTime;
-                    this.monitoring.recordRequest(latency, false);
-                    this.monitoring.recordCacheAccess(false);
-                }
-                return results;
-            }
-            catch (error) {
-                // Track error in health monitor
-                if (this.monitoring) {
-                    const latency = Date.now() - startTime;
-                    this.monitoring.recordRequest(latency, true);
-                }
-                throw error;
-            }
-        });
+    async hasNoun(id) {
+        return this.hasNoun(id);
     }
     /**
-     * Search with cursor-based pagination for better performance on large datasets
-     * @param queryVectorOrData Query vector or data to search for
-     * @param k Number of results to return
-     * @param options Additional options including cursor for pagination
-     * @returns Paginated search results with cursor for next page
+     * Get metadata for a document by ID
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param id The ID of the document
+     * @returns Promise<T | null> The metadata object or null if not found
      */
+    // Legacy getMetadata() method removed - use getNounMetadata() instead
     /**
-     * @deprecated Use search() with cursor option instead
+     * Get multiple documents by their IDs
+     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
+     * @param ids Array of IDs to retrieve
+     * @returns Promise<Array<VectorDocument<T> | null>> Array of documents (null for missing IDs)
+     */
+    /**
+     * Get multiple nouns - by IDs, filters, or pagination
+     * @param idsOrOptions Array of IDs or query options
+     * @returns Array of noun documents
+     *
      * @example
-     * // Old way (deprecated)
-     * await brain.searchWithCursor(query, 10, { cursor: 'abc123' })
-     * // New way
-     * await brain.search(query, { limit: 10, cursor: 'abc123' })
+     * // Get by IDs
+     * await brain.getNouns(['id1', 'id2'])
+     *
+     * // Get with filters
+     * await brain.getNouns({
+     *   filter: { type: 'article' },
+     *   limit: 10
+     * })
+     *
+     * // Get with pagination
+     * await brain.getNouns({
+     *   offset: 20,
+     *   limit: 10
+     * })
      */
-    async searchWithCursor(queryVectorOrData, k = 10, options = {}) {
-        // For cursor-based search, we need to fetch more results and filter
-        const searchK = options.cursor ? k + 20 : k; // Get extra results for filtering
-        // Perform regular search
-        const { cursor, ...searchOptions } = options;
-        const allResults = await this.search(queryVectorOrData, {
-            limit: searchK,
-            nounTypes: searchOptions.nounTypes,
-            metadata: searchOptions.filter
-        });
-        let results = allResults;
-        let startIndex = 0;
-        // If cursor provided, find starting position
-        if (options.cursor) {
-            startIndex = allResults.findIndex((r) => r.id === options.cursor.lastId &&
-                Math.abs(r.score - options.cursor.lastScore) < 0.0001);
-            if (startIndex >= 0) {
-                startIndex += 1; // Start after the cursor position
-                results = allResults.slice(startIndex, startIndex + k);
-            }
-            else {
-                // Cursor not found, might be stale - return from beginning
-                results = allResults.slice(0, k);
-                startIndex = 0;
-            }
-        }
-        else {
-            results = allResults.slice(0, k);
+    async getNouns(idsOrOptions) {
+        // Handle array of IDs
+        if (Array.isArray(idsOrOptions)) {
+            return this.getNounsByIds(idsOrOptions);
         }
-        // Create cursor for next page
-        let nextCursor;
-        const hasMoreResults = startIndex + results.length < allResults.length ||
-            allResults.length >= searchK;
-        if (results.length > 0 && hasMoreResults) {
-            const lastResult = results[results.length - 1];
-            nextCursor = {
-                lastId: lastResult.id,
-                lastScore: lastResult.score,
-                position: startIndex + results.length
-            };
+        // Handle options object
+        const options = idsOrOptions || {};
+        // If ids are provided in options, get by IDs
+        if (options.ids) {
+            return this.getNounsByIds(options.ids);
         }
-        return {
-            results,
-            cursor: nextCursor,
-            hasMore: !!nextCursor,
-            totalEstimate: allResults.length > searchK ? undefined : allResults.length
-        };
+        // Otherwise, do a filtered/paginated query and extract items
+        const result = await this.queryNounsByFilter(options);
+        return result.items;
     }
     /**
-     * Search the local database for similar vectors
-     * @param queryVectorOrData Query vector or data to search for
-     * @param k Number of results to return
-     * @param options Additional options
-     * @returns Array of search results
+     * Internal: Get nouns by IDs
      */
-    async searchLocal(queryVectorOrData, k = 10, options = {}) {
-        if (!this.isInitialized) {
-            throw new Error('BrainyData must be initialized before searching. Call init() first.');
+    async getNounsByIds(ids) {
+        if (!Array.isArray(ids)) {
+            throw new Error('IDs must be provided as an array');
         }
-        // Check if database is in write-only mode
-        this.checkWriteOnly();
-        // Process the query input for vectorization
-        let queryToUse = queryVectorOrData;
-        // Handle string queries
-        if (typeof queryVectorOrData === 'string' && !options.forceEmbed) {
-            queryToUse = await this.embed(queryVectorOrData);
-            options.forceEmbed = false; // Already embedded, don't force again
+        await this.ensureInitialized();
+        // This is a direct storage operation - check if allowed in write-only mode
+        if (this.writeOnly && !this.allowDirectReads) {
+            throw new Error('Cannot perform getBatch() operation: database is in write-only mode. Enable allowDirectReads for direct storage operations.');
         }
-        // Handle JSON object queries with special processing
-        else if (typeof queryVectorOrData === 'object' &&
-            queryVectorOrData !== null &&
-            !Array.isArray(queryVectorOrData) &&
-            !options.forceEmbed) {
-            // If searching within a specific field
-            if (options.searchField) {
-                // Extract text from the specific field
-                const fieldText = extractFieldFromJson(queryVectorOrData, options.searchField);
-                if (fieldText) {
-                    queryToUse = await this.embeddingFunction(fieldText);
-                    options.forceEmbed = false; // Already embedded, don't force again
-                }
-            }
-            // Otherwise process the entire object with priority fields
-            else {
-                const preparedText = prepareJsonForVectorization(queryVectorOrData, {
-                    priorityFields: options.priorityFields || [
-                        'name',
-                        'title',
-                        'company',
-                        'organization',
-                        'description',
-                        'summary'
-                    ]
-                });
-                queryToUse = await this.embeddingFunction(preparedText);
-                options.forceEmbed = false; // Already embedded, don't force again
-            }
-        }
-        // If noun types are specified, use searchByNounTypes
-        let searchResults;
-        if (options.nounTypes && options.nounTypes.length > 0) {
-            searchResults = await this.searchByNounTypes(queryToUse, k, options.nounTypes, {
-                forceEmbed: options.forceEmbed,
-                service: options.service,
-                metadata: options.metadata,
-                offset: options.offset
-            });
-        }
-        else {
-            // Otherwise, search all GraphNouns
-            searchResults = await this.searchByNounTypes(queryToUse, k, null, {
-                forceEmbed: options.forceEmbed,
-                service: options.service,
-                metadata: options.metadata,
-                offset: options.offset
-            });
-        }
-        // Filter out placeholder nouns and deleted items from search results
-        searchResults = searchResults.filter((result) => {
-            if (result.metadata && typeof result.metadata === 'object') {
-                const metadata = result.metadata;
-                // Exclude deleted items from search results (soft delete)
-                // Check namespaced field
-                if (metadata._brainy?.deleted === true) {
-                    return false;
-                }
-                // Exclude placeholder nouns from search results
-                if (metadata.isPlaceholder) {
-                    return false;
-                }
-                // Apply domain filter if specified
-                if (options.filter?.domain) {
-                    if (metadata.domain !== options.filter.domain) {
-                        return false;
-                    }
-                }
-            }
-            return true;
-        });
-        // If includeVerbs is true, retrieve associated GraphVerbs for each result
-        if (options.includeVerbs && this.storage) {
-            for (const result of searchResults) {
-                try {
-                    // Get outgoing verbs for this noun
-                    const outgoingVerbs = await this.storage.getVerbsBySource(result.id);
-                    // Get incoming verbs for this noun
-                    const incomingVerbs = await this.storage.getVerbsByTarget(result.id);
-                    // Combine all verbs
-                    const allVerbs = [...outgoingVerbs, ...incomingVerbs];
-                    // Add verbs to the result metadata
-                    if (!result.metadata) {
-                        result.metadata = {};
-                    }
-                    // Add the verbs to the metadata
-                    ;
-                    result.metadata.associatedVerbs = allVerbs;
-                }
-                catch (error) {
-                    console.warn(`Failed to retrieve verbs for noun ${result.id}:`, error);
-                }
-            }
-        }
-        return searchResults;
-    }
-    /**
-     * Find entities similar to a given entity ID
-     * @param id ID of the entity to find similar entities for
-     * @param options Additional options
-     * @returns Array of search results with similarity scores
-     */
-    async findSimilar(id, options = {}) {
-        await this.ensureInitialized();
-        // Get the entity by ID
-        const entity = await this.getNoun(id);
-        if (!entity) {
-            throw new Error(`Entity with ID ${id} not found`);
-        }
-        // If relationType is specified, directly get related entities by that type
-        if (options.relationType) {
-            // Get all verbs (relationships) from the source entity
-            const outgoingVerbs = await this.storage.getVerbsBySource(id);
-            // Filter to only include verbs of the specified type
-            const verbsOfType = outgoingVerbs.filter((verb) => verb.type === options.relationType);
-            // Get the target IDs
-            const targetIds = verbsOfType.map((verb) => verb.target);
-            // Get the actual entities for these IDs
-            const results = [];
-            for (const targetId of targetIds) {
-                // Skip undefined targetIds
-                if (typeof targetId !== 'string')
-                    continue;
-                const targetEntity = await this.getNoun(targetId);
-                if (targetEntity) {
-                    results.push({
-                        id: targetId,
-                        score: 1.0, // Default similarity score
-                        vector: targetEntity.vector,
-                        metadata: targetEntity.metadata
-                    });
-                }
-            }
-            // Return the results, limited to the requested number
-            return results.slice(0, options.limit || 10);
-        }
-        // If no relationType is specified, use the original vector similarity search
-        const k = (options.limit || 10) + 1; // Add 1 to account for the original entity
-        const searchResults = await this.search(entity.vector, {
-            limit: k,
-            excludeDeleted: false,
-            nounTypes: options.nounTypes
-        });
-        // Filter out the original entity and limit to the requested number
-        return searchResults
-            .filter((result) => result.id !== id)
-            .slice(0, options.limit || 10);
-    }
-    /**
-     * Get a vector by ID
-     */
-    // Legacy get() method removed - use getNoun() instead
-    /**
-     * Check if a document with the given ID exists
-     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
-     * @param id The ID to check for existence
-     * @returns Promise<boolean> True if the document exists, false otherwise
-     */
-    async has(id) {
-        if (id === null || id === undefined) {
-            throw new Error('ID cannot be null or undefined');
-        }
-        await this.ensureInitialized();
-        // This is a direct storage operation - check if allowed in write-only mode
-        if (this.writeOnly && !this.allowDirectReads) {
-            throw new Error('Cannot perform has() operation: database is in write-only mode. Enable allowDirectReads for direct storage operations.');
-        }
-        try {
-            // Always query storage directly for existence check
-            const noun = await this.storage.getNoun(id);
-            return noun !== null;
-        }
-        catch (error) {
-            // If storage lookup fails, the item doesn't exist
-            return false;
-        }
-    }
-    /**
-     * Check if a document with the given ID exists (alias for has)
-     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
-     * @param id The ID to check for existence
-     * @returns Promise<boolean> True if the document exists, false otherwise
-     */
-    /**
-     * Check if a noun exists
-     * @param id The noun ID
-     * @returns True if exists
-     */
-    async hasNoun(id) {
-        return this.hasNoun(id);
-    }
-    /**
-     * Get metadata for a document by ID
-     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
-     * @param id The ID of the document
-     * @returns Promise<T | null> The metadata object or null if not found
-     */
-    // Legacy getMetadata() method removed - use getNounMetadata() instead
-    /**
-     * Get multiple documents by their IDs
-     * This is a direct storage operation that works in write-only mode when allowDirectReads is enabled
-     * @param ids Array of IDs to retrieve
-     * @returns Promise<Array<VectorDocument<T> | null>> Array of documents (null for missing IDs)
-     */
-    /**
-     * Get multiple nouns - by IDs, filters, or pagination
-     * @param idsOrOptions Array of IDs or query options
-     * @returns Array of noun documents
-     *
-     * @example
-     * // Get by IDs
-     * await brain.getNouns(['id1', 'id2'])
-     *
-     * // Get with filters
-     * await brain.getNouns({
-     *   filter: { type: 'article' },
-     *   limit: 10
-     * })
-     *
-     * // Get with pagination
-     * await brain.getNouns({
-     *   offset: 20,
-     *   limit: 10
-     * })
-     */
-    async getNouns(idsOrOptions) {
-        // Handle array of IDs
-        if (Array.isArray(idsOrOptions)) {
-            return this.getNounsByIds(idsOrOptions);
-        }
-        // Handle options object
-        const options = idsOrOptions || {};
-        // If ids are provided in options, get by IDs
-        if (options.ids) {
-            return this.getNounsByIds(options.ids);
-        }
-        // Otherwise, do a filtered/paginated query and extract items
-        const result = await this.queryNounsByFilter(options);
-        return result.items;
-    }
-    /**
-     * Internal: Get nouns by IDs
-     */
-    async getNounsByIds(ids) {
-        if (!Array.isArray(ids)) {
-            throw new Error('IDs must be provided as an array');
-        }
-        await this.ensureInitialized();
-        // This is a direct storage operation - check if allowed in write-only mode
-        if (this.writeOnly && !this.allowDirectReads) {
-            throw new Error('Cannot perform getBatch() operation: database is in write-only mode. Enable allowDirectReads for direct storage operations.');
-        }
-        const results = [];
-        for (const id of ids) {
-            if (id === null || id === undefined) {
-                results.push(null);
-                continue;
+        const results = [];
+        for (const id of ids) {
+            if (id === null || id === undefined) {
+                results.push(null);
+                continue;
             }
             try {
                 const result = await this.getNoun(id);
@@ -4690,8 +4397,12 @@ export class BrainyData {
                             noun.vector = await this.embeddingFunction(noun.metadata);
                         }
                     }
+                    // Extract type from metadata or default to Content
+                    const nounType = (noun.metadata && typeof noun.metadata === 'object' && 'noun' in noun.metadata)
+                        ? noun.metadata.noun
+                        : NounType.Content;
                     // Add the noun with its vector and metadata (custom ID not supported)
-                    await this.addNoun(noun.vector, noun.metadata);
+                    await this.addNoun(noun.vector, nounType, noun.metadata);
                     nounsRestored++;
                 }
                 catch (error) {
@@ -4847,8 +4558,8 @@ export class BrainyData {
                         tags: [`tag-${i % 5}`, `category-${i % 3}`]
                     }
                 };
-                // Add the noun
-                const id = await this.addNoun(metadata.description, metadata);
+                // Add the noun with explicit type
+                const id = await this.addNoun(metadata.description, nounType, metadata);
                 nounIds.push(id);
             }
             // Generate random verbs between nouns
@@ -5038,8 +4749,7 @@ export class BrainyData {
         const configValue = options?.encrypt ? await this.encryptData(JSON.stringify(value)) : value;
         // Use simple text for vectorization
         const searchableText = `Configuration setting for ${key}`;
-        await this.addNoun(searchableText, {
-            nounType: NounType.State,
+        await this.addNoun(searchableText, NounType.State, {
             configKey: key,
             configValue: configValue,
             encrypted: !!options?.encrypt,
@@ -5171,15 +4881,312 @@ export class BrainyData {
      * @returns Created noun ID
      */
     /**
-     * Add a noun to the database
+     * Add a noun to the database with required type
      * Clean 2.0 API - primary method for adding data
      *
      * @param vectorOrData Vector array or data to embed
-     * @param metadata Metadata to store with the noun
+     * @param nounType Required noun type (one of 31 types)
+     * @param metadata Optional metadata object
      * @returns The generated ID
      */
-    async addNoun(vectorOrData, metadata) {
-        return await this.add(vectorOrData, metadata);
+    async addNoun(vectorOrData, nounType, metadata, options = {}) {
+        // Validate noun type
+        const validatedType = validateNounType(nounType);
+        // Enrich metadata with validated type
+        let enrichedMetadata = {
+            ...metadata,
+            noun: validatedType
+        };
+        await this.ensureInitialized();
+        // Check if database is in read-only mode
+        this.checkReadOnly();
+        // Validate input is not null or undefined
+        if (vectorOrData === null || vectorOrData === undefined) {
+            throw new Error('Input cannot be null or undefined');
+        }
+        try {
+            let vector;
+            if (Array.isArray(vectorOrData)) {
+                for (let i = 0; i < vectorOrData.length; i++) {
+                    if (typeof vectorOrData[i] !== 'number') {
+                        throw new Error('Vector contains non-numeric values');
+                    }
+                }
+            }
+            // Check if input is already a vector
+            if (Array.isArray(vectorOrData) && !options.forceEmbed) {
+                // Input is already a vector (and we've validated it contains only numbers)
+                vector = vectorOrData;
+            }
+            else {
+                // Input needs to be vectorized
+                try {
+                    // Check if input is a JSON object and process it specially
+                    if (typeof vectorOrData === 'object' &&
+                        vectorOrData !== null &&
+                        !Array.isArray(vectorOrData)) {
+                        // Process JSON object for better vectorization
+                        const preparedText = prepareJsonForVectorization(vectorOrData, {
+                            // Prioritize common name/title fields if they exist
+                            priorityFields: [
+                                'name',
+                                'title',
+                                'company',
+                                'organization',
+                                'description',
+                                'summary'
+                            ]
+                        });
+                        vector = await this.embeddingFunction(preparedText);
+                        // IMPORTANT: When an object is passed as data and no metadata is provided,
+                        // use the object AS the metadata too. This is expected behavior for the API.
+                        // Users can pass either:
+                        // 1. addNoun(string, metadata) - vectorize string, store metadata
+                        // 2. addNoun(object) - vectorize object text, store object as metadata
+                        // 3. addNoun(object, metadata) - vectorize object text, store provided metadata
+                        if (!enrichedMetadata || Object.keys(enrichedMetadata).length === 1) { // Only has 'noun' key
+                            enrichedMetadata = { ...vectorOrData, noun: validatedType };
+                        }
+                        // Track field names for this JSON document
+                        const service = this.getServiceName(options);
+                        if (this.storage) {
+                            await this.storage.trackFieldNames(vectorOrData, service);
+                        }
+                    }
+                    else {
+                        // Use standard embedding for non-JSON data
+                        vector = await this.embeddingFunction(vectorOrData);
+                    }
+                }
+                catch (embedError) {
+                    throw new Error(`Failed to vectorize data: ${embedError}`);
+                }
+            }
+            // Check if vector is defined
+            if (!vector) {
+                throw new Error('Vector is undefined or null');
+            }
+            // Validate vector dimensions
+            if (vector.length !== this._dimensions) {
+                throw new Error(`Vector dimension mismatch: expected ${this._dimensions}, got ${vector.length}`);
+            }
+            // Use ID from options if it exists, otherwise from metadata, otherwise generate a new UUID
+            const id = options.id ||
+                (enrichedMetadata && typeof enrichedMetadata === 'object' && 'id' in enrichedMetadata
+                    ? enrichedMetadata.id
+                    : uuidv4());
+            // Check for existing noun (both write-only and normal modes)
+            let existingNoun;
+            if (options.id) {
+                try {
+                    if (this.writeOnly) {
+                        // In write-only mode, check storage directly
+                        existingNoun =
+                            (await this.storage.getNoun(options.id)) ?? undefined;
+                    }
+                    else {
+                        // In normal mode, check index first, then storage
+                        existingNoun = this.index.getNouns().get(options.id);
+                        if (!existingNoun) {
+                            existingNoun =
+                                (await this.storage.getNoun(options.id)) ?? undefined;
+                        }
+                    }
+                    if (existingNoun) {
+                        // Check if existing noun is a placeholder
+                        const existingMetadata = await this.storage.getMetadata(options.id);
+                        const isPlaceholder = existingMetadata &&
+                            typeof existingMetadata === 'object' &&
+                            existingMetadata.isPlaceholder;
+                        if (isPlaceholder) {
+                            // Replace placeholder with real data
+                            if (this.loggingConfig?.verbose) {
+                                console.log(`Replacing placeholder noun ${options.id} with real data`);
+                            }
+                        }
+                        else {
+                            // Real noun already exists, update it
+                            if (this.loggingConfig?.verbose) {
+                                console.log(`Updating existing noun ${options.id}`);
+                            }
+                        }
+                    }
+                }
+                catch (storageError) {
+                    // Item doesn't exist, continue with add operation
+                }
+            }
+            let noun;
+            // In write-only mode, skip index operations since index is not loaded
+            if (this.writeOnly) {
+                // Create noun object directly without adding to index
+                noun = {
+                    id,
+                    vector,
+                    connections: new Map(),
+                    level: 0, // Default level for new nodes
+                    metadata: undefined // Will be set separately
+                };
+            }
+            else {
+                // Normal mode: Add to HNSW index first
+                await this.hnswIndex.addItem({ id, vector, metadata: enrichedMetadata });
+                // Get the noun from the HNSW index
+                const indexNoun = this.hnswIndex.getNouns().get(id);
+                if (!indexNoun) {
+                    throw new Error(`Failed to retrieve newly created noun with ID ${id}`);
+                }
+                noun = indexNoun;
+            }
+            // Save noun to storage using augmentation system
+            await this.augmentations.execute('saveNoun', { noun, options }, async () => {
+                await this.storage.saveNoun(noun);
+                const service = this.getServiceName(options);
+                await this.storage.incrementStatistic('noun', service);
+            });
+            // Save metadata if provided and not empty
+            if (enrichedMetadata !== undefined) {
+                // Skip saving if metadata is an empty object
+                if (enrichedMetadata &&
+                    typeof enrichedMetadata === 'object' &&
+                    Object.keys(enrichedMetadata).length === 0) {
+                    // Don't save empty metadata
+                    // Explicitly save null to ensure no metadata is stored
+                    await this.storage.saveMetadata(id, null);
+                }
+                else {
+                    // Validate noun type if metadata is for a GraphNoun
+                    if (enrichedMetadata && typeof enrichedMetadata === 'object' && 'noun' in enrichedMetadata) {
+                        const nounType = enrichedMetadata.noun;
+                        // Check if the noun type is valid
+                        const isValidNounType = Object.values(NounType).includes(nounType);
+                        if (!isValidNounType) {
+                            console.warn(`Invalid noun type: ${nounType}. Falling back to GraphNoun.`);
+                            enrichedMetadata.noun = NounType.Concept;
+                        }
+                        // Ensure createdBy field is populated for GraphNoun
+                        const service = options.service || this.getCurrentAugmentation();
+                        const graphNoun = enrichedMetadata;
+                        // Only set createdBy if it doesn't exist or is being explicitly updated
+                        if (!graphNoun.createdBy || options.service) {
+                            graphNoun.createdBy = getAugmentationVersion(service);
+                        }
+                        // Update timestamps
+                        const now = new Date();
+                        const timestamp = {
+                            seconds: Math.floor(now.getTime() / 1000),
+                            nanoseconds: (now.getTime() % 1000) * 1000000
+                        };
+                        // Set createdAt if it doesn't exist
+                        if (!graphNoun.createdAt) {
+                            graphNoun.createdAt = timestamp;
+                        }
+                        // Always update updatedAt
+                        graphNoun.updatedAt = timestamp;
+                    }
+                    // Create properly namespaced metadata for new items
+                    let metadataToSave = createNamespacedMetadata(enrichedMetadata);
+                    // Add domain metadata if distributed mode is enabled
+                    if (this.domainDetector) {
+                        // First check if domain is already in metadata
+                        if (metadataToSave.domain) {
+                            // Domain already specified, keep it
+                            const domainInfo = this.domainDetector.detectDomain(metadataToSave);
+                            if (domainInfo.domainMetadata) {
+                                ;
+                                metadataToSave.domainMetadata =
+                                    domainInfo.domainMetadata;
+                            }
+                        }
+                        else {
+                            // Try to detect domain from the data
+                            const dataToAnalyze = Array.isArray(vectorOrData)
+                                ? enrichedMetadata
+                                : vectorOrData;
+                            const domainInfo = this.domainDetector.detectDomain(dataToAnalyze);
+                            if (domainInfo.domain) {
+                                ;
+                                metadataToSave.domain = domainInfo.domain;
+                                if (domainInfo.domainMetadata) {
+                                    ;
+                                    metadataToSave.domainMetadata =
+                                        domainInfo.domainMetadata;
+                                }
+                            }
+                        }
+                    }
+                    // Add partition information if distributed mode is enabled
+                    if (this.partitioner) {
+                        const partition = this.partitioner.getPartition(id);
+                        metadataToSave.partition = partition;
+                    }
+                    await this.storage.saveMetadata(id, metadataToSave);
+                    // Update metadata index (write-only mode should build indices!)
+                    if (this.index && !this.frozen) {
+                        await this.metadataIndex?.addToIndex?.(id, metadataToSave);
+                    }
+                    // Track metadata statistics
+                    const metadataService = this.getServiceName(options);
+                    await this.storage.incrementStatistic('metadata', metadataService);
+                    // Content type tracking removed - metrics system not initialized
+                    // Track update timestamp (handled by metrics augmentation)
+                }
+            }
+            // Update HNSW index size with actual index size
+            const indexSize = this.index.size();
+            await this.storage.updateHnswIndexSize(indexSize);
+            // Update health metrics if in distributed mode
+            if (this.monitoring) {
+                const vectorCount = await this.getNounCount();
+                this.monitoring.updateVectorCount(vectorCount);
+            }
+            // If addToRemote is true and we're connected to a remote server, add to remote as well
+            if (options.addToRemote && this.isConnectedToRemoteServer()) {
+                try {
+                    await this.addToRemote(id, vector, enrichedMetadata);
+                }
+                catch (remoteError) {
+                    console.warn(`Failed to add to remote server: ${remoteError}. Continuing with local add.`);
+                }
+            }
+            // Invalidate search cache since data has changed
+            this.cache?.invalidateOnDataChange('add');
+            // Determine processing mode
+            const processingMode = options.process || 'auto';
+            let shouldProcessNeurally = false;
+            if (processingMode === 'neural') {
+                shouldProcessNeurally = true;
+            }
+            else if (processingMode === 'auto') {
+                // Auto-detect whether to use neural processing
+                shouldProcessNeurally = this.shouldAutoProcessNeurally(vectorOrData, enrichedMetadata);
+            }
+            // 'literal' mode means no neural processing
+            // 🧠 AI Processing (Neural Import) - Based on processing mode
+            if (shouldProcessNeurally) {
+                try {
+                    // Execute augmentation pipeline for data processing
+                    // Note: Augmentations will be called via this.augmentations.execute during the actual add operation
+                    // This replaces the legacy SENSE pipeline
+                    if (this.loggingConfig?.verbose) {
+                        console.log(`🧠 AI processing completed for data: ${id}`);
+                    }
+                }
+                catch (processingError) {
+                    // Don't fail the add operation if processing fails
+                    console.warn(`🧠 AI processing failed for ${id}:`, processingError);
+                }
+            }
+            return id;
+        }
+        catch (error) {
+            console.error('Failed to add vector:', error);
+            // Track error in health monitor
+            if (this.monitoring) {
+                this.monitoring.recordRequest(0, true);
+            }
+            throw new Error(`Failed to add vector: ${error}`);
+        }
     }
     /**
      * Add Verb - Unified relationship creation between nouns
@@ -5514,10 +5521,10 @@ export class BrainyData {
             }
         };
         // Store coordination plan in _system directory
-        await this.addNoun({
+        await this.addNoun('Cortex coordination plan', NounType.Process, {
             id: '_system/coordination',
             type: 'cortex_coordination',
-            metadata: coordinationPlan
+            ...coordinationPlan
         });
         prodLog.info('📋 Storage migration coordination plan created');
         prodLog.info('All services will automatically detect and execute the migration');