@soulcraft/brainy 6.1.0 → 6.2.1

package/dist/storage/baseStorage.d.ts

@@ -181,6 +181,24 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * @returns Combined verb + metadata or null
      */
     getVerb(id: string): Promise<HNSWVerbWithMetadata | null>;
+    /**
+     * Batch get multiple verbs (v6.2.0 - N+1 fix)
+     *
+     * **Performance**: Eliminates N+1 pattern for verb loading
+     * - Current: N × getVerb() = N × 50ms on GCS = 250ms for 5 verbs
+     * - Batched: 1 × getVerbsBatch() = 1 × 50ms on GCS = 50ms (**5x faster**)
+     *
+     * **Use cases:**
+     * - graphIndex.getVerbsBatchCached() for relate() duplicate checking
+     * - Loading relationships in batch operations
+     * - Pre-loading verbs for graph traversal
+     *
+     * @param ids Array of verb IDs to fetch
+     * @returns Map of id → HNSWVerbWithMetadata (only successful reads included)
+     *
+     * @since v6.2.0
+     */
+    getVerbsBatch(ids: string[]): Promise<Map<string, HNSWVerbWithMetadata>>;
     /**
      * Convert HNSWVerb to GraphVerb by combining with metadata
      * DEPRECATED: For backward compatibility only. Use getVerb() which returns HNSWVerbWithMetadata.
@@ -494,6 +512,24 @@ export declare abstract class BaseStorage extends BaseStorageAdapter {
      * @since v5.12.0
      */
     getNounMetadataBatch(ids: string[]): Promise<Map<string, NounMetadata>>;
