@yamo/memory-mesh 2.1.3 → 2.2.0

package/README.md

@@ -12,6 +12,8 @@ Built on the [YAMO Protocol](https://github.com/yamo-protocol) for transparent a
 - **Portable CLI**: Simple JSON-based interface for any agent or language.
 - **YAMO Skills Integration**: Includes yamo-super workflow system with automatic memory learning.
 - **Pattern Recognition**: Workflows automatically store and retrieve execution patterns for optimization.
+- **LLM-Powered Reflections**: Generate insights from memories using configurable LLM providers.
+- **YAMO Audit Trail**: Automatic emission of structured blocks for all memory operations.
 
 ## Installation
 
@@ -44,6 +46,63 @@ await mesh.add('Content', { meta: 'data' });
 const results = await mesh.search('query');
 ```
 
+### Enhanced Reflections with LLM
+
+MemoryMesh supports LLM-powered reflection generation that synthesizes insights from stored memories:
+
+```javascript
+import { MemoryMesh } from '@yamo/memory-mesh';
+
+// Enable LLM integration (requires API key or local model)
+const mesh = new MemoryMesh({
+  enableLLM: true,
+  llmProvider: 'openai',  // or 'anthropic', 'ollama'
+  llmApiKey: process.env.OPENAI_API_KEY,
+  llmModel: 'gpt-4o-mini'
+});
+
+// Store some memories
+await mesh.add('Bug: type mismatch in keyword search', { type: 'bug' });
+await mesh.add('Bug: missing content field', { type: 'bug' });
+
+// Generate reflection (automatically stores result to memory)
+const reflection = await mesh.reflect({ topic: 'bugs', lookback: 10 });
+
+console.log(reflection.reflection);
+// Output: "Synthesized from 2 memories: Bug: type mismatch..., Bug: missing content..."
+
+console.log(reflection.confidence);  // 0.85
+console.log(reflection.yamoBlock);    // YAMO audit trail
+```
+
+**CLI Usage:**
+
+```bash
+# With LLM (default)
+memory-mesh reflect '{"topic": "bugs", "limit": 10}'
+
+# Without LLM (prompt-only for external LLM)
+memory-mesh reflect '{"topic": "bugs", "llm": false}'
+```
+
+### YAMO Audit Trail
+
+MemoryMesh automatically emits YAMO blocks for all operations when enabled:
+
+```javascript
+const mesh = new MemoryMesh({ enableYamo: true });
+
+// All operations now emit YAMO blocks
+await mesh.add('Memory content', { type: 'event' });      // emits 'retain' block
+await mesh.search('query');                                 // emits 'recall' block
+await mesh.reflect({ topic: 'test' });                      // emits 'reflect' block
+
+// Query YAMO log
+const yamoLog = await mesh.getYamoLog({ operationType: 'reflect', limit: 10 });
+console.log(yamoLog);
+// [{ id, agentId, operationType, yamoText, timestamp, ... }]
+```
+
 ## Using in a Project
 
 To use MemoryMesh with your Claude Code skills (like `yamo-super`) in a new project:
@@ -127,3 +186,66 @@ Memory Mesh implements YAMO v2.1.0 compliance with:
 - **Development Guide**: [CLAUDE.md](CLAUDE.md) - Guide for Claude Code development
 - **Marketplace**: [.claude-plugin/marketplace.json](.claude-plugin/marketplace.json) - Plugin metadata
 
+## Configuration
+
+### LLM Provider Configuration
+
+```bash
+# Required for LLM-powered reflections
+LLM_PROVIDER=openai          # Provider: 'openai', 'anthropic', 'ollama'
+LLM_API_KEY=sk-...            # API key for OpenAI/Anthropic
+LLM_MODEL=gpt-4o-mini         # Model name
+LLM_BASE_URL=https://...      # Optional: Custom API base URL
+```
+
+**Supported Providers:**
+- **OpenAI**: GPT-4, GPT-4o-mini, etc.
+- **Anthropic**: Claude 3.5 Haiku, Sonnet, Opus
+- **Ollama**: Local models (llama3.2, mistral, etc.)
+
+### YAMO Configuration
+
+```bash
+# Optional YAMO settings
+ENABLE_YAMO=true              # Enable YAMO block emission (default: true)
+YAMO_DEBUG=true               # Enable verbose YAMO logging
+```
+
+### LanceDB Configuration
+
+```bash
+# Vector database settings
+LANCEDB_URI=./runtime/data/lancedb
+LANCEDB_MEMORY_TABLE=memory_entries
+```
+
+### Embedding Configuration
+
+```bash
+# Embedding model settings
+EMBEDDING_MODEL_TYPE=local    # 'local', 'openai', 'cohere', 'ollama'
+EMBEDDING_MODEL_NAME=Xenova/all-MiniLM-L6-v2
+EMBEDDING_DIMENSION=384
+```
+
+### Example .env File
+
+```bash
+# LLM for reflections
+LLM_PROVIDER=openai
+LLM_API_KEY=sk-your-key-here
+LLM_MODEL=gpt-4o-mini
+
+# YAMO audit
+ENABLE_YAMO=true
+YAMO_DEBUG=false
+
+# Vector DB
+LANCEDB_URI=./data/lancedb
+
+# Embeddings (local default)
+EMBEDDING_MODEL_TYPE=local
+EMBEDDING_MODEL_NAME=Xenova/all-MiniLM-L6-v2
+```
+
+

package/lib/llm/client.js

@@ -0,0 +1,391 @@
+/**
+ * LLM Client - Multi-provider LLM API client for reflection generation
+ *
+ * Supports:
+ * - OpenAI (GPT-4, GPT-4o-mini, etc.)
+ * - Anthropic (Claude)
+ * - Ollama (local models)
+ * - Graceful fallback when LLM unavailable
+ */
+
+/**
+ * LLMClient provides unified interface for calling various LLM providers
+ * to generate reflections from memory contexts.
+ */
+export class LLMClient {
+  /**
+   * Create a new LLMClient instance
+   *
+   * @param {Object} [config={}] - Configuration options
+   * @param {string} [config.provider='openai'] - LLM provider ('openai', 'anthropic', 'ollama')
+   * @param {string} [config.apiKey] - API key (defaults to env var)
+   * @param {string} [config.model] - Model name
+   * @param {string} [config.baseUrl] - Base URL for API (optional)
+   * @param {number} [config.timeout=30000] - Request timeout in ms
+   * @param {number} [config.maxRetries=2] - Max retry attempts
+   */
+  constructor(config = {}) {
+    this.provider = config.provider || process.env.LLM_PROVIDER || 'openai';
+    this.apiKey = config.apiKey || process.env.LLM_API_KEY || '';
+    this.model = config.model || process.env.LLM_MODEL || this._getDefaultModel();
+    this.baseUrl = config.baseUrl || process.env.LLM_BASE_URL || this._getDefaultBaseUrl();
+    this.timeout = config.timeout || 30000;
+    this.maxRetries = config.maxRetries || 2;
+
+    // Statistics
+    this.stats = {
+      totalRequests: 0,
+      successfulRequests: 0,
+      failedRequests: 0,
+      fallbackCount: 0
+    };
+  }
+
+  /**
+   * Get default model for provider
+   * @private
+   * @returns {string} Default model name
+   */
+  _getDefaultModel() {
+    const defaults = {
+      openai: 'gpt-4o-mini',
+      anthropic: 'claude-3-5-haiku-20241022',
+      ollama: 'llama3.2'
+    };
+    return defaults[this.provider] || 'gpt-4o-mini';
+  }
+
+  /**
+   * Get default base URL for provider
+   * @private
+   * @returns {string} Default base URL
+   */
+  _getDefaultBaseUrl() {
+    const defaults = {
+      openai: 'https://api.openai.com/v1',
+      anthropic: 'https://api.anthropic.com/v1',
+      ollama: 'http://localhost:11434'
+    };
+    return defaults[this.provider] || 'https://api.openai.com/v1';
+  }
+
+  /**
+   * Generate reflection from memories
+   * Main entry point for reflection generation
+   *
+   * @param {string} prompt - The reflection prompt
+   * @param {Array} memories - Context memories
+   * @returns {Promise<Object>} { reflection, confidence }
+   */
+  async reflect(prompt, memories) {
+    this.stats.totalRequests++;
+
+    if (!memories || memories.length === 0) {
+      return this._fallback('No memories provided');
+    }
+
+    const systemPrompt = `You are a reflective AI agent. Review the provided memories and synthesize a high-level insight, belief, or observation.
+Respond ONLY in JSON format with exactly these keys:
+{
+  "reflection": "a concise insight or observation derived from the memories",
+  "confidence": 0.0 to 1.0
+}
+
+Keep the reflection brief (1-2 sentences) and actionable.`;
+
+    const userContent = this._formatMemoriesForLLM(prompt, memories);
+
+    try {
+      const response = await this._callWithRetry(systemPrompt, userContent);
+      const parsed = JSON.parse(response);
+
+      // Validate response structure
+      if (!parsed.reflection || typeof parsed.confidence !== 'number') {
+        throw new Error('Invalid LLM response format');
+      }
+
+      // Clamp confidence to valid range
+      parsed.confidence = Math.max(0, Math.min(1, parsed.confidence));
+
+      this.stats.successfulRequests++;
+      return parsed;
+
+    } catch (error) {
+      this.stats.failedRequests++;
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.warn(`[LLMClient] LLM call failed: ${errorMessage}`);
+      return this._fallback('LLM error', memories);
+    }
+  }
+
+  /**
+   * Format memories for LLM consumption
+   * @private
+   * @param {string} prompt - User prompt
+   * @param {Array} memories - Memory array
+   * @returns {string} Formatted content
+   */
+  _formatMemoriesForLLM(prompt, memories) {
+    const memoryList = memories
+      .map((m, i) => `${i + 1}. ${m.content}`)
+      .join('\n');
+
+    return `Prompt: ${prompt}\n\nMemories:\n${memoryList}\n\nBased on these memories, provide a brief reflective insight.`;
+  }
+
+  /**
+   * Call LLM with retry logic
+   * @private
+   * @param {string} systemPrompt - System prompt
+   * @param {string} userContent - User content
+   * @returns {Promise<string>} LLM response text
+   */
+  async _callWithRetry(systemPrompt, userContent) {
+    let lastError = null;
+
+    for (let attempt = 1; attempt <= this.maxRetries; attempt++) {
+      try {
+        return await this._callLLM(systemPrompt, userContent);
+      } catch (error) {
+        lastError = error;
+        if (attempt < this.maxRetries) {
+          const delay = Math.pow(2, attempt) * 1000; // Exponential backoff
+          await this._sleep(delay);
+        }
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * Call LLM based on provider
+   * @private
+   * @param {string} systemPrompt - System prompt
+   * @param {string} userContent - User content
+   * @returns {Promise<string>} Response text
+   */
+  async _callLLM(systemPrompt, userContent) {
+    switch (this.provider) {
+      case 'openai':
+        return await this._callOpenAI(systemPrompt, userContent);
+      case 'anthropic':
+        return await this._callAnthropic(systemPrompt, userContent);
+      case 'ollama':
+        return await this._callOllama(systemPrompt, userContent);
+      default:
+        throw new Error(`Unsupported provider: ${this.provider}`);
+    }
+  }
+
+  /**
+   * Call OpenAI API
+   * @private
+   */
+  async _callOpenAI(systemPrompt, userContent) {
+    if (!this.apiKey) {
+      throw new Error('OpenAI API key not configured');
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}/chat/completions`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'Authorization': `Bearer ${this.apiKey}`
+        },
+        body: JSON.stringify({
+          model: this.model,
+          messages: [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userContent }
+          ],
+          temperature: 0.7,
+          max_tokens: 500
+        }),
+        signal: controller.signal
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`OpenAI API error: ${response.status} - ${error}`);
+      }
+
+      const data = await response.json();
+      return data.choices[0].message.content;
+
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new Error('Request timeout');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Call Anthropic (Claude) API
+   * @private
+   */
+  async _callAnthropic(systemPrompt, userContent) {
+    if (!this.apiKey) {
+      throw new Error('Anthropic API key not configured');
+    }
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}/messages`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          'x-api-key': this.apiKey,
+          'anthropic-version': '2023-06-01'
+        },
+        body: JSON.stringify({
+          model: this.model,
+          max_tokens: 500,
+          system: systemPrompt,
+          messages: [
+            { role: 'user', content: userContent }
+          ]
+        }),
+        signal: controller.signal
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Anthropic API error: ${response.status} - ${error}`);
+      }
+
+      const data = await response.json();
+      return data.content[0].text;
+
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new Error('Request timeout');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Call Ollama (local) API
+   * @private
+   */
+  async _callOllama(systemPrompt, userContent) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(`${this.baseUrl}/api/chat`, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify({
+          model: this.model,
+          messages: [
+            { role: 'system', content: systemPrompt },
+            { role: 'user', content: userContent }
+          ],
+          stream: false
+        }),
+        signal: controller.signal
+      });
+
+      clearTimeout(timeoutId);
+
+      if (!response.ok) {
+        const error = await response.text();
+        throw new Error(`Ollama API error: ${response.status} - ${error}`);
+      }
+
+      const data = await response.json();
+      return data.message.content;
+
+    } catch (error) {
+      clearTimeout(timeoutId);
+      if (error instanceof Error && error.name === 'AbortError') {
+        throw new Error('Request timeout');
+      }
+      throw error;
+    }
+  }
+
+  /**
+   * Fallback when LLM fails
+   * @private
+   * @param {string} reason - Fallback reason
+   * @param {Array} [memories=[]] - Memory array
+   * @returns {Object} Fallback result
+   */
+  _fallback(reason, memories = []) {
+    this.stats.fallbackCount++;
+
+    if (memories && memories.length > 0) {
+      // Simple aggregation fallback
+      const contents = memories.map(m => m.content);
+      const combined = contents.join('; ');
+      const preview = combined.length > 200
+        ? combined.substring(0, 200) + '...'
+        : combined;
+
+      return {
+        reflection: `Aggregated from ${memories.length} memories: ${preview}`,
+        confidence: 0.5
+      };
+    }
+
+    return {
+      reflection: `Reflection generation unavailable: ${reason}`,
+      confidence: 0.3
+    };
+  }
+
+  /**
+   * Sleep utility
+   * @private
+   * @param {number} ms - Milliseconds to sleep
+   * @returns {Promise<void>}
+   */
+  _sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Get client statistics
+   * @returns {Object} Statistics
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      successRate: this.stats.totalRequests > 0
+        ? (this.stats.successfulRequests / this.stats.totalRequests).toFixed(2)
+        : '0.00'
+    };
+  }
+
+  /**
+   * Reset statistics
+   */
+  resetStats() {
+    this.stats = {
+      totalRequests: 0,
+      successfulRequests: 0,
+      failedRequests: 0,
+      fallbackCount: 0
+    };
+  }
+}
+
+export default LLMClient;

