@yamo/memory-mesh 2.3.2 → 3.0.1

package/lib/utils/skill-metadata.ts

@@ -0,0 +1,133 @@
+// @ts-nocheck
+/**
+ * Structured skill-identity extraction.
+ *
+ * Reads ONLY the YAML frontmatter block (between --- delimiters) or
+ * root-level identity declarations in legacy v0.4 compact format.
+ * The body of .yamo files is LLM-interpreted and MUST NOT be machine-parsed.
+ */
+import crypto from "crypto";
+/** Fields safe to extract for indexing and display. */
+const IDENTITY_FIELDS = new Set(["name", "intent", "description"]);
+/** Pre-computed regexes for legacy root-level identity declarations. */
+const LEGACY_REGEXES = {
+    name: /^name[;:]\s*([^;\n]+);?/m,
+    intent: /^intent[;:]\s*([^;\n]+);?/m,
+    description: /^description[;:]\s*([^;\n]+);?/m,
+};
+/**
+ * Parse flat key: value or key; value lines from a text block.
+ * Only extracts whitelisted identity fields.
+ */
+function parseFlatBlock(block) {
+    const result = {};
+    for (const line of block.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#")) {
+            continue;
+        }
+        const colonIdx = trimmed.indexOf(":");
+        const semiIdx = trimmed.indexOf(";");
+        let sepIdx;
+        if (colonIdx > 0 && semiIdx > 0) {
+            sepIdx = Math.min(colonIdx, semiIdx);
+        }
+        else if (colonIdx > 0) {
+            sepIdx = colonIdx;
+        }
+        else if (semiIdx > 0) {
+            sepIdx = semiIdx;
+        }
+        else {
+            continue;
+        }
+        const key = trimmed.substring(0, sepIdx).trim();
+        let value = trimmed.substring(sepIdx + 1).trim();
+        // Strip trailing semicolon (legacy compact format)
+        if (value.endsWith(";")) {
+            value = value.slice(0, -1).trim();
+        }
+        if (IDENTITY_FIELDS.has(key) && value) {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+/**
+ * Extract identity fields (name, intent, description) from .yamo content.
+ *
+ * Priority:
+ *   1. YAML frontmatter (--- … --- block at file start)
+ *   2. Legacy v0.4 root-level compact declarations
+ *   3. Content-hash fallback — deterministic and idempotent
+ */
+export function extractSkillIdentity(content) {
+    // 1. YAML frontmatter
+    if (content.startsWith("---")) {
+        const endIdx = content.indexOf("---", 3);
+        if (endIdx !== -1) {
+            const fields = parseFlatBlock(content.substring(3, endIdx));
+            if (fields.name) {
+                return {
+                    name: fields.name,
+                    intent: fields.intent || "general_procedure",
+                    description: fields.description || "",
+                };
+            }
+        }
+    }
+    // 2. Legacy v0.4 root-level identity declarations.
+    // Safe: name/intent/description do not appear as body section headers.
+    const legacyFields = {};
+    for (const field of IDENTITY_FIELDS) {
+        const match = content.match(LEGACY_REGEXES[field]);
+        if (match) {
+            legacyFields[field] = match[1].trim();
+        }
+    }
+    if (legacyFields.name) {
+        return {
+            name: legacyFields.name,
+            intent: legacyFields.intent || "general_procedure",
+            description: legacyFields.description || "",
+        };
+    }
+    // 3. Content-hash fallback
+    const shortHash = crypto
+        .createHash("sha256")
+        .update(content)
+        .digest("hex")
+        .substring(0, 12);
+    return {
+        name: `Unnamed_${shortHash}`,
+        intent: "general_procedure",
+        description: "",
+    };
+}
+/**
+ * Extract tags from YAML frontmatter.
+ * Returns an array of tag strings, or empty array if no tags found.
+ *
+ * Tags are expected in the format:
+ *   tags: tag1, tag2, tag3
+ *
+ * This function ONLY reads the YAML frontmatter block and does NOT parse
+ * the skill body, following the same safety constraints as extractSkillIdentity.
+ */
+export function extractSkillTags(content) {
+    // Only parse YAML frontmatter (between --- delimiters)
+    if (content.startsWith("---")) {
+        const endIdx = content.indexOf("---", 3);
+        if (endIdx !== -1) {
+            const frontmatter = content.substring(3, endIdx);
+            const tagsMatch = frontmatter.match(/^tags:\s*(.+)$/m);
+            if (tagsMatch) {
+                return tagsMatch[1]
+                    .split(",")
+                    .map((t) => t.trim())
+                    .filter((t) => t.length > 0);
+            }
+        }
+    }
+    return [];
+}

package/lib/yamo/emitter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 declare class YamoEmitter {
+    /**
+     * Build a YAMO block for reflect operation
+     * Reflect operations synthesize insights from existing memories
+     */
+    static buildReflectBlock(params: any): string;
+    /**
+     * Build a YAMO block for retain (add) operation
+     * Retain operations store new memories into the system
+     */
+    static buildRetainBlock(params: any): string;
+    /**
+     * Build a YAMO block for recall (search) operation
+     * Recall operations retrieve memories based on semantic similarity
+     */
+    static buildRecallBlock(params: any): string;
+    /**
+     * Build a YAMO block for delete operation (optional)
+     * Delete operations remove memories from the system
+     */
+    static buildDeleteBlock(params: any): string;
+    /**
+     * Validate a YAMO block structure
+     * Checks for required sections and proper formatting
+     */
+    static validateBlock(yamoBlock: any): {
+        valid: boolean;
+        errors: any[];
+    };
+}
+export default YamoEmitter;

package/lib/yamo/emitter.js

@@ -1,3 +1,4 @@
+// @ts-nocheck
 /**
  * YAMO Emitter - Constructs structured YAMO blocks for auditability
  *
@@ -8,40 +9,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 +41,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 +72,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 +97,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 +127,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,171 @@
+// @ts-nocheck
+/**
+ * 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
+     */
+    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
+     */
+    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};
+  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) {
+        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) {
+        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) {
+        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.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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';
+declare const _default: {
+    YamoEmitter: typeof import("./emitter.js").YamoEmitter;
+    createYamoSchema: typeof import("./schema.js").createYamoSchema;
+    createYamoTable: typeof import("./schema.js").createYamoTable;
+    validateYamoRecord: typeof import("./schema.js").validateYamoRecord;
+    generateYamoId: typeof import("./schema.js").generateYamoId;
+};
+export default _default;

package/lib/yamo/index.js

@@ -1,15 +1,14 @@
+// @ts-nocheck
 /**
  * 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
+    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/index.ts

@@ -0,0 +1,16 @@
+// @ts-nocheck
+/**
+ * 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
+};