@yamo/memory-mesh 2.3.2 → 3.0.0

package/lib/memory/adapters/config.d.ts

@@ -0,0 +1,137 @@
+/**
+ * LanceDB Configuration Loader
+ * Loads and validates configuration from environment variables
+ */
+/**
+ * Default configuration values
+ */
+export declare const DEFAULTS: {
+    readonly LANCEDB_URI: "./runtime/data/lancedb";
+    readonly LANCEDB_MEMORY_TABLE: "memory_entries";
+    readonly LANCEDB_MAX_CACHE_SIZE: "2GB";
+    readonly EMBEDDING_MODEL_TYPE: "local";
+    readonly EMBEDDING_MODEL_NAME: "Xenova/all-MiniLM-L6-v2";
+    readonly EMBEDDING_DIMENSION: "384";
+    readonly EMBEDDING_BATCH_SIZE: "32";
+    readonly EMBEDDING_NORMALIZE: "true";
+    readonly OPENAI_EMBEDDING_MODEL: "text-embedding-3-small";
+    readonly DEFAULT_TOP_K: "10";
+    readonly DEFAULT_SIMILARITY_THRESHOLD: "0.7";
+    readonly ENABLE_HYBRID_SEARCH: "true";
+    readonly HYBRID_SEARCH_ALPHA: "0.5";
+    readonly VECTOR_INDEX_TYPE: "ivf_pq";
+    readonly IVF_PARTITIONS: "256";
+    readonly PQ_BITS: "8";
+    readonly ENABLE_QUERY_CACHE: "true";
+    readonly QUERY_CACHE_TTL: "300";
+};
+export type ConfigKey = keyof typeof DEFAULTS;
+export type Config = Record<ConfigKey, string>;
+/**
+ * Memory system configuration defaults
+ */
+export declare const MEMORY_DEFAULTS: {
+    readonly MEMORY_ENABLED: "true";
+    readonly MEMORY_AUTO_CAPTURE: "true";
+    readonly MEMORY_AUTO_RECALL: "true";
+    readonly MEMORY_MAX_CONTEXT: "5";
+    readonly MEMORY_RELEVANCE_THRESHOLD: "0.7";
+    readonly MEMORY_IMPORTANCE_BOOST: "1.5";
+    readonly MEMORY_RECENCY_WEIGHT: "0.3";
+    readonly MEMORY_MIN_IMPORTANCE: "0.3";
+    readonly MEMORY_DEDUP_THRESHOLD: "0.9";
+    readonly MEMORY_CAPTURE_TOOL_RESULTS: "true";
+    readonly MEMORY_CAPTURE_FILE_OPS: "true";
+    readonly MEMORY_RETENTION_ENABLED: "true";
+    readonly MEMORY_RETENTION_DAYS: "90";
+    readonly MEMORY_MAX_PER_SESSION: "100";
+    readonly MEMORY_MIN_IMPORTANCE_TO_KEEP: "0.5";
+    readonly MEMORY_REDACT_PII: "false";
+    readonly MEMORY_ENCRYPTION_ENABLED: "false";
+};
+export interface MemoryConfig {
+    enabled: boolean;
+    autoCapture: boolean;
+    autoRecall: boolean;
+    maxContext: number;
+    relevanceThreshold: number;
+    importanceBoost: number;
+    recencyWeight: number;
+    minImportance: number;
+    dedupThreshold: number;
+    captureToolResults: boolean;
+    captureFileOps: boolean;
+    retention: {
+        enabled: boolean;
+        days: number;
+        maxPerSession: number;
+        minImportanceToKeep: number;
+    };
+    privacy: {
+        redactPii: boolean;
+        encryptionEnabled: boolean;
+    };
+}
+/**
+ * Load configuration with validation
+ */
+export declare function loadConfig(): Config;
+/**
+ * Load memory-specific configuration
+ * @returns {Object} Memory configuration object
+ */
+export declare function loadMemoryConfig(): MemoryConfig;
+/**
+ * Validate configuration
+ */
+export declare function validateConfig(config: Config): string[];
+/**
+ * Get validated configuration
+ */
+export declare function getConfig(): Config;
+declare const _default: {
+    loadConfig: typeof loadConfig;
+    validateConfig: typeof validateConfig;
+    getConfig: typeof getConfig;
+    loadMemoryConfig: typeof loadMemoryConfig;
+    DEFAULTS: {
+        readonly LANCEDB_URI: "./runtime/data/lancedb";
+        readonly LANCEDB_MEMORY_TABLE: "memory_entries";
+        readonly LANCEDB_MAX_CACHE_SIZE: "2GB";
+        readonly EMBEDDING_MODEL_TYPE: "local";
+        readonly EMBEDDING_MODEL_NAME: "Xenova/all-MiniLM-L6-v2";
+        readonly EMBEDDING_DIMENSION: "384";
+        readonly EMBEDDING_BATCH_SIZE: "32";
+        readonly EMBEDDING_NORMALIZE: "true";
+        readonly OPENAI_EMBEDDING_MODEL: "text-embedding-3-small";
+        readonly DEFAULT_TOP_K: "10";
+        readonly DEFAULT_SIMILARITY_THRESHOLD: "0.7";
+        readonly ENABLE_HYBRID_SEARCH: "true";
+        readonly HYBRID_SEARCH_ALPHA: "0.5";
+        readonly VECTOR_INDEX_TYPE: "ivf_pq";
+        readonly IVF_PARTITIONS: "256";
+        readonly PQ_BITS: "8";
+        readonly ENABLE_QUERY_CACHE: "true";
+        readonly QUERY_CACHE_TTL: "300";
+    };
+    MEMORY_DEFAULTS: {
+        readonly MEMORY_ENABLED: "true";
+        readonly MEMORY_AUTO_CAPTURE: "true";
+        readonly MEMORY_AUTO_RECALL: "true";
+        readonly MEMORY_MAX_CONTEXT: "5";
+        readonly MEMORY_RELEVANCE_THRESHOLD: "0.7";
+        readonly MEMORY_IMPORTANCE_BOOST: "1.5";
+        readonly MEMORY_RECENCY_WEIGHT: "0.3";
+        readonly MEMORY_MIN_IMPORTANCE: "0.3";
+        readonly MEMORY_DEDUP_THRESHOLD: "0.9";
+        readonly MEMORY_CAPTURE_TOOL_RESULTS: "true";
+        readonly MEMORY_CAPTURE_FILE_OPS: "true";
+        readonly MEMORY_RETENTION_ENABLED: "true";
+        readonly MEMORY_RETENTION_DAYS: "90";
+        readonly MEMORY_MAX_PER_SESSION: "100";
+        readonly MEMORY_MIN_IMPORTANCE_TO_KEEP: "0.5";
+        readonly MEMORY_REDACT_PII: "false";
+        readonly MEMORY_ENCRYPTION_ENABLED: "false";
+    };
+};
+export default _default;