+    /**
+     * Batch get multiple nouns with vectors (v6.2.0 - N+1 fix)
+     *
+     * **Performance**: Eliminates N+1 pattern for vector loading
+     * - Current: N × getNoun() = N × 50ms on GCS = 500ms for 10 entities
+     * - Batched: 1 × getNounBatch() = 1 × 50ms on GCS = 50ms (**10x faster**)
+     *
+     * **Use cases:**
+     * - batchGet() with includeVectors: true
+     * - Loading entities for similarity computation
+     * - Pre-loading vectors for batch processing
+     *
+     * @param ids Array of entity IDs to fetch (with vectors)
+     * @returns Map of id → HNSWNounWithMetadata (only successful reads included)
+     *
+     * @since v6.2.0
+     */
+    getNounBatch(ids: string[]): Promise<Map<string, HNSWNounWithMetadata>>;
     /**
      * Batch read multiple storage paths with COW inheritance support (v5.12.0)
      *

package/dist/storage/baseStorage.js

@@ -10,7 +10,7 @@ import { getShardIdFromUuid } from './sharding.js';
 import { RefManager } from './cow/RefManager.js';
 import { BlobStorage } from './cow/BlobStorage.js';
 import { CommitLog } from './cow/CommitLog.js';
-import { unwrapBinaryData, wrapBinaryData } from './cow/binaryDataCodec.js';
+import { unwrapBinaryData } from './cow/binaryDataCodec.js';
 import { prodLog } from '../utils/logger.js';
 // Clean directory structure (v4.7.2+)
 // All storage adapters use this consistent structure
@@ -278,9 +278,25 @@ export class BaseStorage extends BaseStorageAdapter {
                 }
             },
             put: async (key, data) => {
-                // v5.10.1: Use shared binaryDataCodec utility (single source of truth)
-                // Wraps binary data or parses JSON for storage
-                const obj = wrapBinaryData(data);
+                // v6.2.0 PERMANENT FIX: Use key naming convention (explicit type contract)
+                // NO GUESSING - key format explicitly declares data type:
+                //
+                // JSON keys (metadata and refs):
+                // - 'ref:*'           → JSON (RefManager: refs, HEAD, branches)
+                // - 'blob-meta:hash'  → JSON (BlobStorage: blob metadata)
+                // - 'commit-meta:hash'→ JSON (BlobStorage: commit metadata)
+                // - 'tree-meta:hash'  → JSON (BlobStorage: tree metadata)
+                //
+                // Binary keys (blob data):
+                // - 'blob:hash'       → Binary (BlobStorage: compressed/raw blob data)
+                // - 'commit:hash'     → Binary (BlobStorage: commit object data)
+                // - 'tree:hash'       → Binary (BlobStorage: tree object data)
+                //
+                // This eliminates the fragile JSON.parse() guessing that caused blob integrity
+                // failures when compressed data accidentally parsed as valid JSON.
+                const obj = key.includes('-meta:') || key.startsWith('ref:')
+                    ? JSON.parse(data.toString()) // Metadata/refs: ALWAYS JSON.stringify'd
+                    : { _binary: true, data: data.toString('base64') }; // Blobs: ALWAYS binary (possibly compressed)
                 await this.writeObjectToPath(`_cow/${key}`, obj);
             },
             delete: async (key) => {
@@ -642,6 +658,76 @@ export class BaseStorage extends BaseStorageAdapter {
             metadata: customMetadata
         };
     }
+    /**
+     * Batch get multiple verbs (v6.2.0 - N+1 fix)
+     *
+     * **Performance**: Eliminates N+1 pattern for verb loading
+     * - Current: N × getVerb() = N × 50ms on GCS = 250ms for 5 verbs
+     * - Batched: 1 × getVerbsBatch() = 1 × 50ms on GCS = 50ms (**5x faster**)
+     *
+     * **Use cases:**
+     * - graphIndex.getVerbsBatchCached() for relate() duplicate checking
+     * - Loading relationships in batch operations
+     * - Pre-loading verbs for graph traversal
+     *
+     * @param ids Array of verb IDs to fetch
+     * @returns Map of id → HNSWVerbWithMetadata (only successful reads included)
+     *
+     * @since v6.2.0
+     */
+    async getVerbsBatch(ids) {
+        await this.ensureInitialized();
+        const results = new Map();
+        if (ids.length === 0)
+            return results;
+        // v6.2.0: Batch-fetch vectors and metadata in parallel
+        // Build paths for vectors
+        const vectorPaths = ids.map(id => ({
+            path: getVerbVectorPath(id),
+            id
+        }));
+        // Build paths for metadata
+        const metadataPaths = ids.map(id => ({
+            path: getVerbMetadataPath(id),
+            id
+        }));
+        // Batch read vectors and metadata in parallel
+        const [vectorResults, metadataResults] = await Promise.all([
+            this.readBatchWithInheritance(vectorPaths.map(p => p.path)),
+            this.readBatchWithInheritance(metadataPaths.map(p => p.path))
+        ]);
+        // Combine vectors + metadata into HNSWVerbWithMetadata
+        for (const { path: vectorPath, id } of vectorPaths) {
+            const vectorData = vectorResults.get(vectorPath);
+            const metadataPath = getVerbMetadataPath(id);
+            const metadataData = metadataResults.get(metadataPath);
+            if (vectorData && metadataData) {
+                // Deserialize verb
+                const verb = this.deserializeVerb(vectorData);
+                // Extract standard fields to top-level (v4.8.0 pattern)
+                const { createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataData;
+                results.set(id, {
+                    id: verb.id,
+                    vector: verb.vector,
+                    connections: verb.connections,
+                    verb: verb.verb,
+                    sourceId: verb.sourceId,
+                    targetId: verb.targetId,
+                    // v4.8.0: Standard fields at top-level
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    // Only custom user fields remain in metadata
+                    metadata: customMetadata
+                });
+            }
+        }
+        return results;
+    }
     /**
      * Convert HNSWVerb to GraphVerb by combining with metadata
      * DEPRECATED: For backward compatibility only. Use getVerb() which returns HNSWVerbWithMetadata.
@@ -1553,6 +1639,75 @@ export class BaseStorage extends BaseStorageAdapter {
         }
         return results;
     }
+    /**
+     * Batch get multiple nouns with vectors (v6.2.0 - N+1 fix)
+     *
+     * **Performance**: Eliminates N+1 pattern for vector loading
+     * - Current: N × getNoun() = N × 50ms on GCS = 500ms for 10 entities
+     * - Batched: 1 × getNounBatch() = 1 × 50ms on GCS = 50ms (**10x faster**)
+     *
+     * **Use cases:**
+     * - batchGet() with includeVectors: true
+     * - Loading entities for similarity computation
+     * - Pre-loading vectors for batch processing
+     *
+     * @param ids Array of entity IDs to fetch (with vectors)
+     * @returns Map of id → HNSWNounWithMetadata (only successful reads included)
+     *
+     * @since v6.2.0
+     */
+    async getNounBatch(ids) {
+        await this.ensureInitialized();
+        const results = new Map();
+        if (ids.length === 0)
+            return results;
+        // v6.2.0: Batch-fetch vectors and metadata in parallel
+        // Build paths for vectors
+        const vectorPaths = ids.map(id => ({
+            path: getNounVectorPath(id),
+            id
+        }));
+        // Build paths for metadata
+        const metadataPaths = ids.map(id => ({
+            path: getNounMetadataPath(id),
+            id
+        }));
+        // Batch read vectors and metadata in parallel
+        const [vectorResults, metadataResults] = await Promise.all([
+            this.readBatchWithInheritance(vectorPaths.map(p => p.path)),
+            this.readBatchWithInheritance(metadataPaths.map(p => p.path))
+        ]);
+        // Combine vectors + metadata into HNSWNounWithMetadata
+        for (const { path: vectorPath, id } of vectorPaths) {
+            const vectorData = vectorResults.get(vectorPath);
+            const metadataPath = getNounMetadataPath(id);
+            const metadataData = metadataResults.get(metadataPath);
+            if (vectorData && metadataData) {
+                // Deserialize noun
+                const noun = this.deserializeNoun(vectorData);
+                // Extract standard fields to top-level (v4.8.0 pattern)
+                const { noun: nounType, createdAt, updatedAt, confidence, weight, service, data, createdBy, ...customMetadata } = metadataData;
+                results.set(id, {
+                    id: noun.id,
+                    vector: noun.vector,
+                    connections: noun.connections,
+                    level: noun.level,
+                    // v4.8.0: Standard fields at top-level
+                    type: nounType || NounType.Thing,
+                    createdAt: createdAt || Date.now(),
+                    updatedAt: updatedAt || Date.now(),
+                    confidence: confidence,
+                    weight: weight,
+                    service: service,
+                    data: data,
+                    createdBy,
+                    // Only custom user fields remain in metadata
+                    metadata: customMetadata
+                });
+            }
+        }
+        return results;
+    }
     /**
      * Batch read multiple storage paths with COW inheritance support (v5.12.0)
      *

package/dist/storage/cow/binaryDataCodec.d.ts

@@ -49,11 +49,22 @@ export declare function unwrapBinaryData(data: any): Buffer;
 /**
  * Wrap binary data for JSON storage
  *
- * This is the SINGLE SOURCE OF TRUTH for wrapping binary data.
- * All storage operations MUST use this function.
+ * ⚠️ WARNING: DO NOT USE THIS ON WRITE PATH! (v6.2.0)
+ * ⚠️ Use key-based dispatch in baseStorage.ts COW adapter instead.
+ * ⚠️ This function exists for legacy/compatibility only.
+ *
+ * DEPRECATED APPROACH: Tries to guess if data is JSON by parsing.
+ * This is FRAGILE because compressed binary can accidentally parse as valid JSON,
+ * causing blob integrity failures.
+ *
+ * v6.2.0 SOLUTION: baseStorage.ts COW adapter now uses key naming convention:
+ * - Keys with '-meta:' or 'ref:' prefix → Always JSON
+ * - Keys with 'blob:', 'commit:', 'tree:' prefix → Always binary
+ * No guessing needed!
  *
  * @param data - Buffer to wrap
  * @returns Wrapped object or parsed JSON object
+ * @deprecated Use key-based dispatch in baseStorage.ts instead
  */
 export declare function wrapBinaryData(data: Buffer): any;
 /**

package/dist/storage/cow/binaryDataCodec.js

@@ -66,14 +66,27 @@ export function unwrapBinaryData(data) {
 /**
  * Wrap binary data for JSON storage
  *
- * This is the SINGLE SOURCE OF TRUTH for wrapping binary data.
- * All storage operations MUST use this function.
+ * ⚠️ WARNING: DO NOT USE THIS ON WRITE PATH! (v6.2.0)
+ * ⚠️ Use key-based dispatch in baseStorage.ts COW adapter instead.
+ * ⚠️ This function exists for legacy/compatibility only.
+ *
+ * DEPRECATED APPROACH: Tries to guess if data is JSON by parsing.
+ * This is FRAGILE because compressed binary can accidentally parse as valid JSON,
+ * causing blob integrity failures.
+ *
+ * v6.2.0 SOLUTION: baseStorage.ts COW adapter now uses key naming convention:
+ * - Keys with '-meta:' or 'ref:' prefix → Always JSON
+ * - Keys with 'blob:', 'commit:', 'tree:' prefix → Always binary
+ * No guessing needed!
  *
  * @param data - Buffer to wrap
  * @returns Wrapped object or parsed JSON object
+ * @deprecated Use key-based dispatch in baseStorage.ts instead
  */
 export function wrapBinaryData(data) {
     // Try to parse as JSON first (for metadata, trees, commits)
+    // NOTE: This is the OLD approach - fragile because compressed data
+    // can accidentally parse as valid JSON!
     try {
         return JSON.parse(data.toString());
     }

package/dist/types/brainy.types.d.ts

@@ -302,6 +302,7 @@ export interface DeleteManyParams {
     where?: any;
     limit?: number;
     onProgress?: (done: number, total: number) => void;
+    continueOnError?: boolean;
 }
 /**
  * Batch relate parameters

package/dist/types/brainyDataInterface.d.ts

@@ -0,0 +1,52 @@
+/**
+ * BrainyInterface - Modern API Only
+ *
+ * This interface defines the MODERN methods from Brainy 3.0.
+ * Used to break circular dependencies while enforcing modern API usage.
+ *
+ * NO DEPRECATED METHODS - Only clean, modern API patterns.
+ */
+import { Vector } from '../coreTypes.js';
+import { AddParams, RelateParams, Result, Entity, FindParams, SimilarParams } from './brainy.types.js';
+export interface BrainyInterface<T = unknown> {
+    /**
+     * Initialize the database
+     */
+    init(): Promise<void>;
+    /**
+     * Modern add method - unified entity creation
+     * @param params Parameters for adding entities
+     * @returns The ID of the created entity
+     */
+    add(params: AddParams<T>): Promise<string>;
+    /**
+     * Modern relate method - unified relationship creation
+     * @param params Parameters for creating relationships
+     * @returns The ID of the created relationship
+     */
+    relate(params: RelateParams<T>): Promise<string>;
+    /**
+     * Modern find method - unified search and discovery
+     * @param query Search query or parameters object
+     * @returns Array of search results
+     */
+    find(query: string | FindParams<T>): Promise<Result<T>[]>;
+    /**
+     * Modern get method - retrieve entities by ID
+     * @param id The entity ID to retrieve
+     * @returns Entity or null if not found
+     */
+    get(id: string): Promise<Entity<T> | null>;
+    /**
+     * Modern similar method - find similar entities
+     * @param params Parameters for similarity search
+     * @returns Array of similar entities with scores
+     */
+    similar(params: SimilarParams<T>): Promise<Result<T>[]>;
+    /**
+     * Generate embedding vector from text
+     * @param text The text to embed
+     * @returns Vector representation of the text
+     */
+    embed(text: string): Promise<Vector>;
+}

package/dist/types/brainyDataInterface.js

@@ -0,0 +1,10 @@
+/**
+ * BrainyInterface - Modern API Only
+ *
+ * This interface defines the MODERN methods from Brainy 3.0.
+ * Used to break circular dependencies while enforcing modern API usage.
+ *
+ * NO DEPRECATED METHODS - Only clean, modern API patterns.
+ */
+export {};
+//# sourceMappingURL=brainyDataInterface.js.map

package/dist/utils/metadataIndex.d.ts

@@ -436,6 +436,23 @@ export declare class MetadataIndexManager {
      * Get all entity types and their counts - O(1) operation
      */
     getAllEntityCounts(): Map<string, number>;
+    /**
+     * Get VFS entity count for a specific type using Roaring bitmap intersection
+     * Uses hardware-accelerated SIMD operations (AVX2/SSE4.2)
+     * @param type The noun type to query
+     * @returns Count of VFS entities of this type
+     */
+    getVFSEntityCountByType(type: string): Promise<number>;
+    /**
+     * Get all VFS entity counts by type using Roaring bitmap operations
+     * @returns Map of type -> VFS entity count
+     */
+    getAllVFSEntityCounts(): Promise<Map<string, number>>;
+    /**
+     * Get total count of VFS entities - O(1) using Roaring bitmap cardinality
+     * @returns Total VFS entity count
+     */
+    getTotalVFSEntityCount(): Promise<number>;
     /**
      * Get entity count for a noun type using type enum (O(1) array access)
      * More efficient than Map-based getEntityCountByType

package/dist/utils/metadataIndex.js

@@ -1230,6 +1230,21 @@ export class MetadataIndexManager {
                 const subIds = await this.getIdsForFilter(subFilter);
                 subIds.forEach(id => unionIds.add(id));
             }
+            // v6.2.1: Fix - Check for outer-level field conditions that need AND application
+            // This handles cases like { anyOf: [...], vfsType: { exists: false } }
+            // where the anyOf results must be intersected with other field conditions
+            const outerFields = Object.keys(filter).filter((k) => k !== 'anyOf' && k !== 'allOf' && k !== 'not');
+            if (outerFields.length > 0) {
+                // Build filter with just outer fields and get matching IDs
+                const outerFilter = {};
+                for (const field of outerFields) {
+                    outerFilter[field] = filter[field];
+                }
+                const outerIds = await this.getIdsForFilter(outerFilter);
+                const outerIdSet = new Set(outerIds);
+                // Intersect: anyOf union AND outer field conditions
+                return Array.from(unionIds).filter((id) => outerIdSet.has(id));
+            }
             return Array.from(unionIds);
         }
         // Process field filters with range support
@@ -1865,6 +1880,54 @@ export class MetadataIndexManager {
         return new Map(this.totalEntitiesByType);
     }
     // ============================================================================
+    // v6.2.1: VFS Statistics Methods (uses existing Roaring bitmap infrastructure)
+    // ============================================================================
+    /**
+     * Get VFS entity count for a specific type using Roaring bitmap intersection
+     * Uses hardware-accelerated SIMD operations (AVX2/SSE4.2)
+     * @param type The noun type to query
+     * @returns Count of VFS entities of this type
+     */
+    async getVFSEntityCountByType(type) {
+        const vfsBitmap = await this.getBitmapFromChunks('isVFSEntity', true);
+        const typeBitmap = await this.getBitmapFromChunks('noun', type);
+        if (!vfsBitmap || !typeBitmap)
+            return 0;
+        // Hardware-accelerated intersection + O(1) cardinality
+        const intersection = RoaringBitmap32.and(vfsBitmap, typeBitmap);
+        return intersection.size;
+    }
+    /**
+     * Get all VFS entity counts by type using Roaring bitmap operations
+     * @returns Map of type -> VFS entity count
+     */
+    async getAllVFSEntityCounts() {
+        const vfsBitmap = await this.getBitmapFromChunks('isVFSEntity', true);
+        if (!vfsBitmap || vfsBitmap.size === 0) {
+            return new Map();
+        }
+        const result = new Map();
+        // Iterate through all known types and compute VFS count via intersection
+        for (const type of this.totalEntitiesByType.keys()) {
+            const typeBitmap = await this.getBitmapFromChunks('noun', type);
+            if (typeBitmap) {
+                const intersection = RoaringBitmap32.and(vfsBitmap, typeBitmap);
+                if (intersection.size > 0) {
+                    result.set(type, intersection.size);
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Get total count of VFS entities - O(1) using Roaring bitmap cardinality
+     * @returns Total VFS entity count
+     */
+    async getTotalVFSEntityCount() {
+        const vfsBitmap = await this.getBitmapFromChunks('isVFSEntity', true);
+        return vfsBitmap?.size ?? 0;
+    }
+    // ============================================================================
     // Phase 1b: Type Enum Methods (O(1) access via Uint32Arrays)
     // ============================================================================
     /**

package/dist/vfs/ConceptSystem.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Universal Concept System for VFS
+ *
+ * Manages concepts that transcend files and exist independently
+ * Ideas that can be linked to multiple manifestations across domains
+ * PRODUCTION-READY: Real implementation using Brainy
+ */
+import { Brainy } from '../brainy.js';
+import { EntityManager, ManagedEntity } from './EntityManager.js';
+/**
+ * Universal concept that exists independently of files
+ */
+export interface UniversalConcept extends ManagedEntity {
+    id: string;
+    name: string;
+    description?: string;
+    domain: string;
+    category: string;
+    keywords: string[];
+    links: ConceptLink[];
+    manifestations: ConceptManifestation[];
+    strength: number;
+    created: number;
+    lastUpdated: number;
+    version: number;
+    metadata: Record<string, any>;
+    conceptType?: string;
+}
+/**
+ * A link between concepts
+ */
+export interface ConceptLink {
+    id: string;
+    targetConceptId: string;
+    relationship: 'extends' | 'implements' | 'uses' | 'opposite' | 'related' | 'contains' | 'part-of';
+    strength: number;
+    context?: string;
+    bidirectional: boolean;
+}
+/**
+ * A manifestation of a concept in a specific location
+ */
+export interface ConceptManifestation extends ManagedEntity {
+    id: string;
+    conceptId: string;
+    filePath: string;
+    context: string;
+    form: 'definition' | 'usage' | 'example' | 'discussion' | 'implementation';
+    position?: {
+        line?: number;
+        column?: number;
+        offset?: number;
+    };
+    confidence: number;
+    timestamp: number;
+    extractedBy: 'manual' | 'auto' | 'ai';
+}
+/**
+ * Configuration for concept system
+ */
+export interface ConceptSystemConfig {
+    autoLink?: boolean;
+    similarityThreshold?: number;
+    maxManifestations?: number;
+    strengthDecay?: number;
+}
+/**
+ * Concept graph structure for visualization
+ */
+export interface ConceptGraph {
+    concepts: Array<{
+        id: string;
+        name: string;
+        domain: string;
+        strength: number;
+        manifestationCount: number;
+    }>;
+    links: Array<{
+        source: string;
+        target: string;
+        relationship: string;
+        strength: number;
+    }>;
+}
+/**
+ * Universal Concept System
+ *
+ * Manages concepts that exist independently of any specific file or context
+ * Examples:
+ * - "Authentication" concept appearing in docs, code, tests
+ * - "Customer Journey" concept in marketing, UX, analytics
+ * - "Dependency Injection" pattern across multiple codebases
+ * - "Sustainability" theme in various research papers
+ */
+export declare class ConceptSystem extends EntityManager {
+    private config;
+    private conceptCache;
+    constructor(brain: Brainy, config?: ConceptSystemConfig);
+    /**
+     * Create a new universal concept
+     */
+    createConcept(concept: Omit<UniversalConcept, 'id' | 'created' | 'lastUpdated' | 'version' | 'links' | 'manifestations'>): Promise<string>;
+    /**
+     * Find concepts by various criteria
+     */
+    findConcepts(query: {
+        name?: string;
+        domain?: string;
+        category?: string;
+        keywords?: string[];
+        similar?: string;
+        manifestedIn?: string;
+    }): Promise<UniversalConcept[]>;
+    /**
+     * Link two concepts together
+     */
+    linkConcept(fromConceptId: string, toConceptId: string, relationship: ConceptLink['relationship'], options?: {
+        strength?: number;
+        context?: string;
+        bidirectional?: boolean;
+    }): Promise<string>;
+    /**
+     * Record a manifestation of a concept in a file
+     */
+    recordManifestation(conceptId: string, filePath: string, context: string, form: ConceptManifestation['form'], options?: {
+        position?: ConceptManifestation['position'];
+        confidence?: number;
+        extractedBy?: ConceptManifestation['extractedBy'];
+    }): Promise<string>;
+    /**
+     * Extract and link concepts from content
+     */
+    extractAndLinkConcepts(filePath: string, content: Buffer): Promise<string[]>;
+    /**
+     * Get concept graph for visualization
+     */
+    getConceptGraph(options?: {
+        domain?: string;
+        minStrength?: number;
+        maxConcepts?: number;
+    }): Promise<ConceptGraph>;
+    /**
+     * Find appearances of a concept
+     */
+    findAppearances(conceptId: string, options?: {
+        filePath?: string;
+        form?: ConceptManifestation['form'];
+        minConfidence?: number;
+        limit?: number;
+    }): Promise<ConceptManifestation[]>;
+    /**
+     * Auto-link concept to similar concepts
+     */
+    private autoLinkConcept;
+    /**
+     * Get concept by ID
+     */
+    private getConcept;
+    /**
+     * Update stored concept
+     */
+    private updateConcept;
+    /**
+     * Calculate similarity between two concepts
+     */
+    private calculateConceptSimilarity;
+    /**
+     * Generate embedding for concept
+     */
+    private generateConceptEmbedding;
+    /**
+     * Generate embedding for text
+     */
+    private generateTextEmbedding;
+    /**
+     * Get reverse relationship type
+     */
+    private getReverseRelationship;
+    /**
+     * Map concept relationship to VerbType
+     */
+    private getVerbType;
+    /**
+     * Detect concept domain from context
+     */
+    private detectDomain;
+    /**
+     * Detect concept category
+     */
+    private detectCategory;
+    /**
+     * Detect manifestation form from context
+     */
+    private detectManifestationForm;
+    /**
+     * Extract context around a position
+     */
+    private extractContext;
+    /**
+     * Clear concept cache
+     */
+    clearCache(conceptId?: string): void;
+}