@memberjunction/ai-agents 5.29.0 → 5.30.0

package/dist/memory-manager-agent.js

@@ -4,6 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
+var MemoryManagerAgent_1;
 import { BaseAgent } from './base-agent.js';
 import { RegisterClass, CleanAndParseJSON } from '@memberjunction/global';
 import { Metadata, RunView, RunQuery, LogError, LogStatus } from '@memberjunction/core';
@@ -35,16 +36,93 @@ const CONSOLIDATION_CONFIG = {
      * - 'daily': Run once per day
      * - number: Run every N executions (e.g., 4 = every 4th run)
      */
-    frequency: 'disabled',
+    frequency: 'daily',
     minClusterSize: 3, // Minimum notes in a cluster to trigger consolidation
-    similarityThreshold: 0.60 // Semantic similarity threshold — 60% captures topically related notes while excluding dissimilar ones
+    maxClusterSize: 7, // Maximum cluster size (Miller's 7±2) — split larger clusters
+    similarityThreshold: 0.60, // Semantic similarity threshold — 60% captures topically related notes
+    maxConsolidationCount: 3, // Cap re-summarization depth to prevent drift (research: 25.5% semantic loss after 5 iterations)
+    noteCountTrigger: 100 // Event-driven trigger: consolidate when an agent accumulates this many new notes since last run
 };
+/**
+ * Configuration for contradiction detection.
+ * Finds semantically similar note pairs and evaluates whether they contain conflicting facts.
+ */
+const CONTRADICTION_CONFIG = {
+    similarityThreshold: 0.70, // Higher than consolidation — targets same-topic pairs
+    maxPairsPerRun: 50, // Limit LLM calls per cycle
+    highImportanceThreshold: 7.0 // Notes above this get importance-weighted protection (both preserved with flag)
+};
+/**
+ * Configuration for composite importance scoring.
+ * 7-signal formula replacing raw AccessCount for authority, retention, and consolidation decisions.
+ * Based on Park et al.'s Generative Agents (2023) and neuroscience research on memory importance.
+ */
+const IMPORTANCE_CONFIG = {
+    weights: {
+        recencyDecay: 0.20, // Exponential decay: 0.995^hours
+        llmImportance: 0.25, // Confidence from extraction prompt
+        relevance: 0.15, // Cosine similarity to recent conversation inputs
+        uniqueness: 0.15, // Min distance to nearest neighbor (rarity signal)
+        correctionBoost: 0.10, // Notes that corrected/superseded existing notes
+        goalAlignment: 0.10, // Alignment with agent goals (Phase 2 enrichment, 0.5 default)
+        userMark: 0.05 // Manual creation flag (IsAutoGenerated=false)
+    },
+    correctionBonusPoints: 1.5, // Flat additive bonus for correction-provenance notes
+    autoPromoteThreshold: 8.0, // Auto-promote Standard notes to Protected above this score
+};
+/**
+ * Configuration for Ebbinghaus-inspired decay function.
+ * Replaces fixed 90/180-day retention windows with continuous importance-weighted decay.
+ * Formula: strength = normalizedImportance * e^(-lambdaEff * daysSinceAccess) * (1 + accessCount * accessBoostFactor)
+ * where lambdaEff = baseLambda * (1 - normalizedImportance * importanceDampening)
+ */
+const DECAY_CONFIG = {
+    baseLambda: 0.16, // Base decay rate (Ebbinghaus-derived)
+    importanceDampening: 0.8, // How much high importance slows decay (0-1)
+    accessBoostFactor: 0.2, // Each access adds 20% to retention strength
+    accessRetentionCap: 1.5, // Hard cap on the access-retention multiplier to prevent frequently-accessed notes from becoming immortal
+    protectedInactivityDays: 365, // Protected tier extended retention before archival
+    ephemeralDecayMultiplier: 2.0, // Ephemeral tier decays 2x faster
+    archivalFloor: 0.5, // Score below this after proportional decay → archive (multiple cycles to reach)
+};
+/**
+ * Configuration for stale reference pruning.
+ * Caps how many orphaned notes the pruning phase will archive per cycle to keep
+ * Memory Manager runtime bounded even on large corpora.
+ */
+const STALE_PRUNING_CONFIG = {
+    maxNotesPerRun: 200,
+};
+/**
+ * Minimum number of scored notes required to compute a 95th-percentile uniqueness
+ * threshold. Below this the percentile is meaningless (a 5-note cohort has a p95
+ * at index 4 which is just "the max"), so outlier auto-protection is disabled.
+ */
+const OUTLIER_PROMOTION_MIN_COHORT = 20;
+/**
+ * Valid Type values for MJAIAgentNote records. Must match the typed union in the
+ * generated entity class (MJCoreEntities/src/generated/entity_subclasses.ts).
+ * Used to validate LLM-returned values before assigning to entity properties.
+ */
+const VALID_NOTE_TYPES = ['Constraint', 'Context', 'Example', 'Issue', 'Preference'];
+function isValidNoteType(value) {
+    return typeof value === 'string' && VALID_NOTE_TYPES.includes(value);
+}
+/** Reusable parameter object for deterministic (temperature=0) LLM prompt calls. */
+const DETERMINISTIC_PROMPT_PARAMS = { temperature: 0 };
+/**
+ * Hard cap on `resolveOriginalSources()` recursion depth.
+ * The `visited` set already prevents cycles, but a depth limit protects against
+ * runaway recursion if `DerivedFromNoteIDs` chains are corrupted in a way that
+ * passes the visited check (e.g., extremely deep legitimate chains from a bug).
+ */
+const MAX_SOURCE_RESOLUTION_DEPTH = 10;
 /**
  * Memory Manager Agent - automatically extracts notes and examples from conversations.
  * This agent runs on a schedule (every 15 minutes) and analyzes high-quality conversations
  * and agent runs to extract learnings and example interactions.
  */