package/lib/memory/adapters/config.js

@@ -0,0 +1,189 @@
+/**
+ * LanceDB Configuration Loader
+ * Loads and validates configuration from environment variables
+ */
+import path from "path";
+/**
+ * Default configuration values
+ */
+export const DEFAULTS = {
+    // LanceDB Configuration
+    LANCEDB_URI: "./runtime/data/lancedb",
+    LANCEDB_MEMORY_TABLE: "memory_entries",
+    LANCEDB_MAX_CACHE_SIZE: "2GB",
+    // Embedding Model Configuration
+    EMBEDDING_MODEL_TYPE: "local",
+    EMBEDDING_MODEL_NAME: "Xenova/all-MiniLM-L6-v2",
+    EMBEDDING_DIMENSION: "384",
+    EMBEDDING_BATCH_SIZE: "32",
+    EMBEDDING_NORMALIZE: "true",
+    // API-based Embeddings
+    OPENAI_EMBEDDING_MODEL: "text-embedding-3-small",
+    // Search Configuration
+    DEFAULT_TOP_K: "10",
+    DEFAULT_SIMILARITY_THRESHOLD: "0.7",
+    ENABLE_HYBRID_SEARCH: "true",
+    HYBRID_SEARCH_ALPHA: "0.5",
+    // Performance Tuning
+    VECTOR_INDEX_TYPE: "ivf_pq",
+    IVF_PARTITIONS: "256",
+    PQ_BITS: "8",
+    ENABLE_QUERY_CACHE: "true",
+    QUERY_CACHE_TTL: "300",
+};
+/**
+ * Memory system configuration defaults
+ */
+export const MEMORY_DEFAULTS = {
+    // Feature flags
+    MEMORY_ENABLED: "true",
+    MEMORY_AUTO_CAPTURE: "true",
+    MEMORY_AUTO_RECALL: "true",
+    // Recall settings
+    MEMORY_MAX_CONTEXT: "5",
+    MEMORY_RELEVANCE_THRESHOLD: "0.7",
+    MEMORY_IMPORTANCE_BOOST: "1.5",
+    MEMORY_RECENCY_WEIGHT: "0.3",
+    // Capture settings
+    MEMORY_MIN_IMPORTANCE: "0.3",
+    MEMORY_DEDUP_THRESHOLD: "0.9",
+    MEMORY_CAPTURE_TOOL_RESULTS: "true",
+    MEMORY_CAPTURE_FILE_OPS: "true",
+    // Retention settings
+    MEMORY_RETENTION_ENABLED: "true",
+    MEMORY_RETENTION_DAYS: "90",
+    MEMORY_MAX_PER_SESSION: "100",
+    MEMORY_MIN_IMPORTANCE_TO_KEEP: "0.5",
+    // Privacy settings
+    MEMORY_REDACT_PII: "false",
+    MEMORY_ENCRYPTION_ENABLED: "false",
+};
+/**
+ * Load configuration with validation
+ */
+export function loadConfig() {
+    const config = {};
+    for (const [key, defaultValue] of Object.entries(DEFAULTS)) {
+        config[key] = process.env[key] || defaultValue;
+    }
+    // Resolve relative paths to absolute relative to package root
+    if (config.LANCEDB_URI &&
+        (config.LANCEDB_URI.startsWith("./") ||
+            config.LANCEDB_URI.startsWith("../"))) {
+        const currentFileUrl = import.meta.url;
+        const currentFilePath = new URL(currentFileUrl).pathname;
+        // config.ts is in lib/brain/adapters, so package root is ../../../
+        const packageRoot = path.resolve(path.dirname(currentFilePath), "../../../");
+        config.LANCEDB_URI = path.resolve(packageRoot, config.LANCEDB_URI);
+    }
+    return config;
+}
+/**
+ * Load memory-specific configuration
+ * @returns {Object} Memory configuration object
+ */
+export function loadMemoryConfig() {
+    return {
+        enabled: process.env.MEMORY_ENABLED !== "false",
+        autoCapture: process.env.MEMORY_AUTO_CAPTURE !== "false",
+        autoRecall: process.env.MEMORY_AUTO_RECALL !== "false",
+        maxContext: parseInt(process.env.MEMORY_MAX_CONTEXT || "5"),
+        relevanceThreshold: parseFloat(process.env.MEMORY_RELEVANCE_THRESHOLD || "0.7"),
+        importanceBoost: parseFloat(process.env.MEMORY_IMPORTANCE_BOOST || "1.5"),
+        recencyWeight: parseFloat(process.env.MEMORY_RECENCY_WEIGHT || "0.3"),
+        minImportance: parseFloat(process.env.MEMORY_MIN_IMPORTANCE || "0.3"),
+        dedupThreshold: parseFloat(process.env.MEMORY_DEDUP_THRESHOLD || "0.9"),
+        captureToolResults: process.env.MEMORY_CAPTURE_TOOL_RESULTS !== "false",
+        captureFileOps: process.env.MEMORY_CAPTURE_FILE_OPS !== "false",
+        retention: {
+            enabled: process.env.MEMORY_RETENTION_ENABLED !== "false",
+            days: parseInt(process.env.MEMORY_RETENTION_DAYS || "90"),
+            maxPerSession: parseInt(process.env.MEMORY_MAX_PER_SESSION || "100"),
+            minImportanceToKeep: parseFloat(process.env.MEMORY_MIN_IMPORTANCE_TO_KEEP || "0.5"),
+        },
+        privacy: {
+            redactPii: process.env.MEMORY_REDACT_PII === "true",
+            encryptionEnabled: process.env.MEMORY_ENCRYPTION_ENABLED === "true",
+        },
+    };
+}
+/**
+ * Validate configuration
+ */
+export function validateConfig(config) {
+    const errors = [];
+    // Validate embedding model type
+    const validModelTypes = ["local", "openai", "cohere", "voyage"];
+    if (!validModelTypes.includes(config.EMBEDDING_MODEL_TYPE)) {
+        errors.push(`Invalid EMBEDDING_MODEL_TYPE: ${config.EMBEDDING_MODEL_TYPE}`);
+    }
+    // Validate numeric values
+    const dimension = parseInt(config.EMBEDDING_DIMENSION);
+    if (isNaN(dimension) || dimension <= 0) {
+        errors.push(`Invalid EMBEDDING_DIMENSION: ${config.EMBEDDING_DIMENSION}`);
+    }
+    const topK = parseInt(config.DEFAULT_TOP_K);
+    if (isNaN(topK) || topK <= 0) {
+        errors.push(`Invalid DEFAULT_TOP_K: ${config.DEFAULT_TOP_K}`);
+    }
+    // Validate boolean strings
+    const boolFields = [
+        "EMBEDDING_NORMALIZE",
+        "ENABLE_HYBRID_SEARCH",
+        "ENABLE_QUERY_CACHE",
+    ];
+    for (const field of boolFields) {
+        const value = config[field].toLowerCase();
+        if (value !== "true" && value !== "false") {
+            errors.push(`Invalid ${field}: must be 'true' or 'false'`);
+        }
+    }
+    // Validate similarity threshold (0-1 range)
+    const threshold = parseFloat(config.DEFAULT_SIMILARITY_THRESHOLD);
+    if (isNaN(threshold) || threshold < 0 || threshold > 1) {
+        errors.push(`Invalid DEFAULT_SIMILARITY_THRESHOLD: must be between 0 and 1`);
+    }
+    // Validate hybrid search alpha (0-1 range)
+    const alpha = parseFloat(config.HYBRID_SEARCH_ALPHA);
+    if (isNaN(alpha) || alpha < 0 || alpha > 1) {
+        errors.push(`Invalid HYBRID_SEARCH_ALPHA: must be between 0 and 1`);
+    }
+    // Validate positive integers
+    const positiveIntFields = [
+        "EMBEDDING_BATCH_SIZE",
+        "IVF_PARTITIONS",
+        "PQ_BITS",
+        "QUERY_CACHE_TTL",
+    ];
+    for (const field of positiveIntFields) {
+        const value = parseInt(config[field]);
+        if (isNaN(value) || value <= 0) {
+            errors.push(`Invalid ${field}: must be a positive integer`);
+        }
+    }
+    // Validate cache size format (e.g., "2GB", "500MB")
+    const cacheSizePattern = /^\d+(\.\d+)?(KB|MB|GB|TB)$/;
+    if (!cacheSizePattern.test(config.LANCEDB_MAX_CACHE_SIZE)) {
+        errors.push(`Invalid LANCEDB_MAX_CACHE_SIZE: must match pattern like "2GB", "500MB"`);
+    }
+    return errors;
+}
+/**
+ * Get validated configuration
+ */
+export function getConfig() {
+    const config = loadConfig();
+    const errors = validateConfig(config);
+    if (errors.length > 0) {
+        throw new Error(`Configuration validation failed:\n${errors.join("\n")}`);
+    }
+    return config;
+}
+export default {
+    loadConfig,
+    validateConfig,
+    getConfig,
+    loadMemoryConfig,
+    DEFAULTS,
+    MEMORY_DEFAULTS,
+};

