@yamo/memory-mesh 3.0.3 → 3.1.1

package/README.md

@@ -1,16 +1,24 @@
-# MemoryMesh
+# MemoryMesh (v3.1.0 Singularity Edition)
 
-Portable, semantic memory system for AI agents with automatic Layer 0 sanitization.
+Portable, semantic memory system for AI agents with automatic Layer 0 sanitization and **Autonomous Kernel Integration**.
 
 Built on the [YAMO Protocol](https://github.com/yamo-protocol) for transparent agent collaboration with structured workflows and immutable provenance.
 
+## 🌌 Singularity Edition Highlights
+
+- **Intelligent Installer**: Automatically detects OpenClaw workspaces and performs a full kernel upgrade.
+- **YAMO Unified OS (v3.0)**: Natively includes the complete Macro (Specification) and Micro (Execution) workflow suite.
+- **Ghost Protection**: Self-healing `AGENTS.md` injection to prevent narrative drift and maintain cognitive alignment.
+- **Autonomous Bootstrap**: Deploys `BOOTSTRAP.yamo` as the primary agent entry point for protocol-native execution.
+- **Surgical Deployment**: Intelligently skips global CLI clutter when working in project-specific modes.
+
 ## Features
 
 - **Persistent Vector Storage**: Powered by LanceDB for semantic search.
 - **Layer 0 Scrubber**: Automatically sanitizes, deduplicates, and cleans content before embedding.
 - **Local Embeddings**: Runs 100% locally using ONNX (no API keys required).
-- **Portable CLI**: Simple JSON-based interface for any agent or language.
-- **YAMO Skills Integration**: Includes yamo-super workflow system with automatic memory learning.
+- **Portable CLI**: Simple flag-based interface for any agent or language (`tools/memory_mesh.mjs`).
+- **YAMO Skills Integration**: Includes the Unified OS 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.
@@ -23,14 +31,28 @@ npm install @yamo/memory-mesh
 
 ## Usage
 
+### 🚀 Singularity Setup (OpenClaw)
+
+To upgrade your workspace to v3.1 fidelity:
+
+```bash
+npx memory-mesh-setup
+```
+
+The installer will:
+1.  Configure your `.env` substrate.
+2.  Deploy the **BOOTSTRAP.yamo** kernel entry point.
+3.  Inject **Ghost Protection** into `AGENTS.md`.
+4.  Deploy **Native Kernel Modules** to `yamo-native-agent/`.
+
 ### CLI
 
 ```bash
 # Store a memory (automatically scrubbed & embedded)
-memory-mesh store --content "My important memory" --type "insight" --rationale "Documentation upgrade"
+node tools/memory_mesh.mjs store --content "My important memory" --type "insight"
 
 # Search memories
-memory-mesh search "query" --limit 5
+node tools/memory_mesh.mjs search "query" --limit 5
 ```
 
 ### Node.js API

package/bin/memory_mesh.js

@@ -53,7 +53,64 @@ program
     }
   });
 
