@jungjaehoon/mama-core 1.5.0 → 1.7.0

package/dist/mama-api.d.ts

@@ -19,9 +19,14 @@
  */
 import { DecisionRecord } from './db-manager.js';
 import { SemanticEdges } from './decision-formatter.js';
-import { saveMemory, recallMemory, buildProfile, ingestMemory, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary } from './memory/api.js';
+import { saveMemory, saveMemoryWithTrustedProvenance, recallMemory, buildProfile, ingestMemory, ingestWithTrustedProvenance, ingestConversation, ingestConversationWithTrustedProvenance, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary } from './memory/api.js';
 import { listOpenAuditFindings } from './memory/finding-store.js';
-import { listRecentMemoryEvents } from './memory/event-store.js';
+import { listMemoryEventsForMemory, listRecentMemoryEvents } from './memory/event-store.js';
+import type { TrustedMemoryWriteOptions } from './memory/provenance.js';
+import { getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId } from './memory/provenance-query.js';
+import { beginModelRun, beginModelRunInAdapter, commitModelRun, commitModelRunInAdapter, failModelRun, failModelRunInAdapter, getModelRun, getModelRunInAdapter } from './model-runs/store.js';
+import { appendToolTrace, listToolTracesForRun } from './model-runs/tool-trace-store.js';
+import { type SearchHitDiagnostics, type SearchQualityOptions } from './search/search-quality.js';
 /**
  * Parameters for mama.save()
  */
@@ -68,6 +73,7 @@ interface SimilarDecision {
     created_at?: number | string;
     event_date?: string | null;
     event_datetime?: number | null;
+    retrieval_diagnostics?: SearchHitDiagnostics;
 }
 /**
  * Search result from mama.search()
@@ -397,34 +403,6 @@ export interface QualityReport {
         meetsTarget: boolean;
     };
 }
-/**
- * Save a decision or insight to MAMA's memory
- *
- * Simple API for Claude to save insights without complex configuration
- * AC #1: Simple API - no complex configuration required
- *
- * @param {Object} params - Decision parameters
- * @param {string} params.topic - Decision topic (e.g., 'auth_strategy', 'date_format')
- * @param {string} params.decision - The decision made (e.g., 'JWT', 'ISO 8601 + Unix')
- * @param {string} params.reasoning - Why this decision was made
- * @param {number} [params.confidence=0.5] - Confidence score 0.0-1.0 (optional)
- * @param {string} [params.type='user_decision'] - 'user_decision' or 'assistant_insight' (optional)
- * @param {string} [params.outcome='pending'] - 'pending', 'success', 'failure', 'partial', 'superseded' (optional)
- * @param {string} [params.failure_reason] - Why this decision failed (optional, used with outcome='failure')
- * @param {string} [params.limitation] - Known limitations of this decision (optional)
- * @returns {Promise<{success: boolean, id: string, similar_decisions?: Array, warning?: string, collaboration_hint?: string, reasoning_graph?: Object}>} Save result with decision ID and metadata
- *
- * @example
- * const decisionId = await mama.save({
- *   topic: 'date_calculation_format',
- *   decision: 'Support both ISO 8601 and Unix timestamp formats',
- *   reasoning: 'Bootstrap data stored as ISO 8601 causing NaN errors',
- *   confidence: 0.95,
- *   type: 'assistant_insight',
- *   outcome: 'success'
- * });
- */
-declare function save({ topic, decision, reasoning, confidence, type, outcome, failure_reason, limitation, trust_context: _trust_context, is_static, scopes: inputScopes, event_date, timelineEvent, }: SaveParams): Promise<SaveResult>;
 /**
  * Recall decisions by topic
  *
@@ -573,23 +551,22 @@ declare function expandWithGraph(candidates: SearchCandidate[]): Promise<SearchC
  * const markdown = await mama.suggest('mesh optimization', { format: 'markdown' });
  * // → "💡 MAMA found 3 related topics:\n1. ..."
  */
