@memberjunction/ai-agents 6.2.0-edge.1 → 6.2.0-edge.3

package/dist/memory-manager-agent.js

@@ -6,13 +6,15 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 var MemoryManagerAgent_1;
 import { BaseAgent } from './base-agent.js';
-import { RegisterClass, CleanAndParseJSON } from '@memberjunction/global';
+import { RegisterClass, CleanAndParseJSON, IsPlainObject } from '@memberjunction/global';
 import { RunView, RunQuery, LogError, LogStatus, LogStatusEx } from '@memberjunction/core';
 import { IsInjectableNoteStatus } from '@memberjunction/core-entities';
 import { AIPromptRunner } from '@memberjunction/ai-prompts';
-import { AIPromptParams } from '@memberjunction/ai-core-plus';
+import { AIPromptParams, DescribeAnsweringModel } from '@memberjunction/ai-core-plus';
 import { AIEngine } from '@memberjunction/aiengine';
 import { UUIDsEqual } from '@memberjunction/global';
+import { AgentDecisionService } from './AgentDecisionService.js';
+import { BuildMemoryNoteQuestions, BuildMemoryNoteState, JudgeMemoryNotes, MemoryNotePromptQuestionCap, ChunkMemoryNotes, GroupMemoryNotesByConversation, MEMORY_NOTE_MIN_PROBABILITY } from './memory-note-gate.js';
 /**
  * Configuration for extraction limits to ensure sparsity
  */
@@ -131,7 +133,7 @@ const SOURCE_RUN_SCOPE_FIELDS = ['AgentID', 'CompanyID', 'UserID', 'PrimaryScope
  * 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 = MemoryManagerAgent_1 = class MemoryManagerAgent extends BaseAgent {
+let MemoryManagerAgent = class MemoryManagerAgent extends BaseAgent {
     constructor() {
         super(...arguments);
         /** Verbose logging flag from params.verbose */
@@ -142,6 +144,21 @@ let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends
         this._stepCounter = 0;
         /** Context user for step operations */
         this._contextUser = null;
+        /** Flag to enable typed decision gate instead of self-confidence threshold */
+        this._enableDecisionGate = false;
+    }
+    static { MemoryManagerAgent_1 = this; }
+    /**
+     * Whether the typed decision gate is enabled for filtering extracted memory notes.
+     * When false (default), uses the self-reported confidence filter (confidence >= 80).
+     * The gate also needs the master switch: the run's agent-type prompt params must set
+     * `decisionsEnabled: true` ({@link DecisionsEnabled}), or the confidence filter is used.
+     */
+    get EnableDecisionGate() {
+        return this._enableDecisionGate;
+    }
+    set EnableDecisionGate(value) {
+        this._enableDecisionGate = value;
     }
     /** Check if a string is a valid UUID format. Filters out LLM-generated placeholders like "user-uuid-here". */
     static isValidUUID(id) {
@@ -152,6 +169,7 @@ let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends
     /**
      * Create an agent run step record for observability.
      * Returns null if agentRunID is not set (defensive check).
+     * Protected so a test can stand in for the database.
      */
     async createRunStep(stepType, stepName, inputData, targetId) {
         if (!this._agentRunID || !this._contextUser) {
@@ -468,7 +486,7 @@ let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends
                 companyId: n.CompanyID
             }))
         };
-        return this.executeNoteExtraction(promptData, existingNotes, contextUser);
+        return this.executeNoteExtraction(promptData, existingNotes, contextUser, true);
     }
     /**
      * Mine corrective ("avoid this") memory from failed/cancelled agent runs. Each failed run
@@ -508,7 +526,9 @@ let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends
                 companyId: n.CompanyID
             }))
         };
-        const extracted = await this.executeNoteExtraction(promptData, existingNotes, contextUser);
+        // The decision gate was measured on conversation notes only; a corrective lesson from a failed run
+        // is not the durable user fact its question asks about, so these keep the self-reported rule.
+        const extracted = await this.executeNoteExtraction(promptData, existingNotes, contextUser, false);
         return this.markCorrectiveNotes(extracted);
     }
     /**
@@ -546,7 +566,7 @@ let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends
      *
      * Each step is its own private helper so the pipeline can be read top-to-bottom.
      */
-    async executeNoteExtraction(promptData, existingNotes, contextUser) {
+    async executeNoteExtraction(promptData, existingNotes, contextUser, decisionGateApplies) {
         // Step 1: run the extraction prompt and parse out the raw notes
         const rawNotes = await this.runNoteExtractionPrompt(promptData, existingNotes.length, contextUser);
         if (!rawNotes)
@@ -559,11 +579,11 @@ let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends
                 LogStatus(`Memory Manager: Raw note: [${note.type}] "${note.content}" (confidence: ${note.confidence})${note.mergeWithExistingIds?.length ? ` mergeWith: ${note.mergeWithExistingIds.join(', ')}` : ''}`);
             }
         }
-        // Step 3: filter by confidence and content length
-        const candidateNotes = this.filterByConfidenceAndLength(rawNotes);
+        // Step 3: filter by decision gate or confidence/content length
+        const candidateNotes = await this.filterCandidateNotes(rawNotes, promptData.conversationThreads, contextUser, decisionGateApplies);
         if (candidateNotes.length === 0) {
             if (this._verbose)
-                LogStatus('Memory Manager: No candidates passed confidence/length thresholds');
+                LogStatus('Memory Manager: No candidates passed gating thresholds');
             return [];
         }
         // Step 4: apply per-message and per-conversation sparsity caps
@@ -689,6 +709,134 @@ let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends
         }
         return filtered;
     }
