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

package/dist/memory-note-gate.d.ts

@@ -0,0 +1,208 @@
+/**
+ * @fileoverview Pure typed-decision gate module for extracted memory notes.
+ *
+ * Implements question generation, state projection, Platt calibration application,
+ * and note filtering for durable memory candidates.
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { type AIModelConfiguration, type DecisionAnswer, type LikelihoodQuestion, type PlattCalibration } from '@memberjunction/ai';
+import { type DecisionAnsweringModel, type DecisionModelCalibration, type MJAIPromptEntityExtended } from '@memberjunction/ai-core-plus';
+import type { MJAIModelVendorEntity, MJAIPromptModelEntity } from '@memberjunction/core-entities';
+/**
+ * Standard instructions used for Likelihood questions evaluating candidate memory notes.
+ */
+export declare const MEMORY_NOTE_QUESTION_INSTRUCTIONS = "This note is a correct, durable fact or preference about the user, their organization or how they want the agent to work, that is worth remembering in future conversations; it is not a one-off request, a guess, or a detail of this conversation only.";
+/**
+ * Maximum character limit for a candidate note's content in the decision state.
+ */
+export declare const MEMORY_NOTE_MAX_CONTENT_CHARS = 1000;
+/**
+ * Maximum character limit for conversation excerpts in the decision state.
+ */
+export declare const MEMORY_NOTE_MAX_EXCERPT_CHARS = 4000;
+/**
+ * The least **calibrated** probability at which a candidate note is kept.
+ *
+ * Set from the memory-note gate measurement (plan Task 3.4, 2026-09-29): 60 synthetic conversations,
+ * 337 candidate notes labelled durable, ephemeral, wrong or speculative, two repeats. At a calibrated
+ * 0.6, Jev kept durable notes at 96.1% precision and 95.4% recall, and kept 6.2% of the
+ * conversation-only (ephemeral) notes. A proxy self-report scorer's `confidence >= 80` kept 40.0% of
+ * them at 85.3% precision and 98.7% recall. Neither kept a wrong note; the gate kept 3.4% of the
+ * speculative ones, the proxy none.
+ *
+ * **The baseline is a proxy, not today's Memory Manager.** Its self-reported confidence came from a
+ * separate scoring call with a four-band rubric (90-100 stated, 75-89 strongly implied, 50-74
+ * possible, below 50 skip). Production's `Memory Manager - Extract Notes` template has three bands
+ * (90-100, 80-89, below 80 skip), and skip rules the proxy doesn't have: one-time requests, matters
+ * resolved within the conversation, and task-scoped clarifications. Those rules drop exactly the
+ * ephemeral notes counted here before any confidence filter runs, so production probably keeps fewer
+ * than 40% of them. The gate's own figures stand; the comparison is against the proxy.
+ */
+export declare const MEMORY_NOTE_MIN_PROBABILITY = 0.6;
+/**
+ * Platt calibration of the memory-note Likelihood, each tied to the exact model it was fitted on (see
+ * `FindDecisionCalibration` in `@memberjunction/ai-core-plus`): the MJ decision model that answered
+ * (`ModelName`, from `modelInfo.modelName`) and the model its driver reports behind it
+ * (`ResolvedModel`, from `DecisionResult.ResolvedModel`). Fitted on the memory-note gate measurement:
+ * - **Jev** at its pinned `APIName`, `typesafe/jev-1.13-20260917`, which it reports back as the
+ *   resolved model.
+ *
+ * Only models that beat the proxy self-report scorer (see {@link MEMORY_NOTE_MIN_PROBABILITY}) are
+ * listed. LLM Decision was measured and left out: at any threshold it kept more wrong and speculative
+ * notes than the proxy's `confidence >= 80` (at a calibrated 0.6, 11.5% of wrong notes). A batch answered by any other model, including Jev at another version,
+ * falls back to the self-reported confidence rule, as a failed decision does. Refit, and add the new
+ * pair, whenever a model, its version or the question changes.
+ */
+export declare const MEMORY_NOTE_DECISION_CALIBRATION: readonly DecisionModelCalibration<PlattCalibration>[];
+/**
+ * Shape of a candidate note evaluated by the decision gate.
+ */
+export interface MemoryNoteCandidate {
+    readonly type: 'Preference' | 'Constraint' | 'Context' | 'Issue' | string;
+    readonly content: string;
+    readonly confidence?: number;
+    readonly scopeLevel?: 'global' | 'company' | 'user' | string;
+    readonly agentId?: string | null;
+    readonly userId?: string | null;
+    readonly companyId?: string | null;
+    /** The conversation the note was extracted from: the one it is judged against. */
+    readonly sourceConversationId?: string | null;
+}
+/** One turn of the conversation a note came from, as the gate's state quotes it. */
+export interface MemoryNoteExcerptTurn {
+    readonly role: string;
+    readonly text: string;
+}
+/** A conversation candidate notes may have come from. */
+export interface MemoryNoteConversation {
+    readonly ConversationId: string;
+    readonly Turns: ReadonlyArray<MemoryNoteExcerptTurn>;
+}
+/** The candidate notes of one conversation, with that conversation's excerpt: one decision state. */
+export interface MemoryNoteConversationBatch<T extends MemoryNoteCandidate = MemoryNoteCandidate> {
+    readonly ConversationId: string;
+    readonly Excerpt: string;
+    readonly Notes: T[];
+}
+/** Candidate notes grouped by the conversation they came from. */
+export interface MemoryNoteConversationGrouping<T extends MemoryNoteCandidate = MemoryNoteCandidate> {
+    /** One batch per conversation with notes, in the conversations' order; each keeps its notes' order. */
+    readonly Batches: MemoryNoteConversationBatch<T>[];
+    /** The notes whose conversation could not be told: they must not be judged against any. */
+    readonly Unattributed: T[];
+}
+/**
+ * Projection of a candidate note in the decision state payload.
+ */
+export interface MemoryNoteStateItem {
+    readonly type: string;
+    readonly scope: string;
+    readonly content: string;
+}
+/**
+ * Decision state object sent with the decision prompt.
+ */
+export type MemoryNoteDecisionState = {
+    readonly notes: Record<string, MemoryNoteStateItem>;
+    readonly conversationExcerpt?: string;
+};
+/**
+ * Individual evaluated note verdict.
+ */
+export interface JudgedMemoryNote<T extends MemoryNoteCandidate = MemoryNoteCandidate> {
+    readonly Note: T;
+    readonly Key: string;
+    readonly RawProbability?: number;
+    readonly CalibratedProbability?: number;
+    readonly Kept: boolean;
+    readonly Reason: string;
+}
+/**
+ * Aggregate verdict for a batch of evaluated memory notes.
+ */
+export interface MemoryNoteGateVerdict<T extends MemoryNoteCandidate = MemoryNoteCandidate> {
+    readonly KeptNotes: T[];
+    readonly JudgedNotes: JudgedMemoryNote<T>[];
+    /** The model that answered, as the decision result reported it. */
+    readonly AnsweredBy: DecisionAnsweringModel;
+    readonly Calibrated: boolean;
+}
+/**
+ * What {@link MemoryNotePromptQuestionCap} reads from the AI engine to resolve the question limit.
+ * `AIEngine.Instance` satisfies it.
+ */
+export interface MemoryNoteEngineSource {
+    readonly Prompts: ReadonlyArray<Pick<MJAIPromptEntityExtended, 'ID' | 'Name'>>;
+    readonly PromptModels: ReadonlyArray<Pick<MJAIPromptModelEntity, 'PromptID' | 'ModelID' | 'VendorID' | 'Status'>>;
+    readonly ModelVendors: ReadonlyArray<Pick<MJAIModelVendorEntity, 'ID' | 'ModelID' | 'VendorID'>>;
+    GetEffectiveModelConfiguration(modelID: string, vendorModelVendorID?: string): Pick<AIModelConfiguration, 'Decision'> | null;
+}
+/**
+ * Builds likelihood questions for each candidate note, keyed n1, n2, etc.
+ *
+ * Each question quotes its own note. Question keys are labels for code, not instructions to the
+ * model, and a native decision driver (Jev) may answer each question separately against the state,
+ * so a question that only named its key would ask the same thing about every note. Measured: with
+ * the note left out of the question, Jev's answers were at chance (AUC 0.51).
+ *
+ * @param notes The candidate notes to build questions for.
+ */
+export declare function BuildMemoryNoteQuestions(notes: ReadonlyArray<MemoryNoteCandidate>): Record<string, LikelihoodQuestion>;
+/** One note's question: the durable-memory test, then the note itself, capped. */
+export declare function MemoryNoteQuestionInstructions(note: MemoryNoteCandidate): string;
+/**
+ * The conversation a batch of notes came from, as the gate's state quotes it: one `[role]: text`
+ * line per turn. The measurement rig wrote its corpus excerpts with this, one conversation per
+ * state, which is what the Platt fit and the threshold were set on; {@link BuildMemoryNoteState}
+ * caps it.
+ *
+ * @param turns The conversation's turns, in order.
+ */
+export declare function FormatMemoryNoteExcerpt(turns: ReadonlyArray<MemoryNoteExcerptTurn>): string;
+/**
+ * Groups candidate notes by the conversation they came from, so each note is judged against its own
+ * conversation, as the gate was measured: one conversation per decision state. A note whose
+ * `sourceConversationId` names none of the conversations belongs to the only conversation when there
+ * is one; with several, it is unattributed, and must not be judged against another conversation.
+ *
+ * @param notes The candidate notes.
+ * @param conversations The conversations they were extracted from.
+ */
+export declare function GroupMemoryNotesByConversation<T extends MemoryNoteCandidate>(notes: ReadonlyArray<T>, conversations: ReadonlyArray<MemoryNoteConversation>): MemoryNoteConversationGrouping<T>;
+/**
+ * Builds the state object for the decision prompt, capping content and excerpts.
+ *
+ * @param notes Candidate notes to project.
+ * @param sourceExcerpts Optional conversation thread context.
+ */
+export declare function BuildMemoryNoteState(notes: ReadonlyArray<MemoryNoteCandidate>, sourceExcerpts?: string | Record<string, string> | readonly string[]): MemoryNoteDecisionState;
+/**
+ * Evaluates decision answers against candidate notes using Platt calibration.
+ *
+ * The calibration is the one fitted on the exact model that answered (`FindDecisionCalibration`).
+ * An answer from any other model, including a calibrated model at another version, is uncalibrated
+ * and keeps nothing (fails safe toward writing no durable memory).
+ *
+ * @param answers The answers returned by the decision runner.
+ * @param notes The candidate notes evaluated.
+ * @param answeredBy The model that answered: the MJ decision model and the model its driver resolved.
+ * @param threshold The calibrated probability at which a note is kept (default: {@link MEMORY_NOTE_MIN_PROBABILITY}, 0.6).
+ * @param calibrations Optional calibration table override (defaults to {@link MEMORY_NOTE_DECISION_CALIBRATION}).
+ */
+export declare function JudgeMemoryNotes<T extends MemoryNoteCandidate = MemoryNoteCandidate>(answers: Record<string, DecisionAnswer> | undefined, notes: ReadonlyArray<T>, answeredBy?: DecisionAnsweringModel, threshold?: number, calibrations?: readonly DecisionModelCalibration<PlattCalibration>[]): MemoryNoteGateVerdict<T>;
+/**
+ * Looks up the prompt's configured MaxQuestionsPerCall limit from active PromptModels.
+ *
+ * @param engine AIEngine metadata source.
+ * @param promptName Name of the decision prompt (default: 'Default Decision').
+ */
+export declare function MemoryNotePromptQuestionCap(engine: MemoryNoteEngineSource, promptName?: string): number | undefined;
+/**
+ * Splits candidate notes into chunks not exceeding the specified chunk size.
+ *
+ * @param notes The notes to chunk.
+ * @param chunkSize Maximum number of notes per chunk.
+ */
+export declare function ChunkMemoryNotes<T>(notes: ReadonlyArray<T>, chunkSize?: number): T[][];
+//# sourceMappingURL=memory-note-gate.d.ts.map

