@yamo/memory-mesh 2.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YAMO Protocol
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# MemoryMesh
+
+Portable, semantic memory system for AI agents with automatic Layer 0 sanitization.
+
+## Features
+
+- **Persistent Vector Storage**: Powered by LanceDB.
+- **Layer 0 Scrubber**: Automatically sanitizes, deduplicates, and cleans content.
+- **Local Embeddings**: Runs 100% locally using ONNX (no API keys required).
+- **Portable CLI**: Simple JSON-based interface for any agent or language.
+
+## Installation
+
+```bash
+npm install @yamo/memory-mesh
+```
+
+## Usage
+
+### CLI
+
+```bash
+# Store a memory (automatically scrubbed & embedded)
+memory-mesh store "My important memory" '{"tag":"test"}'
+
+# Search memories
+memory-mesh search "query" 5
+
+# Scrub content only
+scrubber scrub "Raw text content"
+```
+
+### Node.js API
+
+```javascript
+import { MemoryMesh } from '@yamo/memory-mesh';
+
+const mesh = new MemoryMesh();
+await mesh.add('Content', { meta: 'data' });
+const results = await mesh.search('query');
+```
+
+## Using in a Project
+
+To use MemoryMesh with your Claude Code skills (like `yamo-super`) in a new project:
+
+### 1. Install the Package
+This installs the heavy dependencies (LanceDB, ONNX) and binaries.
+
+```bash
+npm install @yamo/memory-mesh
+# Or install locally if developing:
+# npm install /path/to/memory-mesh
+```
+
+### 2. Setup the CLI Adapter
+YAMO skills learn how to use the memory system by reading the source code of the CLI adapter. You must ensure `tools/memory_mesh.js` exists in your project so the agent can "see" the interface.
+
+**Quick Setup:**
+```bash
+mkdir -p tools
+cp node_modules/@yamo/memory-mesh/bin/memory_mesh.js tools/memory_mesh.js
+```
+
+### 3. Run Your Skill
+Your `yamo-super` skill (or any skill referencing `memory_script;tools/memory_mesh.js`) will now work automatically.
+
+```bash
+claude "Run yamo-super task='Setup CI pipeline'"
+```
+
+The agent will read `tools/memory_mesh.js`, understand how to call it, and execute memory operations which are handled by the installed `@yamo/memory-mesh` package.
+
+## Docker
+
+```bash
+docker run -v $(pwd)/data:/app/runtime/data \
+  yamo/memory-mesh store "Content"
+```
+

package/bin/memory_mesh.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+
+/**
+ * MemoryMesh CLI Adapter
+ * Provides a portable interface for skills to interact with the MemoryMesh system.
+ * 
+ * Usage:
+ *   node tools/memory_mesh.js store <content_string_or_json> [metadata_json]
+ *   node tools/memory_mesh.js search <query_string> [limit]
+ */
+
+import { MemoryMesh } from '../lib/memory/memory-mesh.js';
+import path from 'path';
+
+// Parse arguments
+const args = process.argv.slice(2);
+const command = args[0];
+
+async function main() {
+    try {
+        const mesh = new MemoryMesh();
+        // Wait for initialization if necessary (MemoryMesh constructor usually doesn't await, 
+        // but operations might need internal init. We assume standard usage.)
+
+        if (command === 'store') {
+            const content = args[1];
+            let metadata = {};
+            if (args[2]) {
+                try {
+                    metadata = JSON.parse(args[2]);
+                } catch (e) {
+                    console.error(JSON.stringify({ error: "Invalid metadata JSON" }));
+                    process.exit(1);
+                }
+            }
+            
+            if (!content) {
+                console.error(JSON.stringify({ error: "Content required for store command" }));
+                process.exit(1);
+            }
+
+            const result = await mesh.add(content, metadata);
+            console.log(JSON.stringify({ success: true, id: result.id, message: "Memory stored successfully" }));
+            
+        } else if (command === 'search') {
+            const query = args[1];
+            const limit = parseInt(args[2]) || 5;
+            
+            if (!query) {
+                console.error(JSON.stringify({ error: "Query required for search command" }));
+                process.exit(1);
+            }
+
+            const results = await mesh.search(query, { limit });
+            console.log(JSON.stringify({ success: true, results: results }));
+            
+        } else {
+            console.error(JSON.stringify({ error: `Unknown command: ${command}` }));
+            console.error("Usage: node tools/memory_mesh.js [store|search] ...");
+            process.exit(1);
+        }
+
+    } catch (error) {
+        console.error(JSON.stringify({ error: error.message }));
+        process.exit(1);
+    }
+}
+
+main();