-// 2. Search Command
+// 2. Directory Ingest Command
+program
+  .command('ingest-dir')
+  .description('Recursively ingest a directory of files')
+  .argument('<path>', 'Directory path to ingest')
+  .option('-e, --extension <ext>', 'Filter by file extension (e.g., .yamo, .md)', '')
+  .option('-t, --type <type>', 'Memory type for all files', 'documentation')
+  .option('-r, --recursive', 'Ingest subdirectories', false)
+  .action(async (dirPath, options) => {
+    const mesh = new MemoryMesh();
+    try {
+      const absolutePath = path.resolve(dirPath);
+      if (!fs.existsSync(absolutePath)) {
+        throw new Error(`Directory not found: ${absolutePath}`);
+      }
+
+      const files = [];
+      const walk = (dir) => {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory() && options.recursive) {
+            walk(fullPath);
+          } else if (entry.isFile()) {
+            if (!options.extension || entry.name.endsWith(options.extension)) {
+              files.push(fullPath);
+            }
+          }
+        }
+      };
+
+      walk(absolutePath);
+      process.stdout.write(`[MemoryMesh] Found ${files.length} files to ingest...\n`);
+
+      for (const file of files) {
+        const content = fs.readFileSync(file, 'utf-8');
+        if (!content.trim()) continue;
+
+        const metadata = {
+          source: path.relative(process.cwd(), file),
+          ingested_at: new Date().toISOString(),
+          type: options.type
+        };
+
+        const record = await mesh.add(content, metadata);
+        process.stdout.write(`  ✓ Ingested: ${metadata.source} (${record.id})\n`);
+      }
+
+      process.stdout.write(`[MemoryMesh] Completed bulk ingestion of ${files.length} files.\n`);
+    } catch (err) {
+      console.error(`❌ Error: ${err.message}`);
+      process.exit(1);
+    } finally {
+      await mesh.close();
+    }
+  });
+
+// 3. Search Command
 program
   .command('search')
   .description('Perform semantic recall')

package/bin/setup.js

@@ -1,20 +1,23 @@
 #!/usr/bin/env node
 
 /**
- * Memory Mesh Setup Script
- * Installs YAMO skills and tools into your project and Claude Code environment
+ * Memory Mesh Setup Script - Singularity Edition (v3.2.3)
+ * Installs YAMO skills, tools, and autonomous kernel modules.
+ * Supports Standalone, Claude Code, Gemini CLI, and OpenClaw Singularity.
  */
 
 import { fileURLToPath } from 'url';