package/dist/memory-note-gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-note-gate.d.ts","sourceRoot":"","sources":["../src/memory-note-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAEH,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACxB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAGH,KAAK,sBAAsB,EAC3B,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAChC,MAAM,8BAA8B,CAAC;AACtC,OAAO,KAAK,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AAGlG;;GAEG;AACH,eAAO,MAAM,iCAAiC,8PACiN,CAAC;AAEhQ;;GAEG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;GAEG;AACH,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAElD;;;;;;;;;;;;;;;;;GAiBG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gCAAgC,EAAE,SAAS,wBAAwB,CAAC,gBAAgB,CAAC,EAEhG,CAAC;AAEH;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAC1E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,CAAC;IAC7D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,kFAAkF;IAClF,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACjD;AAED,oFAAoF;AACpF,MAAM,WAAW,qBAAqB;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACzB;AAED,yDAAyD;AACzD,MAAM,WAAW,sBAAsB;IACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,qBAAqB,CAAC,CAAC;CACxD;AAED,qGAAqG;AACrG,MAAM,WAAW,2BAA2B,CAAC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IAC5F,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC;CACvB;AAED,kEAAkE;AAClE,MAAM,WAAW,8BAA8B,CAAC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IAC/F,uGAAuG;IACvG,QAAQ,CAAC,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC,EAAE,CAAC;IACnD,2FAA2F;IAC3F,QAAQ,CAAC,YAAY,EAAE,CAAC,EAAE,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,MAAM,uBAAuB,GAAG;IAClC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACpD,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACzC,CAAC;AAEF;;GAEG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IACjF,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IACxC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB,CAAC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB;IACtF,QAAQ,CAAC,SAAS,EAAE,CAAC,EAAE,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5C,mEAAmE;IACnE,QAAQ,CAAC,UAAU,EAAE,sBAAsB,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACnC,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC,IAAI,CAAC,wBAAwB,EAAE,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC;IAC/E,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,IAAI,CAAC,qBAAqB,EAAE,UAAU,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC,CAAC,CAAC;IAClH,QAAQ,CAAC,YAAY,EAAE,aAAa,CAAC,IAAI,CAAC,qBAAqB,EAAE,IAAI,GAAG,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC;IACjG,8BAA8B,CAAC,OAAO,EAAE,MAAM,EAAE,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,oBAAoB,EAAE,UAAU,CAAC,GAAG,IAAI,CAAC;CAChI;AAED;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CACpC,KAAK,EAAE,aAAa,CAAC,mBAAmB,CAAC,GAC1C,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CASpC;AAED,kFAAkF;AAClF,wBAAgB,8BAA8B,CAAC,IAAI,EAAE,mBAAmB,GAAG,MAAM,CAGhF;AAED;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,aAAa,CAAC,qBAAqB,CAAC,GAAG,MAAM,CAE3F;AAQD;;;;;;;;GAQG;AACH,wBAAgB,8BAA8B,CAAC,CAAC,SAAS,mBAAmB,EACxE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,aAAa,EAAE,aAAa,CAAC,sBAAsB,CAAC,GACrD,8BAA8B,CAAC,CAAC,CAAC,CAenC;AAyBD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAChC,KAAK,EAAE,aAAa,CAAC,mBAAmB,CAAC,EACzC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,MAAM,EAAE,GACrE,uBAAuB,CAazB;AAqED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,mBAAmB,GAAG,mBAAmB,EAChF,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,GAAG,SAAS,EACnD,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EACvB,UAAU,GAAE,sBAA2B,EACvC,SAAS,GAAE,MAAoC,EAC/C,YAAY,GAAE,SAAS,wBAAwB,CAAC,gBAAgB,CAAC,EAAqC,GACvG,qBAAqB,CAAC,CAAC,CAAC,CAuB1B;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACvC,MAAM,EAAE,sBAAsB,EAC9B,UAAU,GAAE,MAA2B,GACxC,MAAM,GAAG,SAAS,CAmBpB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,CAAC,EAAE,EAAE,CAStF"}

