@yamo/memory-mesh 2.3.1 → 3.0.0

package/lib/memory/memory-mesh.js

@@ -12,1249 +12,1505 @@
  * Also supports STDIN input for YAMO skill compatibility:
  *   echo '{"action": "ingest", "content": "..."}' | node tools/memory_mesh.js
  */
-
-import { fileURLToPath } from 'url';
+import { fileURLToPath } from "url";
 import fs from "fs";
+import path from "path";
 import crypto from "crypto";
-import { LanceDBClient } from "../lancedb/client.js";
-import { getConfig } from "../lancedb/config.js";
-import { getEmbeddingDimension } from "../lancedb/schema.js";
-import { handleError, StorageError, QueryError } from "../lancedb/errors.js";
-import EmbeddingFactory from "../embeddings/factory.js";
+import { LanceDBClient } from "./adapters/client.js";
+import { getConfig } from "./adapters/config.js";
+import { getEmbeddingDimension, createSynthesizedSkillSchema, } from "./schema.js";
+import { handleError } from "./adapters/errors.js";
+import EmbeddingFactory from "./embeddings/factory.js";
 import { Scrubber } from "../scrubber/scrubber.js";
-import { KeywordSearch } from "../search/keyword-search.js";
+import { extractSkillIdentity, extractSkillTags, } from "../utils/skill-metadata.js";
+import { KeywordSearch } from "./search/keyword-search.js";
 import { YamoEmitter } from "../yamo/emitter.js";
 import { LLMClient } from "../llm/client.js";
-
+import * as lancedb from "@lancedb/lancedb";
+import { createLogger } from "../utils/logger.js";
+const logger = createLogger("brain");
 /**
  * MemoryMesh class for managing vector memory storage
  */