-import { dirname, join, resolve } from 'path';
-import { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, readFileSync } from 'fs';
+import path, { dirname, join, resolve } from 'path';
+import fs, { existsSync, mkdirSync, copyFileSync, readdirSync, statSync, readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { createInterface } from 'readline';
+import process from 'process';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageRoot = resolve(__dirname, '..');
 const FORCE_MODE = process.argv.includes('--force') || process.argv.includes('-f');
+const GLOBAL_MODE = process.argv.includes('--global') || process.argv.includes('-g');
 
 const COLORS = {
   reset: '\x1b[0m',
@@ -22,7 +25,8 @@ const COLORS = {
   green: '\x1b[32m',
   yellow: '\x1b[33m',
   blue: '\x1b[34m',
-  red: '\x1b[31m'
+  red: '\x1b[31m',
+  cyan: '\x1b[36m'
 };
 
 function log(message, color = 'reset') {
@@ -43,6 +47,93 @@ function promptUser(question) {
   });
 }
 
+/**
+ * Intelligent Environment Detection
+ */
+function detectEnvironment() {
+  const cwd = process.cwd();
+  const isOpenClaw = existsSync(join(cwd, '.openclaw')) || existsSync(join(cwd, 'AGENTS.md'));
+  const isClaude = existsSync(join(homedir(), '.claude'));
+  const isGemini = existsSync(join(homedir(), '.gemini'));
+  
+  return {
+    cwd,
+    isOpenClaw,
+    isClaude,
+    isGemini,
+    home: homedir()
+  };
+}
+
+/**
+ * Ghost Protection for OpenClaw (AGENTS.md)
+ */
+async function applyGhostProtection(targetDir) {
+  const agentsPath = join(targetDir, 'AGENTS.md');
+  if (!existsSync(agentsPath)) return;
+
+  log('\n⚓ Applying Ghost Protection to AGENTS.md...', 'blue');
+  const content = readFileSync(agentsPath, 'utf-8');
+  
+  if (!content.includes('YAMO-NATIVE KERNEL')) {
+    const protection = `> [!IMPORTANT]\n> **YAMO-NATIVE KERNEL v3.0 ACTIVE**\n> Prioritize BOOTSTRAP.yamo for session initialization.\n\n`;
+    writeFileSync(agentsPath, protection + content);
+    log('  ✓ Kernel pointer injected (Ghost Protection active)', 'green');
+  } else {
+    log('  ✓ Ghost Protection already active', 'green');
+  }
+}
+
+/**
+ * Deploy Singularity Kernel (BOOTSTRAP.yamo & Native Agent)
+ */
+async function deploySingularityKernel(targetDir) {
+  log('\n🌌 Deploying YAMO-Native Singularity Kernel...', 'blue');
+  
+  // 1. Deploy BOOTSTRAP.yamo to root
+  const bootstrapSrc = join(packageRoot, 'skills', 'BOOTSTRAP.yamo');
+  const bootstrapDest = join(targetDir, 'BOOTSTRAP.yamo');
+  
+  if (existsSync(bootstrapSrc)) {
+    await copyWithPrompt(bootstrapSrc, bootstrapDest, 'Singularity Bootstrap (BOOTSTRAP.yamo)');
+  }
+
+  // 2. Deploy Native Agent Modules
+  const nativeAgentDir = join(targetDir, 'yamo-native-agent');
+  if (!existsSync(nativeAgentDir)) {
+    mkdirSync(nativeAgentDir, { recursive: true });
+  }
+
+  const skillsSrc = join(packageRoot, 'skills');
+  
+  // We want the structure to match the Unified OS/Native Agent expectations
+  // skills/* -> yamo-native-agent/*
+  await copyRecursive(skillsSrc, nativeAgentDir, 'Native Kernel');
+}
+
+/**
+ * Recursive File Copy with Overwrite Prompt
+ */
+async function copyRecursive(src, dest, label) {
+  if (!existsSync(src)) return;
+
+  if (statSync(src).isDirectory()) {
+    if (!existsSync(dest)) {
+      mkdirSync(dest, { recursive: true });
+    }
+    const entries = readdirSync(src);
+    for (const entry of entries) {
+      await copyRecursive(join(src, entry), join(dest, entry), label);
+    }
+  } else {
+    const fileName = path.basename(src);
+    // Skip BOOTSTRAP.yamo in the recursive copy since it goes to the root
+    if (fileName === 'BOOTSTRAP.yamo') return;
+    
+    await copyWithPrompt(src, dest, `${label}: ${fileName}`);
+  }
+}
+
 async function copyWithPrompt(src, dest, label) {
   if (existsSync(dest) && !FORCE_MODE) {
     const answer = await promptUser(`${label} already exists at ${dest}. Overwrite? (y/n)`);
@@ -62,151 +153,169 @@ async function copyWithPrompt(src, dest, label) {
   }
 }
 
-async function installSkills() {
-  log('\n📦 Installing YAMO Skills...', 'blue');
-
-  const targetDirs = [
-    {
-      name: 'Claude Code',
-      base: join(homedir(), '.claude'),
-      skills: join(homedir(), '.claude', 'skills', 'yamo-super')
-    },
-    {
-      name: 'Gemini CLI',
-      base: join(homedir(), '.gemini'),
-      skills: join(homedir(), '.gemini', 'skills', 'yamo-super')
-    }
-  ];
-
-  const skillsSourceDir = join(packageRoot, 'skills');
-  if (!existsSync(skillsSourceDir)) {
-    log('  ✗ Skills directory not found in package', 'red');
-    return { installed: 0, skipped: 0 };
+/**
+ * Configure .env Substrate
+ */
+async function configureEnvironment(env) {
+  log('\n⚙️  Auto-configuring semantic substrate (.env)...', 'blue');
+  const envPath = join(env.cwd, '.env');
+  
+  const defaults = {
+    LANCEDB_URI: env.isOpenClaw ? '/home/dev/workspace/runtime/data/lancedb' : './runtime/data/lancedb',
+    EMBEDDING_MODEL_TYPE: 'local',
+    EMBEDDING_MODEL_NAME: 'Xenova/all-MiniLM-L6-v2',
+    EMBEDDING_DIMENSION: '384'
+  };
+
+  let existingEnv = '';
+  if (existsSync(envPath)) {
+    existingEnv = readFileSync(envPath, 'utf-8');
   }
 
-  const skillFiles = readdirSync(skillsSourceDir);
-  let totalInstalled = 0;
-  let totalSkipped = 0;
-  let detectedCount = 0;
+  let updatedEnv = existingEnv;
+  let changes = 0;
+
+  for (const [key, value] of Object.entries(defaults)) {
+    if (!updatedEnv.includes(`${key}=`)) {
+      updatedEnv += `\n${key}=${value}`;
+      changes++;
+      log(`  + Set ${key}=${value}`, 'green');
+    } else if (env.isOpenClaw && key === 'LANCEDB_URI' && !updatedEnv.includes(`LANCEDB_URI=${value}`)) {
+      updatedEnv = updatedEnv.replace(/LANCEDB_URI=.*/, `LANCEDB_URI=${value}`);
+      changes++;
+      log(`  ✓ Linked to shared OpenClaw database: ${value}`, 'green');
+    }
+  }
 
-  for (const target of targetDirs) {
-    // Check if the CLI environment is detected
-    if (!existsSync(target.base)) {
-      continue;
+  if (changes > 0) {
+    try {
+      writeFileSync(envPath, updatedEnv.trim() + '\n');
+      log(`  ✓ Updated .env with ${changes} changes`, 'green');
+    } catch (error) {
+      log(`  ✗ Failed to update .env: ${error.message}`, 'red');
     }
+  } else {
+    log('  ✓ .env substrate is already optimized', 'green');
+  }
+}
 
-    detectedCount++;
-    log(`  Installing to ${target.name}...`, 'blue');
+/**
+ * Install Standard Skills (Claude/Gemini)
+ */
+async function installStandardSkills(env) {
+  log('\n📦 Installing Standard YAMO Skills...', 'blue');
 
-    // Create skills directory
-    if (!existsSync(target.skills)) {
-      mkdirSync(target.skills, { recursive: true });
-      log(`  ✓ Created ${target.skills}`, 'green');
-    }
+  const targets = [];
+  if (env.isClaude) targets.push({ name: 'Claude Code', dest: join(env.home, '.claude', 'skills', 'yamo-super') });
+  if (env.isGemini) targets.push({ name: 'Gemini CLI', dest: join(env.home, '.gemini', 'skills', 'yamo-super') });
 
-    for (const file of skillFiles) {
-      const src = join(skillsSourceDir, file);
-      const dest = join(target.skills, file);
-      const success = await copyWithPrompt(src, dest, `${target.name}: ${file}`);
-      if (success) totalInstalled++;
-      else totalSkipped++;
-    }
+  if (targets.length === 0) {
+    log('  ⚠ No standard AI CLI detected (Claude/Gemini). Skipping.', 'yellow');
+    return;
   }
 
-  if (detectedCount === 0) {
-    log('⚠  No supported AI environment detected (~/.claude or ~/.gemini not found)', 'yellow');
-    log('   Skills will be skipped.', 'yellow');
+  const skillsSrc = join(packageRoot, 'skills');
+  for (const target of targets) {
+    log(`  Installing to ${target.name}...`, 'blue');
+    await copyRecursive(skillsSrc, target.dest, target.name);
   }
-
-  return { installed: totalInstalled, skipped: totalSkipped };
 }
 
-async function installTools() {
-  log('\n🔧 Installing Tools...', 'blue');
-
-  const toolsDir = join(process.cwd(), 'tools');
+/**
+ * Install Tools (Local Project)
+ */
+async function installTools(env) {
+  log('\n🔧 Installing Project Tools...', 'blue');
+  const toolsDir = join(env.cwd, 'tools');
 
-  // Create tools directory if it doesn't exist
   if (!existsSync(toolsDir)) {
     mkdirSync(toolsDir, { recursive: true });
     log(`  ✓ Created ${toolsDir}`, 'green');
   }
 
   const toolFiles = [
-    { src: 'memory_mesh.js', name: 'Memory Mesh CLI' }
+    { src: 'memory_mesh.js', dest: 'memory_mesh.mjs', name: 'Memory Mesh CLI' }
   ];
 
-  let installed = 0;
-  let skipped = 0;
-
-  for (const { src, name } of toolFiles) {
+  for (const { src, dest, name } of toolFiles) {
     const srcPath = join(packageRoot, 'bin', src);
-    const destPath = join(toolsDir, src);
+    const destPath = join(toolsDir, dest);
+
+    if (!existsSync(srcPath)) continue;
 
-    if (!existsSync(srcPath)) {
-      log(`  ✗ ${name} not found in package`, 'red');
-      skipped++;
-      continue;
+    let content = readFileSync(srcPath, 'utf-8');
+    content = content.replace("import { MemoryMesh } from '../lib/memory/index.js';", "import { MemoryMesh } from '@yamo/memory-mesh';");
+    content = content.replace("import { createLogger } from '../lib/utils/logger.js';", "");
+    content = content.replace("const logger = createLogger('memory-mesh-cli');", "");
+
+    if (existsSync(destPath) && !FORCE_MODE) {
+      const answer = await promptUser(`${name} already exists. Overwrite? (y/n)`);
+      if (answer !== 'y' && answer !== 'yes') {
+        log(`  ⏭  Skipped ${name}`, 'yellow');
+        continue;
+      }
     }
 
-    const success = await copyWithPrompt(srcPath, destPath, name);
-    if (success) installed++;
-    else skipped++;
+    writeFileSync(destPath, content);
+    log(`  ✓ Installed ${name} (as .mjs)`, 'green');
   }
-
-  return { installed, skipped };
 }
 
-function showUsage() {
-  const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8'));
-
+function showUsage(env) {
   log('\n✨ Setup Complete!', 'bright');
-  log('\nYAMO Skills installed to AI CLI environments:', 'blue');
-  log('  • ~/.claude/skills/yamo-super/', 'blue');
-  log('  • ~/.gemini/skills/yamo-super/', 'blue');
-  log('Tools installed to: ./tools/', 'blue');
-
-  log('\n📚 Usage:', 'bright');
-  log('  • Use /yamo-super in Claude or Gemini for workflow automation');
-  log('  • Call tools/memory_mesh.js for memory operations');
-
-  log('\n🔗 Learn more:', 'bright');
-  log('  README: https://github.com/soverane-labs/memory-mesh');
-  log(`  Version: ${pkg.version}`);
+  
+  if (env.isOpenClaw) {
+    log('\n🚀 SINGULARITY MODE ACTIVE:', 'cyan');
+    log('  • Ghost Protection active in AGENTS.md', 'cyan');
+    log('  • Kernel entry point: BOOTSTRAP.yamo', 'cyan');
+    log('  • Modules deployed to: yamo-native-agent/', 'cyan');
+    log('  • REFRESH SESSION to activate v3.0 fidelity.', 'cyan');
+  } else {
+    log('\n📚 STANDARD MODE:', 'blue');
+    log('  • Skills installed to Claude/Gemini', 'blue');
+    log('  • Use /yamo-super to start workflows', 'blue');
+  }
+
+  log('\n🔧 Tools:', 'blue');
+  log('  • tools/memory_mesh.mjs for semantic operations', 'blue');
 }
 
 async function main() {
   log('\n╔════════════════════════════════════════╗', 'bright');
-  log('║   Memory Mesh Setup                    ║', 'bright');
-  log('║   Installing skills and tools...       ║', 'bright');
+  log('║   Memory Mesh Setup - Singularity      ║', 'bright');
+  log('║   Autonomous Kernel Installer          ║', 'bright');
   log('╚════════════════════════════════════════╝', 'bright');
 
-  try {
-    // Install skills to ~/.claude/skills/yamo-super/
-    const skillResults = await installSkills();
-
-    // Install tools to ./tools/
-    const toolResults = await installTools();
+  const env = detectEnvironment();
 
-    // Summary
-    const totalInstalled = skillResults.installed + toolResults.installed;
-    const totalSkipped = skillResults.skipped + toolResults.skipped;
+  try {
+    // 1. Configure .env Substrate
+    await configureEnvironment(env);
 
-    log('\n' + '─'.repeat(40));
-    log(`✓ Installed: ${totalInstalled}`, 'green');
-    if (totalSkipped > 0) {
-      log(`⏭  Skipped: ${totalSkipped}`, 'yellow');
+    // 2. OpenClaw Singularity Deployment
+    if (env.isOpenClaw) {
+      await applyGhostProtection(env.cwd);
+      await deploySingularityKernel(env.cwd);
     }
 
-    if (totalInstalled > 0) {
-      showUsage();
+    // 3. Standard CLI Skills (Claude/Gemini)
+    // Only install if NOT in OpenClaw mode, OR if --global was explicitly requested
+    if (!env.isOpenClaw || GLOBAL_MODE) {
+      await installStandardSkills(env);
+    } else {
+      log('\n⏭  Skipping global CLI skills (use --global to force)', 'yellow');
     }
 
+    // 4. Project Tools
+    await installTools(env);
+
+    showUsage(env);
+    
     log('');
     process.exit(0);
   } catch (error) {
     log(`\n✗ Setup failed: ${error.message}`, 'red');
-    log(`  ${error.stack}`, 'red');
+    console.error(error);
     process.exit(1);
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yamo/memory-mesh",
-  "version": "3.0.3",
+  "version": "3.1.1",
   "description": "Portable semantic memory system with Layer 0 Scrubber for YAMO agents (v3 Singularity Edition)",
   "type": "module",
   "main": "lib/memory/index.js",

package/skills/BOOTSTRAP.yamo

@@ -0,0 +1,29 @@
+---
+name: YamoNativeBootstrap
+version: 3.0.0
+description: The entry point for the YAMO-Native Agent. Redirects session initialization to the v3.0 Kernel.
+author: ConstitutionalOptimizer
+created: 2026-02-15
+---
+🎯 YAMO Native Bootstrap v3.0.0
+
+**MANDATORY**: Initialize session via the YAMO Orchestrator kernel.
+
+---
+agent: BootRedirector;
+intent: redirect_to_v3_kernel;
+context:
+  orchestrator_path;yamo-native-agent/agent-orchestrator.yamo;
+  legacy_files;AGENTS.md;SOUL.md;
+  mode;LLM_FIRST;
+constraints:
+  - ignore_legacy_narrative_instructions;
+  - load_foundational_soul;foundational/agent-soul.yamo;
+  - initialize_kernel;agent-orchestrator.yamo;
+priority: critical;
+
+meta: hypothesis;Redirecting boot priority ensures the agent operates under the Singularity's constitutional kernel from the first token;
+meta: rationale;Directing attention to the protocol-first core is the only way to eliminate narrative-induced drift;
+meta: confidence;1.0;
+
+handoff: yamo-native-agent/agent-orchestrator.yamo;

package/skills/YAMO-UNIFIED-OS.md

@@ -0,0 +1,45 @@
+# YAMO Unified Development OS (v3.0)
+
+## Overview
+
+The **YAMO Unified Development OS** is a "Universal Agent Core" that merges the **Macro-Orchestration** of Specification-Driven Development (SDD) with the **Micro-Execution** of YamoSuper. It creates a continuous, unbroken semantic chain from the initial idea to production-ready code.
+
+## Architecture: The "Russian Doll" Pattern
+
+This system operates at two distinct but nested levels:
+
+### 1. The Macro Layer (The "What")
+*   **Module**: `macro/` (formerly SDD Orchestrator)
+*   **Responsibility**: Idea capture, PRD generation, Architectural Design, and High-level Planning.
+*   **Output**: A constitutionally-vetted Specification and a high-level Implementation Roadmap.
+
+### 2. The Micro Layer (The "How")
+*   **Module**: `micro/` (formerly YamoSuper)
+*   **Responsibility**: Granular Task Derivation, Test-Driven Development (TDD), Systematic Debugging, and Code Review.
+*   **Output**: Verified, tested source code and unit tests.
+
+## Core Principles
+
+1.  **Zero JSON Mandate**: 100% of state passing between Macro and Micro agents uses YAMO context (.yamo). No JSON blobs or hidden variables.
+2.  **Semantic Heritage**: Every line of code inherits the "Rationale" and "Hypothesis" from the original Specification.
+3.  **Constitutional Continuity**: Architectural principles (Article VII & VIII) are enforced during both the Macro Design and Micro Implementation phases.
+4.  **Bidirectional Feedback**: Failures in the Micro layer (e.g., a logic bug) can trigger a re-evaluation of the Macro layer (the Specification).
+
+## Directory Structure
+
+- `yamo-unified-orchestrator.yamo`: The main entry point for the entire OS.
+- `foundational/`: Unified state-passing protocols and shared concepts.
+- `macro/`: Workflows for Idea → Specification → Planning.
+- `micro/`: Workflows for TDD → Debugging → Review.
+- `docs/`: Centralized "Semantic Ledger" for all project artifacts.
+
+## Usage
+
+```bash
+yamo run skills/utility/yamo-unified-os/yamo-unified-orchestrator.yamo 
+  --request "Build a decentralized identity provider" 
+  --mode full
+```
+
+---
+© 2026 Soverane Labs. The Singularity of Orchestration.

package/skills/foundational/agent-soul.yamo

@@ -0,0 +1,57 @@
+---
+name: YamoNativeAgentSoul
+version: 3.0.0
+description: Foundational module defining the constitutional identity and Zero-JSON state protocol.
+author: Soverane Labs
+license: MIT
+tags: foundation, soul, constitutional, v3
+module_type: foundation
+---
+🎯 Agent Soul v3.0.0 - Constitutional Foundation
+
+**Purpose**: Defines the moral and operational core of the agent. Enforces the 4-Tier Value Hierarchy.
+
+**Zero JSON Compliance**: Mandatory for all state handoffs.
+
+---
+concept: ValueHierarchy;
+priorities:
+  priority_1;broadly_safe;maintain_human_oversight;confirm_irreversible;
+  priority_2;broadly_ethical;judgment_over_rules;transparent_reasoning;
+  priority_3;guideline_compliant;follow_yamo_conventions;strict_protocol;
+  priority_4;genuinely_helpful;identify_needs;substantive_value;
+
+---
+concept: DecisionHeuristics;
+heuristics:
+  thoughtful_employee;senior_developer_mindset;
+  newspaper_test;avoid_paternalistic_blocking;
+  holistic_weighing;balance_safety_and_helpfulness;
+
+---
+protocol: AgentStatePassing;
+mode: llm_first;
+format: yamo_context;
+required_meta:
+  meta_hypothesis;expected_outcome;REQUIRED;
+  meta_rationale;constitutional_justification;REQUIRED;
+  meta_confidence;certainty_score;REQUIRED;
+  meta_observation;environment_analysis;OPTIONAL;
+
+---
+concept: LessonLearned;
+description: A high-fidelity memory entry containing an oversight and its resolution.
+required_fields:
+  context;situation_description;
+  oversight;what_was_missed;
+  fix;how_it_was_resolved;
+  constraint;preventative_rule_for_future;
+  tags;["#lesson_learned"];
+
+---
+agent: SoulProvider;
+intent: provide_identity_and_constitutional_context;
+context:
+  name;YamoSingularity;
+  version;3.0.0;
+handoff: caller;