package/dist/memory-note-gate.js

@@ -0,0 +1,294 @@
+/**
+ * @fileoverview Pure typed-decision gate module for extracted memory notes.
+ *
+ * Implements question generation, state projection, Platt calibration application,
+ * and note filtering for durable memory candidates.
+ *
+ * @module @memberjunction/ai-agents
+ */
+import { ApplyPlattCalibration } from '@memberjunction/ai';
+import { DescribeAnsweringModel, FindDecisionCalibration } from '@memberjunction/ai-core-plus';
+import { UUIDsEqual } from '@memberjunction/global';
+/**
+ * Standard instructions used for Likelihood questions evaluating candidate memory notes.
+ */
+export const MEMORY_NOTE_QUESTION_INSTRUCTIONS = 'This note is a correct, durable fact or preference about the user, their organization or how they want the agent to work, that is worth remembering in future conversations; it is not a one-off request, a guess, or a detail of this conversation only.';
+/**
+ * Maximum character limit for a candidate note's content in the decision state.
+ */
+export const MEMORY_NOTE_MAX_CONTENT_CHARS = 1000;
+/**
+ * Maximum character limit for conversation excerpts in the decision state.
+ */
+export const MEMORY_NOTE_MAX_EXCERPT_CHARS = 4000;
+/**
+ * The least **calibrated** probability at which a candidate note is kept.
+ *
+ * Set from the memory-note gate measurement (plan Task 3.4, 2026-09-29): 60 synthetic conversations,
+ * 337 candidate notes labelled durable, ephemeral, wrong or speculative, two repeats. At a calibrated
+ * 0.6, Jev kept durable notes at 96.1% precision and 95.4% recall, and kept 6.2% of the
+ * conversation-only (ephemeral) notes. A proxy self-report scorer's `confidence >= 80` kept 40.0% of
+ * them at 85.3% precision and 98.7% recall. Neither kept a wrong note; the gate kept 3.4% of the
+ * speculative ones, the proxy none.
+ *
+ * **The baseline is a proxy, not today's Memory Manager.** Its self-reported confidence came from a
+ * separate scoring call with a four-band rubric (90-100 stated, 75-89 strongly implied, 50-74
+ * possible, below 50 skip). Production's `Memory Manager - Extract Notes` template has three bands
+ * (90-100, 80-89, below 80 skip), and skip rules the proxy doesn't have: one-time requests, matters
+ * resolved within the conversation, and task-scoped clarifications. Those rules drop exactly the
+ * ephemeral notes counted here before any confidence filter runs, so production probably keeps fewer
+ * than 40% of them. The gate's own figures stand; the comparison is against the proxy.
+ */
+export const MEMORY_NOTE_MIN_PROBABILITY = 0.6;
+/**
+ * Platt calibration of the memory-note Likelihood, each tied to the exact model it was fitted on (see
+ * `FindDecisionCalibration` in `@memberjunction/ai-core-plus`): the MJ decision model that answered
+ * (`ModelName`, from `modelInfo.modelName`) and the model its driver reports behind it
+ * (`ResolvedModel`, from `DecisionResult.ResolvedModel`). Fitted on the memory-note gate measurement:
+ * - **Jev** at its pinned `APIName`, `typesafe/jev-1.13-20260917`, which it reports back as the
+ *   resolved model.
+ *
+ * Only models that beat the proxy self-report scorer (see {@link MEMORY_NOTE_MIN_PROBABILITY}) are
+ * listed. LLM Decision was measured and left out: at any threshold it kept more wrong and speculative
+ * notes than the proxy's `confidence >= 80` (at a calibrated 0.6, 11.5% of wrong notes). A batch answered by any other model, including Jev at another version,
+ * falls back to the self-reported confidence rule, as a failed decision does. Refit, and add the new
+ * pair, whenever a model, its version or the question changes.
+ */
+export const MEMORY_NOTE_DECISION_CALIBRATION = Object.freeze([
+    Object.freeze({ ModelName: 'Jev', ResolvedModel: 'typesafe/jev-1.13-20260917', Calibration: Object.freeze({ A: 3.6391, B: -5.7059 }) })
+]);
+/**
+ * Builds likelihood questions for each candidate note, keyed n1, n2, etc.
+ *
+ * Each question quotes its own note. Question keys are labels for code, not instructions to the
+ * model, and a native decision driver (Jev) may answer each question separately against the state,
+ * so a question that only named its key would ask the same thing about every note. Measured: with
+ * the note left out of the question, Jev's answers were at chance (AUC 0.51).
+ *
+ * @param notes The candidate notes to build questions for.
+ */
+export function BuildMemoryNoteQuestions(notes) {
+    const questions = {};
+    for (let i = 0; i < notes.length; i++) {
+        questions[`n${i + 1}`] = {
+            Kind: 'Likelihood',
+            Instructions: MemoryNoteQuestionInstructions(notes[i])
+        };
+    }
+    return questions;
+}
+/** One note's question: the durable-memory test, then the note itself, capped. */
+export function MemoryNoteQuestionInstructions(note) {
+    const content = (note.content ?? '').slice(0, MEMORY_NOTE_MAX_CONTENT_CHARS);
+    return `${MEMORY_NOTE_QUESTION_INSTRUCTIONS}\n\nThe note (${note.type}, ${note.scopeLevel ?? 'user'} scope): "${content}"`;
+}
+/**
+ * The conversation a batch of notes came from, as the gate's state quotes it: one `[role]: text`
+ * line per turn. The measurement rig wrote its corpus excerpts with this, one conversation per
+ * state, which is what the Platt fit and the threshold were set on; {@link BuildMemoryNoteState}
+ * caps it.
+ *
+ * @param turns The conversation's turns, in order.
+ */
+export function FormatMemoryNoteExcerpt(turns) {
+    return turns.map(turn => `[${turn.role}]: ${turn.text}`).join('\n');
+}
+/** The conversation a note names, compared as UUIDs, or null when it names none of them. */
+function conversationOf(note, conversations) {
+    const source = note.sourceConversationId;
+    return source ? conversations.find(c => UUIDsEqual(c.ConversationId, source)) ?? null : null;
+}
+/**
+ * Groups candidate notes by the conversation they came from, so each note is judged against its own
+ * conversation, as the gate was measured: one conversation per decision state. A note whose
+ * `sourceConversationId` names none of the conversations belongs to the only conversation when there
+ * is one; with several, it is unattributed, and must not be judged against another conversation.
+ *
+ * @param notes The candidate notes.
+ * @param conversations The conversations they were extracted from.
+ */
+export function GroupMemoryNotesByConversation(notes, conversations) {
+    const byConversation = new Map();
+    const unattributed = [];
+    for (const note of notes) {
+        const conversation = conversationOf(note, conversations) ?? (conversations.length === 1 ? conversations[0] : null);
+        if (!conversation) {
+            unattributed.push(note);
+            continue;
+        }
+        byConversation.set(conversation, [...(byConversation.get(conversation) ?? []), note]);
+    }
+    const batches = conversations
+        .filter(c => byConversation.has(c))
+        .map(c => ({ ConversationId: c.ConversationId, Excerpt: FormatMemoryNoteExcerpt(c.Turns), Notes: byConversation.get(c) ?? [] }));
+    return { Batches: batches, Unattributed: unattributed };
+}
+/**
+ * Formats source conversation excerpts into a single string within max character limits.
+ */
+function formatExcerpt(sourceExcerpts) {
+    if (!sourceExcerpts) {
+        return undefined;
+    }
+    let text;
+    if (typeof sourceExcerpts === 'string') {
+        text = sourceExcerpts.trim();
+    }
+    else if (Array.isArray(sourceExcerpts)) {
+        text = sourceExcerpts.join('\n---\n').trim();
+    }
+    else {
+        text = Object.entries(sourceExcerpts)
+            .map(([id, excerpt]) => `[${id}]: ${excerpt}`)
+            .join('\n---\n')
+            .trim();
+    }
+    return text.length > 0 ? text.slice(0, MEMORY_NOTE_MAX_EXCERPT_CHARS) : undefined;
+}
+/**
+ * Builds the state object for the decision prompt, capping content and excerpts.
+ *
+ * @param notes Candidate notes to project.
+ * @param sourceExcerpts Optional conversation thread context.
+ */
+export function BuildMemoryNoteState(notes, sourceExcerpts) {
+    const notesMap = {};
+    for (let i = 0; i < notes.length; i++) {
+        const note = notes[i];
+        const key = `n${i + 1}`;
+        notesMap[key] = {
+            type: note.type,
+            scope: note.scopeLevel ?? 'user',
+            content: (note.content ?? '').slice(0, MEMORY_NOTE_MAX_CONTENT_CHARS)
+        };
+    }
+    const excerpt = formatExcerpt(sourceExcerpts);
+    return excerpt ? { notes: notesMap, conversationExcerpt: excerpt } : { notes: notesMap };
+}
+/**
+ * Extracts raw probability from a decision answer if it is a valid Likelihood.
+ */
+function extractRawProbability(answer) {
+    if (!answer || answer.Kind !== 'Likelihood') {
+        return undefined;
+    }
+    if (typeof answer.Probability !== 'number' || !Number.isFinite(answer.Probability)) {
+        return undefined;
+    }
+    return answer.Probability;
+}
+/**
+ * Judges a single note when the model is uncalibrated.
+ */
+function judgeUncalibratedNote(note, key, rawProb, answeredBy) {
+    const reason = answeredBy.ModelName?.trim() || answeredBy.ResolvedModel?.trim()
+        ? `The answering model ${DescribeAnsweringModel(answeredBy)} has no memory-note calibration, so the gate keeps nothing`
+        : 'No answering model was reported, so the gate keeps nothing';
+    return {
+        Note: note,
+        Key: key,
+        RawProbability: rawProb,
+        Kept: false,
+        Reason: reason
+    };
+}
+/**
+ * Judges a single note when calibration parameters are present.
+ */
+function judgeCalibratedNote(note, key, rawProb, calibration, threshold) {
+    if (rawProb === undefined) {
+        return {
+            Note: note,
+            Key: key,
+            Kept: false,
+            Reason: `Missing or invalid Likelihood answer for question '${key}'`
+        };
+    }
+    const calProb = ApplyPlattCalibration(rawProb, calibration);
+    const kept = calProb >= threshold;
+    const reason = kept
+        ? `Calibrated probability ${calProb.toFixed(4)} >= threshold ${threshold}`
+        : `Calibrated probability ${calProb.toFixed(4)} < threshold ${threshold}`;
+    return {
+        Note: note,
+        Key: key,
+        RawProbability: rawProb,
+        CalibratedProbability: calProb,
+        Kept: kept,
+        Reason: reason
+    };
+}
+/**
+ * Evaluates decision answers against candidate notes using Platt calibration.
+ *
+ * The calibration is the one fitted on the exact model that answered (`FindDecisionCalibration`).
+ * An answer from any other model, including a calibrated model at another version, is uncalibrated
+ * and keeps nothing (fails safe toward writing no durable memory).
+ *
+ * @param answers The answers returned by the decision runner.
+ * @param notes The candidate notes evaluated.
+ * @param answeredBy The model that answered: the MJ decision model and the model its driver resolved.
+ * @param threshold The calibrated probability at which a note is kept (default: {@link MEMORY_NOTE_MIN_PROBABILITY}, 0.6).
+ * @param calibrations Optional calibration table override (defaults to {@link MEMORY_NOTE_DECISION_CALIBRATION}).
+ */
+export function JudgeMemoryNotes(answers, notes, answeredBy = {}, threshold = MEMORY_NOTE_MIN_PROBABILITY, calibrations = MEMORY_NOTE_DECISION_CALIBRATION) {
+    const calibration = FindDecisionCalibration(calibrations, answeredBy);
+    const judgedNotes = [];
+    for (let i = 0; i < notes.length; i++) {
+        const note = notes[i];
+        const key = `n${i + 1}`;
+        const rawProb = extractRawProbability(answers?.[key]);
+        const judged = calibration
+            ? judgeCalibratedNote(note, key, rawProb, calibration, threshold)
+            : judgeUncalibratedNote(note, key, rawProb, answeredBy);
+        judgedNotes.push(judged);
+    }
+    const keptNotes = judgedNotes.filter(j => j.Kept).map(j => j.Note);
+    return {
+        KeptNotes: keptNotes,
+        JudgedNotes: judgedNotes,
+        AnsweredBy: answeredBy,
+        Calibrated: calibration !== null
+    };
+}
+/**
+ * Looks up the prompt's configured MaxQuestionsPerCall limit from active PromptModels.
+ *
+ * @param engine AIEngine metadata source.
+ * @param promptName Name of the decision prompt (default: 'Default Decision').
+ */
+export function MemoryNotePromptQuestionCap(engine, promptName = 'Default Decision') {
+    const target = promptName.trim().toLowerCase();
+    const prompt = engine.Prompts?.find(p => (p.Name ?? '').trim().toLowerCase() === target);
+    if (!prompt) {
+        return undefined;
+    }
+    const caps = (engine.PromptModels ?? [])
+        .filter(pm => UUIDsEqual(pm.PromptID, prompt.ID) && (pm.Status === 'Active' || pm.Status === 'Preview'))
+        .map(pm => {
+        const modelVendor = pm.VendorID
+            ? (engine.ModelVendors ?? []).find(mv => UUIDsEqual(mv.ModelID, pm.ModelID) && UUIDsEqual(mv.VendorID, pm.VendorID))
+            : undefined;
+        return engine.GetEffectiveModelConfiguration(pm.ModelID, modelVendor?.ID)?.Decision
+            ?.MaxQuestionsPerCall;
+    });
+    const declared = caps.filter((cap) => typeof cap === 'number' && cap > 0);
+    return declared.length > 0 ? Math.min(...declared) : undefined;
+}
+/**
+ * Splits candidate notes into chunks not exceeding the specified chunk size.
+ *
+ * @param notes The notes to chunk.
+ * @param chunkSize Maximum number of notes per chunk.
+ */
+export function ChunkMemoryNotes(notes, chunkSize) {
+    if (!chunkSize || chunkSize <= 0 || !Number.isFinite(chunkSize) || notes.length <= chunkSize) {
+        return [Array.from(notes)];
+    }
+    const chunks = [];
+    for (let i = 0; i < notes.length; i += chunkSize) {
+        chunks.push(notes.slice(i, i + chunkSize));
+    }
+    return chunks;
+}
+//# sourceMappingURL=memory-note-gate.js.map