package/lib/memory/adapters/config.ts

@@ -0,0 +1,259 @@
+/**
+ * LanceDB Configuration Loader
+ * Loads and validates configuration from environment variables
+ */
+
+import path from "path";
+
+/**
+ * Default configuration values
+ */
+export const DEFAULTS = {
+  // LanceDB Configuration
+  LANCEDB_URI: "./runtime/data/lancedb",
+  LANCEDB_MEMORY_TABLE: "memory_entries",
+  LANCEDB_MAX_CACHE_SIZE: "2GB",
+
+  // Embedding Model Configuration
+  EMBEDDING_MODEL_TYPE: "local",
+  EMBEDDING_MODEL_NAME: "Xenova/all-MiniLM-L6-v2",
+  EMBEDDING_DIMENSION: "384",
+  EMBEDDING_BATCH_SIZE: "32",
+  EMBEDDING_NORMALIZE: "true",
+
+  // API-based Embeddings
+  OPENAI_EMBEDDING_MODEL: "text-embedding-3-small",
+
+  // Search Configuration
+  DEFAULT_TOP_K: "10",
+  DEFAULT_SIMILARITY_THRESHOLD: "0.7",
+  ENABLE_HYBRID_SEARCH: "true",
+  HYBRID_SEARCH_ALPHA: "0.5",
+
+  // Performance Tuning
+  VECTOR_INDEX_TYPE: "ivf_pq",
+  IVF_PARTITIONS: "256",
+  PQ_BITS: "8",
+  ENABLE_QUERY_CACHE: "true",
+  QUERY_CACHE_TTL: "300",
+} as const;
+
+export type ConfigKey = keyof typeof DEFAULTS;
+export type Config = Record<ConfigKey, string>;
+
+/**
+ * Memory system configuration defaults
+ */
+export const MEMORY_DEFAULTS = {
+  // Feature flags
+  MEMORY_ENABLED: "true",
+  MEMORY_AUTO_CAPTURE: "true",
+  MEMORY_AUTO_RECALL: "true",
+
+  // Recall settings
+  MEMORY_MAX_CONTEXT: "5",
+  MEMORY_RELEVANCE_THRESHOLD: "0.7",
+  MEMORY_IMPORTANCE_BOOST: "1.5",
+  MEMORY_RECENCY_WEIGHT: "0.3",
+
+  // Capture settings
+  MEMORY_MIN_IMPORTANCE: "0.3",
+  MEMORY_DEDUP_THRESHOLD: "0.9",
+  MEMORY_CAPTURE_TOOL_RESULTS: "true",
+  MEMORY_CAPTURE_FILE_OPS: "true",
+
+  // Retention settings
+  MEMORY_RETENTION_ENABLED: "true",
+  MEMORY_RETENTION_DAYS: "90",
+  MEMORY_MAX_PER_SESSION: "100",
+  MEMORY_MIN_IMPORTANCE_TO_KEEP: "0.5",
+
+  // Privacy settings
+  MEMORY_REDACT_PII: "false",
+  MEMORY_ENCRYPTION_ENABLED: "false",
+} as const;
+
+export interface MemoryConfig {
+  enabled: boolean;
+  autoCapture: boolean;
+  autoRecall: boolean;
+  maxContext: number;
+  relevanceThreshold: number;
+  importanceBoost: number;
+  recencyWeight: number;
+  minImportance: number;
+  dedupThreshold: number;
+  captureToolResults: boolean;
+  captureFileOps: boolean;
+  retention: {
+    enabled: boolean;
+    days: number;
+    maxPerSession: number;
+    minImportanceToKeep: number;
+  };
+  privacy: {
+    redactPii: boolean;
+    encryptionEnabled: boolean;
+  };
+}
+
+/**
+ * Load configuration with validation
+ */
+export function loadConfig(): Config {
+  const config: Partial<Config> = {};
+
+  for (const [key, defaultValue] of Object.entries(DEFAULTS)) {
+    config[key as ConfigKey] = process.env[key] || defaultValue;
+  }
+
+  // Resolve relative paths to absolute relative to package root
+  if (
+    config.LANCEDB_URI &&
+    (config.LANCEDB_URI.startsWith("./") ||
+      config.LANCEDB_URI.startsWith("../"))
+  ) {
+    const currentFileUrl = import.meta.url;
+    const currentFilePath = new URL(currentFileUrl).pathname;
+    // config.ts is in lib/brain/adapters, so package root is ../../../
+    const packageRoot = path.resolve(
+      path.dirname(currentFilePath),
+      "../../../",
+    );
+    config.LANCEDB_URI = path.resolve(packageRoot, config.LANCEDB_URI);
+  }
+
+  return config as Config;
+}
+
+/**
+ * Load memory-specific configuration
+ * @returns {Object} Memory configuration object
+ */
+export function loadMemoryConfig(): MemoryConfig {
+  return {
+    enabled: process.env.MEMORY_ENABLED !== "false",
+    autoCapture: process.env.MEMORY_AUTO_CAPTURE !== "false",
+    autoRecall: process.env.MEMORY_AUTO_RECALL !== "false",
+    maxContext: parseInt(process.env.MEMORY_MAX_CONTEXT || "5"),
+    relevanceThreshold: parseFloat(
+      process.env.MEMORY_RELEVANCE_THRESHOLD || "0.7",
+    ),
+    importanceBoost: parseFloat(process.env.MEMORY_IMPORTANCE_BOOST || "1.5"),
+    recencyWeight: parseFloat(process.env.MEMORY_RECENCY_WEIGHT || "0.3"),
+    minImportance: parseFloat(process.env.MEMORY_MIN_IMPORTANCE || "0.3"),
+    dedupThreshold: parseFloat(process.env.MEMORY_DEDUP_THRESHOLD || "0.9"),
+    captureToolResults: process.env.MEMORY_CAPTURE_TOOL_RESULTS !== "false",
+    captureFileOps: process.env.MEMORY_CAPTURE_FILE_OPS !== "false",
+    retention: {
+      enabled: process.env.MEMORY_RETENTION_ENABLED !== "false",
+      days: parseInt(process.env.MEMORY_RETENTION_DAYS || "90"),
+      maxPerSession: parseInt(process.env.MEMORY_MAX_PER_SESSION || "100"),
+      minImportanceToKeep: parseFloat(
+        process.env.MEMORY_MIN_IMPORTANCE_TO_KEEP || "0.5",
+      ),
+    },
+    privacy: {
+      redactPii: process.env.MEMORY_REDACT_PII === "true",
+      encryptionEnabled: process.env.MEMORY_ENCRYPTION_ENABLED === "true",
+    },
+  };
+}
+
+/**
+ * Validate configuration
+ */
+export function validateConfig(config: Config): string[] {
+  const errors: string[] = [];
+
+  // Validate embedding model type
+  const validModelTypes = ["local", "openai", "cohere", "voyage"];
+  if (!validModelTypes.includes(config.EMBEDDING_MODEL_TYPE)) {
+    errors.push(`Invalid EMBEDDING_MODEL_TYPE: ${config.EMBEDDING_MODEL_TYPE}`);
+  }
+
+  // Validate numeric values
+  const dimension = parseInt(config.EMBEDDING_DIMENSION);
+  if (isNaN(dimension) || dimension <= 0) {
+    errors.push(`Invalid EMBEDDING_DIMENSION: ${config.EMBEDDING_DIMENSION}`);
+  }
+
+  const topK = parseInt(config.DEFAULT_TOP_K);
+  if (isNaN(topK) || topK <= 0) {
+    errors.push(`Invalid DEFAULT_TOP_K: ${config.DEFAULT_TOP_K}`);
+  }
+
+  // Validate boolean strings
+  const boolFields: (keyof Config)[] = [
+    "EMBEDDING_NORMALIZE",
+    "ENABLE_HYBRID_SEARCH",
+    "ENABLE_QUERY_CACHE",
+  ];
+  for (const field of boolFields) {
+    const value = config[field].toLowerCase();
+    if (value !== "true" && value !== "false") {
+      errors.push(`Invalid ${field}: must be 'true' or 'false'`);
+    }
+  }
+
+  // Validate similarity threshold (0-1 range)
+  const threshold = parseFloat(config.DEFAULT_SIMILARITY_THRESHOLD);
+  if (isNaN(threshold) || threshold < 0 || threshold > 1) {
+    errors.push(
+      `Invalid DEFAULT_SIMILARITY_THRESHOLD: must be between 0 and 1`,
+    );
+  }
+
+  // Validate hybrid search alpha (0-1 range)
+  const alpha = parseFloat(config.HYBRID_SEARCH_ALPHA);
+  if (isNaN(alpha) || alpha < 0 || alpha > 1) {
+    errors.push(`Invalid HYBRID_SEARCH_ALPHA: must be between 0 and 1`);
+  }
+
+  // Validate positive integers
+  const positiveIntFields: (keyof Config)[] = [
+    "EMBEDDING_BATCH_SIZE",
+    "IVF_PARTITIONS",
+    "PQ_BITS",
+    "QUERY_CACHE_TTL",
+  ];
+  for (const field of positiveIntFields) {
+    const value = parseInt(config[field]);
+    if (isNaN(value) || value <= 0) {
+      errors.push(`Invalid ${field}: must be a positive integer`);
+    }
+  }
+
+  // Validate cache size format (e.g., "2GB", "500MB")
+  const cacheSizePattern = /^\d+(\.\d+)?(KB|MB|GB|TB)$/;
+  if (!cacheSizePattern.test(config.LANCEDB_MAX_CACHE_SIZE)) {
+    errors.push(
+      `Invalid LANCEDB_MAX_CACHE_SIZE: must match pattern like "2GB", "500MB"`,
+    );
+  }
+
+  return errors;
+}
+
+/**
+ * Get validated configuration
+ */
+export function getConfig(): Config {
+  const config = loadConfig();
+  const errors = validateConfig(config);
+
+  if (errors.length > 0) {
+    throw new Error(`Configuration validation failed:\n${errors.join("\n")}`);
+  }
+
+  return config;
+}
+
+export default {
+  loadConfig,
+  validateConfig,
+  getConfig,
+  loadMemoryConfig,
+  DEFAULTS,
+  MEMORY_DEFAULTS,
+};

