@weavelogic/knowledge-graph-agent 0.3.0 → 0.4.0

package/dist/vector/config.d.ts

@@ -0,0 +1,300 @@
+/**
+ * Vector Configuration
+ *
+ * Configuration types and defaults for RuVector-compatible vector storage.
+ * Supports multiple backends (memory, postgres, standalone) with HNSW indexing.
+ *
+ * @module vector/config
+ */
+import type { VectorIndexConfig } from './types.js';
+/**
+ * Backend storage type for vectors
+ */
+export type VectorBackend = 'memory' | 'postgres' | 'standalone' | 'sqlite' | 'cloud';
+/**
+ * HNSW (Hierarchical Navigable Small World) index configuration
+ *
+ * HNSW provides fast approximate nearest neighbor search with
+ * configurable accuracy/speed tradeoffs.
+ */
+export interface HNSWConfig {
+    /**
+     * Maximum number of connections per layer
+     * Higher values improve recall but increase memory usage
+     * @default 16
+     */
+    m: number;
+    /**
+     * Size of dynamic candidate list for construction
+     * Higher values improve index quality but slow down construction
+     * @default 200
+     */
+    efConstruction: number;
+    /**
+     * Size of dynamic candidate list for search
+     * Higher values improve recall but slow down search
+     * @default 100
+     */
+    efSearch: number;
+}
+/**
+ * Re-export VectorIndexConfig from types for convenience
+ */
+export type { VectorIndexConfig } from './types.js';
+/**
+ * PostgreSQL backend configuration
+ */
+export interface PostgresBackendConfig {
+    /**
+     * PostgreSQL connection string
+     * @example 'postgres://user:pass@localhost:5432/dbname'
+     */
+    connectionString: string;
+    /**
+     * Database schema for vector tables
+     * @default 'ruvector'
+     */
+    schema: string;
+}
+/**
+ * Cloud backend configuration
+ */
+export interface CloudBackendConfig {
+    /**
+     * Cloud vector database endpoint URL
+     */
+    url: string;
+    /**
+     * API key for authentication
+     */
+    apiKey?: string;
+}
+/**
+ * Standalone backend configuration
+ */
+export interface StandaloneBackendConfig {
+    /**
+     * Directory for vector data storage
+     * @default '.ruvector'
+     */
+    dataDir: string;
+}
+/**
+ * RuVector configuration
+ *
+ * Main configuration interface for the vector database system.
+ */
+export interface RuVectorConfig {
+    /**
+     * Storage backend type
+     */
+    backend: VectorBackend;
+    /**
+     * Vector index configuration
+     */
+    index: VectorIndexConfig;
+    /**
+     * PostgreSQL connection configuration
+     * Required when backend is 'postgres'
+     */
+    postgres?: PostgresBackendConfig;
+    /**
+     * Cloud endpoint configuration
+     * Required when backend is 'cloud'
+     */
+    cloud?: CloudBackendConfig;
+    /**
+     * Standalone file path configuration
+     * Required when backend is 'standalone'
+     */
+    standalone?: StandaloneBackendConfig;
+    /**
+     * Enable self-learning SONA (Self-Optimizing Neural Architecture) engine
+     * When enabled, the system learns from agent trajectories to improve performance
+     * @default false
+     */
+    enableSona?: boolean;
+    /**
+     * Enable trajectory tracking for agents
+     * Records agent actions for analysis and learning
+     * @default false
+     */
+    enableTrajectoryTracking?: boolean;
+    /**
+     * Cache configuration
+     */
+    cache?: {
+        /** Enable result caching */
+        enabled: boolean;
+        /** Maximum cache size in entries */
+        maxSize: number;
+        /** Cache TTL in seconds */
+        ttlSeconds: number;
+    };
+    /**
+     * Performance tuning
+     */
+    performance?: {
+        /** Batch size for bulk operations */
+        batchSize: number;
+        /** Enable parallel processing */
+        parallelProcessing: boolean;
+        /** Maximum concurrent operations */
+        maxConcurrency: number;
+        /** Memory limit in MB for index */
+        memoryLimitMb?: number;
+    };
+    /**
+     * Hybrid search configuration
+     */
+    hybrid?: {
+        /** Enable hybrid search */
+        enabled: boolean;
+        /** Default vector weight (0-1) */
+        defaultVectorWeight: number;
+        /** Graph database connection (for Cypher queries) */
+        graphConnection?: {
+            type: 'neo4j' | 'memgraph' | 'sqlite';
+            uri?: string;
+            database?: string;
+            auth?: {
+                user: string;
+                password: string;
+            };
+        };
+    };
+    /**
+     * Namespace configuration for multi-tenant support
+     */
+    namespace?: {
+        /** Default namespace */
+        defaultNamespace: string;
+        /** Namespace isolation level */
+        isolation: 'soft' | 'hard';
+    };
+}
+/**
+ * Default HNSW configuration
+ * Balanced settings for most use cases
+ */
+export declare const DEFAULT_HNSW_CONFIG: HNSWConfig;
+/**
+ * Default vector index configuration
+ * Optimized for OpenAI/Claude embeddings (1536 dimensions)
+ */
+export declare const DEFAULT_INDEX_CONFIG: VectorIndexConfig;
+/**
+ * Default cache configuration
+ */
+export declare const DEFAULT_CACHE_CONFIG: {
+    readonly enabled: true;
+    readonly maxSize: 1000;
+    readonly ttlSeconds: 300;
+};
+/**
+ * Default performance configuration
+ */
+export declare const DEFAULT_PERFORMANCE_CONFIG: {
+    readonly batchSize: 100;
+    readonly parallelProcessing: true;
+    readonly maxConcurrency: 4;
+};
+/**
+ * Create RuVector configuration from environment variables
+ *
+ * Reads configuration from the following environment variables:
+ * - RUVECTOR_BACKEND: Storage backend type (default: 'memory')
+ * - RUVECTOR_DIMENSIONS: Vector dimensions (default: 384)
+ * - RUVECTOR_ENABLE_SONA: Enable SONA learning (default: false)
+ * - RUVECTOR_ENABLE_TRAJECTORY: Enable trajectory tracking (default: false)
+ * - DATABASE_URL: PostgreSQL connection string (for postgres backend)
+ * - RUVECTOR_SCHEMA: PostgreSQL schema (default: 'ruvector')
+ * - RUVECTOR_CLOUD_URL: Cloud endpoint URL (for cloud backend)
+ * - RUVECTOR_API_KEY: Cloud API key (for cloud backend)
+ * - RUVECTOR_DATA_DIR: Data directory (for standalone backend)
+ *
+ * @returns RuVectorConfig configured from environment
+ *
+ * @example
+ * ```typescript
+ * // Set environment variables
+ * process.env.RUVECTOR_BACKEND = 'postgres';
+ * process.env.DATABASE_URL = 'postgres://localhost:5432/mydb';
+ *
+ * // Create configuration
+ * const config = createRuVectorConfig();
+ * ```
+ */
+export declare function createRuVectorConfig(): RuVectorConfig;
+/**
+ * Validation result for RuVector configuration
+ */
+export interface ConfigValidationResult {
+    /**
+     * Whether the configuration is valid
+     */
+    valid: boolean;
+    /**
+     * List of validation errors (empty if valid)
+     */
+    errors: string[];
+    /**
+     * List of validation warnings
+     */
+    warnings: string[];
+}
+/**
+ * Legacy alias for backwards compatibility
+ */
+export type ValidationResult = ConfigValidationResult;
+/**
+ * Validate RuVector configuration
+ *
+ * Checks that all required fields are present and valid based on
+ * the selected backend type.
+ *
+ * @param config - Configuration to validate
+ * @returns Validation result with errors if invalid
+ *
+ * @example
+ * ```typescript
+ * const config = createRuVectorConfig();
+ * const result = validateRuVectorConfig(config);
+ *
+ * if (!result.valid) {
+ *   console.error('Configuration errors:', result.errors);
+ *   process.exit(1);
+ * }
+ * ```
+ */
+export declare function validateRuVectorConfig(config: RuVectorConfig): ConfigValidationResult;
+/**
+ * Default configuration instance
+ * Created from environment variables at module load time
+ */
+export declare const defaultConfig: RuVectorConfig;
+/**
+ * Create configuration for high-performance scenarios
+ *
+ * Optimized for large-scale deployments with many vectors
+ */
+export declare function createHighPerformanceConfig(dimensions?: number): RuVectorConfig;
+/**
+ * Create configuration for memory-constrained environments
+ *
+ * Optimized for minimal memory usage
+ */
+export declare function createLowMemoryConfig(dimensions?: number): RuVectorConfig;
+/**
+ * Create configuration for hybrid search with graph integration
+ */
+export declare function createHybridSearchConfig(dimensions?: number, graphType?: 'neo4j' | 'memgraph' | 'sqlite'): RuVectorConfig;
+/**
+ * Get recommended configuration based on vector count
+ *
+ * @param estimatedVectorCount - Estimated number of vectors to store
+ * @param dimensions - Vector dimensions
+ * @returns Recommended configuration
+ */
+export declare function getRecommendedConfig(estimatedVectorCount: number, dimensions?: number): RuVectorConfig;
+//# sourceMappingURL=config.d.ts.map