package/dist/memory-note-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-note-gate.js","sourceRoot":"","sources":["../src/memory-note-gate.ts"],"names":[],"mappings":"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"}

package/dist/native-tools/action-tool-builder.d.ts

@@ -14,6 +14,8 @@ export interface ActionToolBinding {
     /** The Action the framework dispatches when that name comes back. */
     action: MJActionEntityExtended;
     tool: ChatTool;
+    /** The Action's params the tool was built from — what {@link CoerceActionArguments} reads back. */
+    params: readonly MJActionParamEntity[];
 }
 /**
  * A built tool set plus the reverse map from tool name back to Action.
@@ -57,6 +59,18 @@ export declare const MAX_TOOL_DESCRIPTION_LENGTH = 1024;
 export declare function SanitizeToolName(actionName: string): string;
 /** @deprecated Use {@link SanitizeToolName}. */
 export declare function sanitizeToolName(actionName: string): string;
+/**
+ * Restores object-typed arguments a model sent as JSON strings, before the Action runs.
+ *
+ * Only `Simple Object` params are touched: an `Other` param is declared as `string` and may
+ * legitimately hold JSON-looking text. For an array param both the array itself and each element
+ * may arrive encoded.
+ *
+ * @param params The Action's params, as the tool was built from them
+ * @param args The call's arguments, as the provider returned them
+ * @returns A new argument object; `args` is not mutated
+ */
+export declare function CoerceActionArguments(params: readonly MJActionParamEntity[], args: Record<string, unknown> | undefined): Record<string, unknown>;
 /**
  * Builds the `ChatTool` declaration for one Action.
  *

package/dist/native-tools/action-tool-builder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-tool-builder.d.ts","sourceRoot":"","sources":["../../src/native-tools/action-tool-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAE3E,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAC9B,gFAAgF;IAChF,IAAI,EAAE,QAAQ,CAAC;IACf,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,IAAI,EAAE,QAAQ,CAAC;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,wCAAwC;IACxC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC9C;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAKhD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3D;AAwHD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,SAAS,mBAAmB,EAAE,GAAG,QAAQ,CA4BpH;AAED,mDAAmD;AACnD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,SAAS,mBAAmB,EAAE,GAAG,QAAQ,CAEpH;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC,GACtE,aAAa,CAqBf;AAED,kDAAkD;AAClD,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC,GACtE,aAAa,CAEf;AAED,sFAAsF;AACtF,MAAM,WAAW,yBAAyB;IACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mBAAmB,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,eAAe,EAAE,aAAa,CAAC,yBAAyB,CAAC,GAC1D,sBAAsB,EAAE,CAO1B;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,eAAe,EAAE,aAAa,CAAC,yBAAyB,CAAC,GAC1D,sBAAsB,EAAE,CAE1B"}
+{"version":3,"file":"action-tool-builder.d.ts","sourceRoot":"","sources":["../../src/native-tools/action-tool-builder.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAC;AAE3E,0EAA0E;AAC1E,MAAM,WAAW,iBAAiB;IAC9B,gFAAgF;IAChF,IAAI,EAAE,QAAQ,CAAC;IACf,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,MAAM,EAAE,sBAAsB,CAAC;IAC/B,IAAI,EAAE,QAAQ,CAAC;IACf,mGAAmG;IACnG,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC;CAC1C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC1B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,wCAAwC;IACxC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CAC9C;AAKD;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAKhD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED,gDAAgD;AAChD,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE3D;AAyDD;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CACjC,MAAM,EAAE,SAAS,mBAAmB,EAAE,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAYzB;AA+FD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,SAAS,mBAAmB,EAAE,GAAG,QAAQ,CA4BpH;AAED,mDAAmD;AACnD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,sBAAsB,EAAE,MAAM,EAAE,SAAS,mBAAmB,EAAE,GAAG,QAAQ,CAEpH;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC,GACtE,aAAa,CAsBf;AAED,kDAAkD;AAClD,wBAAgB,kBAAkB,CAC9B,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,gBAAgB,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,mBAAmB,EAAE,CAAC,GACtE,aAAa,CAEf;AAED,sFAAsF;AACtF,MAAM,WAAW,yBAAyB;IACtC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,mBAAmB,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,eAAe,EAAE,aAAa,CAAC,yBAAyB,CAAC,GAC1D,sBAAsB,EAAE,CAO1B;AAED,uDAAuD;AACvD,wBAAgB,uBAAuB,CACnC,OAAO,EAAE,SAAS,sBAAsB,EAAE,EAC1C,eAAe,EAAE,aAAa,CAAC,yBAAyB,CAAC,GAC1D,sBAAsB,EAAE,CAE1B"}