package/lib/llm/index.js

@@ -0,0 +1,10 @@
+/**
+ * LLM Module - LLM client support for yamo-memory-mesh
+ * Exports multi-provider LLM client for reflection generation
+ */
+
+export { LLMClient } from './client.js';
+
+export default {
+  LLMClient: (await import('./client.js')).LLMClient
+};

package/lib/memory/memory-mesh.js

@@ -15,6 +15,7 @@
 
 import { fileURLToPath } from 'url';
 import fs from "fs";
+import crypto from "crypto";
 import { LanceDBClient } from "../lancedb/client.js";
 import { getConfig } from "../lancedb/config.js";
 import { getEmbeddingDimension } from "../lancedb/schema.js";
@@ -22,6 +23,8 @@ import { handleError, StorageError, QueryError } from "../lancedb/errors.js";
 import EmbeddingFactory from "../embeddings/factory.js";
 import { Scrubber } from "../scrubber/scrubber.js";
 import { KeywordSearch } from "../search/keyword-search.js";
+import { YamoEmitter } from "../yamo/emitter.js";
+import { LLMClient } from "../llm/client.js";
 
 /**
  * MemoryMesh class for managing vector memory storage
@@ -29,8 +32,15 @@ import { KeywordSearch } from "../search/keyword-search.js";
 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() {
+  constructor(options = {}) {
     this.client = null;
     this.config = null;
     this.embeddingFactory = new EmbeddingFactory();
@@ -38,8 +48,24 @@ class MemoryMesh {
     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
+      });
+    }
+
     // Scrubber for Layer 0 sanitization
-    this.scrubber = new Scrubber({ 
+    this.scrubber = new Scrubber({
       enabled: true,
       chunking: {
         minTokens: 1 // Allow short memories
@@ -235,6 +261,20 @@ class MemoryMesh {
         }
       }
 
+      // Initialize YAMO blocks table 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');
+          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) {
@@ -314,6 +354,22 @@ class MemoryMesh {
       // 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);
+          }
+        });
+      }
+
       return {
         id: result.id,
         content: sanitizedContent,
@@ -329,15 +385,21 @@ class MemoryMesh {
   }
 
   /**
-   * Reflect on recent memories to generate insights
-   * @param {Object} options 
-   * @returns {Promise<Object>} Reflection prompt and context
+   * 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 });
@@ -348,18 +410,115 @@ class MemoryMesh {
         .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 {
-      topic,
-      count: memories.length,
-      context: memories.map(m => ({ 
-        content: m.content, 
-        type: m.metadata?.type || 'event',
-        id: m.id 
-      })),
-      prompt: `Review these memories. Synthesize a high-level "belief" or "observation".`
+      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
@@ -521,6 +680,21 @@ class MemoryMesh {
         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) {
@@ -577,6 +751,62 @@ class MemoryMesh {
     }
   }
 
+  /**
+   * 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 [];
+    }
+
+    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;
+          }
+        }
+      }
+
+      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
@@ -961,8 +1191,30 @@ ${jsonResult}
       console.log(JSON.stringify({ status: "ok", count: records.length, records }));
 
     } else if (action === 'reflect') {
-      const result = await mesh.reflect({ topic: input.topic, lookback: input.limit });
-      console.log(JSON.stringify({ status: "ok", ...result }));
+      // 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();

package/lib/search/keyword-search.js

@@ -90,9 +90,9 @@ export class KeywordSearch {
 
   /**
    * Search for query terms
-   * @param {string} query 
-   * @param {Object} options 
-   * @returns {Array<{id: string, score: number, matches: string[]}>}
+   * @param {string} query
+   * @param {Object} options
+   * @returns {Array<{id: string, score: number, matches: string[], content: string, metadata: Object}>}
    */
   search(query, options = {}) {
     this._computeStats();

package/lib/yamo/emitter.js

@@ -0,0 +1,235 @@
+/**
+ * YAMO Emitter - Constructs structured YAMO blocks for auditability
+ *
+ * Based on YAMO Protocol specification:
+ * - Semicolon-terminated key-value pairs
+ * - Agent/Intent/Context/Constraints/Meta/Output structure
+ * - Supports reflect, retain, recall operations
+ *
+ * Reference: Hindsight project's yamo_integration.py
+ */
+
+/**
+ * YamoEmitter class for building YAMO protocol blocks
+ * YAMO (Yet Another Multi-agent Orchestration) blocks provide
+ * structured reasoning traces for AI agent operations.
+ */
+export class YamoEmitter {
+  /**
+   * Build a YAMO block for reflect operation
+   * Reflect operations synthesize insights from existing memories
+   *
+   * @param {Object} params - Block parameters
+   * @param {string} [params.topic] - Topic of reflection
+   * @param {number} params.memoryCount - Number of memories considered
+   * @param {string} [params.agentId='default'] - Agent identifier
+   * @param {string} params.reflection - Generated reflection text
+   * @param {number} [params.confidence=0.8] - Confidence score (0-1)
+   * @returns {string} Formatted YAMO block
+   */
+  static buildReflectBlock(params) {
+    const {
+      topic,
+      memoryCount,
+      agentId = 'default',
+      reflection,
+      confidence = 0.8
+    } = params;
+
+    const timestamp = new Date().toISOString();
+
+    return `agent: MemoryMesh_${agentId};
+intent: synthesize_insights_from_context;
+context:
+  topic;${topic || 'general'};
+  memory_count;${memoryCount};
+  timestamp;${timestamp};
+constraints:
+  hypothesis;Reflection generates new insights from existing facts;
+priority: high;
+output:
+  reflection;${reflection};
+  confidence;${confidence};
+meta:
+  rationale;Synthesized from ${memoryCount} relevant memories;
+  observation;High-level belief formed from pattern recognition;
+  confidence;${confidence};
+log: reflection_generated;timestamp;${timestamp};memories;${memoryCount};
+handoff: End;
+`;
+  }
+
+  /**
+   * Build a YAMO block for retain (add) operation
+   * Retain operations store new memories into the system
+   *
+   * @param {Object} params - Block parameters
+   * @param {string} params.content - Memory content
+   * @param {Object} [params.metadata={}] - Memory metadata
+   * @param {string} params.id - Memory ID
+   * @param {string} [params.agentId='default'] - Agent identifier
+   * @param {string} [params.memoryType='event'] - Type of memory
+   * @returns {string} Formatted YAMO block
+   */
+  static buildRetainBlock(params) {
+    const {
+      content,
+      metadata = {},
+      id,
+      agentId = 'default',
+      memoryType = 'event'
+    } = params;
+
+    const timestamp = new Date().toISOString();
+    const contentPreview = content.length > 100
+      ? content.substring(0, 100) + '...'
+      : content;
+
+    // Escape semicolons in content for YAMO format
+    const escapedContent = contentPreview.replace(/;/g, ',');
+
+    return `agent: MemoryMesh_${agentId};
+intent: store_memory_for_future_retrieval;
+context:
+  memory_id;${id};
+  memory_type;${memoryType};
+  timestamp;${timestamp};
+  content_length;${content.length};
+constraints:
+  hypothesis;New information should be integrated into world model;
+priority: medium;
+output:
+  memory_stored;${id};
+  content_preview;${escapedContent};
+meta:
+  rationale;Memory persisted for semantic search and retrieval;
+  observation;Content vectorized and stored in LanceDB;
+  confidence;1.0;
+log: memory_retained;timestamp;${timestamp};id;${id};type;${memoryType};
+handoff: End;
+`;
+  }
+
+  /**
+   * Build a YAMO block for recall (search) operation
+   * Recall operations retrieve memories based on semantic similarity
+   *
+   * @param {Object} params - Block parameters
+   * @param {string} params.query - Search query
+   * @param {number} params.resultCount - Number of results returned
+   * @param {number} [params.limit=10] - Maximum requested results
+   * @param {string} [params.agentId='default'] - Agent identifier
+   * @param {string} [params.searchType='semantic'] - Type of search
+   * @returns {string} Formatted YAMO block
+   */
+  static buildRecallBlock(params) {
+    const {
+      query,
+      resultCount,
+      limit = 10,
+      agentId = 'default',
+      searchType = 'semantic'
+    } = params;
+
+    const timestamp = new Date().toISOString();
+    const recallRatio = resultCount > 0 ? (resultCount / limit).toFixed(2) : '0.00';
+
+    return `agent: MemoryMesh_${agentId};
+intent: retrieve_relevant_memories;
+context:
+  query;${query};
+  search_type;${searchType};
+  requested_limit;${limit};
+  timestamp;${timestamp};
+constraints:
+  hypothesis;Relevant memories retrieved based on query;
+priority: high;
+output:
+  results_count;${resultCount};
+  recall_ratio;${recallRatio};
+meta:
+  rationale;Semantic search finds similar content by vector similarity;
+  observation;${resultCount} memories found matching query;
+  confidence;${resultCount > 0 ? '0.9' : '0.5'};
+log: memory_recalled;timestamp;${timestamp};results;${resultCount};query;${query};
+handoff: End;
+`;
+  }
+
+  /**
+   * Build a YAMO block for delete operation (optional)
+   * Delete operations remove memories from the system
+   *
+   * @param {Object} params - Block parameters
+   * @param {string} params.id - Memory ID being deleted
+   * @param {string} [params.agentId='default'] - Agent identifier
+   * @param {string} [params.reason='user_request'] - Reason for deletion
+   * @returns {string} Formatted YAMO block
+   */
+  static buildDeleteBlock(params) {
+    const {
+      id,
+      agentId = 'default',
+      reason = 'user_request'
+    } = params;
+
+    const timestamp = new Date().toISOString();
+
+    return `agent: MemoryMesh_${agentId};
+intent: remove_memory_from_storage;
+context:
+  memory_id;${id};
+  reason;${reason};
+  timestamp;${timestamp};
+constraints:
+  hypothesis;Memory removal should be traceable for audit;
+priority: low;
+output:
+  deleted;${id};
+meta:
+  rationale;Memory removed from vector store;
+  observation;Deletion recorded for provenance;
+  confidence;1.0;
+log: memory_deleted;timestamp;${timestamp};id;${id};
+handoff: End;
+`;
+  }
+
+  /**
+   * Validate a YAMO block structure
+   * Checks for required sections and proper formatting
+   *
+   * @param {string} yamoBlock - YAMO block to validate
+   * @returns {Object} Validation result { valid, errors }
+   */
+  static validateBlock(yamoBlock) {
+    const errors = [];
+
+    // Check for required sections
+    const requiredSections = ['agent:', 'intent:', 'context:', 'output:', 'log:'];
+    for (const section of requiredSections) {
+      if (!yamoBlock.includes(section)) {
+        errors.push(`Missing required section: ${section}`);
+      }
+    }
+
+    // Check for semicolon termination
+    const lines = yamoBlock.split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (trimmed.length > 0 && !trimmed.startsWith('//') && !trimmed.endsWith(';')) {
+        // Allow empty lines and comments
+        if (trimmed && !trimmed.startsWith('agent:') && !trimmed.startsWith('handoff:')) {
+          errors.push(`Line not semicolon-terminated: ${trimmed.substring(0, 50)}`);
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors
+    };
+  }
+}
+
+export default YamoEmitter;

package/lib/yamo/index.js

@@ -0,0 +1,15 @@
+/**
+ * YAMO Module - YAMO Protocol support for yamo-memory-mesh
+ * Exports YAMO block construction, validation, and schema utilities
+ */
+
+export { YamoEmitter } from './emitter.js';
+export * from './schema.js';
+
+export default {
+  YamoEmitter: (await import('./emitter.js')).YamoEmitter,
+  createYamoSchema: (await import('./schema.js')).createYamoSchema,
+  createYamoTable: (await import('./schema.js')).createYamoTable,
+  validateYamoRecord: (await import('./schema.js')).validateYamoRecord,
+  generateYamoId: (await import('./schema.js')).generateYamoId
+};

package/lib/yamo/schema.js

@@ -0,0 +1,159 @@
+/**
+ * YAMO Block Schema Definitions for yamo-memory-mesh
+ * Uses Apache Arrow Schema format for LanceDB JavaScript SDK
+ *
+ * Provides schema and table creation for YAMO block persistence.
+ * YAMO blocks provide audit trail for all memory operations.
+ */
+
+import * as arrow from "apache-arrow";
+
+/**
+ * Create YAMO blocks table schema
+ * Defines the structure for storing YAMO protocol blocks
+ *
+ * Schema includes:
+ * - Core identifiers (id, agent_id)
+ * - Operation tracking (operation_type, yamo_text)
+ * - Temporal data (timestamp)
+ * - Blockchain fields (block_hash, prev_hash) - nullable for future use
+ * - Metadata (JSON string for flexibility)
+ *
+ * @returns {import('apache-arrow').Schema} Arrow schema for YAMO blocks
+ */
+export function createYamoSchema() {
+  return new arrow.Schema([
+    // Core identifiers
+    new arrow.Field('id', new arrow.Utf8(), false),
+    new arrow.Field('agent_id', new arrow.Utf8(), true),
+
+    // Operation tracking
+    new arrow.Field('operation_type', new arrow.Utf8(), false),  // 'retain', 'recall', 'reflect'
+    new arrow.Field('yamo_text', new arrow.Utf8(), false),       // Full YAMO block content
+
+    // Temporal
+    new arrow.Field('timestamp', new arrow.Timestamp(arrow.TimeUnit.MILLISECOND), false),
+
+    // Blockchain fields (optional, nullable) - for future anchoring
+    new arrow.Field('block_hash', new arrow.Utf8(), true),   // Hash of this block
+    new arrow.Field('prev_hash', new arrow.Utf8(), true),    // Hash of previous block (for chain)
+
+    // Metadata (JSON string for flexibility)
+    new arrow.Field('metadata', new arrow.Utf8(), true),      // Additional metadata as JSON
+  ]);
+}
+
+/**
+ * Create YAMO blocks table in LanceDB
+ * Creates the table if it doesn't exist, opens it if it does
+ *
+ * @param {import('@lancedb/lancedb').Connection} db - LanceDB connection
+ * @param {string} [tableName='yamo_blocks'] - Name of the table
+ * @returns {Promise<import('@lancedb/lancedb').Table>} The created or opened table
+ * @throws {Error} If table creation fails
+ */
+export async function createYamoTable(db, tableName = 'yamo_blocks') {
+  try {
+    // Check if table already exists
+    const existingTables = await db.tableNames();
+
+    if (existingTables.includes(tableName)) {
+      // Table exists, open it
+      return await db.openTable(tableName);
+    }
+
+    // Create new table with YAMO schema
+    const schema = createYamoSchema();
+    const table = await db.createTable(tableName, [], { schema });
+
+    return table;
+
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to create YAMO table '${tableName}': ${message}`);
+  }
+}
+
+/**
+ * Validate a YAMO block record before insertion
+ * Checks for required fields and valid values
+ *
+ * @param {Object} record - Record to validate
+ * @param {string} record.id - Block ID
+ * @param {string} record.operation_type - Operation type
+ * @param {string} record.yamo_text - YAMO block text
+ * @returns {Object} Validation result { valid, errors }
+ */
+export function validateYamoRecord(record) {
+  const errors = [];
+
+  // Check required fields
+  if (!record.id) {
+    errors.push('Missing required field: id');
+  }
+
+  if (!record.operation_type) {
+    errors.push('Missing required field: operation_type');
+  } else {
+    // Validate operation_type is one of the allowed values
+    const validTypes = ['retain', 'recall', 'reflect'];
+    if (!validTypes.includes(record.operation_type)) {
+      errors.push(`Invalid operation_type: ${record.operation_type}. Must be one of: ${validTypes.join(', ')}`);
+    }
+  }
+
+  if (!record.yamo_text) {
+    errors.push('Missing required field: yamo_text');
+  } else {
+    // Validate YAMO block format
+    const requiredSections = ['agent:', 'intent:', 'context:', 'output:', 'log:'];
+    for (const section of requiredSections) {
+      if (!record.yamo_text.includes(section)) {
+        errors.push(`YAMO block missing required section: ${section}`);
+      }
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Generate a YAMO block ID
+ * Creates a unique ID for a YAMO block
+ *
+ * @param {string} operationType - Type of operation
+ * @returns {string} Generated YAMO block ID
+ */
+export function generateYamoId(operationType) {
+  const timestamp = Date.now();
+  const random = Math.random().toString(36).substring(2, 10);
+  return `yamo_${operationType}_${timestamp}_${random}`;
+}
+
+/**
+ * Check if a table uses YAMO schema
+ * Detects if a table has the YAMO block schema structure
+ *
+ * @param {import('apache-arrow').Schema} schema - Table schema to check
+ * @returns {boolean} True if YAMO schema detected
+ */
+export function isYamoSchema(schema) {
+  // Check for unique YAMO fields
+  const hasYamoFields = schema.fields.some(f =>
+    f.name === 'operation_type' || f.name === 'yamo_text'
+  );
+
+  return hasYamoFields;
+}
+
+// Export schema function as default for consistency with lancedb/schema.js
+export default {
+  createYamoSchema,
+  createYamoTable,
+  validateYamoRecord,
+  generateYamoId,
+  isYamoSchema
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yamo/memory-mesh",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "Portable semantic memory system with Layer 0 Scrubber for YAMO agents",
   "type": "module",
   "main": "lib/memory/index.js",