-let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
+let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends BaseAgent {
     constructor() {
         super(...arguments);
         /** Verbose logging flag from params.verbose */
@@ -56,6 +134,12 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
         /** Context user for step operations */
         this._contextUser = null;
     }
+    /** Check if a string is a valid UUID format. Filters out LLM-generated placeholders like "user-uuid-here". */
+    static isValidUUID(id) {
+        if (!id)
+            return false;
+        return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id);
+    }
     /**
      * Create an agent run step record for observability.
      * Returns null if agentRunID is not set (defensive check).
@@ -312,33 +396,67 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
         return this.executeNoteExtraction(promptData, existingNotes, contextUser);
     }
     /**
-     * Common extraction logic for note extraction.
-     * Applies sparsity controls and deduplication.
+     * Common extraction logic for note extraction. Thin orchestrator that coordinates:
+     *   (1) running the extraction prompt,
+     *   (2) normalizing merge-field shape from the LLM,
+     *   (3) applying confidence/length filters,
+     *   (4) enforcing per-message/per-conversation sparsity caps,
+     *   (5) collapsing duplicate merge candidates,
+     *   (6) deduplicating against existing notes,
+     *   (7) enriching with conversation context (userId, agentRunId).
+     *
+     * Each step is its own private helper so the pipeline can be read top-to-bottom.
      */
     async executeNoteExtraction(promptData, existingNotes, contextUser) {
-        const conversationThreads = promptData.conversationThreads;
-        // Find extraction prompt
-        const prompt = AIEngine.Instance.Prompts.find(p => p.Name === 'Memory Manager - Extract Notes' && p.Category === 'MJ: System');
-        if (!prompt) {
-            LogError('Memory Manager note extraction prompt not found');
-            if (this._verbose) {
-                LogStatus(`Memory Manager: Available prompts in MJ: System category: ${AIEngine.Instance.Prompts.filter(p => p.Category === 'MJ: System').map(p => p.Name).join(', ')}`);
-            }
+        // Step 1: run the extraction prompt and parse out the raw notes
+        const rawNotes = await this.runNoteExtractionPrompt(promptData, existingNotes.length, contextUser);
+        if (!rawNotes)
             return [];
-        }
+        // Step 2: normalize the LLM's legacy singular mergeWithExistingId → plural mergeWithExistingIds
+        this.normalizeMergeCandidates(rawNotes);
         if (this._verbose) {
-            LogStatus(`Memory Manager: Found extraction prompt "${prompt.Name}" (ID: ${prompt.ID})`);
-            LogStatus(`Memory Manager: Sending ${conversationThreads.length} conversation threads with ${conversationThreads.reduce((sum, t) => sum + t.messages.length, 0)} total messages for note extraction`);
-            if (conversationThreads.length > 0) {
-                const firstThread = conversationThreads[0];
-                LogStatus(`Memory Manager: Sample thread (conv ${firstThread.conversationId}): ${firstThread.messages.map(m => `[${m.role}] ${m.message?.substring(0, 80)}...`).join(' | ')}`);
+            LogStatus(`Memory Manager: LLM returned ${rawNotes.length} raw notes before filtering`);
+            for (const note of rawNotes) {
+                LogStatus(`Memory Manager: Raw note: [${note.type}] "${note.content}" (confidence: ${note.confidence})${note.mergeWithExistingIds?.length ? ` mergeWith: ${note.mergeWithExistingIds.join(', ')}` : ''}`);
             }
         }
-        // Step 3: Execute AI extraction
-        const step3 = await this.CreateRunStep('Prompt', 'Extract Notes from Conversations', {
+        // Step 3: filter by confidence and content length
+        const candidateNotes = this.filterByConfidenceAndLength(rawNotes);
+        if (candidateNotes.length === 0) {
+            if (this._verbose)
+                LogStatus('Memory Manager: No candidates passed confidence/length thresholds');
+            return [];
+        }
+        // Step 4: apply per-message and per-conversation sparsity caps
+        const sparseCandidates = this.applySparsityLimits(candidateNotes);
+        // Step 5: collapse merge candidates with identical content
+        const collapsedCandidates = this.collapseMergeCandidates(sparseCandidates);
+        if (this._verbose && collapsedCandidates.length < sparseCandidates.length) {
+            LogStatus(`Memory Manager: Collapsed ${sparseCandidates.length} candidates to ${collapsedCandidates.length} after merging duplicate merge targets`);
+        }
+        // Step 6: deduplicate against existing notes (creates and finalizes Step 4 run step)
+        const approvedNotes = await this.deduplicateCandidates(collapsedCandidates, existingNotes, contextUser);
+        if (this._verbose)
+            LogStatus(`Memory Manager: Final approved notes: ${approvedNotes.length}`);
+        // Step 7: enrich with conversation context (userId, agentRunId)
+        this.enrichWithConversationContext(approvedNotes, promptData.conversationThreads);
+        return approvedNotes;
+    }
+    /**
+     * Execute the extraction prompt, wrap it in an observability run step, and
+     * parse the raw result into a typed array. Returns null on any failure so the
+     * caller short-circuits cleanly.
+     */
+    async runNoteExtractionPrompt(promptData, existingNoteCount, contextUser) {
+        const prompt = this.findNoteExtractionPrompt();
+        if (!prompt)
+            return null;
+        const conversationThreads = promptData.conversationThreads;
+        this.logExtractionPromptContext(prompt, conversationThreads);
+        const step = await this.CreateRunStep('Prompt', 'Extract Notes from Conversations', {
             conversationCount: conversationThreads.length,
             messageCount: conversationThreads.reduce((sum, t) => sum + t.messages.length, 0),
-            existingNoteCount: existingNotes.length
+            existingNoteCount
         }, prompt.ID);
         const runner = new AIPromptRunner();
         const params = new AIPromptParams();
@@ -346,93 +464,111 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
         params.data = promptData;
         params.contextUser = contextUser;
         params.attemptJSONRepair = true;
+        params.additionalParameters = DETERMINISTIC_PROMPT_PARAMS;
         const result = await runner.ExecutePrompt(params);
-        // Finalize Step 3 after extraction
-        await this.FinalizeRunStep(step3, result.success, {
+        await this.FinalizeRunStep(step, result.success, {
             success: result.success,
             rawNoteCount: result.result && typeof result.result !== 'string' ? (result.result.notes?.length || 0) : 0
         }, result.promptRun?.ID, result.errorMessage || undefined);
+        return this.parseNoteExtractionResult(result);
+    }
+    /** Look up the extraction prompt, logging available prompts on miss. */
+    findNoteExtractionPrompt() {
+        const prompt = AIEngine.Instance.Prompts.find(p => p.Name === 'Memory Manager - Extract Notes' && p.Category === 'MJ: System');
+        if (!prompt) {
+            LogError('Memory Manager note extraction prompt not found');
+            if (this._verbose) {
+                LogStatus(`Memory Manager: Available prompts in MJ: System category: ${AIEngine.Instance.Prompts.filter(p => p.Category === 'MJ: System').map(p => p.Name).join(', ')}`);
+            }
+        }
+        return prompt;
+    }
+    /** Verbose-only logging block for extraction prompt context. */
+    logExtractionPromptContext(prompt, conversationThreads) {
+        if (!this._verbose)
+            return;
+        LogStatus(`Memory Manager: Found extraction prompt "${prompt.Name}" (ID: ${prompt.ID})`);
+        LogStatus(`Memory Manager: Sending ${conversationThreads.length} conversation threads with ${conversationThreads.reduce((sum, t) => sum + t.messages.length, 0)} total messages for note extraction`);
+        if (conversationThreads.length > 0) {
+            const firstThread = conversationThreads[0];
+            LogStatus(`Memory Manager: Sample thread (conv ${firstThread.conversationId}): ${firstThread.messages.map(m => `[${m.role}] ${m.message?.substring(0, 80)}...`).join(' | ')}`);
+        }
+    }
+    /**
+     * Parse an extraction prompt result into an ExtractedNote array, tolerating JSON-fenced
+     * strings from models like Gemini. Returns null on failure.
+     */
+    parseNoteExtractionResult(result) {
         if (this._verbose) {
             LogStatus(`Memory Manager: Extraction prompt result - success: ${result.success}, hasResult: ${!!result.result}`);
-            if (result.errorMessage) {
+            if (result.errorMessage)
                 LogStatus(`Memory Manager: Extraction error: ${result.errorMessage}`);
-            }
-            if (result.result) {
+            if (result.result)
                 LogStatus(`Memory Manager: Raw extraction result: ${JSON.stringify(result.result)}`);
-            }
         }
         if (!result.success || !result.result) {
             LogError('Failed to extract notes:', result.errorMessage);
-            return [];
+            return null;
         }
-        // Parse result if it's a string (AI sometimes returns JSON as string)
-        // Some models (e.g., Gemini) wrap JSON in ```json fences
-        let parsedResult;
         if (typeof result.result === 'string') {
-            const parsed = CleanAndParseJSON(result.result, true);
-            if (!parsed) {
+            const reparsed = CleanAndParseJSON(result.result, true);
+            if (!reparsed) {
                 LogError('Failed to parse extraction result as JSON');
-                return [];
+                return null;
             }
-            parsedResult = parsed;
             if (this._verbose) {
-                LogStatus(`Memory Manager: Parsed string result into object with ${parsedResult.notes?.length || 0} notes`);
-            }
-        }
-        else {
-            parsedResult = result.result;
-        }
-        // Normalize singular mergeWithExistingId → plural mergeWithExistingIds
-        // The LLM still outputs the singular field; we convert it here.
-        // Notes are plain objects from JSON.parse, so the runtime cast is safe.
-        if (parsedResult.notes) {
-            for (const note of parsedResult.notes) {
-                if (note.mergeWithExistingId && !note.mergeWithExistingIds) {
-                    note.mergeWithExistingIds = [note.mergeWithExistingId];
-                }
+                LogStatus(`Memory Manager: Parsed string result into object with ${reparsed.notes?.length || 0} notes`);
             }
+            return reparsed.notes || [];
         }
-        // Log raw notes before filtering (for debugging)
-        if (this._verbose && parsedResult.notes) {
-            LogStatus(`Memory Manager: LLM returned ${parsedResult.notes.length} raw notes before filtering`);
-            for (const note of parsedResult.notes) {
-                LogStatus(`Memory Manager: Raw note: [${note.type}] "${note.content}" (confidence: ${note.confidence})${note.mergeWithExistingIds?.length ? ` mergeWith: ${note.mergeWithExistingIds.join(', ')}` : ''}`);
+        return result.result.notes || [];
+    }
+    /**
+     * Normalize the legacy singular `mergeWithExistingId` field into the plural
+     * `mergeWithExistingIds` array. The extraction prompt still emits the singular
+     * field in some paths; downstream code only reads the plural form.
+     */
+    normalizeMergeCandidates(notes) {
+        for (const note of notes) {
+            if (note.mergeWithExistingId && !note.mergeWithExistingIds) {
+                note.mergeWithExistingIds = [note.mergeWithExistingId];
             }
         }
-        // Filter by confidence threshold (use EXTRACTION_CONFIG)
-        const candidateNotes = (parsedResult.notes || []).filter(n => n.confidence >= EXTRACTION_CONFIG.minConfidenceThreshold &&
+    }
+    /**
+     * Filter raw extracted notes against the confidence and content-length thresholds
+     * from EXTRACTION_CONFIG. Notes below either threshold are silently dropped.
+     */
+    filterByConfidenceAndLength(notes) {
+        const filtered = notes.filter(n => n.confidence >= EXTRACTION_CONFIG.minConfidenceThreshold &&
             n.content && n.content.length >= EXTRACTION_CONFIG.minContentLength);
-        if (candidateNotes.length === 0) {
-            if (this._verbose) {
-                LogStatus('Memory Manager: No candidates passed confidence/length thresholds');
-            }
-            return [];
-        }
-        if (this._verbose) {
-            LogStatus(`Memory Manager: ${candidateNotes.length} candidates passed confidence threshold (>=${EXTRACTION_CONFIG.minConfidenceThreshold})`);
-            // Log each extracted note for debugging
-            for (const note of candidateNotes) {
+        if (this._verbose && filtered.length > 0) {
+            LogStatus(`Memory Manager: ${filtered.length} candidates passed confidence threshold (>=${EXTRACTION_CONFIG.minConfidenceThreshold})`);
+            for (const note of filtered) {
                 LogStatus(`Memory Manager: Extracted note: [${note.type}] "${note.content}" (confidence: ${note.confidence})`);
             }
         }
-        // Apply sparsity: limit notes per message AND per conversation
+        return filtered;
+    }
+    /**
+     * Enforce per-message and per-conversation note caps from EXTRACTION_CONFIG.
+     * Drops any candidates that would exceed either cap.
+     */
+    applySparsityLimits(candidates) {
         const notesByMessage = new Map();
         const noteCountByConversation = new Map();
-        for (const note of candidateNotes) {
+        for (const note of candidates) {
             const msgId = note.sourceConversationDetailId || 'unknown';
             const convId = note.sourceConversationId || 'unknown';
             const existingForMsg = notesByMessage.get(msgId) || [];
             const convCount = noteCountByConversation.get(convId) || 0;
-            // Check both per-message and per-conversation limits
             if (existingForMsg.length >= EXTRACTION_CONFIG.maxNotesPerMessage) {
-                if (this._verbose) {
+                if (this._verbose)
                     LogStatus(`Memory Manager: Skipping note (max ${EXTRACTION_CONFIG.maxNotesPerMessage} per message reached)`);
-                }
             }
             else if (convCount >= EXTRACTION_CONFIG.maxNotesPerConversation) {
-                if (this._verbose) {
+                if (this._verbose)
                     LogStatus(`Memory Manager: Skipping note (max ${EXTRACTION_CONFIG.maxNotesPerConversation} per conversation reached)`);
-                }
             }
             else {
                 existingForMsg.push(note);
@@ -440,110 +576,123 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
                 noteCountByConversation.set(convId, convCount + 1);
             }
         }
-        const sparseCandidates = Array.from(notesByMessage.values()).flat();
-        if (this._verbose) {
-            LogStatus(`Memory Manager: ${sparseCandidates.length} candidates after sparsity filter`);
-        }
-        // Collapse merge candidates with identical content into single candidates
-        const collapsedCandidates = this.collapseMergeCandidates(sparseCandidates);
-        if (this._verbose && collapsedCandidates.length < sparseCandidates.length) {
-            LogStatus(`Memory Manager: Collapsed ${sparseCandidates.length} candidates to ${collapsedCandidates.length} after merging duplicate merge targets`);
-        }
-        // Step 4: Apply deduplication (summary step)
-        const step4 = await this.CreateRunStep('Decision', 'Deduplicate Note Candidates', {
-            candidateCount: collapsedCandidates.length,
+        const sparse = Array.from(notesByMessage.values()).flat();
+        if (this._verbose)
+            LogStatus(`Memory Manager: ${sparse.length} candidates after sparsity filter`);
+        return sparse;
+    }
+    /**
+     * Deduplicate candidate notes against existing notes in the database using:
+     *   1. Exact text match (fast reject),
+     *   2. Semantic similarity lookup (top-N with ≥85% threshold),
+     *   3. Dedup prompt to resolve genuinely-similar candidates.
+     *
+     * Candidates flagged as merge/replacement by the extraction LLM are auto-approved
+     * (dedup would reject them as "too similar" to the note they are intentionally
+     * replacing). Creates and finalizes its own observability run step.
+     */
+    async deduplicateCandidates(candidates, existingNotes, contextUser) {
+        const step = await this.CreateRunStep('Decision', 'Deduplicate Note Candidates', {
+            candidateCount: candidates.length,
             existingNoteCount: existingNotes.length
         });
-        const approvedNotes = [];
-        let dedupeRejectedCount = 0;
-        let dedupeLlmCallCount = 0;
-        // Find deduplication prompt
+        const approved = [];
+        const stats = { rejectedCount: 0, llmCallCount: 0 };
+        const runner = new AIPromptRunner();
         const dedupePrompt = AIEngine.Instance.Prompts.find(p => p.Name === 'Memory Manager - Deduplicate Note' && p.Category === 'MJ: System');
-        for (const candidate of collapsedCandidates) {
-            // Check global max notes per run
-            if (approvedNotes.length >= EXTRACTION_CONFIG.maxNotesPerRun) {
-                if (this._verbose) {
+        for (const candidate of candidates) {
+            if (approved.length >= EXTRACTION_CONFIG.maxNotesPerRun) {
+                if (this._verbose)
                     LogStatus(`Memory Manager: Stopping - max notes per run (${EXTRACTION_CONFIG.maxNotesPerRun}) reached`);
-                }
                 break;
             }
-            // Notes with mergeWithExistingIds are intentional replacements —
-            // the extraction LLM already determined this is a contradiction.
-            // Dedup would reject them as "too similar" to the note they're replacing.
-            if (candidate.mergeWithExistingIds?.length) {
-                approvedNotes.push(candidate);
-                if (this._verbose) {
-                    LogStatus(`Memory Manager: Auto-approved merge note targeting ${candidate.mergeWithExistingIds.join(', ')}: "${candidate.content.substring(0, 50)}..."`);
-                }
-                continue;
-            }
-            // Step 1: Check for exact content match FIRST (case-insensitive, trimmed)
-            const normalizedContent = candidate.content.toLowerCase().trim();
-            const exactMatch = existingNotes.find(n => n.Note && n.Note.toLowerCase().trim() === normalizedContent);
-            if (exactMatch) {
-                dedupeRejectedCount++;
-                if (this._verbose) {
-                    LogStatus(`Memory Manager: Skipping exact duplicate: "${candidate.content.substring(0, 50)}..."`);
-                }
-                continue;
-            }
-            // Step 2: Find similar existing notes using semantic search with tighter threshold.
-            // Cross-user dedup for org/global notes works naturally because those notes have
-            // UserID=null, so FindSimilarAgentNotes won't filter them out for any user.
-            const similarNotes = await AIEngine.Instance.FindSimilarAgentNotes(candidate.content, candidate.agentId, candidate.userId, candidate.companyId, 10, // Top 10 similar (increased from 5)
-            0.85 // 85% similarity threshold (increased from 70%)
-            );
-            // Step 3: If deduplication prompt exists and similar notes found, ask LLM
-            if (dedupePrompt && similarNotes.length > 0) {
-                const dedupeParams = new AIPromptParams();
-                dedupeParams.prompt = dedupePrompt;
-                dedupeParams.data = {
-                    candidateNote: candidate,
-                    similarNotes: similarNotes.map(s => ({
-                        type: s.note.Type,
-                        content: s.note.Note,
-                        agentId: s.note.AgentID,
-                        userId: s.note.UserID,
-                        companyId: s.note.CompanyID,
-                        similarity: s.similarity
-                    }))
-                };
-                dedupeParams.contextUser = contextUser;
-                dedupeParams.attemptJSONRepair = true;
-                const dedupeResult = await runner.ExecutePrompt(dedupeParams);
-                dedupeLlmCallCount++;
-                if (dedupeResult.success && dedupeResult.result && dedupeResult.result.shouldAdd) {
-                    approvedNotes.push(candidate);
-                    if (this._verbose) {
-                        LogStatus(`Memory Manager: Approved note - ${dedupeResult.result.reason}`);
-                    }
-                }
-                else {
-                    dedupeRejectedCount++;
-                    if (this._verbose) {
-                        LogStatus(`Memory Manager: Skipped duplicate note - ${dedupeResult.result?.reason || 'too similar to existing notes'}`);
-                    }
-                }
-            }
-            else {
-                // No similar notes found or no deduplication prompt, add the note
-                approvedNotes.push(candidate);
-                if (this._verbose) {
-                    LogStatus(`Memory Manager: Approved note (no similar notes found): "${candidate.content.substring(0, 50)}..."`);
-                }
+            const decision = await this.evaluateCandidateForApproval(candidate, existingNotes, dedupePrompt, runner, contextUser, stats);
+            if (decision) {
+                approved.push(candidate);
             }
         }
-        // Finalize Step 4 after deduplication loop
-        await this.FinalizeRunStep(step4, true, {
-            approvedCount: approvedNotes.length,
-            rejectedCount: dedupeRejectedCount,
-            llmCallCount: dedupeLlmCallCount
+        await this.FinalizeRunStep(step, true, {
+            approvedCount: approved.length,
+            rejectedCount: stats.rejectedCount,
+            llmCallCount: stats.llmCallCount
         });
-        if (this._verbose) {
-            LogStatus(`Memory Manager: Final approved notes: ${approvedNotes.length}`);
+        return approved;
+    }
+    /**
+     * Evaluate a single candidate: merge markers auto-approve, exact-text duplicates are
+     * rejected, otherwise run semantic similarity + LLM dedup. Returns true if the candidate
+     * should be kept. Mutates `stats` for rejection + LLM call counts as a side effect.
+     */
+    async evaluateCandidateForApproval(candidate, existingNotes, dedupePrompt, runner, contextUser, stats) {
+        // Merge/replacement candidates are auto-approved — the extraction LLM already
+        // determined they supersede an existing note. Running dedup on them would reject
+        // them as "too similar" to the very note they are replacing.
+        if (candidate.mergeWithExistingIds?.length) {
+            if (this._verbose) {
+                LogStatus(`Memory Manager: Auto-approved merge note targeting ${candidate.mergeWithExistingIds.join(', ')}: "${candidate.content.substring(0, 50)}..."`);
+            }
+            return true;
+        }
+        // Fast path: exact text match (case-insensitive, trimmed)
+        const normalizedContent = candidate.content.toLowerCase().trim();
+        if (existingNotes.some(n => n.Note && n.Note.toLowerCase().trim() === normalizedContent)) {
+            stats.rejectedCount++;
+            if (this._verbose)
+                LogStatus(`Memory Manager: Skipping exact duplicate: "${candidate.content.substring(0, 50)}..."`);
+            return false;
+        }
+        // Semantic similarity lookup. Cross-user dedup for org/global notes works naturally
+        // because those notes have UserID=null — FindSimilarAgentNotes won't filter them out.
+        const similarNotes = await AIEngine.Instance.FindSimilarAgentNotes(candidate.content, candidate.agentId, candidate.userId, candidate.companyId, 10, 0.85);
+        if (!dedupePrompt || similarNotes.length === 0) {
+            if (this._verbose)
+                LogStatus(`Memory Manager: Approved note (no similar notes found): "${candidate.content.substring(0, 50)}..."`);
+            return true;
+        }
+        const decision = await this.runDedupePromptForCandidate(runner, dedupePrompt, candidate, similarNotes, contextUser);
+        stats.llmCallCount++;
+        if (decision.shouldAdd) {
+            if (this._verbose)
+                LogStatus(`Memory Manager: Approved note - ${decision.reason}`);
+            return true;
+        }
+        stats.rejectedCount++;
+        if (this._verbose)
+            LogStatus(`Memory Manager: Skipped duplicate note - ${decision.reason}`);
+        return false;
+    }
+    /**
+     * Invoke the dedupe LLM prompt for a single candidate note against its similar
+     * neighbors. Returns the decision plus reason string — callers handle logging.
+     */
+    async runDedupePromptForCandidate(runner, dedupePrompt, candidate, similarNotes, contextUser) {
+        const params = new AIPromptParams();
+        params.prompt = dedupePrompt;
+        params.data = {
+            candidateNote: candidate,
+            similarNotes: similarNotes.map(s => ({
+                type: s.note.Type,
+                content: s.note.Note,
+                agentId: s.note.AgentID,
+                userId: s.note.UserID,
+                companyId: s.note.CompanyID,
+                similarity: s.similarity
+            }))
+        };
+        params.contextUser = contextUser;
+        params.attemptJSONRepair = true;
+        params.additionalParameters = DETERMINISTIC_PROMPT_PARAMS;
+        const result = await runner.ExecutePrompt(params);
+        if (result.success && result.result) {
+            return { shouldAdd: result.result.shouldAdd, reason: result.result.reason || '' };
         }
-        // Enrich notes with userId and agentRunId from conversation context
-        // Build a map of conversationId -> context for quick lookup
+        return { shouldAdd: false, reason: result.result?.reason || 'too similar to existing notes' };
+    }
+    /**
+     * Populate userId and sourceAgentRunId on approved notes from the source
+     * conversation's context. Only fills fields the LLM didn't already set.
+     */
+    enrichWithConversationContext(notes, conversationThreads) {
         const conversationContext = new Map();
         for (const thread of conversationThreads) {
             conversationContext.set(thread.conversationId, {
@@ -551,23 +700,17 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
                 agentRunId: thread.agentRunId || null
             });
         }
-        // Enrich each note with conversation context
-        for (const note of approvedNotes) {
-            if (note.sourceConversationId) {
-                const ctx = conversationContext.get(note.sourceConversationId);
-                if (ctx) {
-                    // Set userId from conversation if not already set
-                    if (!note.userId && ctx.userId) {
-                        note.userId = ctx.userId;
-                    }
-                    // Set sourceAgentRunId from conversation if not already set
-                    if (!note.sourceAgentRunId && ctx.agentRunId) {
-                        note.sourceAgentRunId = ctx.agentRunId;
-                    }
-                }
-            }
+        for (const note of notes) {
+            if (!note.sourceConversationId)
+                continue;
+            const ctx = conversationContext.get(note.sourceConversationId);
+            if (!ctx)
+                continue;
+            if (!note.userId && ctx.userId)
+                note.userId = ctx.userId;
+            if (!note.sourceAgentRunId && ctx.agentRunId)
+                note.sourceAgentRunId = ctx.agentRunId;
         }
-        return approvedNotes;
     }
     /**
      * Extract examples from conversation details with high ratings.
@@ -601,6 +744,7 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
         extractParams.data = { qaPairs };
         extractParams.contextUser = contextUser;
         extractParams.attemptJSONRepair = true;
+        extractParams.additionalParameters = { temperature: 0 };
         const extractResult = await runner.ExecutePrompt(extractParams);
         if (!extractResult.success || !extractResult.result) {
             await this.FinalizeRunStep(step5, false, {
@@ -662,6 +806,7 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
                 };
                 dedupeParams.contextUser = contextUser;
                 dedupeParams.attemptJSONRepair = true;
+                dedupeParams.additionalParameters = { temperature: 0 };
                 const dedupeResult = await runner.ExecutePrompt(dedupeParams);
                 exampleDedupeLlmCallCount++;
                 if (dedupeResult.success && dedupeResult.result && dedupeResult.result.shouldAdd) {
@@ -690,13 +835,6 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
         });
         return approvedExamples;
     }
-    /**
-     * Check if a string is a valid UUID format.
-     */
-    isValidUUID(str) {
-        const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
-        return uuidRegex.test(str);
-    }
     /**
      * Create note records from extracted data.
      * Inherits scope from source agent run and applies scopeLevel to determine scope specificity.
@@ -746,6 +884,23 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
                     for (const mergeTargetId of extracted.mergeWithExistingIds) {
                         const existingNote = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
                         if (await existingNote.Load(mergeTargetId)) {
+                            // Honor protection tiers — Immutable and Protected notes must NEVER be
+                            // auto-revoked even when the extraction LLM flags them as merge targets.
+                            // The contradiction-detection phase enforces the same rule via tier-based
+                            // filtering, but this earlier merge path bypassed it. Skip the revocation
+                            // and just annotate the existing note so the conflict is observable.
+                            const tier = existingNote.ProtectionTier || 'Standard';
+                            if (tier === 'Immutable' || tier === 'Protected') {
+                                const flagComment = `[Merge-target conflict: extraction LLM flagged this ${tier} note for merge from conversation ${extracted.sourceConversationId || 'unknown'} but tier prevents auto-revocation]`;
+                                existingNote.Comments = `${existingNote.Comments || ''} ${flagComment}`.trim();
+                                if (!await existingNote.Save()) {
+                                    LogError(`Memory Manager: Failed to annotate ${tier} merge target ${existingNote.ID}`);
+                                }
+                                if (this._verbose) {
+                                    LogStatus(`Memory Manager: Skipped revocation of ${tier} note ${existingNote.ID} flagged as merge target`);
+                                }
+                                continue;
+                            }
                             existingNote.Status = 'Revoked';
                             existingNote.Comments = `Superseded: contradiction detected, replaced by new note from conversation ${extracted.sourceConversationId || 'unknown'}`;
                             if (await existingNote.Save()) {
@@ -765,28 +920,25 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
                 if (createNewNote) {
                     // Create new note
                     const note = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
-                    // Only use valid UUIDs, filter out placeholders like "user-uuid-here"
-                    const isValidUUID = (id) => {
-                        if (!id)
-                            return false;
-                        return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id);
-                    };
                     // Determine AgentID - prefer extracted, then inherit from source run
-                    let agentId = isValidUUID(extracted.agentId) ? extracted.agentId : null;
+                    let agentId = MemoryManagerAgent_1.isValidUUID(extracted.agentId) ? extracted.agentId : null;
                     if (!agentId && sourceRun?.AgentID) {
                         agentId = sourceRun.AgentID;
                     }
                     note.AgentID = agentId;
-                    note.CompanyID = isValidUUID(extracted.companyId) ? extracted.companyId : null;
+                    note.CompanyID = sourceRun?.CompanyID || null;
                     note.AgentNoteTypeID = aiNoteTypeId; // "AI" type for AI-generated notes
                     note.Type = extracted.type; // Category: Preference, Constraint, Context, Issue, Example
                     note.Note = extracted.content;
                     note.IsAutoGenerated = true;
                     note.Status = 'Active'; // Auto-approve high-confidence notes
                     note.AccessCount = 1; // Required field
+                    // Consolidation tracking fields
+                    note.ConsolidationCount = 0; // Raw extraction, never consolidated
+                    note.ProtectionTier = note.IsAutoGenerated ? 'Standard' : 'Protected';
                     note.SourceConversationID = extracted.sourceConversationId || null;
                     // Only use if it's a valid UUID (LLM now sees message IDs in the prompt)
-                    note.SourceConversationDetailID = isValidUUID(extracted.sourceConversationDetailId) ? extracted.sourceConversationDetailId : null;
+                    note.SourceConversationDetailID = MemoryManagerAgent_1.isValidUUID(extracted.sourceConversationDetailId) ? extracted.sourceConversationDetailId : null;
                     note.SourceAIAgentRunID = extracted.sourceAgentRunId || null;
                     // Apply scope: Lean towards user-specific memories by default
                     const scopeLevel = extracted.scopeLevel || 'user';
@@ -808,9 +960,7 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
                     // UserID: Only set for user-scoped notes. Company/global notes belong to the
                     // company, not a specific user. This also enables cross-user dedup — FindSimilarAgentNotes
                     // filters by userId, so null UserID makes company notes visible to all users.
-                    note.UserID = scopeLevel === 'user'
-                        ? (isValidUUID(extracted.userId) ? extracted.userId : null)
-                        : null;
+                    note.UserID = scopeLevel === 'user' ? (sourceRun?.UserID || null) : null;
                     const saveResult = await note.Save();
                     if (saveResult) {
                         created++;
@@ -861,6 +1011,175 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
         }
         return result;
     }
+    /**
+     * Compute composite importance scores for all active notes.
+     * Uses a 7-signal weighted formula based on Park et al.'s Generative Agents (2023).
+     * Signals not available for a given note use neutral defaults (0.5) with proportional weight redistribution.
+     *
+     * Auto-promotes Standard-tier notes to Protected via two paths:
+     *  1. ImportanceScore >= IMPORTANCE_CONFIG.autoPromoteThreshold (default 8.0)
+     *  2. Uniqueness at or above the 95th percentile of the cohort (outlier protection,
+     *     FR-094). The cohort must be at least OUTLIER_PROMOTION_MIN_COHORT notes for
+     *     the percentile to be meaningful.
+     *
+     * Also reports the score distribution (min/max/mean/median) so the observability
+     * step can surface it in the agent run step output.
+     */
+    async computeImportanceScores(contextUser) {
+        const allNotes = AIEngine.Instance.AgentNotes.filter(n => n.Status === 'Active');
+        let notesScored = 0;
+        let tierPromotions = 0;
+        const md = new Metadata();
+        const scoresForDistribution = [];
+        // Pre-pass: compute uniqueness per note once, derive 95th-percentile threshold.
+        // Passing uniqueness into gatherImportanceSignals also eliminates a redundant
+        // FindSimilarAgentNotes call per note.
+        const uniquenessByNoteId = await this.precomputeUniqueness(allNotes);
+        const p95Threshold = this.computeUniquenessP95(uniquenessByNoteId);
+        for (const note of allNotes) {
+            const uniquenessInfo = uniquenessByNoteId.get(note.ID);
+            const signals = this.gatherImportanceSignals(note, uniquenessInfo);
+            const importanceScore = this.computeWeightedImportanceScore(signals);
+            const noteToUpdate = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
+            if (await noteToUpdate.Load(note.ID)) {
+                noteToUpdate.ImportanceScore = importanceScore;
+                // Promotion path 1: high ImportanceScore
+                const currentTier = noteToUpdate.ProtectionTier || 'Standard';
+                let promotedByScore = false;
+                if (currentTier === 'Standard' && importanceScore >= IMPORTANCE_CONFIG.autoPromoteThreshold) {
+                    noteToUpdate.ProtectionTier = 'Protected';
+                    noteToUpdate.Comments = `${noteToUpdate.Comments || ''} [Auto-promoted to Protected: ImportanceScore ${importanceScore} >= ${IMPORTANCE_CONFIG.autoPromoteThreshold}]`.trim();
+                    tierPromotions++;
+                    promotedByScore = true;
+                }
+                // Promotion path 2: uniqueness outlier (p95+). Only apply when the cohort
+                // is large enough for the percentile to be meaningful, the note has a
+                // computed uniqueness, and we didn't already promote it via the score path.
+                if (!promotedByScore &&
+                    currentTier === 'Standard' &&
+                    p95Threshold !== null &&
+                    uniquenessInfo?.available &&
+                    uniquenessInfo.value >= p95Threshold) {
+                    noteToUpdate.ProtectionTier = 'Protected';
+                    noteToUpdate.Comments = `${noteToUpdate.Comments || ''} [Auto-protected: uniqueness ${uniquenessInfo.value.toFixed(3)} at/above 95th percentile ${p95Threshold.toFixed(3)}]`.trim();
+                    tierPromotions++;
+                }
+                if (await noteToUpdate.Save()) {
+                    notesScored++;
+                    scoresForDistribution.push(importanceScore);
+                }
+                else {
+                    LogError(`Memory Manager: Failed to update ImportanceScore for note ${note.ID}`);
+                }
+            }
+        }
+        return {
+            notesScored,
+            tierPromotions,
+            scoreDistribution: this.summarizeScores(scoresForDistribution)
+        };
+    }
+    /**
+     * Pre-compute uniqueness (1 - maxSimilarity to nearest neighbor) for each note in
+     * one pass. Returns a map keyed by note ID. Notes without content get an
+     * unavailable signal so downstream scoring falls back to the neutral default.
+     */
+    async precomputeUniqueness(notes) {
+        const map = new Map();
+        for (const note of notes) {
+            if (!note.Note) {
+                map.set(note.ID, { value: 0.5, available: false });
+                continue;
+            }
+            const similar = await AIEngine.Instance.FindSimilarAgentNotes(note.Note, note.AgentID, undefined, undefined, 1, 0.0);
+            const uniqueness = similar.length > 0 ? 1.0 - similar[0].similarity : 1.0;
+            map.set(note.ID, { value: uniqueness, available: true });
+        }
+        return map;
+    }
+    /**
+     * Derive the 95th-percentile uniqueness threshold across the cohort. Returns null
+     * when the cohort is smaller than OUTLIER_PROMOTION_MIN_COHORT (percentile isn't
+     * meaningful) or when no uniqueness was actually computable.
+     */
+    computeUniquenessP95(uniquenessMap) {
+        const available = Array.from(uniquenessMap.values())
+            .filter(u => u.available)
+            .map(u => u.value);
+        if (available.length < OUTLIER_PROMOTION_MIN_COHORT) {
+            return null;
+        }
+        const sorted = available.slice().sort((a, b) => a - b);
+        const index = Math.floor(sorted.length * 0.95);
+        const clampedIndex = Math.min(sorted.length - 1, index);
+        return sorted[clampedIndex];
+    }
+    /**
+     * Summarize importance scores into min/max/mean/median. Returns null for an empty
+     * input so the caller can serialize it as an explicit "no data" signal in the
+     * observability step.
+     */
+    summarizeScores(scores) {
+        if (scores.length === 0)
+            return null;
+        const sorted = scores.slice().sort((a, b) => a - b);
+        const min = sorted[0];
+        const max = sorted[sorted.length - 1];
+        const mean = sorted.reduce((sum, v) => sum + v, 0) / sorted.length;
+        const mid = sorted.length / 2;
+        const median = sorted.length % 2 === 0
+            ? (sorted[mid - 1] + sorted[mid]) / 2
+            : sorted[Math.floor(mid)];
+        return {
+            min: Math.round(min * 100) / 100,
+            max: Math.round(max * 100) / 100,
+            mean: Math.round(mean * 100) / 100,
+            median: Math.round(median * 100) / 100
+        };
+    }
+    /**
+     * Gather the 7 importance signals for a single note. Uniqueness is precomputed by
+     * the caller so the full cohort can be examined in one pass for percentile
+     * analysis. Other signals are derived from the note itself.
+     */
+    gatherImportanceSignals(note, precomputedUniqueness) {
+        const signals = [];
+        const hoursSinceCreation = (Date.now() - new Date(note.__mj_CreatedAt).getTime()) / (1000 * 60 * 60);
+        const hasConfidence = note.Comments?.includes('confidence') || false;
+        const isCorrection = note.Comments?.includes('Superseded') || note.Comments?.includes('contradiction');
+        signals.push({ signal: 'recencyDecay', value: Math.pow(0.995, hoursSinceCreation), available: true });
+        signals.push({ signal: 'llmImportance', value: hasConfidence ? 0.7 : 0.5, available: hasConfidence });
+        signals.push({ signal: 'relevance', value: 0.5, available: false }); // Phase 2 enrichment
+        signals.push({
+            signal: 'uniqueness',
+            value: precomputedUniqueness?.value ?? 0.5,
+            available: precomputedUniqueness?.available ?? false
+        });
+        signals.push({ signal: 'correctionBoost', value: isCorrection ? 1.0 : 0.0, available: true });
+        signals.push({ signal: 'goalAlignment', value: 0.5, available: false }); // Phase 2 enrichment
+        signals.push({ signal: 'userMark', value: note.IsAutoGenerated ? 0.0 : 1.0, available: true });
+        return signals;
+    }
+    /** Compute a weighted importance score (0-10) from signals, redistributing weight from unavailable signals. */
+    computeWeightedImportanceScore(signals) {
+        const weights = IMPORTANCE_CONFIG.weights;
+        const availableSignals = signals.filter(s => s.available);
+        const totalAvailableWeight = availableSignals.reduce((sum, s) => sum + (weights[s.signal] || 0), 0);
+        const unavailableWeight = signals.filter(s => !s.available).reduce((sum, s) => sum + (weights[s.signal] || 0), 0);
+        let rawScore = 0;
+        for (const s of availableSignals) {
+            if (totalAvailableWeight > 0) {
+                const adjustedWeight = (weights[s.signal] || 0) + ((weights[s.signal] || 0) / totalAvailableWeight) * unavailableWeight;
+                rawScore += s.value * adjustedWeight;
+            }
+        }
+        let score = rawScore * 10.0;
+        const isCorrection = signals.some(s => s.signal === 'correctionBoost' && s.value > 0);
+        if (isCorrection) {
+            score = Math.min(10.0, score + IMPORTANCE_CONFIG.correctionBonusPoints);
+        }
+        return Math.round(score * 100) / 100;
+    }
     /**
      * Determine whether consolidation should run based on CONSOLIDATION_CONFIG.frequency.
      * Uses AIAgentRun history instead of static in-memory state so that timing
@@ -871,45 +1190,90 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
      * - 'hourly': Run if 1+ hour since last completed MM run
      * - 'daily': Run if 24+ hours since last completed MM run
      * - number: Run every N completed MM runs
+     *
+     * @param forceMaintenance When true, bypasses all gating and runs maintenance
+     *   regardless of frequency/history. Set by callers via `params.data.forceMaintenance`
+     *   (see `executeAgentInternal`). Intended for tests, manual admin triggers, and
+     *   the E2E verification script — NOT for production config. Previously this was
+     *   an env var (`FORCE_MAINTENANCE=1`), which was removed because an env-var
+     *   sidechannel could accidentally leak into production and cause massive DB/LLM
+     *   churn on every run.
+     *
+     * Returns both a boolean and the reason it fired so the observability layer can
+     * record the trigger type on the parent consolidation run step.
      */
-    async shouldRunConsolidation(agentId, contextUser) {
+    async shouldRunConsolidation(agentId, contextUser, forceMaintenance) {
+        if (forceMaintenance)
+            return { shouldRun: true, triggerType: 'forced' };
         const freq = CONSOLIDATION_CONFIG.frequency;
-        if (freq === 'disabled') {
-            return false;
+        if (freq === 'disabled')
+            return { shouldRun: false, triggerType: 'disabled' };
+        if (freq === 'every-run')
+            return { shouldRun: true, triggerType: 'every-run' };
+        if (freq === 'hourly' || freq === 'daily') {
+            return this.shouldRunConsolidationByTimeWindow(agentId, contextUser, freq === 'hourly' ? 1 : 24);
         }
-        if (freq === 'every-run') {
-            return true;
+        if (typeof freq === 'number') {
+            return this.shouldRunConsolidationByRunCount(agentId, contextUser, freq);
         }
-        if (freq === 'hourly' || freq === 'daily') {
-            const thresholdHours = freq === 'hourly' ? 1 : 24;
-            const lastRun = await this.GetLastRunTime(agentId, contextUser);
-            if (!lastRun) {
-                return true; // First run — consolidate
+        return { shouldRun: true, triggerType: 'every-run' };
+    }
+    /**
+     * Time-window frequency gate: returns shouldRun=true with triggerType='time' when
+     * enough time has passed since the last memory-manager run, or triggerType='event'
+     * when the event-driven new-note threshold has been crossed. Falls back to
+     * triggerType='not-triggered' when neither condition fires.
+     */
+    async shouldRunConsolidationByTimeWindow(agentId, contextUser, thresholdHours) {
+        const lastRun = await this.GetLastRunTime(agentId, contextUser);
+        if (!lastRun)
+            return { shouldRun: true, triggerType: 'time' };
+        const hoursSinceLast = (Date.now() - lastRun.getTime()) / (1000 * 60 * 60);
+        if (hoursSinceLast >= thresholdHours)
+            return { shouldRun: true, triggerType: 'time' };
+        // Event-driven trigger: consolidate when at least `noteCountTrigger` new notes
+        // have been added system-wide since the last Memory Manager run.
+        //
+        // NOTE: this query intentionally does NOT filter by AgentID. The `agentId` parameter
+        // here is the Memory Manager's own ID (passed from `params.agent.ID` at the call
+        // site), not the agent that owns the notes. Filtering the count by MM's own agent
+        // ID would never match anything because MM doesn't own notes — it processes notes
+        // belonging to other (memory-enabled) agents.
+        const rv = new RunView();
+        const newNoteResult = await rv.RunView({
+            EntityName: 'MJ: AI Agent Notes',
+            ExtraFilter: `IsAutoGenerated=1 AND Status='Active' AND __mj_CreatedAt > '${lastRun.toISOString()}'`,
+            ResultType: 'count_only'
+        }, contextUser);
+        if (newNoteResult.Success && (newNoteResult.TotalRowCount || 0) >= CONSOLIDATION_CONFIG.noteCountTrigger) {
+            if (this._verbose) {
+                LogStatus(`Memory Manager: Event-driven consolidation trigger fired (${newNoteResult.TotalRowCount} new notes >= ${CONSOLIDATION_CONFIG.noteCountTrigger} threshold since last MM run)`);
             }
-            const hoursSinceLast = (Date.now() - lastRun.getTime()) / (1000 * 60 * 60);
-            return hoursSinceLast >= thresholdHours;
+            return { shouldRun: true, triggerType: 'event' };
         }
-        // Numeric frequency: run every N completed executions
-        if (typeof freq === 'number') {
-            const rv = new RunView();
-            const countResult = await rv.RunView({
-                EntityName: 'MJ: AI Agent Runs',
-                ExtraFilter: `AgentID='${agentId}' AND Status='Completed'`,
-                ResultType: 'count_only'
-            }, contextUser);
-            const completedCount = countResult.Success ? (countResult.TotalRowCount || 0) : 0;
-            return completedCount > 0 && completedCount % freq === 0;
-        }
-        // Default: run every time
-        return true;
+        return { shouldRun: false, triggerType: 'not-triggered' };
+    }
+    /** Run-count frequency gate: consolidate every N completed runs. */
+    async shouldRunConsolidationByRunCount(agentId, contextUser, everyN) {
+        const rv = new RunView();
+        const countResult = await rv.RunView({
+            EntityName: 'MJ: AI Agent Runs',
+            ExtraFilter: `AgentID='${agentId}' AND Status='Completed'`,
+            ResultType: 'count_only'
+        }, contextUser);
+        const completedCount = countResult.Success ? (countResult.TotalRowCount || 0) : 0;
+        const shouldRun = completedCount > 0 && completedCount % everyN === 0;
+        return { shouldRun, triggerType: shouldRun ? 'count' : 'not-triggered' };
     }
     /**
      * Consolidate related notes into single, comprehensive notes.
      * This method finds clusters of similar notes and synthesizes them.
      *
+     * Returns per-cluster verification results alongside the consolidation counts so
+     * the phase-level "Verify Consolidation Output" run step can aggregate them.
+     *
      * @param agentId Optional - consolidate notes for a specific agent only
      * @param contextUser The context user for database operations
-     * @returns Number of notes consolidated (archived)
      */
     async consolidateRelatedNotes(agentId, contextUser) {
         const allNotes = AIEngine.Instance.AgentNotes;
@@ -921,7 +1285,7 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
             if (this._verbose) {
                 LogStatus(`Memory Manager: Only ${activeNotes.length} active notes - need at least ${CONSOLIDATION_CONFIG.minClusterSize} to consolidate`);
             }
-            return { consolidated: 0, archived: 0 };
+            return { consolidated: 0, archived: 0, newNoteIds: [], verifications: [] };
         }
         if (this._verbose) {
             LogStatus(`Memory Manager: Analyzing ${activeNotes.length} active notes for consolidation`);
@@ -931,7 +1295,7 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
             if (this._verbose) {
                 LogStatus(`Memory Manager: No clusters found with ${CONSOLIDATION_CONFIG.minClusterSize}+ similar notes`);
             }
-            return { consolidated: 0, archived: 0 };
+            return { consolidated: 0, archived: 0, newNoteIds: [], verifications: [] };
         }
         if (this._verbose) {
             LogStatus(`Memory Manager: Found ${clusters.length} clusters to consolidate`);
@@ -940,15 +1304,17 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
         const consolidatePrompt = AIEngine.Instance.Prompts.find(p => p.Name === 'Memory Manager - Consolidate Notes' && p.Category === 'MJ: System');
         if (!consolidatePrompt) {
             LogError('Memory Manager: Consolidation prompt not found');
-            return { consolidated: 0, archived: 0 };
+            return { consolidated: 0, archived: 0, newNoteIds: [], verifications: [] };
         }
         const aiNoteTypeId = AIEngine.Instance.AgenteNoteTypeIDByName('AI');
         if (!aiNoteTypeId) {
             LogError('Memory Manager: Could not find "AI" note type');
-            return { consolidated: 0, archived: 0 };
+            return { consolidated: 0, archived: 0, newNoteIds: [], verifications: [] };
         }
         let consolidated = 0;
         let archived = 0;
+        const newNoteIds = [];
+        const verifications = [];
         const runner = new AIPromptRunner();
         const md = new Metadata();
         for (const cluster of clusters) {
@@ -956,12 +1322,16 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
                 const result = await this.processConsolidationCluster(cluster, consolidatePrompt, aiNoteTypeId, runner, md, contextUser);
                 consolidated += result.consolidated;
                 archived += result.archived;
+                if (result.newNoteId)
+                    newNoteIds.push(result.newNoteId);
+                if (result.verification)
+                    verifications.push(result.verification);
             }
             catch (error) {
                 LogError('Memory Manager: Exception during consolidation:', error);
             }
         }
-        return { consolidated, archived };
+        return { consolidated, archived, newNoteIds, verifications };
     }
     /**
      * Find clusters of semantically similar notes suitable for consolidation.
@@ -970,7 +1340,12 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
     async findConsolidationClusters(activeNotes) {
         const clusters = [];
         const processedIds = new Set();
-        for (const note of activeNotes) {
+        // Protection tier filtering: exclude Immutable and Protected notes from consolidation clustering
+        const eligibleNotes = activeNotes.filter(n => {
+            const tier = n.ProtectionTier || 'Standard';
+            return tier !== 'Immutable' && tier !== 'Protected';
+        });
+        for (const note of eligibleNotes) {
             if (processedIds.has(note.ID)) {
                 continue;
             }
@@ -979,101 +1354,527 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
             processedIds.add(note.ID);
             for (const similar of similarNotes) {
                 if (!processedIds.has(similar.note.ID)) {
-                    cluster.push(similar.note);
-                    processedIds.add(similar.note.ID);
+                    // Also check that similar notes pass protection tier filter
+                    const similarTier = similar.note.ProtectionTier || 'Standard';
+                    if (similarTier !== 'Immutable' && similarTier !== 'Protected') {
+                        cluster.push(similar.note);
+                        processedIds.add(similar.note.ID);
+                    }
                 }
             }
-            if (cluster.length >= CONSOLIDATION_CONFIG.minClusterSize) {
-                clusters.push(cluster);
+            // Determine minClusterSize based on tier: Ephemeral uses relaxed threshold of 2
+            const noteTier = note.ProtectionTier || 'Standard';
+            const minSize = noteTier === 'Ephemeral' ? 2 : CONSOLIDATION_CONFIG.minClusterSize;
+            if (cluster.length >= minSize) {
+                // Enforce maxClusterSize by splitting oversized clusters
+                if (cluster.length > CONSOLIDATION_CONFIG.maxClusterSize) {
+                    const splitClusters = this.splitOversizedCluster(cluster);
+                    clusters.push(...splitClusters);
+                }
+                else {
+                    clusters.push(cluster);
+                }
             }
         }
         return clusters;
     }
     /**
-     * Process a single consolidation cluster: run the LLM prompt, create the consolidated note,
-     * and revoke source notes.
+     * Split a cluster that exceeds maxClusterSize into sub-clusters.
+     * Takes the first maxClusterSize notes (sorted by position in original cluster, which preserves
+     * similarity ordering from FindSimilarAgentNotes), and forms a second cluster from the remainder
+     * if it meets minClusterSize.
      */
-    async processConsolidationCluster(cluster, consolidatePrompt, aiNoteTypeId, runner, md, contextUser) {
-        const promptData = {
-            notesToConsolidate: cluster.map(n => ({
-                id: n.ID,
-                type: n.Type,
-                content: n.Note,
-                createdAt: n.__mj_CreatedAt,
-                accessCount: n.AccessCount,
-                agentId: n.AgentID,
+    splitOversizedCluster(cluster) {
+        const result = [];
+        const maxSize = CONSOLIDATION_CONFIG.maxClusterSize;
+        const minSize = CONSOLIDATION_CONFIG.minClusterSize;
+        // Split into chunks of maxClusterSize
+        for (let i = 0; i < cluster.length; i += maxSize) {
+            const chunk = cluster.slice(i, i + maxSize);
+            if (chunk.length >= minSize) {
+                result.push(chunk);
+            }
+        }
+        return result;
+    }
+    /**
+     * Walk DerivedFromNoteIDs chains breadth-first to find all generation-0 (original) source notes.
+     * Batches each depth level into a single `ID IN (...)` query instead of one query per ID.
+     */
+    async resolveOriginalSources(noteIds, contextUser) {
+        const originals = [];
+        const visited = new Set();
+        let currentIds = noteIds.filter(id => !visited.has(id));
+        currentIds.forEach(id => visited.add(id));
+        let depth = 0;
+        while (currentIds.length > 0 && depth <= MAX_SOURCE_RESOLUTION_DEPTH) {
+            if (depth > MAX_SOURCE_RESOLUTION_DEPTH) {
+                LogError(`Memory Manager: resolveOriginalSources() exceeded max depth ${MAX_SOURCE_RESOLUTION_DEPTH} — treating remaining ${currentIds.length} IDs as terminal to prevent runaway recursion`);
+                break;
+            }
+            const results = await this.loadResolvedNotes(currentIds, contextUser);
+            if (results.length === 0)
+                break;
+            currentIds = this.collectNextLevelSourceIds(results, originals, visited);
+            depth++;
+        }
+        return originals;
+    }
+    /** Load a batch of notes by ID with the fields needed for source resolution. */
+    async loadResolvedNotes(noteIds, contextUser) {
+        const resolvedFields = [
+            'ID', 'ConsolidationCount', 'DerivedFromNoteIDs', 'Note', 'Type',
+            'AccessCount', 'ImportanceScore', 'AgentID', 'UserID', 'CompanyID', '__mj_CreatedAt'
+        ];
+        const inClause = noteIds.map(id => `'${id}'`).join(',');
+        const rv = new RunView();
+        const result = await rv.RunView({
+            EntityName: 'MJ: AI Agent Notes',
+            ExtraFilter: `ID IN (${inClause})`,
+            Fields: resolvedFields,
+        }, contextUser);
+        return result.Success && result.Results ? result.Results : [];
+    }
+    /**
+     * Partition a batch of resolved notes into terminal originals (pushed into `originals`)
+     * and parent IDs that need further resolution. Mutates `originals` and `visited`.
+     */
+    collectNextLevelSourceIds(notes, originals, visited) {
+        const nextLevelIds = [];
+        for (const note of notes) {
+            const consolidationCount = note.ConsolidationCount || 0;
+            if (consolidationCount === 0 || !note.DerivedFromNoteIDs) {
+                originals.push(note);
+                continue;
+            }
+            try {
+                const parentIds = JSON.parse(note.DerivedFromNoteIDs);
+                for (const parentId of parentIds) {
+                    if (!visited.has(parentId)) {
+                        visited.add(parentId);
+                        nextLevelIds.push(parentId);
+                    }
+                }
+            }
+            catch {
+                LogError(`Memory Manager: Malformed DerivedFromNoteIDs on note ${note.ID} — treating as terminal source`);
+                originals.push(note);
+            }
+        }
+        return nextLevelIds;
+    }
+    /**
+     * Verify that a consolidated note preserves key entities from its source notes.
+     * Extracts numbers, dates, and proper nouns from source notes and checks they appear in the output.
+     * Non-blocking: returns verification results but does not prevent consolidation.
+     */
+    verifyConsolidationOutput(sourceNotes, consolidatedText) {
+        const entities = new Set();
+        const consolidatedLower = consolidatedText.toLowerCase();
+        for (const note of sourceNotes) {
+            this.extractVerifiableEntities(note.Note || '', entities);
+        }
+        const missing = [];
+        for (const entity of entities) {
+            if (!consolidatedLower.includes(entity.toLowerCase())) {
+                missing.push(entity);
+            }
+        }
+        return {
+            entitiesChecked: entities.size,
+            entitiesMissing: missing,
+            passed: missing.length === 0
+        };
+    }
+    /**
+     * Harvest numbers, dates, proper nouns, and camelCase identifiers from a note's text
+     * into the supplied set. Used only by verifyConsolidationOutput to assemble a
+     * best-effort entity inventory for post-consolidation checks.
+     */
+    extractVerifiableEntities(text, entities) {
+        const numbers = text.match(/\b\d+\.?\d*%?\b/g);
+        if (numbers)
+            numbers.forEach(n => entities.add(n));
+        const dates = text.match(/\b\d{4}-\d{2}-\d{2}\b|\b(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\w*\s+\d{1,2}\b|\b\d{1,2}\/\d{1,2}\/\d{2,4}\b/gi);
+        if (dates)
+            dates.forEach(d => entities.add(d));
+        const properNouns = text.match(/(?<=[.!?]\s+|^)(?:[A-Z][a-z]+(?:\s+[A-Z][a-z]+)*)/g);
+        if (properNouns) {
+            const skipWords = new Set(['the', 'a', 'an', 'this', 'that', 'it', 'we', 'they', 'user', 'note']);
+            properNouns
+                .filter(pn => !skipWords.has(pn.toLowerCase()) && pn.length > 2)
+                .forEach(pn => entities.add(pn));
+        }
+        const techTerms = text.match(/\b[a-z]+(?:[A-Z][a-z]+)+\b|\b(?:[A-Z][a-z]+){2,}\b/g);
+        if (techTerms)
+            techTerms.forEach(t => entities.add(t));
+    }
+    /**
+     * Detect and resolve contradictions between semantically similar notes.
+     * Uses a three-stage pipeline: embedding pre-filter, entity-attribute extraction, LLM judgment.
+     * High-importance pairs (both >= highImportanceThreshold) are flagged but preserved.
+     * Protected-tier notes are never auto-revoked.
+     *
+     * Aggregates the per-pair entity-attribute-value triple count so the observability
+     * step can report how much structural reasoning the LLM produced.
+     */
+    async detectAndResolveContradictions(contextUser, consolidatedNoteIds) {
+        const result = { contradictionsFound: 0, resolved: 0, flagged: 0, pairsAnalyzed: 0, entityTriplesExtracted: 0 };
+        const prompt = AIEngine.Instance.Prompts.find(p => p.Name === 'Memory Manager - Detect Contradictions' && p.Category === 'MJ: System');
+        if (!prompt) {
+            LogError('Memory Manager: Contradiction detection prompt not found, skipping phase');
+            return result;
+        }
+        const candidatePairs = await this.buildContradictionCandidatePairs(consolidatedNoteIds);
+        if (candidatePairs.length === 0)
+            return result;
+        const runner = new AIPromptRunner();
+        const md = new Metadata();
+        for (const [noteA, noteB] of candidatePairs) {
+            result.pairsAnalyzed++;
+            const llmResult = await this.evaluateContradictionPair(noteA, noteB, prompt, runner, contextUser);
+            if (!llmResult)
+                continue;
+            result.entityTriplesExtracted += llmResult.triplesExtracted;
+            if (!llmResult.isContradiction)
+                continue;
+            result.contradictionsFound++;
+            const resolved = await this.resolveContradiction(noteA, noteB, llmResult, md, contextUser);
+            if (resolved === 'flagged')
+                result.flagged++;
+            else if (resolved === 'resolved')
+                result.resolved++;
+        }
+        return result;
+    }
+    /** Build unique candidate pairs of semantically similar notes for contradiction analysis. */
+    async buildContradictionCandidatePairs(consolidatedNoteIds) {
+        const allNotes = AIEngine.Instance.AgentNotes.filter(n => n.Status === 'Active' && n.IsAutoGenerated && (n.ProtectionTier || 'Standard') !== 'Immutable');
+        const processedPairs = new Set();
+        const pairs = [];
+        for (const note of allNotes) {
+            if (!note.Note || pairs.length >= CONTRADICTION_CONFIG.maxPairsPerRun)
+                break;
+            const similarNotes = await AIEngine.Instance.FindSimilarAgentNotes(note.Note, note.AgentID, undefined, undefined, 5, CONTRADICTION_CONFIG.similarityThreshold);
+            for (const similar of similarNotes) {
+                const pairKey = [note.ID, similar.note.ID].sort().join('|');
+                if (processedPairs.has(pairKey))
+                    continue;
+                processedPairs.add(pairKey);
+                if (consolidatedNoteIds.has(note.ID) && consolidatedNoteIds.has(similar.note.ID))
+                    continue;
+                pairs.push([note, similar.note]);
+                if (pairs.length >= CONTRADICTION_CONFIG.maxPairsPerRun)
+                    break;
+            }
+        }
+        return pairs;
+    }
+    /** Evaluate a single note pair for contradiction using the LLM prompt. */
+    async evaluateContradictionPair(noteA, noteB, prompt, runner, contextUser) {
+        const params = new AIPromptParams();
+        params.prompt = prompt;
+        params.data = {
+            noteA: { id: noteA.ID, type: noteA.Type, content: noteA.Note, createdAt: noteA.__mj_CreatedAt, accessCount: noteA.AccessCount, importanceScore: noteA.ImportanceScore || null, agentId: noteA.AgentID, userId: noteA.UserID, companyId: noteA.CompanyID },
+            noteB: { id: noteB.ID, type: noteB.Type, content: noteB.Note, createdAt: noteB.__mj_CreatedAt, accessCount: noteB.AccessCount, importanceScore: noteB.ImportanceScore || null, agentId: noteB.AgentID, userId: noteB.UserID, companyId: noteB.CompanyID }
+        };
+        params.contextUser = contextUser;
+        params.attemptJSONRepair = true;
+        params.additionalParameters = DETERMINISTIC_PROMPT_PARAMS;
+        const llmResult = await runner.ExecutePrompt(params);
+        if (!llmResult.success || !llmResult.result)
+            return null;
+        let parsed = llmResult.result;
+        if (typeof parsed === 'string') {
+            const cleaned = CleanAndParseJSON(parsed, true);
+            if (!cleaned)
+                return null;
+            parsed = cleaned;
+        }
+        return {
+            isContradiction: parsed.isContradiction,
+            keepNoteId: parsed.keepNoteId,
+            revokeNoteId: parsed.revokeNoteId,
+            reason: parsed.reason,
+            triplesExtracted: this.countEntityTriples(parsed.entityTriples)
+        };
+    }
+    /**
+     * Count entity-attribute-value triples returned by the contradiction detection prompt.
+     * Accepts any shape the LLM may produce: object of arrays keyed by noteId, flat array,
+     * or null/undefined. Unrecognized shapes return 0 so a malformed response can't poison
+     * the aggregate counter.
+     */
+    countEntityTriples(entityTriples) {
+        if (!entityTriples)
+            return 0;
+        if (Array.isArray(entityTriples))
+            return entityTriples.length;
+        if (typeof entityTriples === 'object') {
+            let total = 0;
+            for (const value of Object.values(entityTriples)) {
+                if (Array.isArray(value))
+                    total += value.length;
+            }
+            return total;
+        }
+        return 0;
+    }
+    /** Resolve a detected contradiction: flag both notes if high-importance/Protected, otherwise revoke the loser. */
+    async resolveContradiction(noteA, noteB, llmResult, md, contextUser) {
+        if (this.shouldFlagContradiction(noteA, noteB)) {
+            await this.flagContradictionPair(noteA, noteB, llmResult, md, contextUser);
+            return 'flagged';
+        }
+        const { revokeNoteId: revokeId, keepNoteId: keepId } = llmResult;
+        if (!revokeId || !keepId)
+            return 'skipped';
+        const noteToRevoke = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
+        if (!(await noteToRevoke.Load(revokeId)))
+            return 'skipped';
+        noteToRevoke.Status = 'Revoked';
+        noteToRevoke.ConsolidatedIntoNoteID = keepId;
+        noteToRevoke.Comments = `[Contradiction resolved: superseded by note ${keepId}. ${llmResult.reason}]`;
+        if (!(await noteToRevoke.Save()))
+            return 'skipped';
+        if (this._verbose) {
+            LogStatus(`Memory Manager: Contradiction resolved — revoked note ${revokeId} in favor of ${keepId}`);
+        }
+        return 'resolved';
+    }
+    /** Decide whether a contradiction pair must be flagged rather than auto-resolved. */
+    shouldFlagContradiction(noteA, noteB) {
+        const bothHighImportance = (noteA.ImportanceScore || 0) >= CONTRADICTION_CONFIG.highImportanceThreshold &&
+            (noteB.ImportanceScore || 0) >= CONTRADICTION_CONFIG.highImportanceThreshold;
+        const hasProtected = (noteA.ProtectionTier || 'Standard') === 'Protected' || (noteB.ProtectionTier || 'Standard') === 'Protected';
+        return bothHighImportance || hasProtected;
+    }
+    /** Flag both notes in a contradiction pair with a cross-referencing audit comment. */
+    async flagContradictionPair(noteA, noteB, llmResult, md, contextUser) {
+        const flagComment = `[Contradiction flagged: conflicts with note ${llmResult.revokeNoteId && UUIDsEqual(noteA.ID, llmResult.revokeNoteId) ? llmResult.keepNoteId : llmResult.revokeNoteId}. ${llmResult.reason}]`;
+        for (const flagNote of [noteA, noteB]) {
+            const noteToFlag = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
+            if (await noteToFlag.Load(flagNote.ID)) {
+                noteToFlag.Comments = `${noteToFlag.Comments || ''} ${flagComment}`.trim();
+                await noteToFlag.Save();
+            }
+        }
+        if (this._verbose) {
+            const bothHighImportance = (noteA.ImportanceScore || 0) >= CONTRADICTION_CONFIG.highImportanceThreshold &&
+                (noteB.ImportanceScore || 0) >= CONTRADICTION_CONFIG.highImportanceThreshold;
+            const reason = bothHighImportance ? 'both high-importance' : 'Protected tier present';
+            LogStatus(`Memory Manager: Contradiction flagged (${reason}): "${noteA.Note?.substring(0, 40)}..." vs "${noteB.Note?.substring(0, 40)}..."`);
+        }
+    }
+    /**
+     * Process a single consolidation cluster: run the LLM prompt, create the consolidated note,
+     * and revoke source notes.
+     *
+     * Emits a per-cluster "Process Consolidation Cluster" observability step that runs
+     * between the parent consolidation step's create/finalize calls, producing an
+     * implicit parent-child relationship via step-number ordering.
+     */
+    async processConsolidationCluster(cluster, consolidatePrompt, aiNoteTypeId, runner, md, contextUser) {
+        const maxGeneration = Math.max(...cluster.map(n => n.ConsolidationCount || 0));
+        const clusterStep = await this.CreateRunStep('Prompt', 'Process Consolidation Cluster', {
+            clusterSize: cluster.length,
+            noteIds: cluster.map(n => n.ID),
+            maxGeneration
+        });
+        const outcome = {
+            consolidated: 0,
+            archived: 0,
+            newNoteId: null,
+            verification: null
+        };
+        let stepOutput = { clusterSize: cluster.length };
+        try {
+            const { notesForPrompt, promptData } = await this.buildConsolidationPromptData(cluster, contextUser);
+            const parsedResult = await this.runConsolidationPrompt(consolidatePrompt, promptData, runner, contextUser);
+            if (!parsedResult) {
+                stepOutput = { ...stepOutput, shouldConsolidate: false, skipReason: 'prompt-failed' };
+                return outcome;
+            }
+            if (!parsedResult.shouldConsolidate) {
+                if (this._verbose) {
+                    LogStatus(`Memory Manager: Skipping cluster consolidation - ${parsedResult.reason}`);
+                }
+                stepOutput = { ...stepOutput, shouldConsolidate: false, skipReason: parsedResult.reason };
+                return outcome;
+            }
+            const consolidatedNoteData = parsedResult.consolidatedNote;
+            const newNote = await this.createConsolidatedNote(cluster, consolidatedNoteData, parsedResult.reason, aiNoteTypeId, md, contextUser);
+            if (!newNote) {
+                stepOutput = { ...stepOutput, shouldConsolidate: true, skipReason: 'save-failed' };
+                return outcome;
+            }
+            outcome.verification = await this.annotateConsolidationVerification(newNote, notesForPrompt, consolidatedNoteData.content);
+            outcome.archived = await this.revokeSourceNotes(cluster, newNote.ID, parsedResult.reason, md, contextUser);
+            outcome.consolidated = 1;
+            outcome.newNoteId = newNote.ID;
+            if (this._verbose) {
+                LogStatus(`Memory Manager: Consolidated ${cluster.length} notes into: "${consolidatedNoteData.content.substring(0, 50)}..."`);
+            }
+            stepOutput = {
+                ...stepOutput,
+                shouldConsolidate: true,
+                consolidatedNoteId: newNote.ID,
+                sourceNotesArchived: outcome.archived,
+                verificationPassed: outcome.verification?.passed ?? null,
+                entitiesChecked: outcome.verification?.entitiesChecked ?? 0,
+                entitiesMissing: outcome.verification?.entitiesMissing ?? []
+            };
+            return outcome;
+        }
+        finally {
+            // Treat skip (shouldConsolidate: false) as a successful completion rather than a
+            // failure — the phase intentionally chose not to consolidate this cluster.
+            await this.FinalizeRunStep(clusterStep, outcome.consolidated === 1 || stepOutput.shouldConsolidate === false, stepOutput);
+        }
+    }
+    /**
+     * Prepare the prompt payload for consolidation. Handles drift prevention: if any source
+     * note is at the consolidation count cap, resolve back to original generation-0 sources
+     * to avoid re-summarizing summaries. Returns both the notes used (for verification) and
+     * the prompt data.
+     */
+    async buildConsolidationPromptData(cluster, contextUser) {
+        const maxConsolidationCount = Math.max(...cluster.map(n => n.ConsolidationCount || 0));
+        let notesForPrompt = cluster;
+        let anchoredMode = false;
+        if (maxConsolidationCount >= CONSOLIDATION_CONFIG.maxConsolidationCount) {
+            const originals = await this.resolveOriginalSources(cluster.map(n => n.ID), contextUser);
+            if (originals.length > 0) {
+                notesForPrompt = originals;
+                if (this._verbose) {
+                    LogStatus(`Memory Manager: ConsolidationCount cap reached (${maxConsolidationCount}). Resolved ${cluster.length} notes to ${originals.length} original sources.`);
+                }
+            }
+        }
+        else if (maxConsolidationCount > 0) {
+            anchoredMode = true;
+        }
+        const promptData = {
+            anchoredMode,
+            notesToConsolidate: notesForPrompt.map(n => ({
+                id: n.ID,
+                type: n.Type,
+                content: n.Note,
+                createdAt: n.__mj_CreatedAt,
+                accessCount: n.AccessCount,
+                importanceScore: n.ImportanceScore || null,
+                consolidationCount: n.ConsolidationCount || 0,
+                agentId: n.AgentID,
                 userId: n.UserID,
                 companyId: n.CompanyID
             }))
         };
+        return { notesForPrompt, promptData };
+    }
+    /**
+     * Execute the consolidation prompt and parse the result. Returns null on any failure
+     * so the caller can short-circuit.
+     */
+    async runConsolidationPrompt(consolidatePrompt, promptData, runner, contextUser) {
         const params = new AIPromptParams();
         params.prompt = consolidatePrompt;
         params.data = promptData;
         params.contextUser = contextUser;
         params.attemptJSONRepair = true;
+        params.additionalParameters = DETERMINISTIC_PROMPT_PARAMS;
         const result = await runner.ExecutePrompt(params);
         if (!result.success || !result.result) {
             LogError(`Memory Manager: Consolidation prompt failed for cluster: ${result.errorMessage}`);
-            return { consolidated: 0, archived: 0 };
+            return null;
         }
-        // Parse result if string (some models wrap JSON in ```json fences)
-        let parsedResult = result.result;
         if (typeof result.result === 'string') {
             const parsed = CleanAndParseJSON(result.result, true);
             if (!parsed) {
                 LogError('Memory Manager: Failed to parse consolidation result');
-                return { consolidated: 0, archived: 0 };
-            }
-            parsedResult = parsed;
-        }
-        if (!parsedResult.shouldConsolidate) {
-            if (this._verbose) {
-                LogStatus(`Memory Manager: Skipping cluster consolidation - ${parsedResult.reason}`);
+                return null;
             }
-            return { consolidated: 0, archived: 0 };
+            return parsed;
         }
-        // Create consolidated note
-        const consolidatedNoteData = parsedResult.consolidatedNote;
+        return result.result;
+    }
+    /**
+     * Build, validate, and save the consolidated note. Returns the saved entity on success,
+     * null on save failure. The LLM-returned Type is validated against the allowed union and
+     * falls back to the template note's Type on hallucination — previously a blind `as` cast
+     * silently wrote invalid values.
+     */
+    async createConsolidatedNote(cluster, consolidatedNoteData, reason, aiNoteTypeId, md, contextUser) {
         const newNote = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
         const templateNote = cluster[0];
+        let validatedType;
+        if (isValidNoteType(consolidatedNoteData.type)) {
+            validatedType = consolidatedNoteData.type;
+        }
+        else {
+            LogError(`Memory Manager: Consolidation LLM returned invalid note Type "${consolidatedNoteData.type}" — falling back to template note's Type "${templateNote.Type}"`);
+            validatedType = templateNote.Type;
+        }
         newNote.AgentID = templateNote.AgentID;
         newNote.UserID = templateNote.UserID;
         newNote.CompanyID = templateNote.CompanyID;
         newNote.AgentNoteTypeID = aiNoteTypeId;
-        newNote.Type = consolidatedNoteData.type;
+        newNote.Type = validatedType;
         newNote.Note = consolidatedNoteData.content;
         newNote.IsAutoGenerated = true;
         newNote.Status = 'Active';
         newNote.AccessCount = cluster.reduce((sum, n) => sum + (n.AccessCount || 0), 0);
-        newNote.Comments = `Consolidated from ${cluster.length} notes: ${parsedResult.reason}`;
+        newNote.Comments = `Consolidated from ${cluster.length} notes: ${reason}`;
+        const maxSourceConsolidationCount = Math.max(...cluster.map(n => n.ConsolidationCount || 0));
+        newNote.ConsolidationCount = maxSourceConsolidationCount + 1;
+        newNote.DerivedFromNoteIDs = JSON.stringify(cluster.map(n => n.ID));
+        newNote.ProtectionTier = 'Standard';
         this.applyScopeToConsolidatedNote(newNote, templateNote, consolidatedNoteData.scopeLevel);
-        const saveResult = await newNote.Save();
-        if (!saveResult) {
+        if (!(await newNote.Save())) {
             LogError(`Memory Manager: Failed to save consolidated note: ${JSON.stringify(newNote.LatestResult)}`);
-            return { consolidated: 0, archived: 0 };
+            return null;
         }
-        // Revoke source notes in parallel
-        // TODO: When a ConsolidatedIntoNoteID FK column is added to AI Agent Notes,
-        // set it here so decomposition can properly restore source notes.
-        const revokeResults = await Promise.all(cluster.map(async (sourceNote) => {
+        return newNote;
+    }
+    /**
+     * Run post-consolidation entity verification and, if entities are missing, append a
+     * warning to the saved note's Comments (best-effort, non-blocking). Returns the
+     * verification result so the caller can aggregate it into the phase-level
+     * observability step.
+     */
+    async annotateConsolidationVerification(newNote, notesForPrompt, consolidatedContent) {
+        const verification = this.verifyConsolidationOutput(notesForPrompt, consolidatedContent);
+        if (verification.passed || verification.entitiesMissing.length === 0) {
+            return verification;
+        }
+        const missingList = verification.entitiesMissing.slice(0, 10).join(', ');
+        const warning = `[Verification: potentially missing entities: ${missingList}]`;
+        if (this._verbose) {
+            LogStatus(`Memory Manager: Post-consolidation verification warning — ${verification.entitiesMissing.length} entities not found in consolidated output (${verification.entitiesChecked} checked)`);
+        }
+        newNote.Comments = `${newNote.Comments || ''} ${warning}`.trim();
+        await newNote.Save();
+        return verification;
+    }
+    /**
+     * Revoke source notes in parallel, linking each to the consolidated replacement.
+     * Returns the number of notes successfully revoked.
+     */
+    async revokeSourceNotes(cluster, newNoteId, reason, md, contextUser) {
+        const results = await Promise.all(cluster.map(async (sourceNote) => {
             const noteToRevoke = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
-            if (await noteToRevoke.Load(sourceNote.ID)) {
-                noteToRevoke.Status = 'Revoked';
-                noteToRevoke.Comments = 'Revoked during note consolidation';
-                if (await noteToRevoke.Save()) {
-                    return true;
-                }
-                else {
-                    LogError(`Memory Manager: Failed to revoke source note ${sourceNote.ID}`);
-                }
+            if (!(await noteToRevoke.Load(sourceNote.ID))) {
+                return false;
             }
+            noteToRevoke.Status = 'Revoked';
+            noteToRevoke.ConsolidatedIntoNoteID = newNoteId;
+            noteToRevoke.Comments = `Consolidated into note ${newNoteId}: ${reason}`;
+            if (await noteToRevoke.Save()) {
+                return true;
+            }
+            LogError(`Memory Manager: Failed to revoke source note ${sourceNote.ID}`);
             return false;
         }));
-        const archived = revokeResults.filter(Boolean).length;
-        if (this._verbose) {
-            LogStatus(`Memory Manager: Consolidated ${cluster.length} notes into: "${consolidatedNoteData.content.substring(0, 50)}..."`);
-        }
-        return { consolidated: 1, archived };
+        return results.filter(Boolean).length;
     }
     /**
      * Apply scope fields to a consolidated note based on the LLM's scope recommendation.
@@ -1098,6 +1899,577 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
             newNote.SecondaryScopes = templateNote.SecondaryScopes;
         }
     }
+    /**
+     * Prune notes that reference entities which no longer exist or are inactive.
+     * Checks AgentID, UserID, CompanyID, and SourceConversationID against current database state.
+     * Immutable-tier notes are never pruned. Caps at 200 notes per cycle.
+     */
+    async pruneStaleReferences(contextUser) {
+        const maxPerCycle = STALE_PRUNING_CONFIG.maxNotesPerRun;
+        const result = { notesArchived: 0, orphanedAgents: 0, orphanedUsers: 0, orphanedCompanies: 0, orphanedConversations: 0 };
+        const notes = await this.loadPruneCandidateNotes(contextUser, maxPerCycle * 2);
+        if (notes.length === 0) {
+            return result;
+        }
+        const caches = await this.buildReferenceExistenceCache(notes, contextUser);
+        const md = new Metadata();
+        for (const note of notes) {
+            if (result.notesArchived >= maxPerCycle)
+                break;
+            const orphanReasons = this.detectOrphanReasons(note, caches, result);
+            if (orphanReasons.length > 0 && await this.archiveOrphanedNote(note.ID, orphanReasons, md, contextUser)) {
+                result.notesArchived++;
+            }
+        }
+        return result;
+    }
+    /**
+     * Load auto-generated, non-immutable Active notes that are candidates for orphan pruning.
+     */
+    async loadPruneCandidateNotes(contextUser, maxRows) {
+        const rv = new RunView();
+        const notesResult = await rv.RunView({
+            EntityName: 'MJ: AI Agent Notes',
+            ExtraFilter: `IsAutoGenerated = 1 AND Status = 'Active' AND ProtectionTier != 'Immutable'`,
+            Fields: ['ID', 'AgentID', 'UserID', 'CompanyID', 'SourceConversationID'],
+            OrderBy: '__mj_CreatedAt ASC',
+            MaxRows: maxRows,
+            ResultType: 'simple'
+        }, contextUser);
+        if (!notesResult.Success || !notesResult.Results?.length) {
+            return [];
+        }
+        return notesResult.Results;
+    }
+    /**
+     * Build in-memory lookup caches of which referenced users/companies/conversations still
+     * exist and which agents are still Active. Runs all three existence lookups in a single
+     * RunViews batch to minimize round trips.
+     */
+    async buildReferenceExistenceCache(notes, contextUser) {
+        const caches = {
+            activeAgentIds: new Set(AIEngine.Instance.Agents.filter(a => a.Status === 'Active').map(a => a.ID?.toLowerCase())),
+            existingUserIds: new Set(),
+            existingCompanyIds: new Set(),
+            existingConversationIds: new Set()
+        };
+        const { lookupQueries, queryMapping } = this.buildExistenceLookupQueries(notes);
+        if (lookupQueries.length === 0)
+            return caches;
+        const rv = new RunView();
+        const lookupResults = await rv.RunViews(lookupQueries, contextUser);
+        for (let i = 0; i < lookupResults.length; i++) {
+            if (!lookupResults[i].Success)
+                continue;
+            const targetSet = queryMapping[i] === 'users' ? caches.existingUserIds
+                : queryMapping[i] === 'companies' ? caches.existingCompanyIds
+                    : caches.existingConversationIds;
+            lookupResults[i].Results.forEach(r => targetSet.add(r.ID?.toLowerCase()));
+        }
+        return caches;
+    }
+    /**
+     * Collect unique referenced IDs from the note batch and assemble a RunViews query list
+     * for existence checks. Returns the query list alongside a parallel mapping array that
+     * tells the caller which target cache each query result belongs in.
+     */
+    buildExistenceLookupQueries(notes) {
+        const referencedUserIds = new Set();
+        const referencedCompanyIds = new Set();
+        const referencedConversationIds = new Set();
+        for (const note of notes) {
+            if (note.UserID)
+                referencedUserIds.add(note.UserID);
+            if (note.CompanyID)
+                referencedCompanyIds.add(note.CompanyID);
+            if (note.SourceConversationID)
+                referencedConversationIds.add(note.SourceConversationID);
+        }
+        const lookupQueries = [];
+        const queryMapping = [];
+        const push = (entityName, ids, kind) => {
+            if (ids.size === 0)
+                return;
+            lookupQueries.push({ EntityName: entityName, ExtraFilter: `ID IN (${Array.from(ids).map(id => `'${id}'`).join(',')})`, Fields: ['ID'] });
+            queryMapping.push(kind);
+        };
+        push('MJ: Users', referencedUserIds, 'users');
+        push('MJ: Companies', referencedCompanyIds, 'companies');
+        push('MJ: Conversations', referencedConversationIds, 'conversations');
+        return { lookupQueries, queryMapping };
+    }
+    /**
+     * Evaluate a single note's foreign-key references against the existence caches, returning
+     * human-readable reasons for any orphaned fields. Increments the supplied counter as a
+     * side effect so aggregate totals are tracked without a second pass.
+     */
+    detectOrphanReasons(note, caches, counter) {
+        const reasons = [];
+        if (note.AgentID && !caches.activeAgentIds.has(note.AgentID.toLowerCase())) {
+            reasons.push('referenced agent is inactive or deleted');
+            counter.orphanedAgents++;
+        }
+        if (note.UserID && !caches.existingUserIds.has(note.UserID.toLowerCase())) {
+            reasons.push('referenced user no longer exists');
+            counter.orphanedUsers++;
+        }
+        if (note.CompanyID && !caches.existingCompanyIds.has(note.CompanyID.toLowerCase())) {
+            reasons.push('referenced company no longer exists');
+            counter.orphanedCompanies++;
+        }
+        if (note.SourceConversationID && !caches.existingConversationIds.has(note.SourceConversationID.toLowerCase())) {
+            reasons.push('source conversation no longer exists');
+            counter.orphanedConversations++;
+        }
+        return reasons;
+    }
+    /**
+     * Archive a single orphaned note with an audit-trail Comments entry. Returns true on success.
+     */
+    async archiveOrphanedNote(noteId, reasons, md, contextUser) {
+        const noteToArchive = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
+        if (!(await noteToArchive.Load(noteId))) {
+            return false;
+        }
+        noteToArchive.Status = 'Archived';
+        noteToArchive.Comments = `[Archived by Memory Manager: stale reference pruning - ${reasons.join('; ')} on ${new Date().toISOString()}]`;
+        if (!(await noteToArchive.Save())) {
+            LogError(`Memory Manager: Failed to archive orphaned note ${noteId}`);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Compute Ebbinghaus-inspired proportional decay factor for a note.
+     * Returns a multiplier (0-1) to apply to the note's ImportanceScore.
+     * Per research: "decay should be proportional (multiply all strengths by a factor <1),
+     * not threshold-based deletion — this preserves relative importance ordering."
+     */
+    computeDecayFactor(note) {
+        const importanceScore = note.ImportanceScore || 5.0;
+        const normalizedImportance = importanceScore / 10.0;
+        let lambdaEff = DECAY_CONFIG.baseLambda * (1 - normalizedImportance * DECAY_CONFIG.importanceDampening);
+        if (note.ProtectionTier === 'Ephemeral') {
+            lambdaEff *= DECAY_CONFIG.ephemeralDecayMultiplier;
+        }
+        const lastAccess = note.LastAccessedAt || note.__mj_CreatedAt;
+        const daysSinceAccess = (Date.now() - new Date(lastAccess).getTime()) / (1000 * 60 * 60 * 24);
+        // Decay factor: how much of the current score to retain.
+        // Higher access count slows decay (well-used notes persist longer), but the
+        // multiplier is CAPPED — without a cap, a note with AccessCount=1000 would get
+        // accessRetention=201 and the `Math.min(1.0, ...)` clamp below would force the
+        // decay factor to 1.0 forever, making frequently-accessed notes effectively
+        // immortal. Capping at ~1.5 means access count can meaningfully slow decay but
+        // cannot indefinitely prevent it.
+        const rawAccessRetention = 1 + (note.AccessCount || 0) * DECAY_CONFIG.accessBoostFactor;
+        const accessRetention = Math.min(DECAY_CONFIG.accessRetentionCap, rawAccessRetention);
+        return Math.min(1.0, Math.exp(-lambdaEff * daysSinceAccess) * accessRetention);
+    }
+    /**
+     * Decay-based archival replacing fixed 90/180-day retention windows.
+     * Uses Ebbinghaus-inspired decay function weighted by ImportanceScore.
+     * Respects protection tiers: Immutable=never, Protected=365d extended, Ephemeral=2x decay.
+     * Handles both notes and examples. Respects per-agent AutoArchiveEnabled.
+     */
+    async decayBasedArchival(contextUser) {
+        const archiveEnabledAgentIds = new Set(AIEngine.Instance.Agents
+            .filter(a => a.AutoArchiveEnabled !== false)
+            .map(a => a.ID?.toLowerCase()));
+        const [expiredResult, decayResult] = await Promise.all([
+            this.archiveExpiredItems(contextUser),
+            this.applyProportionalDecay(contextUser, archiveEnabledAgentIds)
+        ]);
+        return {
+            notesExpired: expiredResult.notesExpired,
+            examplesExpired: expiredResult.examplesExpired,
+            notesArchived: decayResult.notesArchived,
+            examplesArchived: decayResult.examplesArchived,
+            decayScoreDistribution: this.summarizeDecayFactors(decayResult.stats.decayFactors),
+            protectedPreserved: decayResult.stats.protectedPreserved,
+            ephemeralAccelerated: decayResult.stats.ephemeralAccelerated
+        };
+    }
+    /**
+     * Summarize raw decay factors (values in [0,1]) into a min/max/mean triple for
+     * the observability step. Returns null when no factors were computed (empty
+     * cohort or all notes skipped via tier/config).
+     */
+    summarizeDecayFactors(factors) {
+        if (factors.length === 0)
+            return null;
+        let min = factors[0];
+        let max = factors[0];
+        let sum = 0;
+        for (const f of factors) {
+            if (f < min)
+                min = f;
+            if (f > max)
+                max = f;
+            sum += f;
+        }
+        return {
+            min: Math.round(min * 1000) / 1000,
+            max: Math.round(max * 1000) / 1000,
+            mean: Math.round((sum / factors.length) * 1000) / 1000
+        };
+    }
+    /** Archive notes and examples past their explicit ExpiresAt timestamp, regardless of decay score. */
+    async archiveExpiredItems(contextUser) {
+        const result = { notesExpired: 0, examplesExpired: 0 };
+        const md = new Metadata();
+        const nowISO = new Date().toISOString();
+        const [expiredNotes, expiredExamples] = await this.loadExpiredItems(contextUser, nowISO);
+        for (const note of expiredNotes) {
+            if ((note.ProtectionTier || 'Standard') === 'Immutable')
+                continue;
+            if (await this.archiveExpiredNote(note, md, contextUser))
+                result.notesExpired++;
+        }
+        for (const example of expiredExamples) {
+            if (await this.archiveExpiredExample(example, md, contextUser))
+                result.examplesExpired++;
+        }
+        return result;
+    }
+    async loadExpiredItems(contextUser, nowISO) {
+        const rv = new RunView();
+        const [notesResult, examplesResult] = await Promise.all([
+            rv.RunView({
+                EntityName: 'MJ: AI Agent Notes',
+                ExtraFilter: `Status = 'Active' AND ExpiresAt IS NOT NULL AND ExpiresAt < '${nowISO}'`,
+                Fields: ['ID', 'ExpiresAt', 'ProtectionTier'],
+                MaxRows: 200,
+            }, contextUser),
+            rv.RunView({
+                EntityName: 'MJ: AI Agent Examples',
+                ExtraFilter: `Status = 'Active' AND ExpiresAt IS NOT NULL AND ExpiresAt < '${nowISO}'`,
+                Fields: ['ID', 'ExpiresAt'],
+                MaxRows: 200,
+            }, contextUser)
+        ]);
+        return [
+            notesResult.Success && notesResult.Results ? notesResult.Results : [],
+            examplesResult.Success && examplesResult.Results ? examplesResult.Results : []
+        ];
+    }
+    async archiveExpiredNote(note, md, contextUser) {
+        const noteToArchive = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
+        if (!(await noteToArchive.Load(note.ID)))
+            return false;
+        noteToArchive.Status = 'Archived';
+        noteToArchive.Comments = `${noteToArchive.Comments || ''} [Archived by Memory Manager: expired on ${note.ExpiresAt}]`.trim();
+        return await noteToArchive.Save();
+    }
+    async archiveExpiredExample(example, md, contextUser) {
+        const exampleToArchive = await md.GetEntityObject('MJ: AI Agent Examples', contextUser);
+        if (!(await exampleToArchive.Load(example.ID)))
+            return false;
+        exampleToArchive.Status = 'Archived';
+        exampleToArchive.Comments = `${exampleToArchive.Comments || ''} [Archived by Memory Manager: expired on ${example.ExpiresAt}]`.trim();
+        return await exampleToArchive.Save();
+    }
+    /**
+     * Apply proportional decay to ImportanceScores, archiving only when score reaches the floor.
+     * Per research: "decay should be proportional (multiply all strengths by a factor <1),
+     * not threshold-based deletion — this preserves relative importance ordering while reducing overall load."
+     * Notes without ImportanceScore (not yet scored) are skipped entirely.
+     *
+     * Threads a stats accumulator through decayOneNote/decayOneExample to collect
+     * decay-factor distribution and tier-specific counts for observability.
+     */
+    async applyProportionalDecay(contextUser, archiveEnabledAgentIds) {
+        const result = { notesDecayed: 0, notesArchived: 0, examplesDecayed: 0, examplesArchived: 0 };
+        const stats = { decayFactors: [], protectedPreserved: 0, ephemeralAccelerated: 0 };
+        const md = new Metadata();
+        const [activeNotes, activeExamples] = await this.loadDecayCandidates(contextUser);
+        for (const note of activeNotes) {
+            await this.decayOneNote(note, archiveEnabledAgentIds, md, contextUser, result, stats);
+        }
+        for (const example of activeExamples) {
+            await this.decayOneExample(example, archiveEnabledAgentIds, md, contextUser, result, stats);
+        }
+        return { ...result, stats };
+    }
+    /**
+     * Fetch notes and examples in parallel — they're independent.
+     */
+    async loadDecayCandidates(contextUser) {
+        const rv = new RunView();
+        const [activeNotesResult, activeExamplesResult] = await Promise.all([
+            rv.RunView({
+                EntityName: 'MJ: AI Agent Notes',
+                ExtraFilter: `IsAutoGenerated = 1 AND Status = 'Active'`,
+                Fields: ['ID', 'ImportanceScore', 'ProtectionTier', 'LastAccessedAt', '__mj_CreatedAt', 'AccessCount', 'AgentID'],
+                MaxRows: 1000,
+            }, contextUser),
+            rv.RunView({
+                EntityName: 'MJ: AI Agent Examples',
+                ExtraFilter: `IsAutoGenerated = 1 AND Status = 'Active' AND SuccessScore < 50`,
+                Fields: ['ID', 'SuccessScore', 'LastAccessedAt', '__mj_CreatedAt', 'AccessCount', 'AgentID'],
+                MaxRows: 500,
+            }, contextUser)
+        ]);
+        return [
+            activeNotesResult.Success && activeNotesResult.Results ? activeNotesResult.Results : [],
+            activeExamplesResult.Success && activeExamplesResult.Results ? activeExamplesResult.Results : []
+        ];
+    }
+    /**
+     * Apply proportional decay to a single note. Archives if the decayed score drops below
+     * the archival floor, otherwise writes the reduced score (skipping when the factor is
+     * effectively 1.0 to avoid unnecessary saves).
+     */
+    async decayOneNote(note, archiveEnabledAgentIds, md, contextUser, result, stats) {
+        if (note.AgentID && !archiveEnabledAgentIds.has(note.AgentID.toLowerCase()))
+            return;
+        if (note.ImportanceScore === null)
+            return;
+        const tier = note.ProtectionTier || 'Standard';
+        if (tier === 'Immutable')
+            return;
+        if (tier === 'Protected') {
+            const lastAccess = note.LastAccessedAt || note.__mj_CreatedAt;
+            const daysSinceAccess = (Date.now() - new Date(lastAccess).getTime()) / (1000 * 60 * 60 * 24);
+            if (daysSinceAccess < DECAY_CONFIG.protectedInactivityDays) {
+                // Protected note within the extended-retention window — evaluated but preserved.
+                stats.protectedPreserved++;
+                return;
+            }
+        }
+        if (tier === 'Ephemeral') {
+            stats.ephemeralAccelerated++;
+        }
+        const decayFactor = this.computeDecayFactor(note);
+        stats.decayFactors.push(decayFactor);
+        const newScore = Math.round(note.ImportanceScore * decayFactor * 100) / 100;
+        const noteToUpdate = await md.GetEntityObject('MJ: AI Agent Notes', contextUser);
+        if (!(await noteToUpdate.Load(note.ID)))
+            return;
+        if (newScore < DECAY_CONFIG.archivalFloor) {
+            noteToUpdate.Status = 'Archived';
+            noteToUpdate.ImportanceScore = newScore;
+            noteToUpdate.Comments = `${noteToUpdate.Comments || ''} [Archived by Memory Manager: ImportanceScore decayed to ${newScore.toFixed(2)}, below floor ${DECAY_CONFIG.archivalFloor}]`.trim();
+            if (await noteToUpdate.Save())
+                result.notesArchived++;
+        }
+        else if (decayFactor < 0.99) {
+            noteToUpdate.ImportanceScore = newScore;
+            if (await noteToUpdate.Save())
+                result.notesDecayed++;
+        }
+    }
+    /**
+     * Apply proportional decay to a single example, using SuccessScore as a proxy importance.
+     * Archives if the effective score drops below the archival floor.
+     */
+    async decayOneExample(example, archiveEnabledAgentIds, md, contextUser, result, stats) {
+        if (example.AgentID && !archiveEnabledAgentIds.has(example.AgentID.toLowerCase()))
+            return;
+        const normalizedImportance = (example.SuccessScore || 25) / 100.0;
+        const lambdaEff = DECAY_CONFIG.baseLambda * (1 - normalizedImportance * DECAY_CONFIG.importanceDampening);
+        const lastAccess = example.LastAccessedAt || example.__mj_CreatedAt;
+        const daysSinceAccess = (Date.now() - new Date(lastAccess).getTime()) / (1000 * 60 * 60 * 24);
+        const decayFactor = Math.min(1.0, Math.exp(-lambdaEff * daysSinceAccess) * (1 + (example.AccessCount || 0) * DECAY_CONFIG.accessBoostFactor));
+        stats.decayFactors.push(decayFactor);
+        const effectiveScore = normalizedImportance * 10.0 * decayFactor;
+        if (effectiveScore >= DECAY_CONFIG.archivalFloor)
+            return;
+        const exampleToArchive = await md.GetEntityObject('MJ: AI Agent Examples', contextUser);
+        if (!(await exampleToArchive.Load(example.ID)))
+            return;
+        exampleToArchive.Status = 'Archived';
+        exampleToArchive.Comments = `${exampleToArchive.Comments || ''} [Archived by Memory Manager: effective score ${effectiveScore.toFixed(2)} below floor]`.trim();
+        if (await exampleToArchive.Save())
+            result.examplesArchived++;
+    }
+    /**
+     * Run all 5 maintenance phases in order: importance scoring, consolidation,
+     * contradiction detection, stale-reference pruning, and decay-based archival.
+     * Each phase is wrapped in try/catch so a failure in one does not abort the rest.
+     *
+     * `triggerType` flows through to the parent consolidation run step so observability
+     * records *why* the maintenance cycle fired this run.
+     */
+    async runMaintenancePhases(contextUser, forceMaintenance, triggerType) {
+        const r = {
+            consolidatedCount: 0, consolidationArchived: 0,
+            contradictionsFound: 0, contradictionsResolved: 0, contradictionsFlagged: 0,
+            staleNotesArchived: 0, decayNotesArchived: 0, decayExamplesArchived: 0,
+            importanceScored: 0, tierPromotions: 0
+        };
+        LogStatus(`Memory Manager: Running maintenance phases${forceMaintenance ? ' (forced via params.data.forceMaintenance)' : ''}...`);
+        await this.runImportancePhase(r, contextUser);
+        const consolidatedNoteIds = await this.runConsolidationPhase(r, contextUser, triggerType);
+        await this.runContradictionPhase(r, contextUser, consolidatedNoteIds);
+        await this.runPruneAndDecayPhases(r, contextUser);
+        return r;
+    }
+    async runImportancePhase(r, contextUser) {
+        const importanceStep = await this.CreateRunStep('Decision', 'Compute Importance Scores', {
+            activeNoteCount: AIEngine.Instance.AgentNotes.filter(n => n.Status === 'Active').length
+        });
+        try {
+            const scoringResult = await this.computeImportanceScores(contextUser);
+            r.importanceScored = scoringResult.notesScored;
+            r.tierPromotions = scoringResult.tierPromotions;
+            if (this._verbose)
+                LogStatus(`Memory Manager: Scored ${r.importanceScored} notes, ${r.tierPromotions} tier promotions`);
+            await this.FinalizeRunStep(importanceStep, true, {
+                notesScored: r.importanceScored,
+                tierPromotions: r.tierPromotions,
+                scoreDistribution: scoringResult.scoreDistribution
+            });
+        }
+        catch (error) {
+            LogError('Memory Manager: Importance scoring failed, continuing with other phases:', error);
+            await this.FinalizeRunStep(importanceStep, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+        }
+    }
+    async runConsolidationPhase(r, contextUser, triggerType) {
+        const consolidatedNoteIds = new Set();
+        const consolidationStep = await this.CreateRunStep('Decision', 'Consolidate Related Notes', {
+            frequency: CONSOLIDATION_CONFIG.frequency,
+            triggerType,
+            activeNoteCount: AIEngine.Instance.AgentNotes.filter(n => n.Status === 'Active' && n.IsAutoGenerated).length
+        });
+        let consolidationResult = null;
+        try {
+            consolidationResult = await this.consolidateRelatedNotes(null, contextUser);
+            r.consolidatedCount = consolidationResult.consolidated;
+            r.consolidationArchived = consolidationResult.archived;
+            for (const id of consolidationResult.newNoteIds)
+                consolidatedNoteIds.add(id);
+            if (r.consolidatedCount > 0 && this._verbose) {
+                LogStatus(`Memory Manager: Consolidated ${r.consolidatedCount} clusters, archived ${r.consolidationArchived} source notes`);
+            }
+            await this.FinalizeRunStep(consolidationStep, true, {
+                consolidatedClusterCount: r.consolidatedCount,
+                sourceNotesArchived: r.consolidationArchived,
+                newConsolidatedNoteIds: Array.from(consolidatedNoteIds)
+            });
+        }
+        catch (error) {
+            LogError('Memory Manager: Consolidation failed, continuing with other phases:', error);
+            await this.FinalizeRunStep(consolidationStep, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+        }
+        // Emit the phase-level verification run step (spec Task 8c). Runs whether or not
+        // any clusters were consolidated so "no items" runs still produce a visible step.
+        await this.emitVerificationRunStep(consolidationResult?.verifications ?? []);
+        return consolidatedNoteIds;
+    }
+    /** Aggregate per-cluster verification results into a single phase-level run step. */
+    async emitVerificationRunStep(verifications) {
+        const verificationStep = await this.CreateRunStep('Validation', 'Verify Consolidation Output', {
+            clustersVerified: verifications.length
+        });
+        const verificationsFlagged = verifications.filter(v => !v.passed).length;
+        const verificationsPassed = verifications.filter(v => v.passed).length;
+        const entitiesChecked = verifications.reduce((sum, v) => sum + v.entitiesChecked, 0);
+        const entitiesMissing = verifications.flatMap(v => v.entitiesMissing);
+        await this.FinalizeRunStep(verificationStep, true, {
+            clustersVerified: verifications.length,
+            entitiesChecked,
+            entitiesMissing,
+            verificationsPassed,
+            verificationsFlagged
+        });
+    }
+    async runContradictionPhase(r, contextUser, consolidatedNoteIds) {
+        const contradictionStep = await this.CreateRunStep('Decision', 'Detect Note Contradictions', {
+            consolidatedNoteIdsCount: consolidatedNoteIds.size
+        });
+        try {
+            const contradictionResult = await this.detectAndResolveContradictions(contextUser, consolidatedNoteIds);
+            r.contradictionsFound = contradictionResult.contradictionsFound;
+            r.contradictionsResolved = contradictionResult.resolved;
+            r.contradictionsFlagged = contradictionResult.flagged;
+            if (r.contradictionsFound > 0 && this._verbose) {
+                LogStatus(`Memory Manager: Found ${r.contradictionsFound} contradictions — resolved ${r.contradictionsResolved}, flagged ${r.contradictionsFlagged}`);
+            }
+            await this.FinalizeRunStep(contradictionStep, true, {
+                pairsAnalyzed: contradictionResult.pairsAnalyzed,
+                contradictionsFound: r.contradictionsFound,
+                contradictionsResolved: r.contradictionsResolved,
+                contradictionsFlagged: r.contradictionsFlagged,
+                entityTriplesExtracted: contradictionResult.entityTriplesExtracted
+            });
+        }
+        catch (error) {
+            LogError('Memory Manager: Contradiction detection failed, continuing with other phases:', error);
+            await this.FinalizeRunStep(contradictionStep, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+        }
+    }
+    /**
+     * Prune and decay are independent — run in parallel via Promise.allSettled so one failure
+     * doesn't block the other.
+     */
+    async runPruneAndDecayPhases(r, contextUser) {
+        const pruneStep = await this.CreateRunStep('Decision', 'Prune Stale References', {});
+        const decayStep = await this.CreateRunStep('Decision', 'Decay-Based Archival', {});
+        await Promise.allSettled([
+            this.runPrunePhase(r, contextUser, pruneStep),
+            this.runDecayPhase(r, contextUser, decayStep),
+        ]);
+    }
+    async runPrunePhase(r, contextUser, pruneStep) {
+        try {
+            const pruneResult = await this.pruneStaleReferences(contextUser);
+            r.staleNotesArchived = pruneResult.notesArchived;
+            if (r.staleNotesArchived > 0 && this._verbose) {
+                LogStatus(`Memory Manager: Pruned ${r.staleNotesArchived} orphaned notes`);
+            }
+            await this.FinalizeRunStep(pruneStep, true, {
+                notesArchived: r.staleNotesArchived,
+                orphanedAgents: pruneResult.orphanedAgents,
+                orphanedUsers: pruneResult.orphanedUsers,
+                orphanedCompanies: pruneResult.orphanedCompanies,
+                orphanedConversations: pruneResult.orphanedConversations
+            });
+        }
+        catch (error) {
+            LogError('Memory Manager: Stale reference pruning failed:', error);
+            await this.FinalizeRunStep(pruneStep, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+        }
+    }
+    async runDecayPhase(r, contextUser, decayStep) {
+        try {
+            const decayResult = await this.decayBasedArchival(contextUser);
+            r.decayNotesArchived = decayResult.notesArchived;
+            r.decayExamplesArchived = decayResult.examplesArchived;
+            const totalDecayArchived = decayResult.notesArchived + decayResult.examplesArchived + decayResult.notesExpired + decayResult.examplesExpired;
+            if (totalDecayArchived > 0 && this._verbose) {
+                LogStatus(`Memory Manager: Decay archival — ${decayResult.notesArchived} notes, ${decayResult.examplesArchived} examples, ${decayResult.notesExpired} expired notes, ${decayResult.examplesExpired} expired examples`);
+            }
+            await this.FinalizeRunStep(decayStep, true, {
+                notesArchived: decayResult.notesArchived,
+                examplesArchived: decayResult.examplesArchived,
+                notesExpired: decayResult.notesExpired,
+                examplesExpired: decayResult.examplesExpired,
+                decayScoreDistribution: decayResult.decayScoreDistribution,
+                protectedPreserved: decayResult.protectedPreserved,
+                ephemeralAccelerated: decayResult.ephemeralAccelerated
+            });
+        }
+        catch (error) {
+            LogError('Memory Manager: Decay-based archival failed:', error);
+            await this.FinalizeRunStep(decayStep, false, undefined, undefined, error instanceof Error ? error.message : String(error));
+        }
+    }
+    /** Build a human-readable summary string from maintenance phase results. */
+    buildMaintenanceSummary(m) {
+        const parts = [];
+        if (m.consolidatedCount > 0)
+            parts.push(`consolidated ${m.consolidatedCount} clusters`);
+        if (m.contradictionsResolved > 0)
+            parts.push(`resolved ${m.contradictionsResolved} contradictions`);
+        if (m.contradictionsFlagged > 0)
+            parts.push(`flagged ${m.contradictionsFlagged} high-importance contradictions`);
+        if (m.staleNotesArchived > 0)
+            parts.push(`pruned ${m.staleNotesArchived} stale notes`);
+        if (m.decayNotesArchived + m.decayExamplesArchived > 0)
+            parts.push(`decay-archived ${m.decayNotesArchived} notes + ${m.decayExamplesArchived} examples`);
+        return parts.length > 0 ? ` Maintenance: ${parts.join(', ')}.` : '';
+    }
     /**
      * Create example records from extracted data.
      * Inherits scope from source agent run and applies scopeLevel to determine scope specificity.
@@ -1150,7 +2522,7 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
                 example.Status = 'Active'; // Auto-approve high-confidence examples
                 example.SourceConversationID = extracted.sourceConversationId || null;
                 // Only use if it's a valid UUID
-                example.SourceConversationDetailID = this.isValidUUID(extracted.sourceConversationDetailId) ? extracted.sourceConversationDetailId : null;
+                example.SourceConversationDetailID = MemoryManagerAgent_1.isValidUUID(extracted.sourceConversationDetailId) ? extracted.sourceConversationDetailId : null;
                 example.SourceAIAgentRunID = extracted.sourceAgentRunId || null;
                 // Apply scope from source agent run based on scopeLevel hint
                 if (sourceRun && sourceRun.PrimaryScopeEntityID) {
@@ -1201,7 +2573,7 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
     async executeAgentInternal(params, config) {
         try {
             // Use verbose flag from agent execution params or data payload (UI passes it via data)
-            this._verbose = params.verbose ?? params.data?.verbose ?? false;
+            this._verbose = params.verbose || params.data?.verbose || false;
             // Initialize observability state for this run
             this._agentRunID = this.AgentRun?.ID || null;
             this._stepCounter = 0;
@@ -1252,112 +2624,90 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
             if (this._verbose) {
                 LogStatus(`Memory Manager: Found ${agentRuns.length} high-value agent runs`);
             }
-            if (conversations.length === 0 && agentRuns.length === 0) {
-                if (this._verbose) {
-                    LogStatus('Memory Manager: No data to process');
-                }
-                const finalStep = {
-                    terminate: true,
-                    step: 'Success',
-                    message: 'No conversations with new activity or agent runs to process'
-                };
-                return { finalStep, stepCount: 1 };
-            }
+            const hasNewData = conversations.length > 0 || agentRuns.length > 0;
             // Initialization guard: ensure vector services exist for semantic dedup.
             // If no notes existed at server startup, _noteVectorService is null and
             // AddOrUpdateSingleNoteEmbedding will throw when saving new notes.
             // The two post-creation/post-consolidation Config(true) calls were removed
             // because entity save hooks now update vectors incrementally.
             await AIEngine.Instance.Config(true, params.contextUser);
-            // Extract notes from conversations (with rating context)
-            const extractedNotes = await this.ExtractNotesFromConversations(conversations, params.contextUser);
-            if (this._verbose) {
-                LogStatus(`Memory Manager: Extracted ${extractedNotes.length} potential notes`);
-            }
-            // Extract examples from conversation details (legacy method for now)
-            // Convert conversations back to flat details for example extraction
-            const conversationDetails = conversations.flatMap(conv => conv.messages.map(msg => ({
-                ID: msg.id,
-                ConversationID: conv.conversationId,
-                Role: msg.role,
-                Message: msg.message,
-                Status: 'Complete',
-                __mj_CreatedAt: msg.createdAt
-            })));
-            const extractedExamples = await this.ExtractExamples(conversationDetails, params.contextUser);
-            if (this._verbose) {
-                LogStatus(`Memory Manager: Extracted ${extractedExamples.length} potential examples`);
-            }
-            // Enrich examples with userId and agentRunId from conversation context
-            // Build a map from conversationId to context (same as notes enrichment)
-            const conversationContextForExamples = new Map();
-            for (const conv of conversations) {
-                conversationContextForExamples.set(conv.conversationId, {
-                    userId: conv.userId || null,
-                    agentRunId: conv.agentRunId || null
-                });
-            }
-            for (const example of extractedExamples) {
-                if (example.sourceConversationId) {
-                    const ctx = conversationContextForExamples.get(example.sourceConversationId);
-                    if (ctx) {
-                        // Enrich userId if not set
-                        if (!example.userId && ctx.userId) {
-                            example.userId = ctx.userId;
-                            if (this._verbose) {
-                                LogStatus(`Memory Manager: Enriched example with userId from conversation: ${ctx.userId}`);
+            // Extract notes and examples only when there's new data to process
+            let notesCreated = 0;
+            let examplesCreated = 0;
+            if (hasNewData) {
+                const extractedNotes = await this.ExtractNotesFromConversations(conversations, params.contextUser);
+                if (this._verbose) {
+                    LogStatus(`Memory Manager: Extracted ${extractedNotes.length} potential notes`);
+                }
+                // Convert conversations back to flat details for example extraction.
+                // ExtractExamples accepts a ConversationDetailProjection, so we only
+                // need the fields it reads — no entity cast.
+                const conversationDetails = conversations.flatMap(conv => conv.messages.map(msg => ({
+                    ID: msg.id,
+                    ConversationID: conv.conversationId,
+                    Role: msg.role,
+                    Message: msg.message,
+                    __mj_CreatedAt: msg.createdAt
+                })));
+                const extractedExamples = await this.ExtractExamples(conversationDetails, params.contextUser);
+                if (this._verbose) {
+                    LogStatus(`Memory Manager: Extracted ${extractedExamples.length} potential examples`);
+                }
+                // Enrich examples with userId and agentRunId from conversation context
+                const conversationContextForExamples = new Map();
+                for (const conv of conversations) {
+                    conversationContextForExamples.set(conv.conversationId, {
+                        userId: conv.userId || null,
+                        agentRunId: conv.agentRunId || null
+                    });
+                }
+                for (const example of extractedExamples) {
+                    if (example.sourceConversationId) {
+                        const ctx = conversationContextForExamples.get(example.sourceConversationId);
+                        if (ctx) {
+                            if (!example.userId && ctx.userId) {
+                                example.userId = ctx.userId;
+                                if (this._verbose) {
+                                    LogStatus(`Memory Manager: Enriched example with userId from conversation: ${ctx.userId}`);
+                                }
                             }
-                        }
-                        // Enrich agentRunId if not set
-                        if (!example.sourceAgentRunId && ctx.agentRunId) {
-                            example.sourceAgentRunId = ctx.agentRunId;
-                            if (this._verbose) {
-                                LogStatus(`Memory Manager: Enriched example with agentRunId from conversation: ${ctx.agentRunId}`);
+                            if (!example.sourceAgentRunId && ctx.agentRunId) {
+                                example.sourceAgentRunId = ctx.agentRunId;
+                                if (this._verbose) {
+                                    LogStatus(`Memory Manager: Enriched example with agentRunId from conversation: ${ctx.agentRunId}`);
+                                }
                             }
                         }
                     }
-                }
-                // Clear invalid agentId (LLM sometimes returns placeholder values like "agent-12345")
-                if (example.agentId && !this.isValidUUID(example.agentId)) {
-                    if (this._verbose) {
-                        LogStatus(`Memory Manager: Clearing invalid agentId "${example.agentId}" from example`);
+                    if (example.agentId && !MemoryManagerAgent_1.isValidUUID(example.agentId)) {
+                        if (this._verbose) {
+                            LogStatus(`Memory Manager: Clearing invalid agentId "${example.agentId}" from example`);
+                        }
+                        example.agentId = '';
                     }
-                    example.agentId = '';
-                }
-            }
-            // Create records
-            const notesCreated = await this.CreateNoteRecords(extractedNotes, params.contextUser);
-            const examplesCreated = await this.CreateExampleRecords(extractedExamples, params.contextUser);
-            LogStatus(`Memory Manager: Created ${notesCreated} notes and ${examplesCreated} examples`);
-            // Step 9: Consolidate related notes
-            // This finds clusters of similar notes and synthesizes them into single comprehensive notes
-            let consolidatedCount = 0;
-            let archivedCount = 0;
-            if (await this.shouldRunConsolidation(params.agent.ID, params.contextUser)) {
-                LogStatus(`Memory Manager: Running note consolidation...`);
-                const consolidationResult = await this.consolidateRelatedNotes(null, params.contextUser);
-                consolidatedCount = consolidationResult.consolidated;
-                archivedCount = consolidationResult.archived;
-                if (consolidatedCount > 0 || archivedCount > 0) {
-                    LogStatus(`Memory Manager: Consolidated ${consolidatedCount} note clusters, archived ${archivedCount} source notes`);
-                }
-                else {
-                    LogStatus(`Memory Manager: No notes to consolidate`);
                 }
+                notesCreated = await this.CreateNoteRecords(extractedNotes, params.contextUser);
+                examplesCreated = await this.CreateExampleRecords(extractedExamples, params.contextUser);
+                if (this._verbose)
+                    LogStatus(`Memory Manager: Created ${notesCreated} notes and ${examplesCreated} examples`);
             }
-            const consolidationSummary = consolidatedCount > 0 ? ` Consolidated ${consolidatedCount} clusters (${archivedCount} notes archived).` : '';
+            const forceMaintenance = params.data?.forceMaintenance === true;
+            const triggerDecision = await this.shouldRunConsolidation(params.agent.ID, params.contextUser, forceMaintenance);
+            const maintenance = triggerDecision.shouldRun
+                ? await this.runMaintenancePhases(params.contextUser, forceMaintenance, triggerDecision.triggerType)
+                : { consolidatedCount: 0, consolidationArchived: 0, contradictionsFound: 0, contradictionsResolved: 0, contradictionsFlagged: 0, staleNotesArchived: 0, decayNotesArchived: 0, decayExamplesArchived: 0, importanceScored: 0, tierPromotions: 0 };
+            const maintenanceSummary = this.buildMaintenanceSummary(maintenance);
             const finalStep = {
                 terminate: true,
                 step: 'Success',
-                message: `Processed ${conversations.length} conversations (${totalMessages} messages) and ${agentRuns.length} agent runs. Created ${notesCreated} notes and ${examplesCreated} examples.${consolidationSummary}`,
+                message: `Processed ${conversations.length} conversations (${totalMessages} messages) and ${agentRuns.length} agent runs. Created ${notesCreated} notes and ${examplesCreated} examples.${maintenanceSummary}`,
                 newPayload: {
                     notesCreated,
                     examplesCreated,
                     conversationsProcessed: conversations.length,
                     messagesProcessed: totalMessages,
                     agentRunsProcessed: agentRuns.length,
-                    notesConsolidated: consolidatedCount,
-                    notesArchived: archivedCount
+                    ...maintenance
                 }
             };
             return { finalStep, stepCount: 1 };
@@ -1373,7 +2723,7 @@ let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
         }
     }
 };
-MemoryManagerAgent = __decorate([
+MemoryManagerAgent = MemoryManagerAgent_1 = __decorate([
     RegisterClass(BaseAgent, 'MemoryManagerAgent')
 ], MemoryManagerAgent);
 export { MemoryManagerAgent };