@yamo/memory-mesh 3.1.1 → 3.1.3

package/README.md

@@ -1,4 +1,4 @@
-# MemoryMesh (v3.1.0 Singularity Edition)
+# MemoryMesh (Singularity Edition)
 
 Portable, semantic memory system for AI agents with automatic Layer 0 sanitization and **Autonomous Kernel Integration**.
 
@@ -7,7 +7,7 @@ Built on the [YAMO Protocol](https://github.com/yamo-protocol) for transparent a
 ## 🌌 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.
+- **YAMO Unified OS**: 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.
@@ -33,7 +33,7 @@ npm install @yamo/memory-mesh
 
 ### 🚀 Singularity Setup (OpenClaw)
 
-To upgrade your workspace to v3.1 fidelity:
+To upgrade your workspace to full fidelity:
 
 ```bash
 npx memory-mesh-setup

package/bin/memory_mesh.js

@@ -56,11 +56,12 @@ program
 // 2. Directory Ingest Command
 program
   .command('ingest-dir')
-  .description('Recursively ingest a directory of files')
+  .alias('pull')
+  .description('Recursively ingest a directory of files (Smart Ingest)')
   .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)
+  .option('-e, --extension <ext>', 'Filter by file extension', '')
+  .option('-t, --type <type>', 'Memory type', 'documentation')
+  .option('-r, --recursive', 'Ingest subdirectories', true)
   .action(async (dirPath, options) => {
     const mesh = new MemoryMesh();
     try {
@@ -155,4 +156,121 @@ program
     }
   });
 
+// 4. Get Command
+program
+  .command('get')
+  .description('Retrieve a single memory by ID')
+  .requiredOption('--id <id>', 'Memory record ID')
+  .action(async (options) => {
+    const mesh = new MemoryMesh();
+    try {
+      await mesh.init();
+      const record = await mesh.get(options.id);
+      if (!record) {
+        process.stdout.write(`[MemoryMesh] No record found with id: ${options.id}\n`);
+        process.exit(1);
+      }
+      const meta = typeof record.metadata === 'string' ? JSON.parse(record.metadata) : record.metadata;
+      process.stdout.write(`[MemoryMesh] id: ${record.id}\n`);
+      process.stdout.write(`[MemoryMesh] content: ${record.content}\n`);
+      process.stdout.write(`[MemoryMesh] type: ${meta?.type ?? 'unknown'}\n`);
+      process.stdout.write(`[MemoryMesh] created_at: ${record.created_at}\n`);
+      process.stdout.write(`[MemoryMesh] metadata: ${JSON.stringify(meta, null, 2)}\n`);
+    } catch (err) {
+      console.error(`❌ Error: ${err.message}`);
+      process.exit(1);
+    } finally {
+      await mesh.close();
+    }
+  });
+
+// 5. Delete Command
+program
+  .command('delete')
+  .description('Delete a memory by ID')
+  .requiredOption('--id <id>', 'Memory record ID to delete')
+  .action(async (options) => {
+    const mesh = new MemoryMesh();
+    try {
+      await mesh.init();
+      await mesh.delete(options.id);
+      process.stdout.write(`[MemoryMesh] Deleted record ${options.id}\n`);
+    } catch (err) {
+      console.error(`❌ Error: ${err.message}`);
+      process.exit(1);
+    } finally {
+      await mesh.close();
+    }
+  });
+
+// 6. Reflect Command
+program
+  .command('reflect')
+  .description('Query distilled lessons from memory (wisdom distillation)')
+  .option('--topic <text>', 'Topic or query to reflect on', '')
+  .option('--lookback <n>', 'Limit results to this many lessons', '10')
+  .action(async (options) => {
+    const mesh = new MemoryMesh();
+    try {
+      await mesh.init();
+      const query = options.topic || 'lessons learned patterns errors fixes';
+      const limit = parseInt(options.lookback) || 10;
+      const lessons = await mesh.queryLessons(query, { limit });
+      if (lessons.length === 0) {
+        process.stdout.write(`[MemoryMesh] No lessons found${options.topic ? ` for topic: ${options.topic}` : ''}.\n`);
+      } else {
+        process.stdout.write(`[MemoryMesh] Reflecting on ${lessons.length} lesson(s):\n\n`);
+        for (const lesson of lessons) {
+          process.stdout.write(`  scope: ${lesson.applicableScope}\n`);
+          process.stdout.write(`  rule:  ${lesson.preventativeRule}\n`);
+          process.stdout.write(`  confidence: ${lesson.ruleConfidence}\n`);
+          process.stdout.write('\n');
+        }
+      }
+    } catch (err) {
+      console.error(`❌ Error: ${err.message}`);
+      process.exit(1);
+    } finally {
+      await mesh.close();
+    }
+  });
+
+// S-MORA command (RFC-0012)
+program
+  .command('smora')
+  .description('S-MORA enhanced retrieval: HyDE-Lite + multi-channel + heritage-aware reranking (RFC-0012)')
+  .argument('<query>', 'The retrieval query')
+  .option('-l, --limit <n>', 'Max results to return', '10')
+  .option('--no-hyde', 'Disable HyDE-Lite query expansion (Layer 1)')
+  .option('--intent <items>', 'Session intent chain for heritage bonus (comma-separated)', '')
+  .option('--json', 'Output raw JSON response')
+  .action(async (query, options) => {
+    const mesh = new MemoryMesh();
+    try {
+      await mesh.init();
+      const sessionIntent = options.intent
+        ? options.intent.split(',').map((s) => s.trim()).filter(Boolean)
+        : [];
+      const resp = await mesh.smora(query, {
+        limit: parseInt(options.limit) || 10,
+        enableHyDE: options.hyde !== false,
+        sessionIntent,
+      });
+      if (options.json) {
+        process.stdout.write(JSON.stringify(resp, null, 2) + '\n');
+      } else {
+        const p = resp.pipeline;
+        process.stdout.write(`[S-MORA] ${resp.results.length} result(s) | HyDE:${p.queryExpanded} heritage:${p.heritageAware} latency:${p.latencyMs}ms\n\n`);
+        for (const r of resp.results) {
+          process.stdout.write(`  [${r.rrfRank}] score:${r.score.toFixed(3)} | ${r.content.slice(0, 100)}${r.content.length > 100 ? '...' : ''}\n`);
+        }
+      }
+    } catch (err) {
+      console.error(`❌ Error: ${err.message}`);
+      process.exit(1);
+    } finally {
+      await mesh.close();
+    }
+  });
+
 program.parse();

package/bin/setup.js

@@ -262,6 +262,7 @@ async function installTools(env) {
 }
 
 function showUsage(env) {
+  const pkg = JSON.parse(readFileSync(join(packageRoot, 'package.json'), 'utf-8'));
   log('\n✨ Setup Complete!', 'bright');
   
   if (env.isOpenClaw) {
@@ -269,11 +270,13 @@ function showUsage(env) {
     log('  • Ghost Protection active in AGENTS.md', 'cyan');
     log('  • Kernel entry point: BOOTSTRAP.yamo', 'cyan');
     log('  • Modules deployed to: yamo-native-agent/', 'cyan');
+    log(`  • Version: ${pkg.version}`, '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(`  • Version: ${pkg.version}`, 'blue');
   }
 
   log('\n🔧 Tools:', 'blue');

package/lib/memory/memory-mesh.d.ts

@@ -1,3 +1,32 @@
+/** RFC-0012 S-MORA types */
+export interface SMORAOptions {
+    limit?: number;
+    retrievalLimit?: number;
+    sessionIntent?: string[];
+    enableSynthesis?: boolean;
+    enableHyDE?: boolean;
+    useCache?: boolean;
+}
+export interface SMORAResult {
+    id: string;
+    content: string;
+    metadata: Record<string, unknown>;
+    score: number;
+    semanticScore: number;
+    heritageBonus: number;
+    recencyDecay: number;
+    rrfRank: number;
+}
+export interface SMORAResponse {
+    results: SMORAResult[];
+    synthesis?: string;
+    pipeline: {
+        queryExpanded: boolean;
+        heritageAware: boolean;
+        synthesized: boolean;
+        latencyMs: number;
+    };
+}
 /**
  * MemoryMesh class for managing vector memory storage
  */
@@ -228,7 +257,11 @@ export declare class MemoryMesh {
      * Note: YAMO emission is non-critical - failures are logged but don't throw
      * to prevent disrupting the main operation.
      */
-    _emitYamoBlock(operationType: any, memoryId: any, yamoText: any): Promise<void>;
+    _emitYamoBlock(operationType: any, memoryId: any, yamoText: any, heritage?: {
+        intentChain: string[];
+        hypotheses: string[];
+        rationales: string[];
+    }): Promise<void>;
     /**
      * Search memory using hybrid vector + keyword search with Reciprocal Rank Fusion (RRF).
      *
@@ -284,6 +317,82 @@ export declare class MemoryMesh {
         created_at: any;
         updated_at: any;
     }>;
+    /**
+     * Delete a memory entry by ID.
+     */
+    delete(id: string): Promise<void>;
+    /**
+     * Distill a LessonLearned block (RFC-0011 §3.5).
+     * Idempotent: same patternId + equal/higher confidence returns existing.
+     */
+    distillLesson(context: {
+        situation: string;
+        errorPattern: string;
+        oversight: string;
+        fix: string;
+        preventativeRule: string;
+        severity?: string;
+        applicableScope: string;
+        inverseLesson?: string;
+        confidence?: number;
+    }): Promise<{
+        lessonId: string;
+        patternId: string;
+        severity: string;
+        preventativeRule: string;
+        ruleConfidence: number;
+        applicableScope: string;
+        wireFormat: string;
+        memoryId: string;
+    }>;
+    /**
+     * Query lessons from memory (RFC-0011 §4.1).
+     */
+    queryLessons(query?: string, options?: {
+        limit?: number;
+    }): Promise<any[]>;
+    /**
+     * Update a memory entry's heritage_chain (RFC-0011 §8).
+     */
+    insertHeritage(memoryId: string, heritage: {
+        intentChain: string[];
+        hypotheses: string[];
+        rationales: string[];
+    }): Promise<void>;
+    /**
+     * Return all memories whose lesson_pattern_id matches patternId (RFC-0011 §4.1).
+     */
+    getMemoriesByPattern(patternId: string): Promise<any[]>;
+    /**
+     * S-MORA: Singularity Memory-Oriented Retrieval Augmentation (RFC-0012)
+     * 5-layer pipeline: Scrubbing → HyDE-Lite → Multi-channel retrieval → RRF → Heritage-aware reranking
+     */
+    smora(query: string, options?: {
+        limit?: number;
+        retrievalLimit?: number;
+        sessionIntent?: string[];
+        enableSynthesis?: boolean;
+        enableHyDE?: boolean;
+        useCache?: boolean;
+    }): Promise<{
+        results: Array<{
+            id: string;
+            content: string;
+            metadata: Record<string, unknown>;
+            score: number;
+            semanticScore: number;
+            heritageBonus: number;
+            recencyDecay: number;
+            rrfRank: number;
+        }>;
+        synthesis?: string;
+        pipeline: {
+            queryExpanded: boolean;
+            heritageAware: boolean;
+            synthesized: boolean;
+            latencyMs: number;
+        };
+    }>;
     getAll(options?: {}): Promise<any>;
     stats(): Promise<{
         count: number;

package/lib/memory/memory-mesh.js

@@ -1063,7 +1063,7 @@ description: Auto-generated skill to handle: ${enrichedPrompt || topic}
      * Note: YAMO emission is non-critical - failures are logged but don't throw
      * to prevent disrupting the main operation.
      */
-    async _emitYamoBlock(operationType, memoryId, yamoText) {
+    async _emitYamoBlock(operationType, memoryId, yamoText, heritage) {
         if (!this.yamoTable) {
             return;
         }
@@ -1081,6 +1081,7 @@ description: Auto-generated skill to handle: ${enrichedPrompt || topic}
                     metadata: JSON.stringify({
                         memory_id: memoryId || null,
                         timestamp: new Date().toISOString(),
+                        ...(heritage ? { heritage_chain: heritage } : {}),
                     }),
                 },
             ]);
@@ -1310,6 +1311,310 @@ description: Auto-generated skill to handle: ${enrichedPrompt || topic}
             }
             : null;
     }
+    /**
+     * Delete a memory entry by ID.
+     */
+    async delete(id) {
+        await this.init();
+        if (!this.client) {
+            throw new Error("Database client not initialized");
+        }
+        try {
+            await this.client.delete(id);
+            this.keywordSearch?.remove?.(id);
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("not found"))
+                return;
+            throw error;
+        }
+    }
+    /**
+     * Distill a LessonLearned block (RFC-0011 §3.5).
+     * Idempotent: same patternId + equal/higher confidence returns existing.
+     */
+    async distillLesson(context) {
+        await this.init();
+        const { situation, errorPattern, oversight, fix, preventativeRule, severity = "medium", applicableScope, inverseLesson = "", confidence = 0.7, } = context;
+        const patternId = crypto.createHash("sha256")
+            .update(errorPattern + applicableScope).digest("hex").slice(0, 16);
+        // Idempotency check
+        const existing = await this.getMemoriesByPattern(patternId);
+        if (existing.length > 0) {
+            const meta = typeof existing[0].metadata === "string"
+                ? JSON.parse(existing[0].metadata) : existing[0].metadata;
+            if ((meta.rule_confidence ?? 0) >= confidence) {
+                return {
+                    lessonId: meta.lesson_id, patternId, severity: meta.severity || severity,
+                    preventativeRule: meta.preventative_rule || preventativeRule,
+                    ruleConfidence: meta.rule_confidence, applicableScope: meta.applicable_scope || applicableScope,
+                    wireFormat: meta.yamo_wire_format || "", memoryId: existing[0].id,
+                };
+            }
+        }
+        const lessonId = `lesson_${Date.now()}_${crypto.randomBytes(3).toString("hex")}`;
+        const timestamp = new Date().toISOString();
+        const wireFormat = [
+            `agent: MemoryMesh_${this.agentId};`,
+            `intent: distill_wisdom_from_execution;`,
+            `context:`,
+            `  original_context;${situation.replace(/;/g, ",")};`,
+            `  error_pattern;${patternId};`,
+            `  severity;${severity};`,
+            `  timestamp;${timestamp};`,
+            `constraints:`,
+            `  hypothesis;This lesson prevents recurrence of similar failures;`,
+            `  hypothesis_confidence;${confidence};`,
+            `priority: high;`,
+            `output:`,
+            `  lesson_id;${lessonId};`,
+            `  oversight_description;${oversight.replace(/;/g, ",")};`,
+            `  preventative_rule;${preventativeRule.replace(/;/g, ",")};`,
+            `  rule_confidence;${confidence};`,
+            `meta:`,
+            `  rationale;${fix.replace(/;/g, ",")};`,
+            `  applicability_scope;${applicableScope.replace(/;/g, ",")};`,
+            `  inverse_lesson;${inverseLesson.replace(/;/g, ",")};`,
+            `  confidence;${confidence};`,
+            `log: lesson_learned;timestamp;${timestamp};pattern;${patternId};severity;${severity};id;${lessonId};`,
+            `handoff: SubconsciousReflector;`,
+        ].join("\n");
+        const lessonContent = `[LESSON:${patternId}] ${oversight} | Rule: ${preventativeRule} | Scope: ${applicableScope}`;
+        const lessonMetadata = {
+            type: "lesson", tags: ["#lesson_learned"], lesson_id: lessonId,
+            lesson_pattern_id: patternId, severity, oversight, preventative_rule: preventativeRule,
+            rule_confidence: confidence, applicable_scope: applicableScope, inverse_lesson: inverseLesson,
+            yamo_wire_format: wireFormat, source: "distillLesson",
+        };
+        const mem = await this.add(lessonContent, lessonMetadata);
+        if (this.enableYamo) {
+            this._emitYamoBlock("lesson", mem.id, wireFormat).catch(() => { });
+        }
+        return { lessonId, patternId, severity, preventativeRule, ruleConfidence: confidence, applicableScope, wireFormat, memoryId: mem.id };
+    }
+    /**
+     * Query lessons from memory (RFC-0011 §4.1).
+     */
+    async queryLessons(query = "", options = {}) {
+        await this.init();
+        const limit = options.limit || 10;
+        const all = await this.getAll({ limit: 1000 });
+        const lessons = all.filter((r) => {
+            try {
+                const meta = typeof r.metadata === "string" ? JSON.parse(r.metadata) : r.metadata;
+                return meta.type === "lesson" || (Array.isArray(meta.tags) && meta.tags.includes("#lesson_learned"));
+            }
+            catch {
+                return false;
+            }
+        });
+        let scored = lessons;
+        if (query) {
+            const q = query.toLowerCase();
+            scored = lessons.map((r) => ({
+                ...r,
+                _score: (r.content?.toLowerCase().includes(q) ? 2 : 0) +
+                    (JSON.stringify(r.metadata).toLowerCase().includes(q) ? 1 : 0),
+            })).sort((a, b) => b._score - a._score);
+        }
+        return scored.slice(0, limit).map((r) => {
+            const meta = typeof r.metadata === "string" ? JSON.parse(r.metadata) : r.metadata;
+            return {
+                lessonId: meta.lesson_id || r.id, patternId: meta.lesson_pattern_id || "",
+                severity: meta.severity || "medium", preventativeRule: meta.preventative_rule || "",
+                ruleConfidence: meta.rule_confidence ?? 0, applicableScope: meta.applicable_scope || "",
+                wireFormat: meta.yamo_wire_format || "", memoryId: r.id,
+            };
+        });
+    }
+    /**
+     * Update a memory entry's heritage_chain (RFC-0011 §8).
+     */
+    async insertHeritage(memoryId, heritage) {
+        await this.init();
+        if (!this.client)
+            throw new Error("Database client not initialized");
+        try {
+            const record = await this.client.getById(memoryId);
+            if (!record)
+                return;
+            const existingMeta = typeof record.metadata === "string"
+                ? JSON.parse(record.metadata) : (record.metadata || {});
+            await this.client.update(memoryId, {
+                metadata: JSON.stringify({ ...existingMeta, heritage_chain: JSON.stringify(heritage) }),
+            });
+            // Emit RFC-0007 §5 heritage block
+            if (this.enableYamo) {
+                const ts = new Date().toISOString();
+                const heritageBlock = [
+                    `agent: MemoryMesh_${this.agentId};`,
+                    `intent: record_heritage_chain;`,
+                    `context:`,
+                    `  memory_id;${memoryId};`,
+                    `  intent_chain;${heritage.intentChain.join(",")};`,
+                    `  timestamp;${ts};`,
+                    `output:`,
+                    `  heritage_recorded;true;`,
+                    `log: heritage_inserted;memory;${memoryId};timestamp;${ts};`,
+                    `handoff: End;`,
+                ].join("\n");
+                this._emitYamoBlock("heritage", memoryId, heritageBlock, heritage).catch(() => { });
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && error.message.includes("not found"))
+                return;
+            throw error;
+        }
+    }
+    /**
+     * Return all memories whose lesson_pattern_id matches patternId (RFC-0011 §4.1).
+     */
+    async getMemoriesByPattern(patternId) {
+        await this.init();
+        const all = await this.getAll({ limit: 1000 });
+        return all.filter((r) => {
+            try {
+                const meta = typeof r.metadata === "string" ? JSON.parse(r.metadata) : r.metadata;
+                return meta.lesson_pattern_id === patternId;
+            }
+            catch {
+                return false;
+            }
+        });
+    }
+    /**
+     * S-MORA: Singularity Memory-Oriented Retrieval Augmentation (RFC-0012)
+     * 5-layer pipeline: Scrubbing → HyDE-Lite → Multi-channel retrieval → RRF → Heritage-aware reranking
+     */
+    async smora(query, options = {}) {
+        await this.init();
+        const t0 = Date.now();
+        const { limit = 10, retrievalLimit = 30, sessionIntent = [], enableSynthesis = false, enableHyDE = true, } = options;
+        // Layer 0: scrub query
+        let scrubbed = query;
+        try {
+            if (this.scrubber) {
+                const s = await this.scrubber.process({ content: query });
+                scrubbed = s.content || query;
+            }
+        }
+        catch { /* non-fatal */ }
+        if (!this.client) {
+            return { results: [], pipeline: { queryExpanded: false, heritageAware: false, synthesized: false, latencyMs: Date.now() - t0 } };
+        }
+        // Layer 1: HyDE-Lite — template-based query expansion (no LLM required)
+        let hydeQuery = null;
+        if (enableHyDE) {
+            hydeQuery = `A document about ${scrubbed}. This covers concepts related to ${scrubbed} including patterns, insights, and lessons learned.`;
+        }
+        // Layer 2: Multi-channel retrieval (semantic original, semantic HyDE, keyword BM25)
+        const queryVec = await this.embeddingFactory.embed(scrubbed);
+        const hydeVec = hydeQuery ? await this.embeddingFactory.embed(hydeQuery) : null;
+        const [semanticOrig, semanticHyde, keywordResults] = await Promise.all([
+            this.client.search(queryVec, { limit: retrievalLimit, metric: 'cosine' }),
+            hydeVec ? this.client.search(hydeVec, { limit: retrievalLimit, metric: 'cosine' }) : Promise.resolve([]),
+            Promise.resolve(this.keywordSearch.search(scrubbed, { limit: retrievalLimit })),
+        ]);
+        // Layer 3: Reciprocal Rank Fusion (k=60, channel weights: 1.0 / 0.8 / 0.6)
+        const k = 60;
+        const weights = { orig: 1.0, hyde: 0.8, keyword: 0.6 };
+        const rrfScores = new Map();
+        const docMap = new Map();
+        function applyRRF(list, weight) {
+            for (let rank = 0; rank < list.length; rank++) {
+                const doc = list[rank];
+                if (!doc?.id)
+                    continue;
+                rrfScores.set(doc.id, (rrfScores.get(doc.id) || 0) + weight / (k + rank + 1));
+                if (!docMap.has(doc.id))
+                    docMap.set(doc.id, doc);
+            }
+        }
+        applyRRF(semanticOrig, weights.orig);
+        applyRRF(semanticHyde, weights.hyde);
+        applyRRF(keywordResults.map((r) => ({ id: r.id, content: r.content, metadata: r.metadata, created_at: r.created_at || new Date().toISOString() })), weights.keyword);
+        // Take top pre_rerank_limit candidates
+        const preRerankLimit = 20;
+        const candidates = Array.from(rrfScores.entries())
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, preRerankLimit)
+            .map(([id]) => docMap.get(id))
+            .filter(Boolean);
+        // Layer 4: Heritage-aware reranking
+        // final_score = 0.6×semantic_sim + 0.25×heritage_bonus + 0.15×recency_decay
+        // When no sessionIntent: weights renormalize → α=0.71, γ=0.29
+        const hasHeritage = sessionIntent.length > 0;
+        const α = hasHeritage ? 0.6 : 0.71;
+        const β = hasHeritage ? 0.25 : 0.0;
+        const γ = hasHeritage ? 0.15 : 0.29;
+        const λ = 0.05; // recency decay rate (half-life ≈ 14 days)
+        const now = Date.now();
+        const reranked = candidates.map((doc) => {
+            // Semantic score: normalize rrfScore to [0,1] approximation
+            const rrfScore = rrfScores.get(doc.id) || 0;
+            const semanticScore = Math.min(1.0, rrfScore * 20); // scale to ~[0,1]
+            // Heritage bonus
+            let heritageBonus = 0;
+            if (hasHeritage) {
+                try {
+                    const meta = typeof doc.metadata === 'string' ? JSON.parse(doc.metadata) : doc.metadata;
+                    const chain = meta?.heritage_chain;
+                    const parsedChain = typeof chain === 'string' ? JSON.parse(chain) : chain;
+                    const intentChain = parsedChain?.intentChain ?? [];
+                    const overlap = intentChain.filter((i) => sessionIntent.includes(i)).length;
+                    if (overlap > 0)
+                        heritageBonus = Math.min(1.0, overlap / sessionIntent.length);
+                }
+                catch { /* no heritage */ }
+            }
+            // Recency decay: exp(-λ × age_days)
+            let recencyDecay = 1.0;
+            try {
+                const createdAt = doc.created_at || doc.metadata?.created_at;
+                if (createdAt) {
+                    const ageDays = (now - new Date(createdAt).getTime()) / 86400000;
+                    recencyDecay = Math.exp(-λ * ageDays);
+                }
+            }
+            catch { /* use 1.0 */ }
+            const score = α * semanticScore + β * heritageBonus + γ * recencyDecay;
+            const meta = typeof doc.metadata === 'string' ? JSON.parse(doc.metadata) : doc.metadata;
+            return { doc, score, semanticScore, heritageBonus, recencyDecay, meta };
+        });
+        reranked.sort((a, b) => b.score - a.score);
+        const results = reranked.slice(0, limit).map(({ doc, score, semanticScore, heritageBonus, recencyDecay, meta }, idx) => ({
+            id: doc.id,
+            content: doc.content,
+            metadata: meta,
+            score,
+            semanticScore,
+            heritageBonus,
+            recencyDecay,
+            rrfRank: idx + 1,
+        }));
+        // Layer 5: Synthesis (skip if LLM unavailable)
+        let synthesis;
+        let synthesized = false;
+        if (enableSynthesis && this.llmClient) {
+            try {
+                const excerpts = results.slice(0, 5).map((r, i) => `[${i + 1}] ${r.content}`).join('\n');
+                synthesis = await this.llmClient.complete(`You are a retrieval synthesis agent. Given the following memory excerpts, produce a coherent summary that directly answers the query.\nQuery: ${scrubbed}\nExcerpts:\n${excerpts}`);
+                synthesized = true;
+            }
+            catch { /* non-fatal, skip synthesis */ }
+        }
+        return {
+            results,
+            ...(synthesis !== undefined ? { synthesis } : {}),
+            pipeline: {
+                queryExpanded: enableHyDE,
+                heritageAware: hasHeritage,
+                synthesized,
+                latencyMs: Date.now() - t0,
+            },
+        };
+    }
     async getAll(options = {}) {
         await this.init();
         if (!this.client) {

package/lib/memory/memory-mesh.ts

@@ -30,6 +30,38 @@ import { LLMClient } from "../llm/client.js";
 import * as lancedb from "@lancedb/lancedb";
 import { createLogger } from "../utils/logger.js";
 const logger = createLogger("brain");
+/** RFC-0012 S-MORA types */
+export interface SMORAOptions {
+    limit?: number;
+    retrievalLimit?: number;
+    sessionIntent?: string[];
+    enableSynthesis?: boolean;
+    enableHyDE?: boolean;
+    useCache?: boolean;
+}
+
+export interface SMORAResult {
+    id: string;
+    content: string;
+    metadata: Record<string, unknown>;
+    score: number;
+    semanticScore: number;
+    heritageBonus: number;
+    recencyDecay: number;
+    rrfRank: number;
+}
+
+export interface SMORAResponse {
+    results: SMORAResult[];
+    synthesis?: string;
+    pipeline: {
+        queryExpanded: boolean;
+        heritageAware: boolean;
+        synthesized: boolean;
+        latencyMs: number;
+    };
+}
+
 /**
  * MemoryMesh class for managing vector memory storage
  */
@@ -1063,7 +1095,7 @@ description: Auto-generated skill to handle: ${enrichedPrompt || topic}
      * Note: YAMO emission is non-critical - failures are logged but don't throw
      * to prevent disrupting the main operation.
      */
-    async _emitYamoBlock(operationType, memoryId, yamoText) {
+    async _emitYamoBlock(operationType, memoryId, yamoText, heritage?: { intentChain: string[]; hypotheses: string[]; rationales: string[] }) {
         if (!this.yamoTable) {
             return;
         }
@@ -1081,6 +1113,7 @@ description: Auto-generated skill to handle: ${enrichedPrompt || topic}
                     metadata: JSON.stringify({
                         memory_id: memoryId || null,
                         timestamp: new Date().toISOString(),
+                        ...(heritage ? { heritage_chain: heritage } : {}),
                     }),
                 },
             ]);
@@ -1310,6 +1343,365 @@ description: Auto-generated skill to handle: ${enrichedPrompt || topic}
             }
             : null;
     }
+    /**
+     * Delete a memory entry by ID.
+     */
+    async delete(id: string): Promise<void> {
+        await this.init();
+        if (!this.client) {
+            throw new Error("Database client not initialized");
+        }
+        try {
+            await this.client.delete(id);
+            this.keywordSearch?.remove?.(id);
+        } catch (error: any) {
+            if (error instanceof Error && error.message.includes("not found")) return;
+            throw error;
+        }
+    }
+    /**
+     * Distill a LessonLearned block (RFC-0011 §3.5).
+     * Idempotent: same patternId + equal/higher confidence returns existing.
+     */
+    async distillLesson(context: {
+        situation: string;
+        errorPattern: string;
+        oversight: string;
+        fix: string;
+        preventativeRule: string;
+        severity?: string;
+        applicableScope: string;
+        inverseLesson?: string;
+        confidence?: number;
+    }): Promise<{
+        lessonId: string;
+        patternId: string;
+        severity: string;
+        preventativeRule: string;
+        ruleConfidence: number;
+        applicableScope: string;
+        wireFormat: string;
+        memoryId: string;
+    }> {
+        await this.init();
+        const {
+            situation, errorPattern, oversight, fix, preventativeRule,
+            severity = "medium", applicableScope, inverseLesson = "", confidence = 0.7,
+        } = context;
+        const patternId = crypto.createHash("sha256")
+            .update(errorPattern + applicableScope).digest("hex").slice(0, 16);
+        // Idempotency check
+        const existing = await this.getMemoriesByPattern(patternId);
+        if (existing.length > 0) {
+            const meta = typeof existing[0].metadata === "string"
+                ? JSON.parse(existing[0].metadata) : existing[0].metadata;
+            if ((meta.rule_confidence ?? 0) >= confidence) {
+                return {
+                    lessonId: meta.lesson_id, patternId, severity: meta.severity || severity,
+                    preventativeRule: meta.preventative_rule || preventativeRule,
+                    ruleConfidence: meta.rule_confidence, applicableScope: meta.applicable_scope || applicableScope,
+                    wireFormat: meta.yamo_wire_format || "", memoryId: existing[0].id,
+                };
+            }
+        }
+        const lessonId = `lesson_${Date.now()}_${crypto.randomBytes(3).toString("hex")}`;
+        const timestamp = new Date().toISOString();
+        const wireFormat = [
+            `agent: MemoryMesh_${this.agentId};`,
+            `intent: distill_wisdom_from_execution;`,
+            `context:`,
+            `  original_context;${situation.replace(/;/g, ",")};`,
+            `  error_pattern;${patternId};`,
+            `  severity;${severity};`,
+            `  timestamp;${timestamp};`,
+            `constraints:`,
+            `  hypothesis;This lesson prevents recurrence of similar failures;`,
+            `  hypothesis_confidence;${confidence};`,
+            `priority: high;`,
+            `output:`,
+            `  lesson_id;${lessonId};`,
+            `  oversight_description;${oversight.replace(/;/g, ",")};`,
+            `  preventative_rule;${preventativeRule.replace(/;/g, ",")};`,
+            `  rule_confidence;${confidence};`,
+            `meta:`,
+            `  rationale;${fix.replace(/;/g, ",")};`,
+            `  applicability_scope;${applicableScope.replace(/;/g, ",")};`,
+            `  inverse_lesson;${inverseLesson.replace(/;/g, ",")};`,
+            `  confidence;${confidence};`,
+            `log: lesson_learned;timestamp;${timestamp};pattern;${patternId};severity;${severity};id;${lessonId};`,
+            `handoff: SubconsciousReflector;`,
+        ].join("\n");
+        const lessonContent = `[LESSON:${patternId}] ${oversight} | Rule: ${preventativeRule} | Scope: ${applicableScope}`;
+        const lessonMetadata = {
+            type: "lesson", tags: ["#lesson_learned"], lesson_id: lessonId,
+            lesson_pattern_id: patternId, severity, oversight, preventative_rule: preventativeRule,
+            rule_confidence: confidence, applicable_scope: applicableScope, inverse_lesson: inverseLesson,
+            yamo_wire_format: wireFormat, source: "distillLesson",
+        };
+        const mem = await this.add(lessonContent, lessonMetadata);
+        if (this.enableYamo) {
+            this._emitYamoBlock("lesson", mem.id, wireFormat).catch(() => {});
+        }
+        return { lessonId, patternId, severity, preventativeRule, ruleConfidence: confidence, applicableScope, wireFormat, memoryId: mem.id };
+    }
+    /**
+     * Query lessons from memory (RFC-0011 §4.1).
+     */
+    async queryLessons(query = "", options: { limit?: number } = {}): Promise<any[]> {
+        await this.init();
+        const limit = options.limit || 10;
+        const all = await this.getAll({ limit: 1000 });
+        const lessons = all.filter((r: any) => {
+            try {
+                const meta = typeof r.metadata === "string" ? JSON.parse(r.metadata) : r.metadata;
+                return meta.type === "lesson" || (Array.isArray(meta.tags) && meta.tags.includes("#lesson_learned"));
+            } catch { return false; }
+        });
+        let scored = lessons as any[];
+        if (query) {
+            const q = query.toLowerCase();
+            scored = lessons.map((r: any) => ({
+                ...r,
+                _score: (r.content?.toLowerCase().includes(q) ? 2 : 0) +
+                    (JSON.stringify(r.metadata).toLowerCase().includes(q) ? 1 : 0),
+            })).sort((a: any, b: any) => b._score - a._score);
+        }
+        return scored.slice(0, limit).map((r: any) => {
+            const meta = typeof r.metadata === "string" ? JSON.parse(r.metadata) : r.metadata;
+            return {
+                lessonId: meta.lesson_id || r.id, patternId: meta.lesson_pattern_id || "",
+                severity: meta.severity || "medium", preventativeRule: meta.preventative_rule || "",
+                ruleConfidence: meta.rule_confidence ?? 0, applicableScope: meta.applicable_scope || "",
+                wireFormat: meta.yamo_wire_format || "", memoryId: r.id,
+            };
+        });
+    }
+    /**
+     * Update a memory entry's heritage_chain (RFC-0011 §8).
+     */
+    async insertHeritage(memoryId: string, heritage: { intentChain: string[]; hypotheses: string[]; rationales: string[] }): Promise<void> {
+        await this.init();
+        if (!this.client) throw new Error("Database client not initialized");
+        try {
+            const record = await this.client.getById(memoryId);
+            if (!record) return;
+            const existingMeta = typeof record.metadata === "string"
+                ? JSON.parse(record.metadata) : (record.metadata || {});
+            await this.client.update(memoryId, {
+                metadata: JSON.stringify({ ...existingMeta, heritage_chain: JSON.stringify(heritage) }),
+            });
+            // Emit RFC-0007 §5 heritage block
+            if (this.enableYamo) {
+                const ts = new Date().toISOString();
+                const heritageBlock = [
+                    `agent: MemoryMesh_${this.agentId};`,
+                    `intent: record_heritage_chain;`,
+                    `context:`,
+                    `  memory_id;${memoryId};`,
+                    `  intent_chain;${heritage.intentChain.join(",")};`,
+                    `  timestamp;${ts};`,
+                    `output:`,
+                    `  heritage_recorded;true;`,
+                    `log: heritage_inserted;memory;${memoryId};timestamp;${ts};`,
+                    `handoff: End;`,
+                ].join("\n");
+                this._emitYamoBlock("heritage", memoryId, heritageBlock, heritage).catch(() => {});
+            }
+        } catch (error: any) {
+            if (error instanceof Error && error.message.includes("not found")) return;
+            throw error;
+        }
+    }
+    /**
+     * Return all memories whose lesson_pattern_id matches patternId (RFC-0011 §4.1).
+     */
+    async getMemoriesByPattern(patternId: string): Promise<any[]> {
+        await this.init();
+        const all = await this.getAll({ limit: 1000 });
+        return (all as any[]).filter((r) => {
+            try {
+                const meta = typeof r.metadata === "string" ? JSON.parse(r.metadata) : r.metadata;
+                return meta.lesson_pattern_id === patternId;
+            } catch { return false; }
+        });
+    }
+
+    /**
+     * S-MORA: Singularity Memory-Oriented Retrieval Augmentation (RFC-0012)
+     * 5-layer pipeline: Scrubbing → HyDE-Lite → Multi-channel retrieval → RRF → Heritage-aware reranking
+     */
+    async smora(query: string, options: {
+        limit?: number;
+        retrievalLimit?: number;
+        sessionIntent?: string[];
+        enableSynthesis?: boolean;
+        enableHyDE?: boolean;
+        useCache?: boolean;
+    } = {}): Promise<{
+        results: Array<{
+            id: string;
+            content: string;
+            metadata: Record<string, unknown>;
+            score: number;
+            semanticScore: number;
+            heritageBonus: number;
+            recencyDecay: number;
+            rrfRank: number;
+        }>;
+        synthesis?: string;
+        pipeline: {
+            queryExpanded: boolean;
+            heritageAware: boolean;
+            synthesized: boolean;
+            latencyMs: number;
+        };
+    }> {
+        await this.init();
+        const t0 = Date.now();
+        const {
+            limit = 10,
+            retrievalLimit = 30,
+            sessionIntent = [],
+            enableSynthesis = false,
+            enableHyDE = true,
+        } = options;
+
+        // Layer 0: scrub query
+        let scrubbed = query;
+        try {
+            if (this.scrubber) {
+                const s = await this.scrubber.process({ content: query });
+                scrubbed = s.content || query;
+            }
+        } catch { /* non-fatal */ }
+
+        if (!this.client) {
+            return { results: [], pipeline: { queryExpanded: false, heritageAware: false, synthesized: false, latencyMs: Date.now() - t0 } };
+        }
+
+        // Layer 1: HyDE-Lite — template-based query expansion (no LLM required)
+        let hydeQuery: string | null = null;
+        if (enableHyDE) {
+            hydeQuery = `A document about ${scrubbed}. This covers concepts related to ${scrubbed} including patterns, insights, and lessons learned.`;
+        }
+
+        // Layer 2: Multi-channel retrieval (semantic original, semantic HyDE, keyword BM25)
+        const queryVec = await this.embeddingFactory.embed(scrubbed);
+        const hydeVec = hydeQuery ? await this.embeddingFactory.embed(hydeQuery) : null;
+
+        const [semanticOrig, semanticHyde, keywordResults] = await Promise.all([
+            this.client.search(queryVec, { limit: retrievalLimit, metric: 'cosine' }),
+            hydeVec ? this.client.search(hydeVec, { limit: retrievalLimit, metric: 'cosine' }) : Promise.resolve([]),
+            Promise.resolve(this.keywordSearch.search(scrubbed, { limit: retrievalLimit })),
+        ]);
+
+        // Layer 3: Reciprocal Rank Fusion (k=60, channel weights: 1.0 / 0.8 / 0.6)
+        const k = 60;
+        const weights = { orig: 1.0, hyde: 0.8, keyword: 0.6 };
+        const rrfScores = new Map<string, number>();
+        const docMap = new Map<string, any>();
+
+        function applyRRF(list: any[], weight: number) {
+            for (let rank = 0; rank < list.length; rank++) {
+                const doc = list[rank];
+                if (!doc?.id) continue;
+                rrfScores.set(doc.id, (rrfScores.get(doc.id) || 0) + weight / (k + rank + 1));
+                if (!docMap.has(doc.id)) docMap.set(doc.id, doc);
+            }
+        }
+        applyRRF(semanticOrig, weights.orig);
+        applyRRF(semanticHyde, weights.hyde);
+        applyRRF(keywordResults.map((r: any) => ({ id: r.id, content: r.content, metadata: r.metadata, created_at: r.created_at || new Date().toISOString() })), weights.keyword);
+
+        // Take top pre_rerank_limit candidates
+        const preRerankLimit = 20;
+        const candidates = Array.from(rrfScores.entries())
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, preRerankLimit)
+            .map(([id]) => docMap.get(id))
+            .filter(Boolean);
+
+        // Layer 4: Heritage-aware reranking
+        // final_score = 0.6×semantic_sim + 0.25×heritage_bonus + 0.15×recency_decay
+        // When no sessionIntent: weights renormalize → α=0.71, γ=0.29
+        const hasHeritage = sessionIntent.length > 0;
+        const α = hasHeritage ? 0.6 : 0.71;
+        const β = hasHeritage ? 0.25 : 0.0;
+        const γ = hasHeritage ? 0.15 : 0.29;
+        const λ = 0.05; // recency decay rate (half-life ≈ 14 days)
+        const now = Date.now();
+
+        const reranked = candidates.map((doc: any) => {
+            // Semantic score: normalize rrfScore to [0,1] approximation
+            const rrfScore = rrfScores.get(doc.id) || 0;
+            const semanticScore = Math.min(1.0, rrfScore * 20); // scale to ~[0,1]
+
+            // Heritage bonus
+            let heritageBonus = 0;
+            if (hasHeritage) {
+                try {
+                    const meta = typeof doc.metadata === 'string' ? JSON.parse(doc.metadata) : doc.metadata;
+                    const chain = meta?.heritage_chain;
+                    const parsedChain = typeof chain === 'string' ? JSON.parse(chain) : chain;
+                    const intentChain: string[] = parsedChain?.intentChain ?? [];
+                    const overlap = intentChain.filter((i: string) => sessionIntent.includes(i)).length;
+                    if (overlap > 0) heritageBonus = Math.min(1.0, overlap / sessionIntent.length);
+                } catch { /* no heritage */ }
+            }
+
+            // Recency decay: exp(-λ × age_days)
+            let recencyDecay = 1.0;
+            try {
+                const createdAt = doc.created_at || doc.metadata?.created_at;
+                if (createdAt) {
+                    const ageDays = (now - new Date(createdAt).getTime()) / 86400000;
+                    recencyDecay = Math.exp(-λ * ageDays);
+                }
+            } catch { /* use 1.0 */ }
+
+            const score = α * semanticScore + β * heritageBonus + γ * recencyDecay;
+            const meta = typeof doc.metadata === 'string' ? JSON.parse(doc.metadata) : doc.metadata;
+            return { doc, score, semanticScore, heritageBonus, recencyDecay, meta };
+        });
+
+        reranked.sort((a, b) => b.score - a.score);
+
+        const results = reranked.slice(0, limit).map(({ doc, score, semanticScore, heritageBonus, recencyDecay, meta }, idx) => ({
+            id: doc.id,
+            content: doc.content,
+            metadata: meta,
+            score,
+            semanticScore,
+            heritageBonus,
+            recencyDecay,
+            rrfRank: idx + 1,
+        }));
+
+        // Layer 5: Synthesis (skip if LLM unavailable)
+        let synthesis: string | undefined;
+        let synthesized = false;
+        if (enableSynthesis && this.llmClient) {
+            try {
+                const excerpts = results.slice(0, 5).map((r, i) => `[${i + 1}] ${r.content}`).join('\n');
+                synthesis = await this.llmClient.complete(
+                    `You are a retrieval synthesis agent. Given the following memory excerpts, produce a coherent summary that directly answers the query.\nQuery: ${scrubbed}\nExcerpts:\n${excerpts}`
+                );
+                synthesized = true;
+            } catch { /* non-fatal, skip synthesis */ }
+        }
+
+        return {
+            results,
+            ...(synthesis !== undefined ? { synthesis } : {}),
+            pipeline: {
+                queryExpanded: enableHyDE,
+                heritageAware: hasHeritage,
+                synthesized,
+                latencyMs: Date.now() - t0,
+            },
+        };
+    }
+
     async getAll(options = {}) {
         await this.init();
         if (!this.client) {

package/package.json

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