package/bin/scrubber.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+
+/**
+ * Scrubber CLI Tool
+ * 
+ * A portable CLI wrapper for the S-MORA Layer 0 Scrubber.
+ * Sanitizes, deduplicates, and cleans text content.
+ * 
+ * Usage:
+ *   node tools/scrubber.js scrub "some text content"
+ *   node tools/scrubber.js scrub-file path/to/file.md
+ * 
+ * Output:
+ *   JSON object with { success, cleaned_content, metadata }
+ */
+
+import { Scrubber } from '../lib/smora/scrubber/scrubber.js';
+import fs from 'fs';
+import path from 'path';
+
+const args = process.argv.slice(2);
+const command = args[0];
+const input = args[1];
+
+async function main() {
+    // Initialize with default aggressive cleaning
+    const scrubber = new Scrubber({
+        enabled: true,
+        structural: { stripHTML: true, normalizeMarkdown: true },
+        semantic: { removeBoilerplate: true },
+        chunking: { minTokens: 1 } // Allow short inputs
+    });
+
+    try {
+        let content = '';
+        let source = 'cli-input';
+        let type = 'txt';
+
+        if (command === 'scrub') {
+            if (!input) throw new Error('Content argument required');
+            content = input;
+        } else if (command === 'scrub-file') {
+            if (!input) throw new Error('File path argument required');
+            if (!fs.existsSync(input)) throw new Error(`File not found: ${input}`);
+            content = fs.readFileSync(input, 'utf8');
+            source = path.basename(input);
+            type = path.extname(input).replace('.', '') || 'txt';
+        } else {
+            console.error(JSON.stringify({ error: `Unknown command: ${command}` }));
+            console.error('Usage: node tools/scrubber.js [scrub|scrub-file] <input>');
+            process.exit(1);
+        }
+
+        const result = await scrubber.process({
+            content,
+            source,
+            type
+        });
+
+        // Reassemble chunks for simple return
+        const cleanedContent = result.chunks.map(c => c.text).join('\n\n');
+
+        console.log(JSON.stringify({
+            success: true,
+            original_length: content.length,
+            cleaned_length: cleanedContent.length,
+            cleaned_content: cleanedContent,
+            chunks: result.chunks.length,
+            metadata: result.metadata
+        }));
+
+    } catch (error) {
+        console.error(JSON.stringify({
+            success: false,
+            error: error.message
+        }));
+        process.exit(1);
+    }
+}
+
+main();

package/index.d.ts

@@ -0,0 +1,111 @@
+export declare class MemoryMesh {
+    constructor();
+    init(): Promise<void>;
+    add(content: string, metadata?: Record<string, any>): Promise<{
+        id: string;
+        content: string;
+        metadata: Record<string, any>;
+        created_at: string;
+    }>;
+    addBatch(entries: Array<{
+        content: string;
+        metadata?: Record<string, any>;
+    }>): Promise<{
+        count: number;
+        success: boolean;
+        ids: string[];
+    }>;
+    search(query: string, options?: {
+        limit?: number;
+        filter?: string;
+        useCache?: boolean;
+    }): Promise<Array<{
+        id: string;
+        content: string;
+        metadata: Record<string, any>;
+        score: number;
+        created_at: string;
+    }>>;
+    get(id: string): Promise<{
+        id: string;
+        content: string;
+        metadata: Record<string, any>;
+        created_at: string;
+        updated_at: string;
+    } | null>;
+    getAll(options?: {
+        limit?: number;
+    }): Promise<Array<any>>;
+    update(id: string, content: string, metadata?: Record<string, any>): Promise<{
+        id: string;
+        content: string;
+        success: boolean;
+    }>;
+    delete(id: string): Promise<{
+        deleted: string;
+        success: boolean;
+    }>;
+    stats(): Promise<{
+        count: number;
+        tableName: string;
+        uri: string;
+        isConnected: boolean;
+        embedding: any;
+    }>;
+    healthCheck(): Promise<{
+        status: string;
+        timestamp: string;
+        checks: Record<string, any>;
+    }>;
+}
+
+export declare class Scrubber {
+    constructor(config?: ScrubberConfig);
+    process(document: {
+        content: string;
+        source: string;
+        type: 'html' | 'md' | 'txt';
+    }): Promise<ScrubberResult>;
+}
+
+export interface ScrubberConfig {
+    enabled?: boolean;
+    structural?: {
+        stripHTML?: boolean;
+        normalizeMarkdown?: boolean;
+        collapseWhitespace?: boolean;
+        removeScripts?: boolean;
+        removeStyles?: boolean;
+    };
+    semantic?: {
+        removeDuplicates?: boolean;
+        removeBoilerplate?: boolean;
+        minSignalRatio?: number;
+    };
+    chunking?: {
+        maxTokens?: number;
+        minTokens?: number;
+        splitOnHeadings?: boolean;
+    };
+    validation?: {
+        enforceMinLength?: boolean;
+    };
+}
+
+export interface ScrubberResult {
+    chunks: Array<{
+        text: string;
+        metadata: Record<string, any>;
+    }>;
+    metadata: {
+        source: string;
+        type: string;
+        processingTimestamp: string;
+    };
+    telemetry: {
+        totalDuration: number;
+        stages: Record<string, any>;
+    };
+    success: boolean;
+    error?: string;
+}