-class MemoryMesh {
-  /**
-   * Create a new MemoryMesh instance
-   * @param {Object} [options={}] - Configuration options
-   * @param {boolean} [options.enableYamo=true] - Enable YAMO block emission
-   * @param {boolean} [options.enableLLM=true] - Enable LLM for reflections
-   * @param {string} [options.agentId='default'] - Agent identifier for YAMO blocks
-   * @param {string} [options.llmProvider] - LLM provider (openai, anthropic, ollama)
-   * @param {string} [options.llmApiKey] - LLM API key
-   * @param {string} [options.llmModel] - LLM model name
-   */
-  constructor(options = {}) {
-    this.client = null;
-    this.config = null;
-    this.embeddingFactory = new EmbeddingFactory();
-    this.keywordSearch = new KeywordSearch();
-    this.isInitialized = false;
-    this.vectorDimension = 384; // Will be set during init()
-
-    // YAMO and LLM support
-    this.enableYamo = options.enableYamo !== false;  // Default: true
-    this.enableLLM = options.enableLLM !== false;    // Default: true
-    this.agentId = options.agentId || 'default';
-    this.yamoTable = null;  // Will be initialized in init()
-    this.llmClient = null;
-
-    // Initialize LLM client if enabled
-    if (this.enableLLM) {
-      this.llmClient = new LLMClient({
-        provider: options.llmProvider,
-        apiKey: options.llmApiKey,
-        model: options.llmModel
-      });
+export class MemoryMesh {
+    client;
+    config;
+    embeddingFactory;
+    keywordSearch;
+    isInitialized;
+    vectorDimension;
+    enableYamo;
+    enableLLM;
+    enableMemory;
+    agentId;
+    yamoTable;
+    skillTable;
+    llmClient;
+    scrubber;
+    queryCache;
+    cacheConfig;
+    skillDirectories; // Store skill directories for synthesis
+    dbDir; // Store custom dbDir for in-memory databases
+    /**
+     * Create a new MemoryMesh instance
+     * @param {Object} [options={}]
+     */
+    constructor(options = {}) {
+        this.client = null;
+        this.config = null;
+        this.embeddingFactory = new EmbeddingFactory();
+        this.keywordSearch = new KeywordSearch();
+        this.isInitialized = false;
+        this.vectorDimension = 384; // Will be set during init()
+        // YAMO and LLM support
+        this.enableYamo = options.enableYamo !== false;
+        this.enableLLM = options.enableLLM !== false;
+        this.enableMemory = options.enableMemory !== false;
+        this.agentId = options.agentId || "YAMO_AGENT";
+        this.yamoTable = null;
+        this.skillTable = null;
+        this.llmClient = this.enableLLM ? new LLMClient() : null;
+        // Store skill directories for synthesis
+        if (Array.isArray(options.skill_directories)) {
+            this.skillDirectories = options.skill_directories;
+        }
+        else if (options.skill_directories) {
+            this.skillDirectories = [options.skill_directories];
+        }
+        else {
+            this.skillDirectories = ["skills"];
+        }
+        // Initialize LLM client if enabled
+        if (this.enableLLM) {
+            this.llmClient = new LLMClient({
+                provider: options.llmProvider,
+                apiKey: options.llmApiKey,
+                model: options.llmModel,
+                maxTokens: options.llmMaxTokens,
+            });
+        }
+        // Scrubber for Layer 0 sanitization
+        this.scrubber = new Scrubber({
+            enabled: true,
+            chunking: {
+                minTokens: 1, // Allow short memories
+            }, // Type cast for partial config
+            validation: {
+                enforceMinLength: false, // Disable strict length validation
+            },
+        });
+        // Simple LRU cache for search queries (5 minute TTL)
+        this.queryCache = new Map();
+        this.cacheConfig = {
+            maxSize: 500,
+            ttlMs: 5 * 60 * 1000, // 5 minutes
+        };
+        // Store custom dbDir for test isolation
+        this.dbDir = options.dbDir;
     }
-
-    // Scrubber for Layer 0 sanitization
-    this.scrubber = new Scrubber({
-      enabled: true,
-      chunking: {
-        minTokens: 1 // Allow short memories
-      },
-      validation: {
-        enforceMinLength: false // Disable strict length validation
-      }
-    });
-
-    // Simple LRU cache for search queries (5 minute TTL)
-    this.queryCache = new Map();
-    this.cacheConfig = {
-      maxSize: 500,
-      ttlMs: 5 * 60 * 1000, // 5 minutes
-    };
-  }
-
-  /**
-   * Generate a cache key from query and options
-   * @private
-   * @param {string} query - Search query
-   * @param {Object} options - Search options
-   * @returns {string} Cache key
-   */
-  _generateCacheKey(query, options = {}) {
-    const normalizedOptions = {
-      limit: options.limit || 10,
-      filter: options.filter || null,
-      // Normalize options that affect results
-    };
-    return `search:${query}:${JSON.stringify(normalizedOptions)}`;
-  }
-
-  /**
-   * Get cached result if valid
-   * @private
-   * @param {string} key - Cache key
-   * @returns {Object|null} Cached result or null if expired/missing
-   */
-  _getCachedResult(key) {
-    const entry = this.queryCache.get(key);
-    if (!entry) return null;
-
-    // Check TTL
-    if (Date.now() - entry.timestamp > this.cacheConfig.ttlMs) {
-      this.queryCache.delete(key);
-      return null;
+    /**
+     * Generate a cache key from query and options
+     * @private
+     */
+    _generateCacheKey(query, options = {}) {
+        const normalizedOptions = {
+            limit: options.limit || 10,
+            filter: options.filter || null,
+            // Normalize options that affect results
+        };
+        return `search:${query}:${JSON.stringify(normalizedOptions)}`;
     }
-
-    // Move to end (most recently used)
-    this.queryCache.delete(key);
-    this.queryCache.set(key, entry);
-
-    return entry.result;
-  }
-
-  /**
-   * Cache a search result
-   * @private
-   * @param {string} key - Cache key
-   * @param {Object} result - Search result to cache
-   */
-  _cacheResult(key, result) {
-    // Evict oldest if at max size
-    if (this.queryCache.size >= this.cacheConfig.maxSize) {
-      const firstKey = this.queryCache.keys().next().value;
-      this.queryCache.delete(firstKey);
+    /**
+     * Get cached result if valid
+     * @private
+     *
+     * Race condition fix: The delete-then-set pattern for LRU tracking creates a window
+     * where another operation could observe the key as missing. We use a try-finally
+     * pattern to ensure atomicity at the application level.
+     */
+    _getCachedResult(key) {
+        const entry = this.queryCache.get(key);
+        if (!entry) {
+            return null;
+        }
+        // Check TTL - must be done before any mutation
+        const now = Date.now();
+        if (now - entry.timestamp > this.cacheConfig.ttlMs) {
+            this.queryCache.delete(key);
+            return null;
+        }
+        // Move to end (most recently used) - delete and re-add with updated timestamp
+        // While not truly atomic, the key remains accessible during the operation
+        // since we already have the entry reference
+        this.queryCache.delete(key);
+        this.queryCache.set(key, {
+            ...entry,
+            timestamp: now, // Update timestamp for LRU tracking
+        });
+        return entry.result;
     }
-
-    this.queryCache.set(key, {
-      result,
-      timestamp: Date.now()
-    });
-  }
-
-  /**
-   * Clear all cached results
-   */
-  clearCache() {
-    this.queryCache.clear();
-  }
-
-  /**
-   * Get cache statistics
-   * @returns {Object} Cache stats
-   */
-  getCacheStats() {
-    return {
-      size: this.queryCache.size,
-      maxSize: this.cacheConfig.maxSize,
-      ttlMs: this.cacheConfig.ttlMs
-    };
-  }
-
-  /**
-   * Validate and sanitize metadata to prevent prototype pollution
-   * @param {Object} metadata - Metadata to validate
-   * @returns {Object} Sanitized metadata
-   * @private
-   */
-  _validateMetadata(metadata) {
-    if (typeof metadata !== 'object' || metadata === null) {
-      throw new Error('Metadata must be a non-null object');
+    /**
+     * Cache a search result
+     * @private
+     */
+    _cacheResult(key, result) {
+        // Evict oldest if at max size
+        if (this.queryCache.size >= this.cacheConfig.maxSize) {
+            const firstKey = this.queryCache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.queryCache.delete(firstKey);
+            }
+        }
+        this.queryCache.set(key, {
+            result,
+            timestamp: Date.now(),
+        });
     }
-
-    // Sanitize keys to prevent prototype pollution
-    const sanitized = {};
-    for (const [key, value] of Object.entries(metadata)) {
-      // Skip dangerous keys that could pollute prototype
-      // Note: 'constructor' and 'prototype' are handled by hasOwnProperty check
-      // '.__proto__' needs explicit check because Object.entries() doesn't include it
-      if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
-        continue;
-      }
-      // Skip inherited properties
-      if (!Object.prototype.hasOwnProperty.call(metadata, key)) {
-        continue;
-      }
-      sanitized[key] = value;
+    /**
+     * Clear all cached results
+     */
+    clearCache() {
+        this.queryCache.clear();
     }
-    return sanitized;
-  }
-
-  /**
-   * Sanitize and validate content before storage
-   * @param {string} content - Content to sanitize
-   * @returns {string} Sanitized content
-   * @private
-   */
-  _sanitizeContent(content) {
-    if (typeof content !== 'string') {
-      throw new Error('Content must be a string');
+    /**
+     * Get cache statistics
+     */
+    getCacheStats() {
+        return {
+            size: this.queryCache.size,
+            maxSize: this.cacheConfig.maxSize,
+            ttlMs: this.cacheConfig.ttlMs,
+        };
     }
-
-    // Limit content length
-    const MAX_CONTENT_LENGTH = 100000; // 100KB limit
-    if (content.length > MAX_CONTENT_LENGTH) {
-      throw new Error(`Content exceeds maximum length of ${MAX_CONTENT_LENGTH} characters`);
+    /**
+     * Validate and sanitize metadata to prevent prototype pollution
+     * @private
+     */
+    _validateMetadata(metadata) {
+        if (typeof metadata !== "object" || metadata === null) {
+            throw new Error("Metadata must be a non-null object");
+        }
+        // Sanitize keys to prevent prototype pollution
+        const sanitized = {};
+        for (const [key, value] of Object.entries(metadata)) {
+            // Skip dangerous keys that could pollute prototype
+            if (key === "__proto__" || key === "constructor" || key === "prototype") {
+                continue;
+            }
+            // Skip inherited properties
+            if (!Object.prototype.hasOwnProperty.call(metadata, key)) {
+                continue;
+            }
+            sanitized[key] = value;
+        }
+        return sanitized;
     }
-
-    return content.trim();
-  }
-
-  /**
-   * Initialize the LanceDB client
-   * @returns {Promise<void>}
-   */
-  async init() {
-    if (this.isInitialized) {
-      return;
+    /**
+     * Sanitize and validate content before storage
+     * @private
+     */
+    _sanitizeContent(content) {
+        if (typeof content !== "string") {
+            throw new Error("Content must be a string");
+        }
+        // Limit content length
+        const MAX_CONTENT_LENGTH = 100000; // 100KB limit
+        if (content.length > MAX_CONTENT_LENGTH) {
+            throw new Error(`Content exceeds maximum length of ${MAX_CONTENT_LENGTH} characters`);
+        }
+        return content.trim();
     }
-
-    try {
-      // Load configuration
-      this.config = getConfig();
-
-      // Detect vector dimension from embedding model configuration
-      const modelName = process.env.EMBEDDING_MODEL_NAME || 'Xenova/all-MiniLM-L6-v2';
-      const envDimension = parseInt(process.env.EMBEDDING_DIMENSION || '0') || null;
-      this.vectorDimension = envDimension || getEmbeddingDimension(modelName);
-
-      // Only log in debug mode to avoid corrupting spinner/REPL display
-      if (process.env.YAMO_DEBUG === 'true') {
-        console.error(`[MemoryMesh] Using vector dimension: ${this.vectorDimension} (model: ${modelName})`);
-      }
-
-      // Create LanceDBClient with detected dimension
-      this.client = new LanceDBClient({
-        uri: this.config.LANCEDB_URI,
-        tableName: this.config.LANCEDB_MEMORY_TABLE,
-        vectorDimension: this.vectorDimension,
-        maxRetries: 3,
-        retryDelay: 1000
-      });
-
-      // Connect to database
-      await this.client.connect();
-
-      // Configure embedding factory from environment
-      const embeddingConfigs = this._parseEmbeddingConfig();
-      this.embeddingFactory.configure(embeddingConfigs);
-      await this.embeddingFactory.init();
-
-      // Hydrate Keyword Search (In-Memory)
-      // Note: This is efficient for small datasets (< 10k).
-      // For larger, we should persist the inverted index or use LanceDB FTS.
-      if (this.client) {
+    /**
+     * Initialize the LanceDB client
+     */
+    async init() {
+        if (this.isInitialized) {
+            return;
+        }
+        if (!this.enableMemory) {
+            this.isInitialized = true;
+            if (process.env.YAMO_DEBUG === "true") {
+                logger.debug("MemoryMesh initialization skipped (enableMemory=false)");
+            }
+            return;
+        }
         try {
-          const allRecords = await this.client.getAll({ limit: 10000 });
-          this.keywordSearch.load(allRecords);
-        } catch (e) {
-          // Ignore if table doesn't exist yet
+            // Load configuration
+            this.config = getConfig();
+            // Detect vector dimension from embedding model configuration
+            const modelName = process.env.EMBEDDING_MODEL_NAME || "Xenova/all-MiniLM-L6-v2";
+            const envDimension = parseInt(process.env.EMBEDDING_DIMENSION || "0") || null;
+            this.vectorDimension = envDimension || getEmbeddingDimension(modelName);
+            // Only log in debug mode to avoid corrupting spinner/REPL display
+            if (process.env.YAMO_DEBUG === "true") {
+                logger.debug({ dimension: this.vectorDimension, model: modelName }, "Using vector dimension");
+            }
+            // Use custom dbDir if provided (for test isolation), otherwise use config
+            const dbUri = this.dbDir || this.config.LANCEDB_URI;
+            // Create LanceDBClient with detected dimension
+            this.client = new LanceDBClient({
+                uri: dbUri,
+                tableName: this.config.LANCEDB_MEMORY_TABLE,
+                vectorDimension: this.vectorDimension,
+                maxRetries: 3,
+                retryDelay: 1000,
+            });
+            // Connect to database
+            await this.client.connect();
+            // Configure embedding factory from environment
+            const embeddingConfigs = this._parseEmbeddingConfig();
+            this.embeddingFactory.configure(embeddingConfigs);
+            await this.embeddingFactory.init();
+            // Hydrate Keyword Search (In-Memory)
+            if (this.client) {
+                try {
+                    const allRecords = await this.client.getAll({ limit: 10000 });
+                    this.keywordSearch.load(allRecords);
+                }
+                catch (_e) {
+                    // Ignore if table doesn't exist yet
+                }
+            }
+            // Initialize extension tables if enabled
+            if (this.enableYamo && this.client && this.client.db) {
+                try {
+                    const { createYamoTable } = await import("../yamo/schema.js");
+                    this.yamoTable = await createYamoTable(this.client.db, "yamo_blocks");
+                    // Initialize synthesized skills table (Recursive Skill Synthesis)
+                    // const { createSynthesizedSkillSchema } = await import('./schema'); // Imported statically now
+                    const existingTables = await this.client.db.tableNames();
+                    if (existingTables.includes("synthesized_skills")) {
+                        this.skillTable =
+                            await this.client.db.openTable("synthesized_skills");
+                    }
+                    else {
+                        const skillSchema = createSynthesizedSkillSchema(this.vectorDimension);
+                        this.skillTable = await this.client.db.createTable("synthesized_skills", [], {
+                            schema: skillSchema,
+                        });
+                    }
+                    if (process.env.YAMO_DEBUG === "true") {
+                        logger.debug("YAMO blocks and synthesized skills tables initialized");
+                    }
+                }
+                catch (e) {
+                    logger.warn({ err: e }, "Failed to initialize extension tables");
+                }
+            }
+            this.isInitialized = true;
         }
-      }
-
-      // Initialize YAMO blocks table if enabled
-      if (this.enableYamo && this.client && this.client.db) {
+        catch (error) {
+            const e = error instanceof Error ? error : new Error(String(error));
+            throw e;
+        }
+    }
+    /**
+     * Add content to memory with auto-generated embedding and scrubbing.
+     *
+     * This is the primary method for storing information in the memory mesh.
+     * The content goes through several processing steps:
+     *
+     * 1. **Scrubbing**: PII and sensitive data are sanitized (if enabled)
+     * 2. **Validation**: Content length and metadata are validated
+     * 3. **Embedding**: Content is converted to a vector representation
+     * 4. **Storage**: Record is stored in LanceDB with metadata
+     * 5. **Emission**: Optional YAMO block emitted for provenance tracking
+     *
+     * @param content - The text content to store in memory
+     * @param metadata - Optional metadata (type, source, tags, etc.)
+     * @returns Promise with memory record containing id, content, metadata, created_at
+     *
+     * @example
+     * ```typescript
+     * const memory = await mesh.add("User likes TypeScript", {
+     *   type: "preference",
+     *   source: "chat",
+     *   tags: ["programming", "languages"]
+     * });
+     * ```
+     *
+     * @throws {Error} If content exceeds max length (100KB)
+     * @throws {Error} If embedding generation fails
+     * @throws {Error} If database client is not initialized
+     */
+    async add(content, metadata = {}) {
+        await this.init();
+        const type = metadata.type || "event";
+        const enrichedMetadata = { ...metadata, type };
         try {
-          const { createYamoTable } = await import('../yamo/schema.js');
-          this.yamoTable = await createYamoTable(this.client.db, 'yamo_blocks');
-          if (process.env.YAMO_DEBUG === 'true') {
-            console.error('[MemoryMesh] YAMO blocks table initialized');
-          }
-        } catch (e) {
-          // Log warning but don't fail initialization
-          console.warn('[MemoryMesh] Failed to initialize YAMO table:', e instanceof Error ? e.message : String(e));
-        }
-      }
-
-      this.isInitialized = true;
-
-    } catch (error) {
-      const e = error instanceof Error ? error : new Error(String(error));
-      throw e;
+            let processedContent = content;
+            let scrubbedMetadata = {};
+            try {
+                const scrubbedResult = await this.scrubber.process({
+                    content: content,
+                    source: "memory-api",
+                    type: "txt",
+                });
+                if (scrubbedResult.success && scrubbedResult.chunks.length > 0) {
+                    processedContent = scrubbedResult.chunks
+                        .map((c) => c.text)
+                        .join("\n\n");
+                    if (scrubbedResult.metadata) {
+                        scrubbedMetadata = {
+                            ...scrubbedResult.metadata,
+                            scrubber_telemetry: JSON.stringify(scrubbedResult.telemetry),
+                        };
+                    }
+                }
+            }
+            catch (scrubError) {
+                if (process.env.YAMO_DEBUG === "true") {
+                    logger.error({ err: scrubError }, "Scrubber failed");
+                }
+            }
+            const sanitizedContent = this._sanitizeContent(processedContent);
+            const sanitizedMetadata = this._validateMetadata({
+                ...scrubbedMetadata,
+                ...enrichedMetadata,
+            });
+            if (process.env.YAMO_DEBUG === "true") {
+                console.error("[DEBUG] brain.add() scrubbedMetadata.type:", scrubbedMetadata.type);
+                console.error("[DEBUG] brain.add() enrichedMetadata.type:", enrichedMetadata.type);
+                console.error("[DEBUG] brain.add() sanitizedMetadata.type:", sanitizedMetadata.type);
+            }
+            const vector = await this.embeddingFactory.embed(sanitizedContent);
+            // Dedup: search by the already-computed vector before inserting.
+            // Catches exact duplicates regardless of which write path is used,
+            // protecting callers that bypass captureInteraction()'s dedup guard.
+            if (this.client) {
+                const nearest = await this.client.search(vector, { limit: 1 });
+                if (nearest.length > 0 && nearest[0].content === sanitizedContent) {
+                    return {
+                        id: nearest[0].id,
+                        content: sanitizedContent,
+                        metadata: sanitizedMetadata,
+                        created_at: new Date().toISOString(),
+                    };
+                }
+            }
+            const id = `mem_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+            const record = {
+                id,
+                vector,
+                content: sanitizedContent,
+                metadata: JSON.stringify(sanitizedMetadata),
+            };
+            if (process.env.YAMO_DEBUG === "true") {
+                console.error("[DEBUG] record.metadata.type:", JSON.parse(record.metadata).type);
+            }
+            if (!this.client) {
+                throw new Error("Database client not initialized");
+            }
+            const result = await this.client.add(record);
+            if (process.env.YAMO_DEBUG === "true") {
+                try {
+                    console.error("[DEBUG] result.metadata.type:", JSON.parse(result.metadata).type);
+                }
+                catch {
+                    console.error("[DEBUG] result.metadata:", result.metadata);
+                }
+            }
+            this.keywordSearch.add(record.id, record.content, sanitizedMetadata);
+            if (this.enableYamo) {
+                this._emitYamoBlock("retain", result.id, YamoEmitter.buildRetainBlock({
+                    content: sanitizedContent,
+                    metadata: sanitizedMetadata,
+                    id: result.id,
+                    agentId: this.agentId,
+                    memoryType: sanitizedMetadata.type || "event",
+                })).catch((error) => {
+                    // Log emission failures in debug mode but don't throw
+                    if (process.env.YAMO_DEBUG === "true") {
+                        logger.warn({ err: error }, "Failed to emit YAMO block (retain)");
+                    }
+                });
+            }
+            return {
+                id: result.id,
+                content: sanitizedContent,
+                metadata: sanitizedMetadata,
+                created_at: new Date().toISOString(),
+            };
+        }
+        catch (error) {
+            throw error instanceof Error ? error : new Error(String(error));
+        }
     }
-  }
-
-  /**
-   * Add content to memory with auto-generated embedding
-   * @param {string} content - Text content to store
-   * @param {Object} metadata - Optional metadata tags
-   * @returns {Promise<Object>} Created record with ID
-   */
-  async add(content, metadata = {}) {
-    await this.init();
-
-    // Default to 'event' if no type provided
-    const type = metadata.type || 'event';
-    const enrichedMetadata = { ...metadata, type };
-
-    try {
-      // Layer 0: Scrubber Sanitization
-      let processedContent = content;
-      let scrubbedMetadata = {};
-      
-      try {
-        const scrubbedResult = await this.scrubber.process({
-          content: content,
-          source: 'memory-api',
-          type: 'txt' // Default to text
-        });
-
-        if (scrubbedResult.success && scrubbedResult.chunks.length > 0) {
-          // Reconstruct cleaned content
-          processedContent = scrubbedResult.chunks.map(c => c.text).join('\n\n');
-          
-          // Merge scrubber telemetry/metadata if useful
-          if (scrubbedResult.metadata) {
-             scrubbedMetadata = {
-               ...scrubbedResult.metadata,
-               scrubber_telemetry: JSON.stringify(scrubbedResult.telemetry)
-             };
-          }
-        }
-      } catch (scrubError) {
-        // Fallback to raw content if scrubber fails, but log it
-        if (process.env.YAMO_DEBUG === 'true') {
-           const message = scrubError instanceof Error ? scrubError.message : String(scrubError);
-           console.error(`[MemoryMesh] Scrubber failed: ${message}`);
-        }
-      }
-
-      // Validate and sanitize inputs (legacy check)
-      const sanitizedContent = this._sanitizeContent(processedContent);
-      const sanitizedMetadata = this._validateMetadata({ ...enrichedMetadata, ...scrubbedMetadata });
-
-      // Generate ID
-      const id = `mem_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
-
-      // Generate embedding using EmbeddingFactory
-      const vector = await this.embeddingFactory.embed(sanitizedContent);
-
-      // Prepare record data with sanitized metadata
-      const record = {
-        id,
-        vector,
-        content: sanitizedContent,
-        metadata: JSON.stringify(sanitizedMetadata)
-      };
-
-
-      // Add to LanceDB
-      if (!this.client) throw new Error('Database client not initialized');
-      const result = await this.client.add(record);
-
-      // Add to Keyword Search
-      this.keywordSearch.add(record.id, record.content, sanitizedMetadata);
-
-      // Emit YAMO block for retain operation (async, non-blocking)
-      if (this.enableYamo) {
-        // Fire and forget - don't await
-        this._emitYamoBlock('retain', result.id, YamoEmitter.buildRetainBlock({
-          content: sanitizedContent,
-          metadata: sanitizedMetadata,
-          id: result.id,
-          agentId: this.agentId,
-          memoryType: sanitizedMetadata.type || 'event'
-        })).catch(err => {
-          if (process.env.YAMO_DEBUG === 'true') {
-            console.error('[MemoryMesh] YAMO emission failed in add():', err);
-          }
+    /**
+     * Reflect on recent memories
+     */
+    async reflect(options = {}) {
+        await this.init();
+        const lookback = options.lookback || 10;
+        const topic = options.topic;
+        const generate = options.generate !== false;
+        let memories = [];
+        if (topic) {
+            memories = await this.search(topic, { limit: lookback });
+        }
+        else {
+            const all = await this.getAll();
+            memories = all
+                .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())
+                .slice(0, lookback);
+        }
+        const prompt = `Review these memories. Synthesize a high-level "belief" or "observation".`;
+        if (!generate || !this.enableLLM || !this.llmClient) {
+            return {
+                topic,
+                count: memories.length,
+                context: memories.map((m) => ({
+                    content: m.content,
+                    type: m.metadata?.type || "event",
+                    id: m.id,
+                })),
+                prompt,
+            };
+        }
+        let reflection = "";
+        let confidence = 0;
+        try {
+            const result = await this.llmClient.reflect(prompt, memories);
+            reflection = result.reflection;
+            confidence = result.confidence;
+        }
+        catch (_error) {
+            reflection = `Aggregated from ${memories.length} memories on topic: ${topic || "general"}`;
+            confidence = 0.5;
+        }
+        const reflectionId = `reflect_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`;
+        await this.add(reflection, {
+            type: "reflection",
+            topic: topic || "general",
+            source_memory_count: memories.length,
+            confidence,
+            generated_at: new Date().toISOString(),
         });
-      }
-
-      return {
-        id: result.id,
-        content: sanitizedContent,
-        metadata: sanitizedMetadata,
-        created_at: new Date().toISOString()
-      };
-
-
-    } catch (error) {
-      const e = error instanceof Error ? error : new Error(String(error));
-      throw e;
-    }
-  }
-
-  /**
-   * Reflect on recent memories to generate insights (enhanced with LLM + YAMO)
-   * @param {Object} options
-   * @param {string} [options.topic] - Topic to search for
-   * @param {number} [options.lookback=10] - Number of memories to consider
-   * @param {boolean} [options.generate=true] - Whether to generate reflection via LLM
-   * @returns {Promise<Object>} Reflection result with YAMO block
-   */
-  async reflect(options = {}) {
-    await this.init();
-
-    const lookback = options.lookback || 10;
-    const topic = options.topic;
-    const generate = options.generate !== false;
-
-    // Gather memories
-    let memories = [];
-    if (topic) {
-      memories = await this.search(topic, { limit: lookback });
-    } else {
-      const all = await this.getAll();
-      memories = all
-        .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())
-        .slice(0, lookback);
-    }
-
-    const prompt = `Review these memories. Synthesize a high-level "belief" or "observation".`;
-
-    // Check if LLM generation is requested and available
-    if (!generate || !this.enableLLM || !this.llmClient) {
-      // Return prompt-only mode (backward compatible)
-      return {
-        topic,
-        count: memories.length,
-        context: memories.map(m => ({
-          content: m.content,
-          type: m.metadata?.type || 'event',
-          id: m.id
-        })),
-        prompt
-      };
-    }
-
-    // Generate reflection via LLM
-    let reflection = null;
-    let confidence = 0;
-
-    try {
-      const result = await this.llmClient.reflect(prompt, memories);
-      reflection = result.reflection;
-      confidence = result.confidence;
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.warn(`[MemoryMesh] LLM reflection failed: ${errorMessage}`);
-      // Fall back to simple aggregation
-      reflection = `Aggregated from ${memories.length} memories on topic: ${topic || 'general'}`;
-      confidence = 0.5;
-    }
-
-    // Store reflection to memory
-    const reflectionId = `reflect_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
-    await this.add(reflection, {
-      type: 'reflection',
-      topic: topic || 'general',
-      source_memory_count: memories.length,
-      confidence,
-      generated_at: new Date().toISOString()
-    });
-
-    // Emit YAMO block if enabled
-    let yamoBlock = null;
-    if (this.enableYamo) {
-      yamoBlock = YamoEmitter.buildReflectBlock({
-        topic: topic || 'general',
-        memoryCount: memories.length,
-        agentId: this.agentId,
-        reflection,
-        confidence
-      });
-
-      await this._emitYamoBlock('reflect', reflectionId, yamoBlock);
-    }
-
-    return {
-      id: reflectionId,
-      topic: topic || 'general',
-      reflection,
-      confidence,
-      sourceMemoryCount: memories.length,
-      yamoBlock,
-      createdAt: new Date().toISOString()
-    };
-  }
-
-  /**
-   * Emit a YAMO block to the YAMO blocks table
-   * @private
-   * @param {string} operationType - 'retain', 'recall', 'reflect'
-   * @param {string|undefined} memoryId - Associated memory ID (undefined for recall)
-   * @param {string} yamoText - The YAMO block text
-   */
-  async _emitYamoBlock(operationType, memoryId, yamoText) {
-    if (!this.yamoTable) {
-      if (process.env.YAMO_DEBUG === 'true') {
-        console.warn('[MemoryMesh] YAMO table not initialized, skipping emission');
-      }
-      return;
-    }
-
-    const yamoId = `yamo_${operationType}_${Date.now()}_${crypto.randomBytes(4).toString('hex')}`;
-
-    try {
-      await this.yamoTable.add([{
-        id: yamoId,
-        agent_id: this.agentId,
-        operation_type: operationType,
-        yamo_text: yamoText,
-        timestamp: new Date(),
-        block_hash: null,  // Future: blockchain anchoring
-        prev_hash: null,
-        metadata: JSON.stringify({
-          memory_id: memoryId || null,
-          timestamp: new Date().toISOString()
-        })
-      }]);
-
-      if (process.env.YAMO_DEBUG === 'true') {
-        console.log(`[MemoryMesh] YAMO block emitted: ${yamoId}`);
-      }
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.error(`[MemoryMesh] Failed to emit YAMO block: ${errorMessage}`);
-    }
-  }
-
-  /**
-   * Add multiple memory entries in batch for efficiency
-   * @param {Array<{content: string, metadata?: Object}>} entries - Array of entries to add
-   * @returns {Promise<Object>} Result with count and IDs
-   */
-  async addBatch(entries) {
-    if (!Array.isArray(entries) || entries.length === 0) {
-      throw new Error('Entries must be a non-empty array');
+        let yamoBlock = null;
+        if (this.enableYamo) {
+            yamoBlock = YamoEmitter.buildReflectBlock({
+                topic: topic || "general",
+                memoryCount: memories.length,
+                agentId: this.agentId,
+                reflection,
+                confidence,
+            });
+            await this._emitYamoBlock("reflect", reflectionId, yamoBlock);
+        }
+        return {
+            id: reflectionId,
+            topic: topic || "general",
+            reflection,
+            confidence,
+            sourceMemoryCount: memories.length,
+            yamoBlock,
+            createdAt: new Date().toISOString(),
+        };
     }
-
-    await this.init();
-
-    try {
-      const now = Date.now();
-      const records = [];
-
-      // Process entries in parallel for embeddings
-      const embeddingPromises = entries.map(async (entry, index) => {
-        // Layer 0: Scrubber Sanitization
-        let processedContent = entry.content;
-        let scrubbedMetadata = {};
-
+    /**
+     * Ingest synthesized skill
+     * @param sourceFilePath - If provided, skip file write (file already exists)
+     */
+    async ingestSkill(yamoText, metadata = {}, sourceFilePath) {
+        await this.init();
+        if (!this.skillTable) {
+            throw new Error("Skill table not initialized");
+        }
+        // DEBUG: Trace sourceFilePath parameter
+        if (process.env.YAMO_DEBUG_PATHS === "true") {
+            console.error(`[BRAIN.ingestSkill] sourceFilePath parameter: ${sourceFilePath || "undefined"}`);
+        }
         try {
-          const scrubbedResult = await this.scrubber.process({
-            content: entry.content,
-            source: 'memory-batch',
-            type: 'txt'
-          });
-
-          if (scrubbedResult.success && scrubbedResult.chunks.length > 0) {
-            processedContent = scrubbedResult.chunks.map(c => c.text).join('\n\n');
-             if (scrubbedResult.metadata) {
-               scrubbedMetadata = {
-                 ...scrubbedResult.metadata,
-                 scrubber_telemetry: JSON.stringify(scrubbedResult.telemetry)
-               };
+            const identity = extractSkillIdentity(yamoText);
+            const name = metadata.name || identity.name;
+            const intent = identity.intent;
+            const description = identity.description;
+            // RECURSION DETECTION: Check for recursive naming patterns
+            // Patterns like "SkillSkill", "SkillSkillSkill" indicate filename-derived names
+            const recursivePattern = /^(Skill|skill){2,}/;
+            if (recursivePattern.test(name)) {
+                logger.warn({ originalName: name }, "Detected recursive naming pattern, rejecting ingestion to prevent loop");
+                throw new Error(`Recursive naming pattern detected: ${name}. Skills must have proper name: field.`);
+            }
+            // Extract tags for tag-aware embeddings (improves semantic search)
+            const tags = extractSkillTags(yamoText);
+            const tagText = tags.length > 0 ? `\nTags: ${tags.join(", ")}` : "";
+            const embeddingText = `Skill: ${name}\nIntent: ${intent}${tagText}\nDescription: ${description}`;
+            const vector = await this.embeddingFactory.embed(embeddingText);
+            const id = `skill_${Date.now()}_${crypto.randomBytes(2).toString("hex")}`;
+            const skillMetadata = {
+                reliability: 0.5,
+                use_count: 0,
+                source: "manual",
+                ...metadata,
+                // Store source file path for policy loading and parent discovery
+                ...(sourceFilePath && { source_file: sourceFilePath }),
+            };
+            const record = {
+                id,
+                name,
+                intent,
+                yamo_text: yamoText,
+                vector,
+                metadata: JSON.stringify(skillMetadata),
+                created_at: new Date(),
+            };
+            await this.skillTable.add([record]);
+            // NEW: Persist to filesystem for longevity and visibility
+            // Skip if sourceFilePath provided (file already exists from SkillCreator)
+            // Skip if using in-memory database (:memory:)
+            if (!sourceFilePath && this.dbDir !== ":memory:") {
+                try {
+                    const skillsDir = path.resolve(process.cwd(), this.skillDirectories[0] || "skills");
+                    if (!fs.existsSync(skillsDir)) {
+                        fs.mkdirSync(skillsDir, { recursive: true });
+                    }
+                    // Robust filename with length limit to prevent ENAMETOOLONG
+                    const safeName = name
+                        .toLowerCase()
+                        .replace(/[^a-z0-9]/g, "-")
+                        .replace(/-+/g, "-")
+                        .substring(0, 50);
+                    const fileName = `skill-${safeName}.yamo`;
+                    const filePath = path.join(skillsDir, fileName);
+                    // Only write if file doesn't already exist to prevent duplicates
+                    if (!fs.existsSync(filePath)) {
+                        fs.writeFileSync(filePath, yamoText, "utf8");
+                        if (process.env.YAMO_DEBUG === "true") {
+                            logger.debug({ filePath }, "Skill persisted to file");
+                        }
+                    }
+                }
+                catch (fileError) {
+                    logger.warn({ err: fileError }, "Failed to persist skill to file");
+                }
             }
-          }
-        } catch (e) {
-           // Fallback silently
+            return { id, name, intent };
         }
-
-        const sanitizedContent = this._sanitizeContent(processedContent);
-        const sanitizedMetadata = this._validateMetadata({ ...(entry.metadata || {}), ...scrubbedMetadata });
-
-        const id = `mem_${now}_${Math.random().toString(36).substr(2, 9)}_${index}`;
-        const vector = await this.embeddingFactory.embed(sanitizedContent);
-
+        catch (error) {
+            throw new Error(`Skill ingestion failed: ${error.message}`);
+        }
+    }
+    /**
+     * Recursive Skill Synthesis
+     */
+    async synthesize(options = {}) {
+        await this.init();
+        const topic = options.topic || "general_improvement";
+        const enrichedPrompt = options.enrichedPrompt || topic; // PHASE 4: Use enriched prompt
+        // const lookback = options.lookback || 20;
+        logger.info({ topic, enrichedPrompt }, "Synthesizing logic");
+        // OPTIMIZATION: If we have an execution engine (kernel), use SkillCreator!
+        if (this._kernel_execute) {
+            logger.info("Dispatching to SkillCreator agent...");
+            try {
+                // Use stored skill directories
+                const skillDirs = this.skillDirectories;
+                // Track existing .yamo files before SkillCreator runs
+                const filesBefore = new Set();
+                for (const dir of skillDirs) {
+                    if (fs.existsSync(dir)) {
+                        const walk = (currentDir) => {
+                            try {
+                                const entries = fs.readdirSync(currentDir, {
+                                    withFileTypes: true,
+                                });
+                                for (const entry of entries) {
+                                    const fullPath = path.join(currentDir, entry.name);
+                                    if (entry.isDirectory()) {
+                                        walk(fullPath);
+                                    }
+                                    else if (entry.isFile() && entry.name.endsWith(".yamo")) {
+                                        filesBefore.add(fullPath);
+                                    }
+                                }
+                            }
+                            catch (e) {
+                                // Skip directories we can't read
+                                logger.debug({ dir, error: e }, "Could not read directory");
+                            }
+                        };
+                        walk(dir);
+                    }
+                }
+                // PHASE 4: Use enriched prompt for SkillCreator
+                await this._kernel_execute(`SkillCreator: design a new skill to handle ${enrichedPrompt}`, {
+                    v1_1_enabled: true,
+                });
+                // Find newly created .yamo file
+                let newSkillFile;
+                for (const dir of skillDirs) {
+                    if (fs.existsSync(dir)) {
+                        const walk = (currentDir) => {
+                            try {
+                                const entries = fs.readdirSync(currentDir, {
+                                    withFileTypes: true,
+                                });
+                                for (const entry of entries) {
+                                    const fullPath = path.join(currentDir, entry.name);
+                                    if (entry.isDirectory()) {
+                                        walk(fullPath);
+                                    }
+                                    else if (entry.isFile() && entry.name.endsWith(".yamo")) {
+                                        if (!filesBefore.has(fullPath)) {
+                                            newSkillFile = fullPath;
+                                        }
+                                    }
+                                }
+                            }
+                            catch (e) {
+                                logger.debug({ dir, error: e }, "Could not read directory");
+                            }
+                        };
+                        walk(dir);
+                    }
+                }
+                // Ingest the newly created skill file
+                if (newSkillFile) {
+                    logger.info({ skillFile: newSkillFile }, "Ingesting newly synthesized skill");
+                    let skillContent = fs.readFileSync(newSkillFile, "utf8");
+                    // PHASE 4: Expand compressed → canonical for disk storage
+                    // Skills created by evolution are typically compressed; expand to canonical for readability
+                    // Skip expansion in test environment or when disabled
+                    const expansionEnabled = process.env.YAMO_EXPANSION_ENABLED !== "false";
+                    const isCompressed = !skillContent.includes("---") ||
+                        (skillContent.includes("---") &&
+                            skillContent.split("---").length <= 1);
+                    if (expansionEnabled && isCompressed) {
+                        logger.info({ skillFile: newSkillFile }, "Expanding compressed skill to canonical format");
+                        try {
+                            const expanded = await this._kernel_execute("skill-expansion-system-prompt.yamo", {
+                                input_yamo: skillContent,
+                            });
+                            if (expanded && expanded.canonical_yamo) {
+                                skillContent = expanded.canonical_yamo;
+                                // Write expanded canonical format back to disk
+                                fs.writeFileSync(newSkillFile, skillContent, "utf8");
+                                logger.info({ skillFile: newSkillFile }, "Skill expanded to canonical format on disk");
+                            }
+                        }
+                        catch (e) {
+                            logger.warn({ err: e }, "Failed to expand skill to canonical, using compressed format");
+                        }
+                    }
+                    // ENSURE: Synthesized skills always have proper metadata with meaningful name
+                    // This prevents duplicate skill-agent-{timestamp}.yamo files
+                    const synIdentity = extractSkillIdentity(skillContent);
+                    const hasName = !synIdentity.name.startsWith("Unnamed_");
+                    if (!skillContent.includes("---") || !hasName) {
+                        logger.info({ skillFile: newSkillFile }, "Adding metadata block to synthesized skill");
+                        const intent = synIdentity.intent !== "general_procedure"
+                            ? synIdentity.intent.replace(/[^a-zA-Z0-9]/g, "")
+                            : "Synthesized";
+                        const PascalCase = intent.charAt(0).toUpperCase() + intent.slice(1);
+                        const skillName = `${PascalCase}_${Date.now().toString(36)}`;
+                        const metadata = `---
+name: ${skillName}
+version: 1.0.0
+author: YAMO Evolution
+license: MIT
+tags: synthesized, evolution, auto-generated
+description: Auto-generated skill to handle: ${enrichedPrompt || topic}
+---
+`;
+                        // Prepend metadata if skill doesn't have it
+                        if (!skillContent.startsWith("---")) {
+                            skillContent = metadata + skillContent;
+                            // Write back to disk with proper metadata
+                            fs.writeFileSync(newSkillFile, skillContent, "utf8");
+                            logger.info({ skillFile: newSkillFile, skillName }, "Added metadata block to synthesized skill");
+                        }
+                    }
+                    const skill = await this.ingestSkill(skillContent, {
+                        source: "synthesized",
+                        trigger_topic: topic,
+                    }, newSkillFile);
+                    return {
+                        status: "success",
+                        analysis: "SkillCreator orchestrated evolution",
+                        skill_id: skill.id,
+                        skill_name: skill.name,
+                        yamo_text: skillContent,
+                    };
+                }
+                // Fallback if no new file found
+                return {
+                    status: "success",
+                    analysis: "SkillCreator orchestrated evolution (no file detected)",
+                    skill_name: topic.split(" ")[0],
+                };
+            }
+            catch (e) {
+                logger.error({ err: e }, "SkillCreator agent failed");
+                return {
+                    status: "error",
+                    error: e.message,
+                    analysis: "SkillCreator agent failed",
+                };
+            }
+        }
+        // SkillCreator is required for synthesis
+        if (!this._kernel_execute) {
+            throw new Error("Kernel execution (_kernel_execute) is required for synthesis. Use YamoKernel instead of MemoryMesh directly.");
+        }
+        // Should never reach here
         return {
-          id,
-          vector,
-          content: sanitizedContent,
-          metadata: JSON.stringify(sanitizedMetadata)
+            status: "error",
+            analysis: "Unexpected state in synthesis",
         };
-      });
-
-      const recordsWithEmbeddings = await Promise.all(embeddingPromises);
-
-      // Add all records to database
-      if (!this.client) throw new Error('Database client not initialized');
-      const result = await this.client.addBatch(recordsWithEmbeddings);
-
-      return {
-        count: result.count,
-        success: result.success,
-        ids: recordsWithEmbeddings.map(r => r.id)
-      };
-
-    } catch (error) {
-      const e = error instanceof Error ? error : new Error(String(error));
-      throw e;
-    }
-  }
-
-  /**
-   * Search memory by semantic similarity
-   * @param {string} query - Search query text
-   * @param {Object} options - Search options
-   * @param {number} [options.limit=10] - Maximum number of results
-   * @param {string} [options.filter] - Optional filter expression
-   * @param {boolean} [options.useCache=true] - Whether to use query cache
-   * @returns {Promise<Array>} Search results with scores
-   */
-  async search(query, options = {}) {
-    await this.init();
-
-    try {
-      const limit = options.limit || 10;
-      const filter = options.filter || null;
-      // @ts-ignore
-      const useCache = options.useCache !== undefined ? options.useCache : true;
-
-      // Check cache first (unless disabled)
-      if (useCache) {
-        const cacheKey = this._generateCacheKey(query, { limit, filter });
-        const cached = this._getCachedResult(cacheKey);
-        if (cached) {
-          return cached;
-        }
-      }
-
-      // Generate embedding using EmbeddingFactory
-      const vector = await this.embeddingFactory.embed(query);
-
-      // 1. Vector Search
-      if (!this.client) throw new Error('Database client not initialized');
-      const vectorResults = await this.client.search(vector, {
-        limit: limit * 2, // Fetch more for re-ranking
-        metric: 'cosine',
-        filter
-      });
-
-      // 2. Keyword Search
-      const keywordResults = this.keywordSearch.search(query, { limit: limit * 2 });
-
-      // 3. Reciprocal Rank Fusion (RRF)
-      const k = 60; // RRF constant
-      const scores = new Map(); // id -> score
-      const docMap = new Map(); // id -> doc
-
-      // Process Vector Results
-      vectorResults.forEach((doc, rank) => {
-        const rrf = 1 / (k + rank + 1);
-        scores.set(doc.id, (scores.get(doc.id) || 0) + rrf);
-        docMap.set(doc.id, doc);
-      });
-
-      // Process Keyword Results
-      keywordResults.forEach((doc, rank) => {
-        const rrf = 1 / (k + rank + 1);
-        scores.set(doc.id, (scores.get(doc.id) || 0) + rrf);
-        
-        if (!docMap.has(doc.id)) {
-           // Add keyword-only match
-           docMap.set(doc.id, {
-             id: doc.id,
-             content: doc.content,
-             metadata: doc.metadata,
-             score: 0, // Base score, will be overwritten
-             created_at: new Date().toISOString() // Approximate or missing
-           });
-        }
-      });
-
-      // Sort by RRF score
-      const mergedResults = Array.from(scores.entries())
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, limit)
-        .map(([id, score]) => {
-          const doc = docMap.get(id);
-          if (doc) return { ...doc, score }; 
-          return null; 
-        })
-        .filter(d => d !== null);
-
-      // Cache the result (unless disabled)
-      if (useCache) {
-        const cacheKey = this._generateCacheKey(query, { limit, filter });
-        this._cacheResult(cacheKey, mergedResults);
-      }
-
-      // Emit YAMO block for recall operation (async, non-blocking)
-      if (this.enableYamo) {
-        this._emitYamoBlock('recall', undefined, YamoEmitter.buildRecallBlock({
-          query,
-          resultCount: mergedResults.length,
-          limit,
-          agentId: this.agentId,
-          searchType: 'hybrid'
-        })).catch(err => {
-          if (process.env.YAMO_DEBUG === 'true') {
-            console.error('[MemoryMesh] YAMO emission failed in search():', err);
-          }
-        });
-      }
-
-      return mergedResults;
-
-    } catch (error) {
-      const e = error instanceof Error ? error : new Error(String(error));
-      throw e;
     }
-  }
-
-  /**
-   * Get a record by ID
-   * @param {string} id - Record ID
-   * @returns {Promise<Object|null>} Record object or null if not found
-   */
-  async get(id) {
-    await this.init();
-
-    try {
-      if (!this.client) throw new Error('Database client not initialized');
-      const record = await this.client.getById(id);
-
-      if (!record) {
-        return null;
-      }
-
-      return {
-        id: record.id,
-        content: record.content,
-        metadata: record.metadata,
-        created_at: record.created_at,
-        updated_at: record.updated_at
-      };
-
-
-    } catch (error) {
-      const e = error instanceof Error ? error : new Error(String(error));
-      throw e;
+    /**
+     * Update reliability
+     */
+    async updateSkillReliability(id, success) {
+        await this.init();
+        if (!this.skillTable) {
+            throw new Error("Skill table not initialized");
+        }
+        try {
+            const results = await this.skillTable
+                .query()
+                .filter(`id == '${id}'`)
+                .toArray();
+            if (results.length === 0) {
+                throw new Error(`Skill ${id} not found`);
+            }
+            const record = results[0];
+            const metadata = JSON.parse(record.metadata);
+            const adjustment = success ? 0.1 : -0.2;
+            metadata.reliability = Math.max(0, Math.min(1.0, (metadata.reliability || 0.5) + adjustment));
+            metadata.use_count = (metadata.use_count || 0) + 1;
+            metadata.last_used = new Date().toISOString();
+            await this.skillTable.update({
+                where: `id == '${id}'`,
+                values: { metadata: JSON.stringify(metadata) },
+            });
+            return {
+                id,
+                reliability: metadata.reliability,
+                use_count: metadata.use_count,
+            };
+        }
+        catch (error) {
+            throw new Error(`Failed to update skill reliability: ${error.message}`);
+        }
     }
-  }
-
-  /**
-   * Get all memory records
-   * @param {Object} options - Options
-   * @param {number} [options.limit] - Limit results
-   * @returns {Promise<Array>} Array of records
-   */
-  async getAll(options = {}) {
-    await this.init();
-    try {
-      if (!this.client) throw new Error('Database client not initialized');
-      return await this.client.getAll(options);
-    } catch (error) {
-      const e = error instanceof Error ? error : new Error(String(error));
-      throw e;
+    /**
+     * Prune skills
+     */
+    async pruneSkills(threshold = 0.3) {
+        await this.init();
+        if (!this.skillTable) {
+            throw new Error("Skill table not initialized");
+        }
+        try {
+            const allSkills = await this.skillTable.query().toArray();
+            let prunedCount = 0;
+            for (const skill of allSkills) {
+                const metadata = JSON.parse(skill.metadata);
+                if (metadata.reliability < threshold) {
+                    await this.skillTable.delete(`id == '${skill.id}'`);
+                    prunedCount++;
+                }
+            }
+            return {
+                pruned_count: prunedCount,
+                total_remaining: allSkills.length - prunedCount,
+            };
+        }
+        catch (error) {
+            throw new Error(`Pruning failed: ${error.message}`);
+        }
     }
-  }
-
-  /**
-   * Get YAMO blocks for this agent (audit trail)
-   * @param {Object} options - Query options
-   * @param {string} [options.operationType] - Filter by operation type ('retain', 'recall', 'reflect')
-   * @param {number} [options.limit=10] - Max results to return
-   * @returns {Promise<Array>} List of YAMO blocks
-   */
-  async getYamoLog(options = {}) {
-    if (!this.yamoTable) {
-      return [];
+    /**
+     * List all synthesized skills
+     * @param {Object} [options={}] - Search options
+     * @returns {Promise<Array>} Normalized skill results
+     */
+    async listSkills(options = {}) {
+        await this.init();
+        if (!this.skillTable) {
+            return [];
+        }
+        try {
+            const limit = options.limit || 10;
+            const results = await this.skillTable.query().limit(limit).toArray();
+            return results.map((r) => ({
+                ...r,
+                score: 1.0, // Full score for direct listing
+                // Parse metadata JSON string to object
+                metadata: typeof r.metadata === "string" ? JSON.parse(r.metadata) : r.metadata,
+            }));
+        }
+        catch (error) {
+            if (process.env.YAMO_DEBUG === "true") {
+                logger.error({ err: error }, "Skill list failed");
+            }
+            return [];
+        }
     }
-
-    const limit = options.limit || 10;
-    const operationType = options.operationType;
-
-    try {
-      // Use search with empty vector to get all records, then filter
-      // This avoids using the protected execute() method
-      const allResults = [];
-
-      // Build query manually using the LanceDB table
-      // @ts-ignore - LanceDB types may not match exactly
-      const table = this.yamoTable;
-
-      // Get all records and filter
-      // @ts-ignore
-      const records = await table.query().limit(limit * 2).toArrow();
-
-      // Process Arrow table
-      for (const row of records) {
-        const opType = row.operationType;
-        if (!operationType || opType === operationType) {
-          allResults.push({
-            id: row.id,
-            agentId: row.agentId,
-            operationType: row.operationType,
-            yamoText: row.yamoText,
-            timestamp: row.timestamp,
-            blockHash: row.blockHash,
-            metadata: row.metadata ? JSON.parse(row.metadata) : null
-          });
-
-          if (allResults.length >= limit) {
-            break;
-          }
+    /**
+     * Search for synthesized skills by semantic intent
+     * @param {string} query - Search query (intent description)
+     * @param {Object} [options={}] - Search options
+     * @returns {Promise<Array>} Normalized skill results
+     */
+    async searchSkills(query, options = {}) {
+        await this.init();
+        if (!this.skillTable) {
+            return [];
+        }
+        try {
+            // 1. Check for explicit skill targeting (e.g., "Architect: ...")
+            const explicitMatch = query.match(/^([a-zA-Z0-9_-]+):/);
+            if (explicitMatch) {
+                const targetName = explicitMatch[1];
+                const directResults = await this.skillTable
+                    .query()
+                    .where(`name == '${targetName}'`)
+                    .limit(1)
+                    .toArray();
+                if (directResults.length > 0) {
+                    return directResults.map((r) => ({
+                        ...r,
+                        score: 1.0, // Maximum score for explicit target
+                    }));
+                }
+            }
+            // 2. Hybrid search: vector + keyword matching
+            const limit = options.limit || 5;
+            // 2a. Vector search (get more candidates for fusion)
+            const vector = await this.embeddingFactory.embed(query);
+            const vectorResults = await this.skillTable
+                .search(vector)
+                .limit(limit * 3)
+                .toArray();
+            // 2b. Keyword matching against skill fields (including tags)
+            const queryTokens = this._tokenizeQuery(query);
+            const keywordScores = new Map();
+            let maxKeywordScore = 0;
+            for (const result of vectorResults) {
+                let score = 0;
+                const nameTokens = this._tokenizeQuery(result.name);
+                const intentTokens = this._tokenizeQuery(result.intent || "");
+                const tags = extractSkillTags(result.yamo_text);
+                const tagTokens = tags.flatMap((t) => this._tokenizeQuery(t));
+                const descTokens = this._tokenizeQuery(result.yamo_text.substring(0, 500)); // First 500 chars
+                // Token matching with field-based weights
+                // Support both exact and partial matches (for compound words)
+                for (const qToken of queryTokens) {
+                    // Exact or partial match in name
+                    if (nameTokens.some((nt) => nt === qToken || qToken.includes(nt) || nt.includes(qToken))) {
+                        score += 10.0; // Highest: name match
+                    }
+                    // Exact or partial match in tags
+                    if (tagTokens.some((tt) => tt === qToken || qToken.includes(tt) || tt.includes(qToken))) {
+                        score += 7.0; // High: tag match
+                    }
+                    // Exact match in intent
+                    if (intentTokens.some((it) => it === qToken)) {
+                        score += 5.0; // Medium: intent match
+                    }
+                    // Exact match in description
+                    if (descTokens.some((dt) => dt === qToken)) {
+                        score += 1.0; // Low: description match
+                    }
+                }
+                if (score > 0) {
+                    keywordScores.set(result.id, score);
+                    maxKeywordScore = Math.max(maxKeywordScore, score);
+                }
+            }
+            // 2c. Combine scores using weighted fusion
+            const fusedResults = vectorResults.map((r) => {
+                // Normalize vector distance to [0, 1] similarity score
+                // LanceDB cosine distance ranges from 0 (identical) to 2 (opposite)
+                const rawDistance = r._distance !== undefined ? r._distance : 1.0;
+                const vectorScore = Math.max(0, Math.min(1.0, 1 - rawDistance / 2));
+                const keywordScore = keywordScores.get(r.id) || 0;
+                // Normalize keyword score by max observed (or use fixed max to avoid division by zero)
+                const normalizedKeyword = maxKeywordScore > 0 ? keywordScore / maxKeywordScore : 0;
+                // Weighted combination: 70% keyword, 30% vector
+                // Keywords get higher weight to prioritize exact matches
+                const combinedScore = 0.7 * normalizedKeyword + 0.3 * vectorScore;
+                return {
+                    ...r,
+                    score: combinedScore,
+                    _vectorScore: vectorScore,
+                    _keywordScore: keywordScore,
+                };
+            });
+            // Sort by combined score and return top results
+            // Don't normalize - we already calculated hybrid scores
+            return fusedResults
+                .sort((a, b) => b.score - a.score)
+                .slice(0, limit)
+                .map((r) => ({
+                ...r,
+                // Parse metadata JSON string to object for policy loading
+                metadata: typeof r.metadata === "string"
+                    ? JSON.parse(r.metadata)
+                    : r.metadata,
+            }))
+                .map((r) => ({
+                ...r,
+                score: parseFloat(r.score.toFixed(2)), // Round for consistency
+            }));
+        }
+        catch (error) {
+            if (process.env.YAMO_DEBUG === "true") {
+                logger.error({ err: error }, "Skill search failed");
+            }
+            return [];
         }
-      }
-
-      return allResults;
-    } catch (error) {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      console.error('[MemoryMesh] Failed to get YAMO log:', errorMessage);
-      return [];
     }
-  }
-
-  /**
-   * Update a memory record
-   * @param {string} id - Record ID
-   * @param {string} content - New content
-   * @param {Object} metadata - New metadata
-   * @returns {Promise<Object>} Result
-   */
-  async update(id, content, metadata = {}) {
-    await this.init();
-
-    try {
-      // Layer 0: Scrubber Sanitization
-      let processedContent = content;
-      let scrubbedMetadata = {};
-      
-      try {
-        const scrubbedResult = await this.scrubber.process({
-          content: content,
-          source: 'memory-update',
-          type: 'txt'
-        });
-
-        if (scrubbedResult.success && scrubbedResult.chunks.length > 0) {
-          processedContent = scrubbedResult.chunks.map(c => c.text).join('\n\n');
-          if (scrubbedResult.metadata) {
-             scrubbedMetadata = {
-               ...scrubbedResult.metadata,
-               scrubber_telemetry: JSON.stringify(scrubbedResult.telemetry)
-             };
-          }
-        }
-      } catch (e) {
-        // Fallback
-      }
-
-      const sanitizedContent = this._sanitizeContent(processedContent);
-      const sanitizedMetadata = this._validateMetadata({ ...metadata, ...scrubbedMetadata });
-
-      // Re-generate embedding
-      const vector = await this.embeddingFactory.embed(sanitizedContent);
-
-      const updateData = {
-        vector,
-        content: sanitizedContent,
-        metadata: JSON.stringify(sanitizedMetadata)
-      };
-
-      if (!this.client) throw new Error('Database client not initialized');
-      const result = await this.client.update(id, updateData);
-
-      return {
-        id: result.id,
-        content: sanitizedContent,
-        success: result.success
-      };
-
-    } catch (error) {
-      const e = error instanceof Error ? error : new Error(String(error));
-      throw e;
+    /**
+     * Get recent YAMO logs for the heartbeat
+     * @param {Object} options
+     */
+    async getYamoLog(options = {}) {
+        if (!this.yamoTable) {
+            return [];
+        }
+        const limit = options.limit || 10;
+        const maxRetries = 5;
+        for (let attempt = 1; attempt <= maxRetries; attempt++) {
+            try {
+                // orderBy might not be in LanceDB types but is supported in runtime
+                const query = this.yamoTable.query();
+                let results;
+                try {
+                    results = await query
+                        .orderBy("timestamp", "desc")
+                        .limit(limit)
+                        .toArray();
+                }
+                catch (_e) {
+                    // Fallback if orderBy not supported
+                    results = await query.limit(1000).toArray(); // Get more and sort manually
+                }
+                // Sort newest first in memory
+                return results
+                    .sort((a, b) => {
+                    const tA = a.timestamp instanceof Date
+                        ? a.timestamp.getTime()
+                        : Number(a.timestamp);
+                    const tB = b.timestamp instanceof Date
+                        ? b.timestamp.getTime()
+                        : Number(b.timestamp);
+                    return tB - tA;
+                })
+                    .slice(0, limit)
+                    .map((r) => ({
+                    id: r.id,
+                    yamoText: r.yamo_text,
+                    timestamp: r.timestamp,
+                }));
+            }
+            catch (error) {
+                const msg = error.message || "";
+                const isRetryable = msg.includes("LanceError(IO)") ||
+                    msg.includes("next batch") ||
+                    msg.includes("No such file") ||
+                    msg.includes("busy");
+                if (isRetryable && attempt < maxRetries) {
+                    // If we suspect stale table handle, try to refresh it
+                    try {
+                        // Re-open table to get fresh file handles
+                        const { createYamoTable } = await import("../yamo/schema.js");
+                        if (this.dbDir) {
+                            const db = await lancedb.connect(this.dbDir);
+                            this.yamoTable = await createYamoTable(db, "yamo_blocks");
+                            if (process.env.YAMO_DEBUG === "true") {
+                                logger.debug({ attempt, msg: msg.substring(0, 100) }, "Refreshed yamoTable handle during retry");
+                            }
+                        }
+                    }
+                    catch (e) {
+                        logger.warn({ err: e }, "Failed to refresh table handle during retry");
+                    }
+                    const delay = 500 * Math.pow(2, attempt - 1); // 500ms, 1000ms, 2000ms, 4000ms
+                    await new Promise((resolve) => setTimeout(resolve, delay));
+                    continue;
+                }
+                // Only log warning on final failure
+                if (attempt === maxRetries) {
+                    logger.warn({ err: error }, "Failed to get log after retries");
+                }
+                else if (!isRetryable) {
+                    // Non-retryable error
+                    logger.warn({ err: error }, "Failed to get log (non-retryable)");
+                    break;
+                }
+            }
+        }
+        return [];
     }
-  }
-
-  /**
-   * Delete a record by ID
-   * @param {string} id - Record ID to delete
-   * @returns {Promise<Object>} Result with success status
-   */
-  async delete(id) {
-    await this.init();
-
-    try {
-      if (!this.client) throw new Error('Database client not initialized');
-      const result = await this.client.delete(id);
-
-      // Remove from Keyword Search
-      this.keywordSearch.remove(id);
-
-      return {
-        deleted: result.id,
-        success: result.success
-      };
-
-
-    } catch (error) {
-      const e = error instanceof Error ? error : new Error(String(error));
-      throw e;
+    /**
+     * Emit a YAMO block to the YAMO blocks table
+     * @private
+     *
+     * Note: YAMO emission is non-critical - failures are logged but don't throw
+     * to prevent disrupting the main operation.
+     */
+    async _emitYamoBlock(operationType, memoryId, yamoText) {
+        if (!this.yamoTable) {
+            return;
+        }
+        const yamoId = `yamo_${operationType}_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`;
+        try {
+            await this.yamoTable.add([
+                {
+                    id: yamoId,
+                    agent_id: this.agentId,
+                    operation_type: operationType,
+                    yamo_text: yamoText,
+                    timestamp: new Date(),
+                    block_hash: null,
+                    prev_hash: null,
+                    metadata: JSON.stringify({
+                        memory_id: memoryId || null,
+                        timestamp: new Date().toISOString(),
+                    }),
+                },
+            ]);
+        }
+        catch (error) {
+            // Log emission failures in debug mode
+            // Emission is non-critical, so we don't throw
+            if (process.env.YAMO_DEBUG === "true") {
+                logger.warn({ err: error, operationType }, "YAMO emission failed");
+            }
+        }
     }
-  }
-
-  /**
-   * Get database statistics
-   * @returns {Promise<Object>} Statistics including count, size, etc.
-   */
-  async stats() {
-    await this.init();
-
-    try {
-      if (!this.client) throw new Error('Database client not initialized');
-      const dbStats = await this.client.getStats();
-      const embeddingStats = this.embeddingFactory.getStats();
-
-      return {
-        count: dbStats.count,
-        tableName: dbStats.tableName,
-        uri: dbStats.uri,
-        isConnected: dbStats.isConnected,
-        embedding: embeddingStats
-      };
-
-
-    } catch (error) {
-      const e = error instanceof Error ? error : new Error(String(error));
-      throw e;
+    /**
+     * Search memory using hybrid vector + keyword search with Reciprocal Rank Fusion (RRF).
+     *
+     * This method performs semantic search by combining:
+     * 1. **Vector Search**: Uses embeddings to find semantically similar content
+     * 2. **Keyword Search**: Uses BM25-style keyword matching
+     * 3. **RRF Fusion**: Combines both result sets using Reciprocal Rank Fusion
+     *
+     * The RRF algorithm scores each document as: `sum(1 / (k + rank))` where k=60.
+     * This gives higher scores to documents that rank well in BOTH searches.
+     *
+     * **Performance**: Uses adaptive sorting strategy
+     * - Small datasets (≤ 2× limit): Full sort O(n log n)
+     * - Large datasets: Partial selection sort O(n×k) where k=limit
+     *
+     * **Caching**: Results are cached for 5 minutes by default (configurable via options)
+     *
+     * @param query - The search query text
+     * @param options - Search options
+     * @param options.limit - Maximum results to return (default: 10)
+     * @param options.filter - LanceDB filter expression (e.g., "type == 'preference'")
+     * @param options.useCache - Enable/disable result caching (default: true)
+     * @returns Promise with array of search results, sorted by relevance score
+     *
+     * @example
+     * ```typescript
+     * // Simple search
+     * const results = await mesh.search("TypeScript preferences");
+     *
+     * // Search with filter
+     * const code = await mesh.search("bug fix", { filter: "type == 'error'" });
+     *
+     * // Search with limit
+     * const top3 = await mesh.search("security issues", { limit: 3 });
+     * ```
+     *
+     * @throws {Error} If embedding generation fails
+     * @throws {Error} If database client is not initialized
+     */
+    async search(query, options = {}) {
+        await this.init();
+        try {
+            const limit = options.limit || 10;
+            const filter = options.filter || null;
+            const useCache = options.useCache !== undefined ? options.useCache : true;
+            if (useCache) {
+                const cacheKey = this._generateCacheKey(query, { limit, filter });
+                const cached = this._getCachedResult(cacheKey);
+                if (cached) {
+                    return cached;
+                }
+            }
+            const vector = await this.embeddingFactory.embed(query);
+            if (!this.client) {
+                throw new Error("Database client not initialized");
+            }
+            const vectorResults = await this.client.search(vector, {
+                limit: limit * 2,
+                metric: "cosine",
+                filter,
+            });
+            const keywordResults = this.keywordSearch.search(query, {
+                limit: limit * 2,
+            });
+            // Optimized Reciprocal Rank Fusion (RRF) with min-heap for O(n log k) performance
+            // Instead of sorting all results (O(n log n)), we maintain a heap of size k (O(n log k))
+            const k = 60; // RRF constant
+            const scores = new Map();
+            const docMap = new Map();
+            // Process vector results - O(m) where m = vectorResults.length
+            for (let rank = 0; rank < vectorResults.length; rank++) {
+                const doc = vectorResults[rank];
+                const rrf = 1 / (k + rank + 1);
+                scores.set(doc.id, (scores.get(doc.id) || 0) + rrf);
+                docMap.set(doc.id, doc);
+            }
+            // Process keyword results - O(n) where n = keywordResults.length
+            for (let rank = 0; rank < keywordResults.length; rank++) {
+                const doc = keywordResults[rank];
+                const rrf = 1 / (k + rank + 1);
+                scores.set(doc.id, (scores.get(doc.id) || 0) + rrf);
+                if (!docMap.has(doc.id)) {
+                    docMap.set(doc.id, {
+                        id: doc.id,
+                        content: doc.content,
+                        metadata: doc.metadata,
+                        score: 0,
+                        created_at: new Date().toISOString(),
+                    });
+                }
+            }
+            // Extract top k results using min-heap pattern - O(n log k)
+            // Since JavaScript doesn't have a built-in heap, we use an efficient approach:
+            // Convert to array and sort only if results exceed limit significantly
+            const scoreEntries = Array.from(scores.entries());
+            let mergedResults;
+            if (scoreEntries.length <= limit * 2) {
+                // Small dataset: standard sort is fine
+                mergedResults = scoreEntries
+                    .sort((a, b) => b[1] - a[1]) // O(n log n) but n is small
+                    .slice(0, limit)
+                    .map(([id, score]) => {
+                    const doc = docMap.get(id);
+                    return doc ? { ...doc, score } : null;
+                })
+                    .filter((d) => d !== null);
+            }
+            else {
+                // Large dataset: use partial selection sort (O(n*k) but k is small)
+                // This is more efficient than full sort when we only need top k results
+                const topK = [];
+                for (const entry of scoreEntries) {
+                    if (topK.length < limit) {
+                        topK.push(entry);
+                        // Keep topK sorted in descending order
+                        topK.sort((a, b) => b[1] - a[1]);
+                    }
+                    else if (entry[1] > topK[topK.length - 1][1]) {
+                        // Replace smallest in topK if current is larger
+                        topK[limit - 1] = entry;
+                        topK.sort((a, b) => b[1] - a[1]);
+                    }
+                }
+                mergedResults = topK
+                    .map(([id, score]) => {
+                    const doc = docMap.get(id);
+                    return doc ? { ...doc, score } : null;
+                })
+                    .filter((d) => d !== null);
+            }
+            const normalizedResults = this._normalizeScores(mergedResults);
+            if (useCache) {
+                const cacheKey = this._generateCacheKey(query, { limit, filter });
+                this._cacheResult(cacheKey, normalizedResults);
+            }
+            if (this.enableYamo) {
+                this._emitYamoBlock("recall", undefined, YamoEmitter.buildRecallBlock({
+                    query,
+                    resultCount: normalizedResults.length,
+                    limit,
+                    agentId: this.agentId,
+                    searchType: "hybrid",
+                })).catch((error) => {
+                    // Log emission failures in debug mode but don't throw
+                    if (process.env.YAMO_DEBUG === "true") {
+                        logger.warn({ err: error }, "Failed to emit YAMO block (recall)");
+                    }
+                });
+            }
+            return normalizedResults;
+        }
+        catch (error) {
+            throw error instanceof Error ? error : new Error(String(error));
+        }
     }
-  }
-
-  /**
-   * Health check for MemoryMesh
-   * @returns {Promise<Object>} Health status with checks for all components
-   */
-  async healthCheck() {
-    const health = {
-      status: 'healthy',
-      timestamp: new Date().toISOString(),
-      checks: {}
-    };
-
-    // Check 1: Database connectivity
-    try {
-      const startDb = Date.now();
-      await this.init();
-      const dbLatency = Date.now() - startDb;
-
-      // @ts-ignore
-      health.checks.database = {
-        status: 'up',
-        latency: dbLatency,
-        isConnected: this.client?.isConnected || false,
-        tableName: this.client?.tableName || 'unknown'
-      };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      // @ts-ignore
-      health.checks.database = {
-        status: 'error',
-        error: message
-      };
-      health.status = 'degraded';
+    _normalizeScores(results) {
+        if (results.length === 0) {
+            return [];
+        }
+        return results.map((r) => {
+            // LanceDB _distance is squared L2 or cosine distance
+            // For cosine distance in MiniLM, it ranges from 0 to 2
+            const rawDistance = r._distance !== undefined ? r._distance : 1.0;
+            // Convert to similarity score [0, 1]
+            const score = Math.max(0, Math.min(1.0, 1 - rawDistance / 2));
+            return {
+                ...r,
+                score: parseFloat(score.toFixed(2)),
+            };
+        });
     }
-
-    // Check 2: Embedding service
-    try {
-      const startEmbedding = Date.now();
-      const testEmbedding = await this.embeddingFactory.embed('health check');
-      const embeddingLatency = Date.now() - startEmbedding;
-
-      // @ts-ignore
-      health.checks.embedding = {
-        status: 'up',
-        latency: embeddingLatency,
-        dimension: testEmbedding.length,
-        configured: true
-      };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      // @ts-ignore
-      health.checks.embedding = {
-        status: 'error',
-        error: message
-      };
-      health.status = 'degraded';
+    /**
+     * Tokenize query for keyword matching (private helper for searchSkills)
+     * Converts text to lowercase tokens, filtering out short tokens and punctuation.
+     * Handles camelCase/PascalCase by splitting on uppercase letters.
+     */
+    _tokenizeQuery(text) {
+        return text
+            .replace(/([a-z])([A-Z])/g, "$1 $2") // Split camelCase: "targetSkill" → "target Skill"
+            .toLowerCase()
+            .replace(/[^\w\s]/g, "")
+            .split(/\s+/)
+            .filter((t) => t.length > 2); // Filter out very short tokens
     }
-
-    // Check 3: Get stats (verifies read operations work)
-    try {
-      const stats = await this.stats();
-      // @ts-ignore
-      health.checks.stats = {
-        status: 'up',
-        recordCount: stats.count || 0
-      };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      // @ts-ignore
-      health.checks.stats = {
-        status: 'warning',
-        error: message
-      };
-      // Don't degrade status for stats failure - it's not critical
+    formatResults(results) {
+        if (results.length === 0) {
+            return "No relevant memories found.";
+        }
+        let output = `[ATTENTION DIRECTIVE]\nThe following [MEMORY CONTEXT] is weighted by relevance.
+- ALIGN attention to entries with [IMPORTANCE >= 0.8].
+- TREAT entries with [IMPORTANCE <= 0.4] as auxiliary background info.
+
+[MEMORY CONTEXT]`;
+        results.forEach((res, i) => {
+            const metadata = typeof res.metadata === "string"
+                ? JSON.parse(res.metadata)
+                : res.metadata;
+            output += `\n\n--- MEMORY ${i + 1}: ${res.id} [IMPORTANCE: ${res.score}] ---\nType: ${metadata.type || "event"} | Source: ${metadata.source || "unknown"}\n${res.content}`;
+        });
+        return output;
     }
-
-    // Check 4: Cache status (if caching enabled)
-    if (this.queryCache) {
-      // @ts-ignore
-      health.checks.cache = {
-        status: 'up',
-        size: this.queryCache.size || 0,
-        max: this.cacheConfig?.maxSize || 'unknown'
-      };
+    async get(id) {
+        await this.init();
+        if (!this.client) {
+            throw new Error("Database client not initialized");
+        }
+        const record = await this.client.getById(id);
+        return record
+            ? {
+                id: record.id,
+                content: record.content,
+                metadata: record.metadata,
+                created_at: record.created_at,
+                updated_at: record.updated_at,
+            }
+            : null;
     }
-
-    return health;
-  }
-
-  /**
-   * Parse embedding configuration from environment
-   * @private
-   */
-  _parseEmbeddingConfig() {
-    const configs = [];
-
-    // Primary: from EMBEDDING_MODEL_TYPE
-    configs.push({
-      modelType: process.env.EMBEDDING_MODEL_TYPE || 'local',
-      modelName: process.env.EMBEDDING_MODEL_NAME || 'Xenova/all-MiniLM-L6-v2',
-      dimension: parseInt(process.env.EMBEDDING_DIMENSION || '384'),
-      priority: 1,
-      apiKey: process.env.EMBEDDING_API_KEY || process.env.OPENAI_API_KEY || process.env.COHERE_API_KEY
-    });
-
-    // Fallback 1: local model (if primary is API)
-    if (configs[0].modelType !== 'local') {
-      configs.push({
-        modelType: 'local',
-        modelName: 'Xenova/all-MiniLM-L6-v2',
-        dimension: 384,
-        priority: 2
-      });
+    async getAll(options = {}) {
+        await this.init();
+        if (!this.client) {
+            throw new Error("Database client not initialized");
+        }
+        return this.client.getAll(options);
     }
-
-    // Fallback 2: OpenAI (if key available)
-    if (process.env.OPENAI_API_KEY && configs[0].modelType !== 'openai') {
-      configs.push({
-        modelType: 'openai',
-        modelName: 'text-embedding-3-small',
-        dimension: 1536,
-        priority: 3,
-        apiKey: process.env.OPENAI_API_KEY
-      });
+    async stats() {
+        await this.init();
+        if (!this.enableMemory || !this.client) {
+            return {
+                count: 0,
+                totalMemories: 0,
+                totalSkills: 0,
+                tableName: "N/A",
+                uri: "N/A",
+                isConnected: false,
+                embedding: { configured: false, primary: null, fallbacks: [] },
+                status: "disabled",
+            };
+        }
+        const dbStats = await this.client.getStats();
+        // Enrich embedding stats with total persisted count
+        const embeddingStats = this.embeddingFactory.getStats();
+        if (embeddingStats.primary) {
+            embeddingStats.primary.totalPersisted = dbStats.count;
+        }
+        // Get skill count
+        let totalSkills = 0;
+        if (this.skillTable) {
+            try {
+                const skills = await this.skillTable.query().limit(10000).toArray();
+                totalSkills = skills.length;
+            }
+            catch (_e) {
+                // Ignore errors
+            }
+        }
+        return {
+            count: dbStats.count,
+            totalMemories: dbStats.count,
+            totalSkills,
+            tableName: dbStats.tableName,
+            uri: dbStats.uri,
+            isConnected: dbStats.isConnected,
+            embedding: embeddingStats,
+        };
     }
-
-    return configs;
-  }
-
-  /**
-   * Build a LanceDB filter expression from an object
-   * Supports basic filtering on metadata fields
-   * @param {Object} filter - Filter object
-   * @returns {string|null} LanceDB filter expression
-   * @private
-   */
-  _buildFilter(filter) {
-    if (!filter || typeof filter !== 'object') {
-      return null;
+    _parseEmbeddingConfig() {
+        const configs = [
+            {
+                modelType: process.env.EMBEDDING_MODEL_TYPE || "local",
+                modelName: process.env.EMBEDDING_MODEL_NAME || "Xenova/all-MiniLM-L6-v2",
+                dimension: parseInt(process.env.EMBEDDING_DIMENSION || "384"),
+                priority: 1,
+                apiKey: process.env.EMBEDDING_API_KEY ||
+                    process.env.OPENAI_API_KEY ||
+                    process.env.COHERE_API_KEY,
+            },
+        ];
+        if (configs[0].modelType !== "local") {
+            configs.push({
+                modelType: "local",
+                modelName: "Xenova/all-MiniLM-L6-v2",
+                dimension: 384,
+                priority: 2,
+                apiKey: undefined,
+            });
+        }
+        return configs;
     }
-
-    const conditions = [];
-
-    for (const [key, value] of Object.entries(filter)) {
-      if (typeof value === 'string') {
-        conditions.push(`${key} == '${value}'`);
-      } else if (typeof value === 'number') {
-        conditions.push(`${key} == ${value}`);
-      } else if (typeof value === 'boolean') {
-        conditions.push(`${key} == ${value}`);
-      }
-      // Note: Complex filtering on JSON metadata field not supported
-      // Filters work on top-level schema fields only
+    /**
+     * Close database connections and release resources
+     *
+     * This should be called when done with the MemoryMesh to properly:
+     * - Close LanceDB connections
+     * - Release file handles
+     * - Clean up resources
+     *
+     * Important for tests and cleanup to prevent connection leaks.
+     *
+     * @returns {Promise<void>}
+     *
+     * @example
+     * ```typescript
+     * const mesh = new MemoryMesh();
+     * await mesh.init();
+     * // ... use mesh ...
+     * await mesh.close(); // Clean up
+     * ```
+     */
+    // eslint-disable-next-line @typescript-eslint/require-await
+    async close() {
+        try {
+            // Close LanceDB client connection
+            if (this.client) {
+                this.client.disconnect();
+                this.client = null;
+            }
+            // Clear extension table references
+            this.yamoTable = null;
+            this.skillTable = null;
+            // Reset initialization state
+            this.isInitialized = false;
+            logger.debug("MemoryMesh closed successfully");
+        }
+        catch (error) {
+            const e = error instanceof Error ? error : new Error(String(error));
+            logger.warn({ err: e }, "Error closing MemoryMesh");
+            // Don't throw - cleanup should always succeed
+        }
     }
-
-    // @ts-ignore
-    return conditions.length > 0 ? conditions.join(' AND ') : null;
-  }
 }
-
 /**
  * Main CLI handler
  */
-async function run() {
-  let action, input;
-
-  // Check if arguments are provided via CLI
-  if (process.argv.length > 3) {
-    action = process.argv[2];
-    try {
-      input = JSON.parse(process.argv[3]);
-    } catch (e) {
-      const error = e instanceof Error ? e : new Error(String(e));
-      const errorResponse = handleError(error, { context: 'CLI argument parsing' });
-      console.error(`❌ Error: Invalid JSON argument: ${error.message}`);
-      console.error(`Received: ${process.argv[3]}`);
-      console.error(JSON.stringify(errorResponse, null, 2));
-      process.exit(1);
+export async function run() {
+    let action, input;
+    if (process.argv.length > 3) {
+        action = process.argv[2];
+        try {
+            input = JSON.parse(process.argv[3]);
+        }
+        catch (e) {
+            logger.error({ err: e }, "Invalid JSON argument");
+            process.exit(1);
+        }
+    }
+    else {
+        try {
+            const rawInput = fs.readFileSync(0, "utf8");
+            input = JSON.parse(rawInput);
+            action = input.action || action;
+        }
+        catch (_e) {
+            logger.error("No input provided");
+            process.exit(1);
+        }
     }
-  } else {
-    // Fallback to STDIN for System Skill compatibility
+    const mesh = new MemoryMesh({
+        llmProvider: process.env.LLM_PROVIDER ||
+            (process.env.OPENAI_API_KEY ? "openai" : "ollama"),
+        llmApiKey: process.env.LLM_API_KEY || process.env.OPENAI_API_KEY,
+        llmModel: process.env.LLM_MODEL,
+    });
     try {
-      const rawInput = fs.readFileSync(0, 'utf8');
-      const data = JSON.parse(rawInput);
-      action = data.action || action;
-      input = data;
-    } catch (e) {
-      const error = e instanceof Error ? e : new Error(String(e));
-      const errorResponse = handleError(error, { context: 'STDIN parsing' });
-      console.error("❌ Error: No input provided via CLI or STDIN.");
-      console.error(`Details: ${error.message}`);
-      console.error(JSON.stringify(errorResponse, null, 2));
-      process.exit(1);
+        if (action === "ingest" || action === "store") {
+            const record = await mesh.add(input.content, input.metadata || {});
+            process.stdout.write(`[MemoryMesh] Ingested record ${record.id}\n${JSON.stringify({ status: "ok", record })}\n`);
+        }
+        else if (action === "search") {
+            const results = await mesh.search(input.query, {
+                limit: input.limit || 10,
+                filter: input.filter || null,
+            });
+            process.stdout.write(`[MemoryMesh] Found ${results.length} matches.\n**Formatted Context**:\n\`\`\`yamo\n${mesh.formatResults(results)}\n\`\`\`\n**Output**: memory_results.json\n\`\`\`json\n${JSON.stringify(results, null, 2)}\n\`\`\`\n${JSON.stringify({ status: "ok", results })}\n`);
+        }
+        else if (action === "synthesize") {
+            const result = await mesh.synthesize({
+                topic: input.topic,
+                lookback: input.limit || 20,
+            });
+            process.stdout.write(`[MemoryMesh] Synthesis Outcome: ${result.status}\n${JSON.stringify(result, null, 2)}\n`);
+        }
+        else if (action === "ingest-skill") {
+            const record = await mesh.ingestSkill(input.yamo_text, input.metadata || {});
+            process.stdout.write(`[MemoryMesh] Ingested skill ${record.name} (${record.id})\n${JSON.stringify({ status: "ok", record })}\n`);
+        }
+        else if (action === "search-skills") {
+            await mesh.init();
+            const vector = await mesh.embeddingFactory.embed(input.query);
+            if (mesh.skillTable) {
+                const results = await mesh.skillTable
+                    .search(vector)
+                    .limit(input.limit || 5)
+                    .toArray();
+                process.stdout.write(`[MemoryMesh] Found ${results.length} synthesized skills.\n${JSON.stringify({ status: "ok", results }, null, 2)}\n`);
+            }
+            else {
+                process.stdout.write(`[MemoryMesh] Skill table not initialized.\n`);
+            }
+        }
+        else if (action === "skill-feedback") {
+            const result = await mesh.updateSkillReliability(input.id, input.success !== false);
+            process.stdout.write(`[MemoryMesh] Feedback recorded for ${input.id}: Reliability now ${result.reliability}\n${JSON.stringify({ status: "ok", ...result })}\n`);
+        }
+        else if (action === "skill-prune") {
+            const result = await mesh.pruneSkills(input.threshold || 0.3);
+            process.stdout.write(`[MemoryMesh] Pruning complete. Removed ${result.pruned_count} unreliable skills.\n${JSON.stringify({ status: "ok", ...result })}\n`);
+        }
+        else if (action === "stats") {
+            process.stdout.write(`[MemoryMesh] Database Statistics:\n${JSON.stringify({ status: "ok", stats: await mesh.stats() }, null, 2)}\n`);
+        }
+        else {
+            logger.error({ action }, "Unknown action");
+            process.exit(1);
+        }
     }
-  }
-
-  // Create MemoryMesh instance
-  const mesh = new MemoryMesh();
-
-  try {
-    // Route to appropriate action
-    if (action === 'ingest' || action === 'store') {
-      // Validate required fields
-      if (!input.content) {
-        console.error('❌ Error: "content" field is required for ingest action');
-        process.exit(1);
-      }
-
-      const record = await mesh.add(input.content, input.metadata || {});
-      console.log(`[MemoryMesh] Ingested record ${record.id}`);
-      console.log(JSON.stringify({ status: "ok", record }));
-
-    } else if (action === 'search') {
-      // Validate required fields
-      if (!input.query) {
-        console.error('❌ Error: "query" field is required for search action');
-        process.exit(1);
-      }
-
-      const options = {
-        limit: input.limit || 10,
-        filter: input.filter || null
-      };
-
-
-      const results = await mesh.search(input.query, options);
-      console.log(`[MemoryMesh] Found ${results.length} matches.`);
-
-      const jsonResult = JSON.stringify(results, null, 2);
-      // YAMO Skill compatibility: Output as a marked block for auto-saving
-      console.log(`\n**Output**: memory_results.json
-\`\`\`json
-${jsonResult}
-\`\`\`
-`);
-      // Also output raw JSON for STDIN callers
-      console.log(JSON.stringify({ status: "ok", results }));
-
-    } else if (action === 'get') {
-      // Validate required fields
-      if (!input.id) {
-        console.error('❌ Error: "id" field is required for get action');
-        process.exit(1);
-      }
-
-      const record = await mesh.get(input.id);
-
-      if (!record) {
-        console.log(JSON.stringify({ status: "ok", record: null }));
-      } else {
-        console.log(JSON.stringify({ status: "ok", record }));
-      }
-
-    } else if (action === 'delete') {
-      // Validate required fields
-      if (!input.id) {
-        console.error('❌ Error: "id" field is required for delete action');
+    catch (error) {
+        const errorResponse = handleError(error, {
+            action,
+            input: { ...input, content: input.content ? "[REDACTED]" : undefined },
+        });
+        logger.error({ err: error, errorResponse }, "Fatal Error");
         process.exit(1);
-      }
-
-      const result = await mesh.delete(input.id);
-      console.log(`[MemoryMesh] Deleted record ${result.deleted}`);
-      console.log(JSON.stringify({ status: "ok", ...result }));
-
-    } else if (action === 'export') {
-      const records = await mesh.getAll({ limit: input.limit || 10000 });
-      console.log(JSON.stringify({ status: "ok", count: records.length, records }));
-
-    } else if (action === 'reflect') {
-      // Enhanced reflect with LLM support
-      const enableLLM = input.llm !== false;  // Default true
-      const result = await mesh.reflect({
-        topic: input.topic,
-        lookback: input.limit || 10,
-        generate: enableLLM
-      });
-
-      if (result.reflection) {
-        // New format with LLM-generated reflection
-        console.log(JSON.stringify({
-          status: "ok",
-          reflection: result.reflection,
-          confidence: result.confidence,
-          id: result.id,
-          topic: result.topic,
-          sourceMemoryCount: result.sourceMemoryCount,
-          yamoBlock: result.yamoBlock,
-          createdAt: result.createdAt
-        }));
-      } else {
-        // Old format for backward compatibility (prompt-only mode)
-        console.log(JSON.stringify({ status: "ok", ...result }));
-      }
-
-    } else if (action === 'stats') {
-      const stats = await mesh.stats();
-      console.log('[MemoryMesh] Database Statistics:');
-      console.log(JSON.stringify({ status: "ok", stats }, null, 2));
-
-    } else {
-      console.error(`❌ Error: Unknown action "${action}". Valid actions: ingest, search, get, delete, stats`);
-      process.exit(1);
-    }
-
-  } catch (error) {
-    // Handle errors using the error handler
-    const e = error instanceof Error ? error : new Error(String(error));
-    const errorResponse = handleError(e, { action, input: { ...input, content: input.content ? '[REDACTED]' : undefined } });
-
-    if (errorResponse.success === false) {
-      console.error(`❌ Fatal Error: ${errorResponse.error.message}`);
-      if (process.env.NODE_ENV === 'development' && errorResponse.error.details) {
-        console.error(`Details:`, errorResponse.error.details);
-      }
-      console.error(JSON.stringify(errorResponse, null, 2));
-    } else {
-      console.error(`❌ Fatal Error: ${e.message}`);
-      console.error(e.stack);
     }
-
-    process.exit(1);
-  }
 }
-
-// Export for testing and CLI usage
-export { MemoryMesh, run };
 export default MemoryMesh;
-
-// Run CLI if called directly
 if (process.argv[1] === fileURLToPath(import.meta.url)) {
-  run().catch(err => {
-    console.error(`❌ Fatal Error: ${err.message}`);
-    console.error(err.stack);
-    process.exit(1);
-  });
+    run().catch((err) => {
+        logger.error({ err }, "Fatal Error");
+        process.exit(1);
+    });
 }