package/lib/memory/adapters/errors.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Custom error classes for LanceDB operations
+ *
+ * Base error class for all LanceDB-related errors. Captures proper stack traces
+ * to ensure debugging information points to where errors are thrown, not to the
+ * error constructor.
+ */
+export declare class LanceDBError extends Error {
+    code: string;
+    details: Record<string, any>;
+    timestamp: string;
+    /**
+     * Create a new LanceDBError
+     * @param {string} message - Human-readable error message
+     * @param {string} code - Machine-readable error code (e.g., 'EMBEDDING_ERROR')
+     * @param {Object} details - Additional error context and metadata
+     */
+    constructor(message: string, code: string, details?: Record<string, any>);
+}
+/**
+ * Error raised when embedding generation or comparison fails
+ */
+export declare class EmbeddingError extends LanceDBError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Error raised when storage operations (read/write/delete) fail
+ */
+export declare class StorageError extends LanceDBError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Error raised when database queries fail or return invalid results
+ */
+export declare class QueryError extends LanceDBError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Error raised when configuration is missing or invalid
+ */
+export declare class ConfigurationError extends LanceDBError {
+    constructor(message: string, details?: Record<string, any>);
+}
+/**
+ * Sanitize error messages by redacting sensitive information
+ * @param {string} message - Error message to sanitize
+ * @returns {string} Sanitized error message
+ */
+export declare function sanitizeErrorMessage(message: unknown): string;
+export interface ErrorResponse {
+    success: boolean;
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, any>;
+        context?: Record<string, any>;
+        stack?: string;
+    };
+}
+/**
+ * Normalize errors into a consistent response format
+ * @param {Error} error - The error to handle
+ * @param {Object} context - Additional context about where/when the error occurred
+ * @returns {Object} Formatted error response with success: false
+ */
+export declare function handleError(error: unknown, context?: Record<string, any>): ErrorResponse;
+declare const _default: {
+    LanceDBError: typeof LanceDBError;
+    EmbeddingError: typeof EmbeddingError;
+    StorageError: typeof StorageError;
+    QueryError: typeof QueryError;
+    ConfigurationError: typeof ConfigurationError;
+    handleError: typeof handleError;
+    sanitizeErrorMessage: typeof sanitizeErrorMessage;
+};
+export default _default;