package/lib/adapters/index.js

@@ -0,0 +1,3 @@
+// Adapters module - placeholder for future adapter implementations
+// TODO: Implement adapters for external system integrations (databases, APIs, message queues)
+export {};

package/lib/embeddings/factory.js

@@ -0,0 +1,150 @@
+/**
+ * EmbeddingFactory - Multi-provider embedding with automatic fallback
+ * Manages primary and fallback embedding services
+ */
+
+import EmbeddingService from "./service.js";
+import { ConfigurationError, EmbeddingError } from "../lancedb/errors.js";
+
+class EmbeddingFactory {
+  constructor() {
+    this.primaryService = null;
+    this.fallbackServices = [];
+    this.configured = false;
+  }
+
+  /**
+   * Configure embedding services with fallback chain
+   * @param {Array} configs - Array of { modelType, modelName, priority, apiKey }
+   * @returns {Object} Success status
+   */
+  configure(configs) {
+    // Sort by priority (lower = higher priority)
+    configs.sort((a, b) => a.priority - b.priority);
+
+    this.primaryService = new EmbeddingService(configs[0]);
+
+    if (configs.length > 1) {
+      this.fallbackServices = configs.slice(1).map(c => new EmbeddingService(c));
+    }
+
+    this.configured = true;
+    return { success: true };
+  }
+
+  /**
+   * Initialize all configured services
+   * @returns {Promise<Object>} Initialization status
+   */
+  async init() {
+    if (!this.configured) {
+      throw new ConfigurationError('EmbeddingFactory not configured. Call configure() first.');
+    }
+
+    // Initialize primary service
+    if (this.primaryService && !this.primaryService.initialized) {
+      await this.primaryService.init();
+    }
+
+    // Initialize fallback services lazily (on first use)
+    return {
+      success: true,
+      primary: this.primaryService ? this.primaryService.modelName : null,
+      fallbacks: this.fallbackServices.map(s => s.modelName)
+    };
+  }
+
+  /**
+   * Generate embedding with automatic fallback
+   * @param {string} text - Text to embed
+   * @param {Object} options - Options
+   * @returns {Promise<number[]>} Embedding vector
+   */
+  async embed(text, options = {}) {
+    if (!this.configured || !this.primaryService) {
+      throw new ConfigurationError('EmbeddingFactory not configured');
+    }
+
+    // Try primary service
+    try {
+      if (!this.primaryService.initialized) {
+        await this.primaryService.init();
+      }
+      return await this.primaryService.embed(text, options);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.warn(`[EmbeddingFactory] Primary service failed: ${errorMessage}`);
+
+      // Try fallback services in order
+      for (const fallback of this.fallbackServices) {
+        try {
+          if (!fallback.initialized) {
+            await fallback.init();
+          }
+          console.log(`[EmbeddingFactory] Using fallback: ${fallback.modelName}`);
+          return await fallback.embed(text, options);
+        } catch (fallbackError) {
+          const fallbackErrorMessage = fallbackError instanceof Error ? fallbackError.message : String(fallbackError);
+          console.warn(`[EmbeddingFactory] Fallback ${fallback.modelName} failed: ${fallbackErrorMessage}`);
+        }
+      }
+
+      throw new EmbeddingError('All embedding services failed', {
+        primaryError: errorMessage,
+        fallbackCount: this.fallbackServices.length
+      });
+    }
+  }
+
+  /**
+   * Generate embeddings for batch of texts
+   * @param {string[]} texts - Texts to embed
+   * @param {Object} options - Options
+   * @returns {Promise<number[][]>} Array of embedding vectors
+   */
+  async embedBatch(texts, options = {}) {
+    if (!this.configured || !this.primaryService) {
+      throw new ConfigurationError('EmbeddingFactory not configured');
+    }
+
+    // Try primary service
+    try {
+      if (!this.primaryService.initialized) {
+        await this.primaryService.init();
+      }
+      return await this.primaryService.embedBatch(texts, options);
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      console.warn(`[EmbeddingFactory] Primary batch failed: ${errorMessage}`);
+      // Fallback to individual embedding with fallback services
+      const results = [];
+      for (const text of texts) {
+        results.push(await this.embed(text, options));
+      }
+      return results;
+    }
+  }
+
+  /**
+   * Get factory statistics
+   * @returns {Object} Statistics
+   */
+  getStats() {
+    const stats = {
+      configured: this.configured,
+      primary: this.primaryService?.getStats() || null,
+      fallbacks: this.fallbackServices.map(s => s.getStats())
+    };
+    return stats;
+  }
+
+  /**
+   * Clear all caches
+   */
+  clearCache() {
+    this.primaryService?.clearCache();
+    this.fallbackServices.forEach(s => s.clearCache());
+  }
+}
+
+export default EmbeddingFactory;

package/lib/embeddings/index.js

@@ -0,0 +1,2 @@
+export { default as EmbeddingService } from './service.js';
+export { default as EmbeddingFactory } from './factory.js';