package/dist/vector/config.d.ts.map

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

package/dist/vector/config.js

@@ -0,0 +1,124 @@
+const DEFAULT_HNSW_CONFIG = {
+  m: 16,
+  efConstruction: 200,
+  efSearch: 100
+};
+const DEFAULT_INDEX_CONFIG = {
+  dimensions: 1536,
+  distanceMetric: "cosine",
+  indexType: "hnsw",
+  hnswConfig: DEFAULT_HNSW_CONFIG
+};
+function createRuVectorConfig() {
+  const backend = process.env.RUVECTOR_BACKEND || "memory";
+  const dimensions = parseInt(process.env.RUVECTOR_DIMENSIONS || "384", 10);
+  const baseConfig = {
+    backend,
+    index: {
+      ...DEFAULT_INDEX_CONFIG,
+      dimensions
+    },
+    enableSona: process.env.RUVECTOR_ENABLE_SONA === "true",
+    enableTrajectoryTracking: process.env.RUVECTOR_ENABLE_TRAJECTORY === "true"
+  };
+  switch (backend) {
+    case "postgres":
+      return {
+        ...baseConfig,
+        postgres: {
+          connectionString: process.env.DATABASE_URL || "postgres://localhost:5432/kg_agent",
+          schema: process.env.RUVECTOR_SCHEMA || "ruvector"
+        }
+      };
+    case "cloud":
+      return {
+        ...baseConfig,
+        cloud: {
+          url: process.env.RUVECTOR_CLOUD_URL || "",
+          apiKey: process.env.RUVECTOR_API_KEY
+        }
+      };
+    case "standalone":
+      return {
+        ...baseConfig,
+        standalone: {
+          dataDir: process.env.RUVECTOR_DATA_DIR || ".ruvector"
+        }
+      };
+    default:
+      return baseConfig;
+  }
+}
+function validateRuVectorConfig(config) {
+  const errors = [];
+  const warnings = [];
+  if (config.index.dimensions < 1) {
+    errors.push("Dimensions must be at least 1");
+  }
+  if (config.index.dimensions > 4096) {
+    warnings.push("Dimensions > 4096 may impact performance");
+  }
+  if (!Number.isInteger(config.index.dimensions)) {
+    errors.push("Vector dimensions must be an integer");
+  }
+  if (config.backend === "postgres" && !config.postgres?.connectionString) {
+    errors.push("PostgreSQL connection string required for postgres backend");
+  }
+  if (config.backend === "cloud" && !config.cloud?.url) {
+    errors.push("Cloud URL required for cloud backend");
+  }
+  if (config.backend === "standalone" && !config.standalone?.dataDir) {
+    errors.push("Data directory required for standalone backend");
+  }
+  if (config.index.indexType === "hnsw" && config.index.hnswConfig) {
+    const { m, efConstruction, efSearch } = config.index.hnswConfig;
+    if (m < 2 || m > 100) {
+      errors.push("HNSW m must be between 2 and 100");
+    }
+    if (efConstruction < m) {
+      warnings.push("efConstruction should be >= m for good index quality");
+    }
+    if (efSearch < 10) {
+      warnings.push("efSearch < 10 may result in poor recall");
+    }
+  }
+  if (config.cache?.enabled) {
+    if (config.cache.maxSize < 1) {
+      errors.push("Cache maxSize must be at least 1");
+    }
+    if (config.cache.ttlSeconds < 1) {
+      errors.push("Cache TTL must be at least 1 second");
+    }
+  }
+  if (config.performance) {
+    if (config.performance.batchSize < 1) {
+      errors.push("Batch size must be at least 1");
+    }
+    if (config.performance.maxConcurrency < 1) {
+      errors.push("Max concurrency must be at least 1");
+    }
+    if (config.performance.memoryLimitMb && config.performance.memoryLimitMb < 64) {
+      warnings.push("Memory limit < 64MB may cause issues");
+    }
+  }
+  if (config.hybrid?.enabled && !config.hybrid.graphConnection) {
+    warnings.push("Hybrid search enabled but no graph connection configured");
+  }
+  const validMetrics = ["cosine", "euclidean", "dotProduct", "manhattan"];
+  if (!validMetrics.includes(config.index.distanceMetric)) {
+    errors.push(`Invalid distance metric: ${config.index.distanceMetric}`);
+  }
+  const validIndexTypes = ["hnsw", "flat", "ivf", "pq"];
+  if (!validIndexTypes.includes(config.index.indexType)) {
+    errors.push(`Invalid index type: ${config.index.indexType}`);
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+createRuVectorConfig();
+export {
+  DEFAULT_HNSW_CONFIG,
+  DEFAULT_INDEX_CONFIG,
+  createRuVectorConfig,
+  validateRuVectorConfig
+};
+//# sourceMappingURL=config.js.map

package/dist/vector/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sources":["../../src/vector/config.ts"],"sourcesContent":["/**\n * Vector Configuration\n *\n * Configuration types and defaults for RuVector-compatible vector storage.\n * Supports multiple backends (memory, postgres, standalone) with HNSW indexing.\n *\n * @module vector/config\n */\n\nimport type { DistanceMetric, IndexType, VectorIndexConfig } from './types.js';\n\n/**\n * Backend storage type for vectors\n */\nexport type VectorBackend = 'memory' | 'postgres' | 'standalone' | 'sqlite' | 'cloud';\n\n/**\n * HNSW (Hierarchical Navigable Small World) index configuration\n *\n * HNSW provides fast approximate nearest neighbor search with\n * configurable accuracy/speed tradeoffs.\n */\nexport interface HNSWConfig {\n  /**\n   * Maximum number of connections per layer\n   * Higher values improve recall but increase memory usage\n   * @default 16\n   */\n  m: number;\n\n  /**\n   * Size of dynamic candidate list for construction\n   * Higher values improve index quality but slow down construction\n   * @default 200\n   */\n  efConstruction: number;\n\n  /**\n   * Size of dynamic candidate list for search\n   * Higher values improve recall but slow down search\n   * @default 100\n   */\n  efSearch: number;\n}\n\n/**\n * Re-export VectorIndexConfig from types for convenience\n */\nexport type { VectorIndexConfig } from './types.js';\n\n/**\n * PostgreSQL backend configuration\n */\nexport interface PostgresBackendConfig {\n  /**\n   * PostgreSQL connection string\n   * @example 'postgres://user:pass@localhost:5432/dbname'\n   */\n  connectionString: string;\n\n  /**\n   * Database schema for vector tables\n   * @default 'ruvector'\n   */\n  schema: string;\n}\n\n/**\n * Cloud backend configuration\n */\nexport interface CloudBackendConfig {\n  /**\n   * Cloud vector database endpoint URL\n   */\n  url: string;\n\n  /**\n   * API key for authentication\n   */\n  apiKey?: string;\n}\n\n/**\n * Standalone backend configuration\n */\nexport interface StandaloneBackendConfig {\n  /**\n   * Directory for vector data storage\n   * @default '.ruvector'\n   */\n  dataDir: string;\n}\n\n/**\n * RuVector configuration\n *\n * Main configuration interface for the vector database system.\n */\nexport interface RuVectorConfig {\n  /**\n   * Storage backend type\n   */\n  backend: VectorBackend;\n\n  /**\n   * Vector index configuration\n   */\n  index: VectorIndexConfig;\n\n  /**\n   * PostgreSQL connection configuration\n   * Required when backend is 'postgres'\n   */\n  postgres?: PostgresBackendConfig;\n\n  /**\n   * Cloud endpoint configuration\n   * Required when backend is 'cloud'\n   */\n  cloud?: CloudBackendConfig;\n\n  /**\n   * Standalone file path configuration\n   * Required when backend is 'standalone'\n   */\n  standalone?: StandaloneBackendConfig;\n\n  /**\n   * Enable self-learning SONA (Self-Optimizing Neural Architecture) engine\n   * When enabled, the system learns from agent trajectories to improve performance\n   * @default false\n   */\n  enableSona?: boolean;\n\n  /**\n   * Enable trajectory tracking for agents\n   * Records agent actions for analysis and learning\n   * @default false\n   */\n  enableTrajectoryTracking?: boolean;\n\n  /**\n   * Cache configuration\n   */\n  cache?: {\n    /** Enable result caching */\n    enabled: boolean;\n    /** Maximum cache size in entries */\n    maxSize: number;\n    /** Cache TTL in seconds */\n    ttlSeconds: number;\n  };\n\n  /**\n   * Performance tuning\n   */\n  performance?: {\n    /** Batch size for bulk operations */\n    batchSize: number;\n    /** Enable parallel processing */\n    parallelProcessing: boolean;\n    /** Maximum concurrent operations */\n    maxConcurrency: number;\n    /** Memory limit in MB for index */\n    memoryLimitMb?: number;\n  };\n\n  /**\n   * Hybrid search configuration\n   */\n  hybrid?: {\n    /** Enable hybrid search */\n    enabled: boolean;\n    /** Default vector weight (0-1) */\n    defaultVectorWeight: number;\n    /** Graph database connection (for Cypher queries) */\n    graphConnection?: {\n      type: 'neo4j' | 'memgraph' | 'sqlite';\n      uri?: string;\n      database?: string;\n      auth?: {\n        user: string;\n        password: string;\n      };\n    };\n  };\n\n  /**\n   * Namespace configuration for multi-tenant support\n   */\n  namespace?: {\n    /** Default namespace */\n    defaultNamespace: string;\n    /** Namespace isolation level */\n    isolation: 'soft' | 'hard';\n  };\n}\n\n/**\n * Default HNSW configuration\n * Balanced settings for most use cases\n */\nexport const DEFAULT_HNSW_CONFIG: HNSWConfig = {\n  m: 16,\n  efConstruction: 200,\n  efSearch: 100,\n};\n\n/**\n * Default vector index configuration\n * Optimized for OpenAI/Claude embeddings (1536 dimensions)\n */\nexport const DEFAULT_INDEX_CONFIG: VectorIndexConfig = {\n  dimensions: 1536,\n  distanceMetric: 'cosine',\n  indexType: 'hnsw',\n  hnswConfig: DEFAULT_HNSW_CONFIG,\n};\n\n/**\n * Default cache configuration\n */\nexport const DEFAULT_CACHE_CONFIG = {\n  enabled: true,\n  maxSize: 1000,\n  ttlSeconds: 300, // 5 minutes\n} as const;\n\n/**\n * Default performance configuration\n */\nexport const DEFAULT_PERFORMANCE_CONFIG = {\n  batchSize: 100,\n  parallelProcessing: true,\n  maxConcurrency: 4,\n} as const;\n\n/**\n * Create RuVector configuration from environment variables\n *\n * Reads configuration from the following environment variables:\n * - RUVECTOR_BACKEND: Storage backend type (default: 'memory')\n * - RUVECTOR_DIMENSIONS: Vector dimensions (default: 384)\n * - RUVECTOR_ENABLE_SONA: Enable SONA learning (default: false)\n * - RUVECTOR_ENABLE_TRAJECTORY: Enable trajectory tracking (default: false)\n * - DATABASE_URL: PostgreSQL connection string (for postgres backend)\n * - RUVECTOR_SCHEMA: PostgreSQL schema (default: 'ruvector')\n * - RUVECTOR_CLOUD_URL: Cloud endpoint URL (for cloud backend)\n * - RUVECTOR_API_KEY: Cloud API key (for cloud backend)\n * - RUVECTOR_DATA_DIR: Data directory (for standalone backend)\n *\n * @returns RuVectorConfig configured from environment\n *\n * @example\n * ```typescript\n * // Set environment variables\n * process.env.RUVECTOR_BACKEND = 'postgres';\n * process.env.DATABASE_URL = 'postgres://localhost:5432/mydb';\n *\n * // Create configuration\n * const config = createRuVectorConfig();\n * ```\n */\nexport function createRuVectorConfig(): RuVectorConfig {\n  const backend = (process.env.RUVECTOR_BACKEND || 'memory') as VectorBackend;\n  const dimensions = parseInt(process.env.RUVECTOR_DIMENSIONS || '384', 10);\n\n  const baseConfig: RuVectorConfig = {\n    backend,\n    index: {\n      ...DEFAULT_INDEX_CONFIG,\n      dimensions,\n    },\n    enableSona: process.env.RUVECTOR_ENABLE_SONA === 'true',\n    enableTrajectoryTracking: process.env.RUVECTOR_ENABLE_TRAJECTORY === 'true',\n  };\n\n  switch (backend) {\n    case 'postgres':\n      return {\n        ...baseConfig,\n        postgres: {\n          connectionString:\n            process.env.DATABASE_URL || 'postgres://localhost:5432/kg_agent',\n          schema: process.env.RUVECTOR_SCHEMA || 'ruvector',\n        },\n      };\n    case 'cloud':\n      return {\n        ...baseConfig,\n        cloud: {\n          url: process.env.RUVECTOR_CLOUD_URL || '',\n          apiKey: process.env.RUVECTOR_API_KEY,\n        },\n      };\n    case 'standalone':\n      return {\n        ...baseConfig,\n        standalone: {\n          dataDir: process.env.RUVECTOR_DATA_DIR || '.ruvector',\n        },\n      };\n    default:\n      return baseConfig;\n  }\n}\n\n/**\n * Validation result for RuVector configuration\n */\nexport interface ConfigValidationResult {\n  /**\n   * Whether the configuration is valid\n   */\n  valid: boolean;\n\n  /**\n   * List of validation errors (empty if valid)\n   */\n  errors: string[];\n\n  /**\n   * List of validation warnings\n   */\n  warnings: string[];\n}\n\n/**\n * Legacy alias for backwards compatibility\n */\nexport type ValidationResult = ConfigValidationResult;\n\n/**\n * Validate RuVector configuration\n *\n * Checks that all required fields are present and valid based on\n * the selected backend type.\n *\n * @param config - Configuration to validate\n * @returns Validation result with errors if invalid\n *\n * @example\n * ```typescript\n * const config = createRuVectorConfig();\n * const result = validateRuVectorConfig(config);\n *\n * if (!result.valid) {\n *   console.error('Configuration errors:', result.errors);\n *   process.exit(1);\n * }\n * ```\n */\nexport function validateRuVectorConfig(config: RuVectorConfig): ConfigValidationResult {\n  const errors: string[] = [];\n  const warnings: string[] = [];\n\n  // Validate dimensions\n  if (config.index.dimensions < 1) {\n    errors.push('Dimensions must be at least 1');\n  }\n  if (config.index.dimensions > 4096) {\n    warnings.push('Dimensions > 4096 may impact performance');\n  }\n\n  if (!Number.isInteger(config.index.dimensions)) {\n    errors.push('Vector dimensions must be an integer');\n  }\n\n  // Validate backend-specific configuration\n  if (config.backend === 'postgres' && !config.postgres?.connectionString) {\n    errors.push('PostgreSQL connection string required for postgres backend');\n  }\n\n  if (config.backend === 'cloud' && !config.cloud?.url) {\n    errors.push('Cloud URL required for cloud backend');\n  }\n\n  if (config.backend === 'standalone' && !config.standalone?.dataDir) {\n    errors.push('Data directory required for standalone backend');\n  }\n\n  // Validate HNSW configuration\n  if (config.index.indexType === 'hnsw' && config.index.hnswConfig) {\n    const { m, efConstruction, efSearch } = config.index.hnswConfig;\n\n    if (m < 2 || m > 100) {\n      errors.push('HNSW m must be between 2 and 100');\n    }\n\n    if (efConstruction < m) {\n      warnings.push('efConstruction should be >= m for good index quality');\n    }\n\n    if (efSearch < 10) {\n      warnings.push('efSearch < 10 may result in poor recall');\n    }\n  }\n\n  // Validate cache config\n  if (config.cache?.enabled) {\n    if (config.cache.maxSize < 1) {\n      errors.push('Cache maxSize must be at least 1');\n    }\n    if (config.cache.ttlSeconds < 1) {\n      errors.push('Cache TTL must be at least 1 second');\n    }\n  }\n\n  // Validate performance config\n  if (config.performance) {\n    if (config.performance.batchSize < 1) {\n      errors.push('Batch size must be at least 1');\n    }\n    if (config.performance.maxConcurrency < 1) {\n      errors.push('Max concurrency must be at least 1');\n    }\n    if (config.performance.memoryLimitMb && config.performance.memoryLimitMb < 64) {\n      warnings.push('Memory limit < 64MB may cause issues');\n    }\n  }\n\n  // Validate hybrid config\n  if (config.hybrid?.enabled && !config.hybrid.graphConnection) {\n    warnings.push('Hybrid search enabled but no graph connection configured');\n  }\n\n  // Validate distance metric\n  const validMetrics: DistanceMetric[] = ['cosine', 'euclidean', 'dotProduct', 'manhattan'];\n  if (!validMetrics.includes(config.index.distanceMetric)) {\n    errors.push(`Invalid distance metric: ${config.index.distanceMetric}`);\n  }\n\n  // Validate index type\n  const validIndexTypes = ['hnsw', 'flat', 'ivf', 'pq'];\n  if (!validIndexTypes.includes(config.index.indexType)) {\n    errors.push(`Invalid index type: ${config.index.indexType}`);\n  }\n\n  return { valid: errors.length === 0, errors, warnings };\n}\n\n/**\n * Default configuration instance\n * Created from environment variables at module load time\n */\nexport const defaultConfig = createRuVectorConfig();\n\n/**\n * Create configuration for high-performance scenarios\n *\n * Optimized for large-scale deployments with many vectors\n */\nexport function createHighPerformanceConfig(\n  dimensions: number = 1536\n): RuVectorConfig {\n  return {\n    ...createRuVectorConfig(),\n    backend: 'memory',\n    index: {\n      dimensions,\n      indexType: 'hnsw',\n      distanceMetric: 'cosine',\n      hnswConfig: {\n        m: 32, // More connections for better recall\n        efConstruction: 400, // Higher quality index\n        efSearch: 200, // Better search accuracy\n      },\n    },\n    cache: {\n      enabled: true,\n      maxSize: 10000,\n      ttlSeconds: 600,\n    },\n    performance: {\n      batchSize: 500,\n      parallelProcessing: true,\n      maxConcurrency: 8,\n    },\n  };\n}\n\n/**\n * Create configuration for memory-constrained environments\n *\n * Optimized for minimal memory usage\n */\nexport function createLowMemoryConfig(\n  dimensions: number = 1536\n): RuVectorConfig {\n  return {\n    ...createRuVectorConfig(),\n    backend: 'memory',\n    index: {\n      dimensions,\n      indexType: 'hnsw',\n      distanceMetric: 'cosine',\n      hnswConfig: {\n        m: 8, // Fewer connections\n        efConstruction: 100, // Faster construction\n        efSearch: 50, // Faster search\n      },\n    },\n    cache: {\n      enabled: false,\n      maxSize: 100,\n      ttlSeconds: 60,\n    },\n    performance: {\n      batchSize: 50,\n      parallelProcessing: false,\n      maxConcurrency: 2,\n      memoryLimitMb: 256,\n    },\n  };\n}\n\n/**\n * Create configuration for hybrid search with graph integration\n */\nexport function createHybridSearchConfig(\n  dimensions: number = 1536,\n  graphType: 'neo4j' | 'memgraph' | 'sqlite' = 'sqlite'\n): RuVectorConfig {\n  return {\n    ...createRuVectorConfig(),\n    backend: 'memory',\n    index: {\n      dimensions,\n      indexType: 'hnsw',\n      distanceMetric: 'cosine',\n      hnswConfig: DEFAULT_HNSW_CONFIG,\n    },\n    hybrid: {\n      enabled: true,\n      defaultVectorWeight: 0.7,\n      graphConnection: {\n        type: graphType,\n      },\n    },\n  };\n}\n\n/**\n * Get recommended configuration based on vector count\n *\n * @param estimatedVectorCount - Estimated number of vectors to store\n * @param dimensions - Vector dimensions\n * @returns Recommended configuration\n */\nexport function getRecommendedConfig(\n  estimatedVectorCount: number,\n  dimensions: number = 1536\n): RuVectorConfig {\n  if (estimatedVectorCount < 1000) {\n    // Small scale - flat index is fine\n    return createLowMemoryConfig(dimensions);\n  } else if (estimatedVectorCount < 100000) {\n    // Medium scale - standard HNSW\n    return {\n      ...createRuVectorConfig(),\n      index: { ...DEFAULT_INDEX_CONFIG, dimensions },\n    };\n  } else {\n    // Large scale - optimized HNSW\n    return createHighPerformanceConfig(dimensions);\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/vector/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Vector Module
+ *
+ * Exports all vector-related functionality for the knowledge-graph-agent.
+ * This module provides configuration, types, services, and utilities for working
+ * with vector embeddings, similarity search, and agent trajectory tracking.
+ *
+ * @module vector
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createRuVectorConfig,
+ *   validateRuVectorConfig,
+ *   createVectorStore,
+ *   createTrajectoryTracker,
+ *   type VectorEntry,
+ *   type SearchResult,
+ *   type HybridSearchQuery,
+ * } from './vector/index.js';
+ *
+ * // Create and validate configuration
+ * const config = createRuVectorConfig();
+ * const validation = validateRuVectorConfig(config);
+ *
+ * if (!validation.valid) {
+ *   throw new Error(`Invalid config: ${validation.errors.join(', ')}`);
+ * }
+ *
+ * // Create a trajectory tracker for agent operations
+ * const tracker = createTrajectoryTracker({
+ *   maxTrajectories: 1000,
+ *   enableAutoLearning: true,
+ * });
+ *
+ * // Track agent operations
+ * const trajectoryId = tracker.startTrajectory('agent-1');
+ * tracker.addStep(trajectoryId, {
+ *   action: 'search',
+ *   state: { query: 'example' },
+ *   outcome: 'success',
+ *   duration: 100
+ * });
+ * tracker.finalizeTrajectory(trajectoryId, { success: true });
+ * ```
+ */
+export { createRuVectorConfig, createHighPerformanceConfig, createLowMemoryConfig, createHybridSearchConfig, validateRuVectorConfig, getRecommendedConfig, DEFAULT_HNSW_CONFIG, DEFAULT_INDEX_CONFIG, DEFAULT_CACHE_CONFIG, DEFAULT_PERFORMANCE_CONFIG, defaultConfig, type RuVectorConfig, type VectorBackend, type ConfigValidationResult, type ValidationResult, type HNSWConfig, type PostgresBackendConfig, type CloudBackendConfig, type StandaloneBackendConfig, } from './config.js';
+export type { DistanceMetric, IndexType, SearchSource, VectorEntry, SearchResult, HybridSearchQuery, HybridSearchResult, BatchInsertEntry, BatchInsertOperation, BatchInsertResult, VectorIndexStats, VectorSearchOptions, VectorIndexConfig, VectorStoreEvent, VectorStoreEventListener, IVectorStore, TrajectoryStep, AgentTrajectory, SonaLearningRecord, GraphNode, GraphEdge, CypherQueryResult, VectorUpdateOperation, VectorDeleteOperation, VectorDeleteResult, VectorNamespace, } from './types.js';
+export { EnhancedVectorStore, createVectorStore, TrajectoryTracker, createTrajectoryTracker, type TrajectoryTrackerConfig, type DetectedPattern, } from './services/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/vector/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/vector/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAGH,OAAO,EACL,oBAAoB,EACpB,2BAA2B,EAC3B,qBAAqB,EACrB,wBAAwB,EACxB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,oBAAoB,EACpB,oBAAoB,EACpB,0BAA0B,EAC1B,aAAa,EACb,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,sBAAsB,EAC3B,KAAK,gBAAgB,EACrB,KAAK,UAAU,EACf,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,uBAAuB,GAC7B,MAAM,aAAa,CAAC;AAGrB,YAAY,EACV,cAAc,EACd,SAAS,EACT,YAAY,EACZ,WAAW,EACX,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,gBAAgB,EAChB,wBAAwB,EACxB,YAAY,EACZ,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,eAAe,GAChB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,mBAAmB,EACnB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAC"}

package/dist/vector/services/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Vector Services
+ *
+ * Exports all vector service modules for the knowledge-graph-agent.
+ * Includes:
+ * - Vector store for HNSW-based similarity search
+ * - Trajectory tracker for agent operation logging and self-learning
+ *
+ * @module vector/services
+ */
+export { EnhancedVectorStore, createVectorStore } from './vector-store.js';
+export { TrajectoryTracker, createTrajectoryTracker, type TrajectoryTrackerConfig, type DetectedPattern, } from './trajectory-tracker.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/vector/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/vector/services/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3E,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EACvB,KAAK,uBAAuB,EAC5B,KAAK,eAAe,GACrB,MAAM,yBAAyB,CAAC"}