@yamo/memory-mesh 2.1.2 → 2.2.0

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.2",
+  "version": "2.2.0",
   "description": "Portable semantic memory system with Layer 0 Scrubber for YAMO agents",
   "type": "module",
   "main": "lib/memory/index.js",
@@ -17,7 +17,7 @@
     "index.d.ts"
   ],
   "scripts": {
-    "test": "npm run type-check",
+    "test": "npm run type-check && node --test test/*.test.js",
     "type-check": "tsc --noEmit"
   },
   "dependencies": {

package/skills/SKILL.md

@@ -1,4 +1,4 @@
 ---
 name: yamo-super
-description: For all code improvement or creation tasks, strictly adhere to the logic, agents, and constraints defined in ~/.claude/skills/yamo-super/skill-super.yamo or ~/.gemini/skills/yamo-super/skill-super.yamo.
+description: A comprehensive AI coding workflow system that orchestrates test-driven development, systematic debugging, collaborative planning, git worktree isolation, and dual-mode execution (subagent-driven or batched) with mandatory TDD red-green-refactor cycles, root-cause analysis, two-stage code review, and branch lifecycle management.For all code improvement or creation tasks, strictly adhere to the logic, agents, and constraints defined in skill-super.yamo.
 ---