+    /**
+     * Filters candidate notes using either the typed decision gate (if enabled, with the master switch
+     * on, and the notes are ones it was measured on) or the traditional self-reported confidence and
+     * length filters. Protected so a test can run the gate the way extraction does.
+     *
+     * @param decisionGateApplies Whether these notes may be gated: conversation notes only.
+     */
+    async filterCandidateNotes(notes, conversationThreads, contextUser, decisionGateApplies) {
+        if (!this._enableDecisionGate || !this.DecisionsEnabled(this._runPromptParams) || !decisionGateApplies) {
+            return this.filterByConfidenceAndLength(notes);
+        }
+        return this.filterWithDecisionGate(notes, conversationThreads, contextUser);
+    }
+    /**
+     * Evaluates candidate notes through the typed decision gate, one conversation at a time: each note
+     * is judged against the conversation it came from, as the gate was measured and calibrated, in
+     * batches no larger than the prompt models' declared MaxQuestionsPerCall. A note whose conversation
+     * can't be told keeps the self-reported rule. The kept notes keep their original order.
+     */
+    async filterWithDecisionGate(notes, conversationThreads, contextUser) {
+        const lengthFiltered = notes.filter(n => n.content && n.content.length >= EXTRACTION_CONFIG.minContentLength);
+        if (lengthFiltered.length === 0) {
+            if (this._verbose)
+                LogStatus('Memory Manager: No candidates passed content length check before decision gate');
+            return [];
+        }
+        const cap = MemoryNotePromptQuestionCap(AIEngine.Instance, 'Default Decision');
+        const grouping = GroupMemoryNotesByConversation(lengthFiltered, conversationThreads.map(t => ({
+            ConversationId: t.conversationId,
+            Turns: t.messages.map(m => ({ role: m.role, text: m.message }))
+        })));
+        const kept = new Set(this.filterByConfidenceAndLength(grouping.Unattributed));
+        if (grouping.Unattributed.length > 0) {
+            LogStatus(`Memory Manager: ${grouping.Unattributed.length} note(s) name no conversation of this batch, so they keep the confidence filter`);
+        }
+        for (const conversation of grouping.Batches) {
+            for (const batch of ChunkMemoryNotes(conversation.Notes, cap)) {
+                const batchPassed = await this.judgeDecisionBatch(batch, conversation.ConversationId, conversation.Excerpt, contextUser, cap);
+                batchPassed.forEach(note => kept.add(note));
+            }
+        }
+        return lengthFiltered.filter(note => kept.has(note));
+    }
+    /**
+     * Runs a decision prompt call for a single batch of candidate notes from one conversation, falling
+     * back to the confidence filter if the decision call fails. The call's step joins the agent run's
+     * steps, and carries the call's prompt run, so the run's cost and token totals count it.
+     */
+    async judgeDecisionBatch(batch, conversationId, excerpt, contextUser, modelCap) {
+        const questions = BuildMemoryNoteQuestions(batch);
+        const state = BuildMemoryNoteState(batch, excerpt);
+        const step = await this.createRunStep('Decision', 'Judge Extracted Notes', {
+            conversationId,
+            noteCount: batch.length,
+            modelCap
+        });
+        if (step) {
+            this.AgentRun?.Steps.push(step);
+        }
+        const decisionService = this._agentDecisionService ?? new AgentDecisionService();
+        const result = await decisionService.Ask({
+            ContextUser: contextUser,
+            PromptName: 'Default Decision',
+            State: state,
+            Questions: questions,
+            AgentID: this.AgentRun?.AgentID ?? undefined,
+            CancellationToken: this._cancellationToken
+        });
+        await this.recordDecisionStep(step, result);
+        if (!result.success) {
+            LogStatus(`Memory Manager: Decision call failed (${result.errorMessage ?? 'unknown error'}), falling back to confidence filter for batch`);
+            return this.filterByConfidenceAndLength(batch);
+        }
+        const answeredBy = { ModelName: result.modelInfo?.modelName, ResolvedModel: result.DecisionResult?.ResolvedModel };
+        return this.evaluateDecisionVerdict(batch, result.Answers, answeredBy);
+    }
+    /**
+     * Puts the decision's prompt run on its step, which is how the agent run counts the call's cost
+     * and tokens, and marks the step complete.
+     */
+    async recordDecisionStep(step, result) {
+        if (!step)
+            return;
+        this.attachDecisionPromptRun(step, result);
+        await this.finalizeRunStep(step, result.success, { answers: result.Answers, model: result.modelInfo?.modelName, resolvedModel: result.DecisionResult?.ResolvedModel }, result.promptRun?.ID, result.errorMessage);
+    }
+    /** The answering models already logged as having no memory-note calibration, so each is logged once per process. */
+    static { this._uncalibratedGateModelsLogged = new Set(); }
+    /**
+     * Logs, once per model, that the decision gate fell back to the confidence filter because the
+     * model that answered has no memory-note calibration. That happens on a failover, when a decision
+     * model is added or renamed, or when a vendor model moves to another version (Jev's `APIName`).
+     */
+    static logUncalibratedGateModel(answeredBy) {
+        const described = DescribeAnsweringModel(answeredBy);
+        if (MemoryManagerAgent_1._uncalibratedGateModelsLogged.has(described)) {
+            return;
+        }
+        MemoryManagerAgent_1._uncalibratedGateModelsLogged.add(described);
+        LogStatus(`Memory Manager: ${described} has no memory-note calibration (MEMORY_NOTE_DECISION_CALIBRATION), so the decision gate falls back to the confidence filter for its batches`);
+    }
+    /**
+     * Applies calibrated probabilities to judge which candidate notes to keep. A note the calibrated
+     * model gave no usable answer for keeps the self-reported rule, as a failed call's batch does.
+     */
+    evaluateDecisionVerdict(batch, answers, answeredBy) {
+        const verdict = JudgeMemoryNotes(answers, batch, answeredBy, MEMORY_NOTE_MIN_PROBABILITY);
+        // Only a calibrated model replaces the self-reported confidence: one that answered without a
+        // calibration (a failover, or a calibrated model at another version) has not been shown to
+        // beat it, so the batch falls back to it.
+        if (!verdict.Calibrated) {
+            MemoryManagerAgent_1.logUncalibratedGateModel(answeredBy);
+            return this.filterByConfidenceAndLength(batch);
+        }
+        if (this._verbose) {
+            LogStatus(`Memory Manager: Decision gate evaluated ${batch.length} notes (calibrated: ${verdict.Calibrated}): kept ${verdict.KeptNotes.length}`);
+            for (const judged of verdict.JudgedNotes) {
+                LogStatus(`Memory Manager: Note [${judged.Note.type}] "${judged.Note.content.slice(0, 50)}..." -> kept: ${judged.Kept} (prob: ${judged.CalibratedProbability ?? judged.RawProbability ?? 'none'}), reason: ${judged.Reason}`);
+            }
+        }
+        const unanswered = verdict.JudgedNotes.filter(j => j.CalibratedProbability === undefined).map(j => j.Note);
+        if (unanswered.length === 0) {
+            return verdict.KeptNotes;
+        }
+        LogStatus(`Memory Manager: ${DescribeAnsweringModel(answeredBy)} gave no usable answer for ${unanswered.length} of ${batch.length} note(s), which keep the confidence filter`);
+        const kept = new Set([...verdict.KeptNotes, ...this.filterByConfidenceAndLength(unanswered)]);
+        return batch.filter(note => kept.has(note));
+    }
     /**
      * Enforce per-message and per-conversation note caps from EXTRACTION_CONFIG.
      * Drops any candidates that would exceed either cap.
@@ -2886,6 +3034,16 @@ let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends
         });
         return created;
     }
+    /**
+     * The run's merged agent-type prompt params: the agent type's defaults, then the Memory Manager
+     * agent's own `AgentTypePromptParams`, then the run's `data.__agentTypePromptParams`. This agent
+     * renders no Loop prompt, so it merges them itself, once per run.
+     */
+    runPromptParams(params) {
+        const agentType = AIEngine.Instance.AgentTypes.find(at => UUIDsEqual(at.ID, params.agent.TypeID));
+        const override = params.data?.__agentTypePromptParams;
+        return this.buildAgentTypePromptParams(agentType, params.agent, IsPlainObject(override) ? override : undefined);
+    }
     /**
      * Main execution method called by scheduler
      */
@@ -2893,6 +3051,11 @@ let MemoryManagerAgent = MemoryManagerAgent_1 = class MemoryManagerAgent extends
         try {
             // Use verbose flag from agent execution params or data payload (UI passes it via data)
             this._verbose = params.verbose || params.data?.verbose || false;
+            if (typeof params.data?.enableDecisionGate === 'boolean') {
+                this._enableDecisionGate = params.data.enableDecisionGate;
+            }
+            this._runPromptParams = this.runPromptParams(params);
+            this._cancellationToken = params.cancellationToken;
             // Initialize observability state for this run
             this._agentRunID = this.AgentRun?.ID || null;
             this._stepCounter = 0;