-interface SuggestFunctionOptions {
+interface SuggestFunctionOptions extends SearchQualityOptions {
     format?: 'json' | 'markdown';
     limit?: number;
-    threshold?: number;
     useReranking?: boolean;
     /** Phase 3 Task 33: apply learned offline ranker rescoring. */
     rerankWithLearned?: boolean;
     recencyWeight?: number;
     recencyScale?: number;
     recencyDecay?: number;
-    disableRecency?: boolean;
-    topicPrefix?: string;
     scopes?: Array<{
         kind: 'global' | 'user' | 'channel' | 'project';
         id: string;
     }>;
 }
+declare function save(params: SaveParams): Promise<SaveResult>;
+declare function saveWithTrustedProvenance(params: SaveParams, options: TrustedMemoryWriteOptions): Promise<SaveResult>;
 declare function suggest(userQuestion: string, options?: SuggestFunctionOptions): Promise<any>;
 /**
  * List recent decisions (all topics, chronological)
@@ -1050,14 +1027,19 @@ declare function generateQualityReport(options?: QualityReportOptions): string |
  */
 declare const mama: {
     save: typeof save;
+    saveWithTrustedProvenance: typeof saveWithTrustedProvenance;
     suggest: typeof suggest;
     saveMemory: typeof saveMemory;
+    saveMemoryWithTrustedProvenance: typeof saveMemoryWithTrustedProvenance;
     recallMemory: typeof recallMemory;
     list: typeof listDecisions;
     listCheckpoints: typeof listCheckpoints;
     updateOutcome: typeof updateOutcome;
     buildProfile: typeof buildProfile;
     ingestMemory: typeof ingestMemory;
+    ingestWithTrustedProvenance: typeof ingestWithTrustedProvenance;
+    ingestConversation: typeof ingestConversation;
+    ingestConversationWithTrustedProvenance: typeof ingestConversationWithTrustedProvenance;
     evolveMemory: typeof evolveMemory;
     buildMemoryBootstrap: typeof buildMemoryBootstrap;
     createAuditAck: typeof createAuditAck;
@@ -1065,7 +1047,22 @@ declare const mama: {
     upsertChannelSummary: typeof upsertChannelSummary;
     getChannelSummary: typeof getChannelSummary;
     listAuditFindings: typeof listOpenAuditFindings;
+    getMemoryProvenance: typeof getMemoryProvenance;
+    listMemoriesByEnvelopeHash: typeof listMemoriesByEnvelopeHash;
+    listMemoriesByGatewayCallId: typeof listMemoriesByGatewayCallId;
+    listMemoriesByModelRunId: typeof listMemoriesByModelRunId;
+    listMemoryEventsForMemory: typeof listMemoryEventsForMemory;
     listRecentMemoryEvents: typeof listRecentMemoryEvents;
+    beginModelRun: typeof beginModelRun;
+    beginModelRunInAdapter: typeof beginModelRunInAdapter;
+    commitModelRun: typeof commitModelRun;
+    commitModelRunInAdapter: typeof commitModelRunInAdapter;
+    failModelRun: typeof failModelRun;
+    failModelRunInAdapter: typeof failModelRunInAdapter;
+    getModelRun: typeof getModelRun;
+    getModelRunInAdapter: typeof getModelRunInAdapter;
+    appendToolTrace: typeof appendToolTrace;
+    listToolTracesForRun: typeof listToolTracesForRun;
     saveCheckpoint: typeof saveCheckpoint;
     loadCheckpoint: typeof loadCheckpoint;
     recall: typeof recall;
@@ -1090,6 +1087,6 @@ declare const mama: {
     validateCleanupResult: typeof validateCleanupResult;
     expandWithGraph: typeof expandWithGraph;
 };
-export { save, suggest, saveMemory, recallMemory, listDecisions as list, listCheckpoints, updateOutcome, buildProfile, ingestMemory, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary, listOpenAuditFindings, listRecentMemoryEvents, saveCheckpoint, loadCheckpoint, recall, proposeLink, approveLink, rejectLink, getPendingLinks, deprecateAutoLinks, calculateCoverage, calculateQuality, generateQualityReport, logRestartAttempt, calculateRestartSuccessRate, calculateRestartLatency, getRestartMetrics, scanAutoLinks, createLinkBackup, generatePreCleanupReport, restoreLinkBackup, verifyBackupExists, deleteAutoLinks, validateCleanupResult, };
+export { save, saveWithTrustedProvenance, suggest, saveMemory, saveMemoryWithTrustedProvenance, recallMemory, listDecisions as list, listCheckpoints, updateOutcome, buildProfile, ingestMemory, ingestWithTrustedProvenance, ingestConversation, ingestConversationWithTrustedProvenance, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, upsertChannelSummary, getChannelSummary, listOpenAuditFindings, getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId, listMemoryEventsForMemory, listRecentMemoryEvents, beginModelRun, beginModelRunInAdapter, commitModelRun, commitModelRunInAdapter, failModelRun, failModelRunInAdapter, getModelRun, getModelRunInAdapter, appendToolTrace, listToolTracesForRun, saveCheckpoint, loadCheckpoint, recall, proposeLink, approveLink, rejectLink, getPendingLinks, deprecateAutoLinks, calculateCoverage, calculateQuality, generateQualityReport, logRestartAttempt, calculateRestartSuccessRate, calculateRestartLatency, getRestartMetrics, scanAutoLinks, createLinkBackup, generatePreCleanupReport, restoreLinkBackup, verifyBackupExists, deleteAutoLinks, validateCleanupResult, expandWithGraph, };
 export default mama;
 //# sourceMappingURL=mama-api.d.ts.map

package/dist/mama-api.js

@@ -22,8 +22,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.listRecentMemoryEvents = exports.listOpenAuditFindings = exports.getChannelSummary = exports.upsertChannelSummary = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestMemory = exports.buildProfile = exports.recallMemory = exports.saveMemory = void 0;
+exports.listToolTracesForRun = exports.appendToolTrace = exports.getModelRunInAdapter = exports.getModelRun = exports.failModelRunInAdapter = exports.failModelRun = exports.commitModelRunInAdapter = exports.commitModelRun = exports.beginModelRunInAdapter = exports.beginModelRun = exports.listRecentMemoryEvents = exports.listMemoryEventsForMemory = exports.listMemoriesByModelRunId = exports.listMemoriesByGatewayCallId = exports.listMemoriesByEnvelopeHash = exports.getMemoryProvenance = exports.listOpenAuditFindings = exports.getChannelSummary = exports.upsertChannelSummary = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestConversationWithTrustedProvenance = exports.ingestConversation = exports.ingestWithTrustedProvenance = exports.ingestMemory = exports.buildProfile = exports.recallMemory = exports.saveMemoryWithTrustedProvenance = exports.saveMemory = void 0;
 exports.save = save;
+exports.saveWithTrustedProvenance = saveWithTrustedProvenance;
 exports.suggest = suggest;
 exports.list = listDecisions;
 exports.listCheckpoints = listCheckpoints;
@@ -50,6 +51,7 @@ exports.restoreLinkBackup = restoreLinkBackup;
 exports.verifyBackupExists = verifyBackupExists;
 exports.deleteAutoLinks = deleteAutoLinks;
 exports.validateCleanupResult = validateCleanupResult;
+exports.expandWithGraph = expandWithGraph;
 // Node built-ins
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
@@ -67,9 +69,13 @@ const ollama_client_js_1 = require("./ollama-client.js");
 const debug_logger_js_1 = require("./debug-logger.js");
 const api_js_1 = require("./memory/api.js");
 Object.defineProperty(exports, "saveMemory", { enumerable: true, get: function () { return api_js_1.saveMemory; } });
+Object.defineProperty(exports, "saveMemoryWithTrustedProvenance", { enumerable: true, get: function () { return api_js_1.saveMemoryWithTrustedProvenance; } });
 Object.defineProperty(exports, "recallMemory", { enumerable: true, get: function () { return api_js_1.recallMemory; } });
 Object.defineProperty(exports, "buildProfile", { enumerable: true, get: function () { return api_js_1.buildProfile; } });
 Object.defineProperty(exports, "ingestMemory", { enumerable: true, get: function () { return api_js_1.ingestMemory; } });
+Object.defineProperty(exports, "ingestWithTrustedProvenance", { enumerable: true, get: function () { return api_js_1.ingestWithTrustedProvenance; } });
+Object.defineProperty(exports, "ingestConversation", { enumerable: true, get: function () { return api_js_1.ingestConversation; } });
+Object.defineProperty(exports, "ingestConversationWithTrustedProvenance", { enumerable: true, get: function () { return api_js_1.ingestConversationWithTrustedProvenance; } });
 Object.defineProperty(exports, "evolveMemory", { enumerable: true, get: function () { return api_js_1.evolveMemory; } });
 Object.defineProperty(exports, "buildMemoryBootstrap", { enumerable: true, get: function () { return api_js_1.buildMemoryBootstrap; } });
 Object.defineProperty(exports, "createAuditAck", { enumerable: true, get: function () { return api_js_1.createAuditAck; } });
@@ -79,10 +85,29 @@ Object.defineProperty(exports, "getChannelSummary", { enumerable: true, get: fun
 const finding_store_js_1 = require("./memory/finding-store.js");
 Object.defineProperty(exports, "listOpenAuditFindings", { enumerable: true, get: function () { return finding_store_js_1.listOpenAuditFindings; } });
 const event_store_js_1 = require("./memory/event-store.js");
+Object.defineProperty(exports, "listMemoryEventsForMemory", { enumerable: true, get: function () { return event_store_js_1.listMemoryEventsForMemory; } });
 Object.defineProperty(exports, "listRecentMemoryEvents", { enumerable: true, get: function () { return event_store_js_1.listRecentMemoryEvents; } });
+const provenance_query_js_1 = require("./memory/provenance-query.js");
+Object.defineProperty(exports, "getMemoryProvenance", { enumerable: true, get: function () { return provenance_query_js_1.getMemoryProvenance; } });
+Object.defineProperty(exports, "listMemoriesByEnvelopeHash", { enumerable: true, get: function () { return provenance_query_js_1.listMemoriesByEnvelopeHash; } });
+Object.defineProperty(exports, "listMemoriesByGatewayCallId", { enumerable: true, get: function () { return provenance_query_js_1.listMemoriesByGatewayCallId; } });
+Object.defineProperty(exports, "listMemoriesByModelRunId", { enumerable: true, get: function () { return provenance_query_js_1.listMemoriesByModelRunId; } });
+const store_js_1 = require("./model-runs/store.js");
+Object.defineProperty(exports, "beginModelRun", { enumerable: true, get: function () { return store_js_1.beginModelRun; } });
+Object.defineProperty(exports, "beginModelRunInAdapter", { enumerable: true, get: function () { return store_js_1.beginModelRunInAdapter; } });
+Object.defineProperty(exports, "commitModelRun", { enumerable: true, get: function () { return store_js_1.commitModelRun; } });
+Object.defineProperty(exports, "commitModelRunInAdapter", { enumerable: true, get: function () { return store_js_1.commitModelRunInAdapter; } });
+Object.defineProperty(exports, "failModelRun", { enumerable: true, get: function () { return store_js_1.failModelRun; } });
+Object.defineProperty(exports, "failModelRunInAdapter", { enumerable: true, get: function () { return store_js_1.failModelRunInAdapter; } });
+Object.defineProperty(exports, "getModelRun", { enumerable: true, get: function () { return store_js_1.getModelRun; } });
+Object.defineProperty(exports, "getModelRunInAdapter", { enumerable: true, get: function () { return store_js_1.getModelRunInAdapter; } });
+const tool_trace_store_js_1 = require("./model-runs/tool-trace-store.js");
+Object.defineProperty(exports, "appendToolTrace", { enumerable: true, get: function () { return tool_trace_store_js_1.appendToolTrace; } });
+Object.defineProperty(exports, "listToolTracesForRun", { enumerable: true, get: function () { return tool_trace_store_js_1.listToolTracesForRun; } });
 const search_rollup_js_1 = require("./cases/search-rollup.js");
 const ranker_rescore_js_1 = require("./search/ranker-rescore.js");
 const ranker_features_js_1 = require("./search/ranker-features.js");
+const search_quality_js_1 = require("./search/search-quality.js");
 // Session-level warning cooldown cache (Story 1.1, 1.2)
 // Prevents spam by tracking warned topics per session
 const warnedTopicsCache = new Map();
@@ -114,7 +139,7 @@ const WARNING_COOLDOWN_MS = 5 * 60 * 1000; // 5 minutes
  *   outcome: 'success'
  * });
  */
-async function save({ topic, decision, reasoning, confidence = 0.5, type = 'user_decision', outcome = 'pending', failure_reason = null, limitation = null, trust_context: _trust_context = null, is_static, scopes: inputScopes, event_date, timelineEvent, }) {
+async function saveInternal({ topic, decision, reasoning, confidence = 0.5, type = 'user_decision', outcome = 'pending', failure_reason = null, limitation = null, trust_context: _trust_context = null, is_static, scopes: inputScopes, event_date, timelineEvent, }, options) {
     // Validate required fields
     if (!topic || typeof topic !== 'string') {
         throw new Error('mama.save() requires topic (string)');
@@ -164,20 +189,35 @@ async function save({ topic, decision, reasoning, confidence = 0.5, type = 'user
     // Future: Will use decision_type column for proper distinction
     const _userInvolvement = type === 'user_decision' ? 'approved' : null;
     (0, progress_indicator_js_1.logProgress)(`Saving decision: ${topic.substring(0, 30)}...`);
-    const { id: decisionId, timeline_event_id: timelineEventId, timeline_event_ids: timelineEventIds, } = await (0, api_js_1.saveMemory)({
-        topic,
-        kind: is_static === 1 ? 'preference' : 'decision',
-        summary: decision,
-        details: reasoning,
-        confidence,
-        scopes: Array.isArray(inputScopes) && inputScopes.length > 0 ? inputScopes : [],
-        source: {
-            package: 'mama-core',
-            source_type: 'legacy_save',
-        },
-        eventDate: event_date ?? undefined,
-        timelineEvent,
-    });
+    const { id: decisionId, timeline_event_id: timelineEventId, timeline_event_ids: timelineEventIds, } = options
+        ? await (0, api_js_1.saveMemoryWithTrustedProvenance)({
+            topic,
+            kind: is_static === 1 ? 'preference' : 'decision',
+            summary: decision,
+            details: reasoning,
+            confidence,
+            scopes: Array.isArray(inputScopes) && inputScopes.length > 0 ? inputScopes : [],
+            source: {
+                package: 'mama-core',
+                source_type: 'legacy_save',
+            },
+            eventDate: event_date ?? undefined,
+            timelineEvent,
+        }, options)
+        : await (0, api_js_1.saveMemory)({
+            topic,
+            kind: is_static === 1 ? 'preference' : 'decision',
+            summary: decision,
+            details: reasoning,
+            confidence,
+            scopes: Array.isArray(inputScopes) && inputScopes.length > 0 ? inputScopes : [],
+            source: {
+                package: 'mama-core',
+                source_type: 'legacy_save',
+            },
+            eventDate: event_date ?? undefined,
+            timelineEvent,
+        });
     (0, progress_indicator_js_1.logComplete)(`Decision saved: ${decisionId.substring(0, 20)}...`);
     // Update user_involvement, outcome, failure_reason, limitation
     // Note: learnDecision always sets 'requested', we need to override it
@@ -760,6 +800,7 @@ function confidenceValue(record, fallback) {
 }
 function mapRolledUpResult(result) {
     const record = resultRecord(result);
+    const retrievalDiagnostics = result.retrieval_diagnostics;
     const topic = stringOrNull(record.topic ?? record.title) ?? result.source_id;
     // For wiki_page leaves, prefer the markdown body (`content`) in `decision` so
     // downstream consumers see the meaningful body rather than the short title.
@@ -787,15 +828,25 @@ function mapRolledUpResult(result) {
         created_at: record.created_at ?? null,
         event_date: record.event_date ?? null,
         event_datetime: record.event_datetime ?? null,
-        graph_source: 'primary',
+        graph_source: retrievalDiagnostics?.graph_source ?? 'primary',
         graph_rank: 1,
         related_to: null,
         edge_reason: null,
         case_id: result.case_id,
         source_type: result.source_type,
         contributing_leaves: result.contributing_leaves ?? null,
+        ...(result.contributing_leaf_diagnostics
+            ? { contributing_leaf_diagnostics: result.contributing_leaf_diagnostics }
+            : {}),
+        ...(retrievalDiagnostics ? { retrieval_diagnostics: retrievalDiagnostics } : {}),
     };
 }
+async function save(params) {
+    return saveInternal(params);
+}
+async function saveWithTrustedProvenance(params, options) {
+    return saveInternal(params, options);
+}
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 async function suggest(userQuestion, options = {}) {
     if (!userQuestion || typeof userQuestion !== 'string') {
@@ -807,17 +858,66 @@ async function suggest(userQuestion, options = {}) {
     recencyScale = 7, // Days until recency score drops to 50%
     recencyDecay = 0.5, // Score at scale point (0.5 = 50%)
     disableRecency = false, // Set true to disable recency boosting entirely
-     } = options;
+    strict, strictness, includeRelated, minLexicalSupport, diagnostics: includeDiagnostics, } = options;
+    const normalizedSearchOptions = (0, search_quality_js_1.normalizeSearchQualityOptions)({
+        threshold,
+        strict,
+        strictness,
+        disableRecency,
+        includeRelated,
+        topicPrefix: options.topicPrefix,
+        minLexicalSupport,
+        diagnostics: includeDiagnostics,
+    });
+    const memoryV2QualityContractRequested = threshold !== undefined ||
+        strict !== undefined ||
+        strictness !== undefined ||
+        includeRelated !== undefined ||
+        minLexicalSupport !== undefined ||
+        includeDiagnostics === true ||
+        options.topicPrefix !== undefined ||
+        options.scopes !== undefined;
     const rerankPoolLimit = rerankWithLearned ? Math.max(limit * 4, limit + 5) : limit;
     try {
         const bundle = await (0, api_js_1.recallMemory)(userQuestion, {
             includeProfile: false,
             topicPrefix: options.topicPrefix,
             limit: rerankPoolLimit,
+            threshold,
+            strict,
+            strictness,
+            disableRecency,
+            includeRelated,
+            minLexicalSupport,
+            diagnostics: includeDiagnostics,
             ...(options.scopes && { scopes: options.scopes }),
         });
-        const fusedHits = bundle.fused_hits ?? [];
+        const diagnosticsByMemoryId = new Map(bundle.memories
+            .filter((memory) => memory.retrieval_diagnostics)
+            .map((memory) => [memory.id, memory.retrieval_diagnostics]));
+        const rawFusedHits = bundle.fused_hits ?? [];
+        const fusedHits = rawFusedHits.map((hit) => {
+            if (hit.source_type !== 'decision') {
+                return hit;
+            }
+            const recordDiagnostics = typeof hit.record === 'object' && hit.record !== null && !Array.isArray(hit.record)
+                ? hit.record.retrieval_diagnostics
+                : undefined;
+            const retrievalDiagnostics = diagnosticsByMemoryId.get(hit.source_id) ?? recordDiagnostics;
+            if (!retrievalDiagnostics) {
+                return hit;
+            }
+            const record = typeof hit.record === 'object' && hit.record !== null && !Array.isArray(hit.record)
+                ? { ...hit.record, retrieval_diagnostics: retrievalDiagnostics }
+                : hit.record;
+            return {
+                ...hit,
+                record,
+                retrieval_diagnostics: retrievalDiagnostics,
+            };
+        });
         const rolledUp = fusedHits.length > 0 ? (0, search_rollup_js_1.rollUpSearchHits)({ fusedHits, adapter: (0, memory_store_js_1.getAdapter)() }) : [];
+        const diagnosticsResponse = includeDiagnostics === true ? { diagnostics: bundle.search_meta.diagnostics ?? null } : {};
         // Phase 3 Task 33: compute base ranker meta once so every return path
         // (rolledUp, memories fallback, vector-search fallback) can attach it.
         // rerankWithLearned-driven rescoring still only applies to result arrays
@@ -901,10 +1001,11 @@ async function suggest(userQuestion, options = {}) {
             return {
                 query: userQuestion,
                 results: limitedResults,
+                ...diagnosticsResponse,
                 meta: {
                     count: limitedResults.length,
                     search_method: 'memory_v2',
-                    threshold: threshold || 'adaptive',
+                    threshold: normalizedSearchOptions.threshold,
                     recency_boost: disableRecency
                         ? null
                         : {
@@ -939,7 +1040,7 @@ async function suggest(userQuestion, options = {}) {
                 created_at: memory.created_at,
                 event_date: memory.event_date ?? null,
                 event_datetime: memory.event_datetime ?? null,
-                graph_source: 'primary',
+                graph_source: memory.retrieval_diagnostics?.graph_source ?? 'primary',
                 graph_rank: 1,
                 related_to: null,
                 edge_reason: null,
@@ -949,6 +1050,9 @@ async function suggest(userQuestion, options = {}) {
                     memory.source_type ??
                     memory.type ??
                     'decision',
+                ...(memory.retrieval_diagnostics
+                    ? { retrieval_diagnostics: memory.retrieval_diagnostics }
+                    : {}),
             }));
             const { results: rankedRows, meta: rankerMeta } = applyLearnedRanker(baseRows);
             const limitedRows = rankedRows.slice(0, limit);
@@ -961,10 +1065,11 @@ async function suggest(userQuestion, options = {}) {
             return {
                 query: userQuestion,
                 results: limitedRows,
+                ...diagnosticsResponse,
                 meta: {
                     count: limitedRows.length,
                     search_method: 'memory_v2',
-                    threshold: threshold || 'adaptive',
+                    threshold: normalizedSearchOptions.threshold,
                     recency_boost: disableRecency
                         ? null
                         : {
@@ -977,6 +1082,32 @@ async function suggest(userQuestion, options = {}) {
                 },
             };
         }
+        if (memoryV2QualityContractRequested) {
+            const emptyRows = [];
+            const { meta: rankerMeta } = applyLearnedRanker(emptyRows);
+            if (format === 'markdown') {
+                return '🔍 Search method: memory_v2\n';
+            }
+            return {
+                query: userQuestion,
+                results: emptyRows,
+                ...diagnosticsResponse,
+                meta: {
+                    count: 0,
+                    search_method: 'memory_v2',
+                    threshold: normalizedSearchOptions.threshold,
+                    recency_boost: disableRecency
+                        ? null
+                        : {
+                            weight: recencyWeight,
+                            scale: recencyScale,
+                            decay: recencyDecay,
+                        },
+                    graph_expansion: summarizeGraphExpansion(emptyRows),
+                    ranker: rankerMeta,
+                },
+            };
+        }
         // 1. Try vector search first (if sqlite-vss is available)
         // eslint-disable-next-line no-unused-vars, @typescript-eslint/no-explicit-any
         let results = [];
@@ -2567,14 +2698,19 @@ function formatQualityReportMarkdown(report) {
 const mama = {
     // Core functions (used by 4 MCP tools)
     save,
+    saveWithTrustedProvenance,
     suggest,
     saveMemory: api_js_1.saveMemory,
+    saveMemoryWithTrustedProvenance: api_js_1.saveMemoryWithTrustedProvenance,
     recallMemory: api_js_1.recallMemory,
     list: listDecisions,
     listCheckpoints,
     updateOutcome,
     buildProfile: api_js_1.buildProfile,
     ingestMemory: api_js_1.ingestMemory,
+    ingestWithTrustedProvenance: api_js_1.ingestWithTrustedProvenance,
+    ingestConversation: api_js_1.ingestConversation,
+    ingestConversationWithTrustedProvenance: api_js_1.ingestConversationWithTrustedProvenance,
     evolveMemory: api_js_1.evolveMemory,
     buildMemoryBootstrap: api_js_1.buildMemoryBootstrap,
     createAuditAck: api_js_1.createAuditAck,
@@ -2582,7 +2718,22 @@ const mama = {
     upsertChannelSummary: api_js_1.upsertChannelSummary,
     getChannelSummary: api_js_1.getChannelSummary,
     listAuditFindings: finding_store_js_1.listOpenAuditFindings,
+    getMemoryProvenance: provenance_query_js_1.getMemoryProvenance,
+    listMemoriesByEnvelopeHash: provenance_query_js_1.listMemoriesByEnvelopeHash,
+    listMemoriesByGatewayCallId: provenance_query_js_1.listMemoriesByGatewayCallId,
+    listMemoriesByModelRunId: provenance_query_js_1.listMemoriesByModelRunId,
+    listMemoryEventsForMemory: event_store_js_1.listMemoryEventsForMemory,
     listRecentMemoryEvents: event_store_js_1.listRecentMemoryEvents,
+    beginModelRun: store_js_1.beginModelRun,
+    beginModelRunInAdapter: store_js_1.beginModelRunInAdapter,
+    commitModelRun: store_js_1.commitModelRun,
+    commitModelRunInAdapter: store_js_1.commitModelRunInAdapter,
+    failModelRun: store_js_1.failModelRun,
+    failModelRunInAdapter: store_js_1.failModelRunInAdapter,
+    getModelRun: store_js_1.getModelRun,
+    getModelRunInAdapter: store_js_1.getModelRunInAdapter,
+    appendToolTrace: tool_trace_store_js_1.appendToolTrace,
+    listToolTracesForRun: tool_trace_store_js_1.listToolTracesForRun,
     saveCheckpoint,
     loadCheckpoint,
     // Legacy functions (retained for internal use, not exposed via MCP)

package/dist/memory/api.d.ts

@@ -1,82 +1,42 @@
 import { type WikiPageIndexRecord } from '../cases/wiki-page-index.js';
 import { resolveMemoryEvolution } from './evolution-engine.js';
 import { getChannelSummary, upsertChannelSummary } from './channel-summary-store.js';
-import type { MemoryKind, MemoryAgentBootstrap, MemoryAuditAck, MemoryEdge, MemoryRecord, MemoryScopeRef, MemoryStatus, ProfileSnapshot, RecallBundle, IngestConversationInput, ExtractedMemoryUnit, IngestConversationResult } from './types.js';
-interface SaveMemoryInput {
-    topic: string;
-    kind: MemoryKind;
-    summary: string;
-    details: string;
-    confidence?: number;
-    status?: MemoryStatus;
-    scopes: MemoryScopeRef[];
-    source: {
-        package: 'mama-core' | 'mcp-server' | 'standalone' | 'claude-code-plugin';
-        source_type: string;
-        user_id?: string;
-        channel_id?: string;
-        project_id?: string;
-    };
-    /** IDs to exclude from supersede candidates (e.g., sibling facts from same ingestion batch) */
-    excludeIds?: string[];
-    /**
-     * ISO 8601 date string for when the event actually occurred (e.g. "2023-01-15").
-     * Stored in the event_date column. Defaults to created_at if omitted.
-     */
-    eventDate?: string;
-    /** Source event timestamp in milliseconds when known. */
-    eventDateTime?: number;
-    entityObservationIds?: string[];
-    timelineEvent?: {
-        id?: string;
-        entity_id?: string;
-        event_type: string;
-        role?: string | null;
-        valid_from?: number | null;
-        valid_to?: number | null;
-        observed_at?: number | null;
-        source_ref?: string | null;
-        summary: string;
-        details?: string | null;
-    };
-}
-interface RecallMemoryOptions {
-    scopes?: MemoryScopeRef[];
-    includeProfile?: boolean;
-    includeHistory?: boolean;
-    skipGraphExpansion?: boolean;
-    topicPrefix?: string;
-    limit?: number;
-}
-interface IngestMemoryInput {
-    content: string;
-    scopes?: MemoryScopeRef[];
-    source: SaveMemoryInput['source'];
-    eventDate?: string;
-    eventDateTime?: number;
-}
+import { type SearchHitDiagnostics } from '../search/search-quality.js';
+import type { MemoryAgentBootstrap, MemoryAuditAck, MemoryEdge, MemoryRecord, MemoryScopeRef, ProfileSnapshot, PublicIngestMemoryInput, PublicSaveMemoryInput, RecallBundle, IngestConversationInput, ExtractedMemoryUnit, IngestConversationResult, RecallMemoryOptions } from './types.js';
+import { type TrustedMemoryWriteOptions } from './provenance.js';
+type SaveMemoryInput = PublicSaveMemoryInput;
+type IngestMemoryInput = PublicIngestMemoryInput;
 export interface FusedHit {
     source_type: 'decision' | 'wiki_page';
     source_id: string;
     record: MemoryRecord | WikiPageIndexRecord;
     fused_rank_score: number;
+    page_type?: WikiPageIndexRecord['page_type'];
+    case_id?: string | null;
+    retrieval_diagnostics?: SearchHitDiagnostics;
 }
 export declare const LEXICAL_STOPWORDS: Set<string>;
 export declare function getLexicalQueryTokens(query: string): string[];
 export declare function loadEdgesForIds(ids: string[]): Promise<MemoryEdge[]>;
-export declare function saveMemory(input: SaveMemoryInput): Promise<{
+type SaveMemoryResult = {
     success: boolean;
     id: string;
     saved_decision_id?: string;
     timeline_event_id?: string | null;
     timeline_event_ids?: string[];
-}>;
+};
+export declare function saveMemory(input: SaveMemoryInput): Promise<SaveMemoryResult>;
+export declare function saveMemoryWithTrustedProvenance(input: SaveMemoryInput, options: TrustedMemoryWriteOptions): Promise<SaveMemoryResult>;
 export declare function buildProfile(scopes: MemoryScopeRef[]): Promise<ProfileSnapshot>;
 export declare function recallMemory(query: string, options?: RecallMemoryOptions): Promise<RecallBundle>;
 export declare function ingestMemory(input: IngestMemoryInput): Promise<{
     success: boolean;
     id: string;
 }>;
+export declare function ingestWithTrustedProvenance(input: IngestMemoryInput, options: TrustedMemoryWriteOptions): Promise<{
+    success: boolean;
+    id: string;
+}>;
 export declare function evolveMemory(input: Parameters<typeof resolveMemoryEvolution>[0]): Promise<import("./evolution-engine.js").EvolutionResult>;
 export declare function buildMemoryBootstrap(params: {
     scopes: MemoryScopeRef[];
@@ -104,5 +64,6 @@ export declare function recordMemoryAudit(input: {
 declare function callExtractionLLM(prompt: string, options: NonNullable<IngestConversationInput['extract']>): Promise<ExtractedMemoryUnit[]>;
 export declare function setExtractionFn(fn: typeof callExtractionLLM | null): void;
 export declare function ingestConversation(input: IngestConversationInput): Promise<IngestConversationResult>;
+export declare function ingestConversationWithTrustedProvenance(input: IngestConversationInput, options: TrustedMemoryWriteOptions): Promise<IngestConversationResult>;
 export { upsertChannelSummary, getChannelSummary };
 //# sourceMappingURL=api.d.ts.map