@yamo/memory-mesh 2.3.2 → 3.0.0

package/lib/yamo/emitter.js

@@ -8,40 +8,23 @@
  *
  * 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};
+    /**
+     * Build a YAMO block for reflect operation
+     * Reflect operations synthesize insights from existing memories
+     */
+    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'};
+  topic;${topic || "general"};
   memory_count;${memoryCount};
   timestamp;${timestamp};
 constraints:
@@ -57,38 +40,18 @@ meta:
 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};
+    }
+    /**
+     * Build a YAMO block for retain (add) operation
+     * Retain operations store new memories into the system
+     */
+    static buildRetainBlock(params) {
+        const { content, metadata: _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};
@@ -108,33 +71,16 @@ meta:
 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};
+    }
+    /**
+     * Build a YAMO block for recall (search) operation
+     * Recall operations retrieve memories based on semantic similarity
+     */
+    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};
@@ -150,32 +96,19 @@ output:
 meta:
   rationale;Semantic search finds similar content by vector similarity;
   observation;${resultCount} memories found matching query;
-  confidence;${resultCount > 0 ? '0.9' : '0.5'};
+  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};
+    }
+    /**
+     * Build a YAMO block for delete operation (optional)
+     * Delete operations remove memories from the system
+     */
+    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};
@@ -193,43 +126,45 @@ meta:
 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)}`);
+    /**
+     * Validate a YAMO block structure
+     * Checks for required sections and proper formatting
+     */
+    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,
+        };
     }
-
-    return {
-      valid: errors.length === 0,
-      errors
-    };
-  }
 }
-
 export default YamoEmitter;

package/lib/yamo/emitter.ts

@@ -0,0 +1,249 @@
+/**
+ * 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
+ */
+
+export interface ReflectBlockParams {
+  topic?: string;
+  memoryCount: number;
+  agentId?: string;
+  reflection: string;
+  confidence?: number;
+}
+
+export interface RetainBlockParams {
+  content: string;
+  metadata?: any;
+  id: string;
+  agentId?: string;
+  memoryType?: string;
+}
+
+export interface RecallBlockParams {
+  query: string;
+  resultCount: number;
+  limit?: number;
+  agentId?: string;
+  searchType?: string;
+}
+
+export interface DeleteBlockParams {
+  id: string;
+  agentId?: string;
+  reason?: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+/**
+ * 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
+   */
+  static buildReflectBlock(params: ReflectBlockParams): string {
+    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
+   */
+  static buildRetainBlock(params: RetainBlockParams): string {
+    const {
+      content,
+      metadata: _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
+   */
+  static buildRecallBlock(params: RecallBlockParams): string {
+    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
+   */
+  static buildDeleteBlock(params: DeleteBlockParams): string {
+    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
+   */
+  static validateBlock(yamoBlock: string): ValidationResult {
+    const errors: string[] = [];
+
+    // 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/schema.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 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";
+import * as lancedb from "@lancedb/lancedb";
+/**
+ * Create YAMO blocks table schema
+ * Defines the structure for storing YAMO protocol blocks
+ * @returns {arrow.Schema} Arrow schema for YAMO blocks
+ */
+export declare function createYamoSchema(): arrow.Schema;
+/**
+ * Create YAMO blocks table in LanceDB
+ * Creates the table if it doesn't exist, opens it if it does
+ *
+ * @param {lancedb.Connection} db - LanceDB connection
+ * @param {string} [tableName='yamo_blocks'] - Name of the table
+ * @returns {Promise<lancedb.Table>} The created or opened table
+ * @throws {Error} If table creation fails
+ */
+export declare function createYamoTable(db: lancedb.Connection, tableName?: string): Promise<lancedb.Table>;
+export interface YamoRecordValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+/**
+ * Validate a YAMO block record before insertion
+ * Checks for required fields and valid values
+ */
+export declare function validateYamoRecord(record: any): YamoRecordValidationResult;
+/**
+ * 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 declare function generateYamoId(operationType: string): string;
+/**
+ * Check if a table uses YAMO schema
+ * Detects if a table has the YAMO block schema structure
+ *
+ * @param {arrow.Schema} schema - Table schema to check
+ * @returns {boolean} True if YAMO schema detected
+ */
+export declare function isYamoSchema(schema: arrow.Schema): boolean;
+declare const _default: {
+    createYamoSchema: typeof createYamoSchema;
+    createYamoTable: typeof createYamoTable;
+    validateYamoRecord: typeof validateYamoRecord;
+    generateYamoId: typeof generateYamoId;
+    isYamoSchema: typeof isYamoSchema;
+};
+export default _default;