@jungjaehoon/mama-core 1.5.0 → 1.6.0

package/dist/edges/types.d.ts

@@ -0,0 +1,86 @@
+import type { Buffer } from 'node:buffer';
+export declare const TWIN_REF_KINDS: readonly ["memory", "case", "entity", "report", "edge", "raw"];
+export type TwinRefKind = (typeof TWIN_REF_KINDS)[number];
+export declare const TWIN_EDGE_SOURCES: readonly ["agent", "human", "code"];
+export type TwinEdgeSource = (typeof TWIN_EDGE_SOURCES)[number];
+export declare const TWIN_EDGE_TYPES: readonly ["supersedes", "builds_on", "debates", "synthesizes", "mentions", "derived_from", "case_member", "alias_of", "next_action_for", "blocks"];
+export type TwinEdgeType = (typeof TWIN_EDGE_TYPES)[number];
+export type TwinRef = {
+    [Kind in TwinRefKind]: {
+        kind: Kind;
+        id: string;
+    };
+}[TwinRefKind];
+export type TwinEdgeSubjectRef = Exclude<TwinRef, {
+    kind: 'raw';
+}>;
+export interface TwinScopeRef {
+    kind: 'global' | 'user' | 'channel' | 'project';
+    id: string;
+}
+export interface TwinProjectRef {
+    kind: string;
+    id: string;
+}
+export interface TwinVisibility {
+    scopes?: TwinScopeRef[];
+    connectors?: string[];
+    projectRefs?: TwinProjectRef[];
+    tenantId?: string | null;
+    asOfMs?: number | null;
+}
+export interface InsertTwinEdgeInput {
+    edge_id?: string;
+    edge_type: TwinEdgeType;
+    subject_ref: TwinEdgeSubjectRef;
+    object_ref: TwinRef;
+    relation_attrs?: unknown;
+    confidence?: number;
+    source: TwinEdgeSource;
+    agent_id?: string;
+    model_run_id?: string;
+    envelope_hash?: string;
+    request_idempotency_key?: string;
+    edge_idempotency_key?: string;
+    human_actor_id?: string;
+    human_actor_role?: 'commander' | 'configurator_elevated';
+    authority_scope_json?: unknown;
+    reason_classification?: 'factual_correction' | 'agent_inference_wrong' | 'privacy_redaction' | 'duplicate_merge' | 'state_override' | 'other';
+    reason_text?: string;
+    evidence_refs?: unknown;
+}
+export interface TwinEdgeRecord {
+    edge_id: string;
+    edge_type: TwinEdgeType;
+    subject_ref: TwinRef;
+    object_ref: TwinRef;
+    relation_attrs_json: string | null;
+    relation_attrs: unknown | null;
+    confidence: number;
+    source: TwinEdgeSource;
+    agent_id: string | null;
+    model_run_id: string | null;
+    envelope_hash: string | null;
+    human_actor_id: string | null;
+    human_actor_role: string | null;
+    authority_scope_json: string | null;
+    authority_scope: unknown | null;
+    reason_classification: string | null;
+    reason_text: string | null;
+    evidence_refs_json: string | null;
+    evidence_refs: unknown | null;
+    request_idempotency_key: string | null;
+    edge_idempotency_key: string | null;
+    content_hash: Buffer;
+    created_at: number;
+}
+export interface ListVisibleTwinEdgesOptions {
+    scopes?: TwinScopeRef[];
+    connectors?: string[];
+    projectRefs?: TwinProjectRef[];
+    tenantId?: string | null;
+    edgeTypes?: TwinEdgeType[];
+    asOfMs?: number | null;
+    limit?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/edges/types.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.TWIN_REF_KINDS = void 0;
+exports.TWIN_REF_KINDS = ['memory', 'case', 'entity', 'report', 'edge', 'raw'];
+exports.TWIN_EDGE_SOURCES = ['agent', 'human', 'code'];
+exports.TWIN_EDGE_TYPES = [
+    'supersedes',
+    'builds_on',
+    'debates',
+    'synthesizes',
+    'mentions',
+    'derived_from',
+    'case_member',
+    'alias_of',
+    'next_action_for',
+    'blocks',
+];
+//# sourceMappingURL=types.js.map

package/dist/embeddings.js

@@ -32,10 +32,20 @@ Object.defineProperty(exports, "getEmbeddingDim", { enumerable: true, get: funct
 Object.defineProperty(exports, "getQuantized", { enumerable: true, get: function () { return config_loader_js_1.getQuantized; } });
 // Shared cache directory (not in node_modules)
 const DEFAULT_CACHE_DIR = path_1.default.join(os_1.default.homedir(), '.cache', 'huggingface', 'transformers');
+const TIER3_ENV_VALUES = new Set(['1', 'true', 'yes']);
 // Singleton pattern for model loading
 let embeddingPipeline = null;
 let currentModelName = null;
 let modelLoadFailed = false; // Cache load failures to avoid repeated slow retries
+function isForceTier3Enabled() {
+    return TIER3_ENV_VALUES.has(String(process.env.MAMA_FORCE_TIER_3 || '').toLowerCase());
+}
+function assertEmbeddingsEnabled() {
+    if (isForceTier3Enabled()) {
+        throw new Error('Embedding generation disabled because MAMA_FORCE_TIER_3=true. ' +
+            'Tier 3 test mode must use lexical/no-vector fallback instead of loading the embedding model.');
+    }
+}
 /**
  * Load embedding model (configurable)
  *
@@ -45,6 +55,7 @@ let modelLoadFailed = false; // Cache load failures to avoid repeated slow retri
  * @returns Embedding pipeline
  */
 async function loadModel() {
+    assertEmbeddingsEnabled();
     const modelName = (0, config_loader_js_1.getModelName)();
     // Check if model has changed (Story M1.4 AC #3)
     if (embeddingPipeline && currentModelName && currentModelName !== modelName) {
@@ -104,6 +115,7 @@ async function generateEmbedding(text) {
     if (!text || text.trim().length === 0) {
         throw new Error('Text cannot be empty');
     }
+    assertEmbeddingsEnabled();
     // Task 2: Check cache first (AC #3)
     const cached = embedding_cache_js_1.embeddingCache.get(text);
     if (cached) {
@@ -189,6 +201,7 @@ async function generateEnhancedEmbedding(decision) {
  * @returns Array of embeddings
  */
 async function generateBatchEmbeddings(texts) {
+    assertEmbeddingsEnabled();
     if (!Array.isArray(texts) || texts.length === 0) {
         throw new Error('Texts must be a non-empty array');
     }

package/dist/index.d.ts

@@ -15,10 +15,22 @@ export { createAdapter, DatabaseAdapter, SQLiteAdapter, type AdapterConfig, type
 export { getSessionDecisions, incrementUsageSuccess, incrementUsageFailure, getDecisionById, traverseDecisionChain, DB_PATH, DB_DIR, LEGACY_DB_PATH, DEFAULT_DB_PATH, } from './memory-store.js';
 import mama from './mama-api.js';
 export { mama };
-export { MEMORY_SCOPE_KINDS, MEMORY_KINDS, MEMORY_STATUSES, MEMORY_EDGE_TYPES, createEmptyRecallBundle, type MemoryScopeKind, type MemoryKind, type MemoryStatus, type MemoryEdgeType, type MemoryScopeRef, type MemoryRecord, type MemorySearchResultHit, type MemoryEdge, type ProfileSnapshot, type RecallBundle, type ConversationMessage, type IngestConversationInput, type ExtractedMemoryUnit, type IngestConversationResult, } from './memory/types.js';
-export { saveMemory, recallMemory, buildProfile, ingestMemory, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, ingestConversation, setExtractionFn, upsertChannelSummary, getChannelSummary, } from './memory/api.js';
+export { MEMORY_SCOPE_KINDS, MEMORY_KINDS, MEMORY_STATUSES, MEMORY_EDGE_TYPES, createEmptyRecallBundle, type MemoryScopeKind, type MemoryKind, type MemoryStatus, type MemoryEdgeType, type MemoryScopeRef, type MemorySourceRef, type MemoryRecord, type MemoryWriteProvenance, type MemoryProvenanceRecord, type PublicSaveMemoryInput, type PublicIngestMemoryInput, type PublicIngestConversationInput, type MemorySearchResultHit, type MemoryEdge, type ProfileSnapshot, type RecallBundle, type ConversationMessage, type IngestConversationInput, type ExtractedMemoryUnit, type IngestConversationResult, } from './memory/types.js';
+export { saveMemory, saveMemoryWithTrustedProvenance, recallMemory, buildProfile, ingestMemory, ingestWithTrustedProvenance, evolveMemory, buildMemoryBootstrap, createAuditAck, recordMemoryAudit, ingestConversation, ingestConversationWithTrustedProvenance, setExtractionFn, upsertChannelSummary, getChannelSummary, } from './memory/api.js';
 export { buildExtractionPrompt, parseExtractionResponse } from './memory/extraction-prompt.js';
-export { appendMemoryEvent, listRecentMemoryEvents } from './memory/event-store.js';
+export { appendMemoryEvent, insertMemoryEventInTransaction, listMemoryEventsForMemory, listRecentMemoryEvents, } from './memory/event-store.js';
+export { createTrustedProvenanceCapability, assertTrustedProvenanceCapability, type TrustedProvenanceCapability, type TrustedMemoryWriteOptions, } from './memory/provenance.js';
+export { getMemoryProvenance, listMemoriesByEnvelopeHash, listMemoriesByGatewayCallId, listMemoriesByModelRunId, } from './memory/provenance-query.js';
+export { backfillLegacyMemoryProvenance, backfillConnectorEventScopeMetadata, type BackfillResult, type ConnectorEventScopeBackfillInput, } from './memory/scope-backfill.js';
+export { getMemoryProvenanceAudit, listMemoryProvenanceAudit, type MemoryProvenanceAuditRecord, type MemoryProvenanceAuditListOptions, } from './memory/provenance-audit.js';
+export { MODEL_RUN_STATUSES, type ModelRunStatus, type BeginModelRunInput, type ModelRunRecord, type AppendToolTraceInput, type ToolTraceRecord, } from './model-runs/types.js';
+export { beginModelRun, beginModelRunInAdapter, commitModelRun, commitModelRunInAdapter, failModelRun, failModelRunInAdapter, getModelRun, getModelRunInAdapter, } from './model-runs/store.js';
+export { appendToolTrace, listToolTracesForRun } from './model-runs/tool-trace-store.js';
+export { TWIN_EDGE_SOURCES, TWIN_EDGE_TYPES, TWIN_REF_KINDS, type InsertTwinEdgeInput, type ListVisibleTwinEdgesOptions, type TwinEdgeRecord, type TwinEdgeSource, type TwinEdgeType, type TwinRef, type TwinRefKind, type TwinScopeRef, } from './edges/types.js';
+export { getTwinEdge, insertTwinEdge, listTwinEdgesForRefs, mapTwinEdgeRow, } from './edges/store.js';
+export { assertTwinRefsVisibleToScopes, listVisibleTwinEdgesForRefs, } from './edges/ref-validation.js';
+export * from './agent-situation/index.js';
+export * from './agent-graph/index.js';
 export * from './entities/types.js';
 export * from './entities/errors.js';
 export * from './entities/store.js';
@@ -72,10 +84,12 @@ export * from './cases/composition-overrides.js';
 export * from './cases/freshness.js';
 export * from './cases/membership-explain.js';
 export * from './connectors/event-index.js';
+export * from './connectors/raw-query.js';
 export * from './connectors/types.js';
 export * from './search/question-type.js';
 export * from './search/feedback-store.js';
 export * from './search/ranker-features.js';
 export * from './search/ranker-trainer.js';
 export * from './search/ranker-rescore.js';
+export * from './search/search-quality.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -26,10 +26,10 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.recallMemory = exports.saveMemory = exports.createEmptyRecallBundle = exports.MEMORY_EDGE_TYPES = exports.MEMORY_STATUSES = exports.MEMORY_KINDS = exports.MEMORY_SCOPE_KINDS = exports.mama = exports.DEFAULT_DB_PATH = exports.LEGACY_DB_PATH = exports.DB_DIR = exports.DB_PATH = exports.traverseDecisionChain = exports.getDecisionById = exports.incrementUsageFailure = exports.incrementUsageSuccess = exports.getSessionDecisions = exports.SQLiteAdapter = exports.DatabaseAdapter = exports.createAdapter = exports.reindexEmbeddings = exports.fts5Search = exports.getDbPath = exports.getPreparedStmt = exports.updateDecisionOutcome = exports.querySemanticEdges = exports.queryDecisionGraph = exports.insertDecisionWithEmbedding = exports.queryVectorSearch = exports.vectorSearch = exports.insertEmbedding = exports.closeDB = exports.getAdapter = exports.getDB = exports.initDB = exports.TIMEOUT_MS = exports.HOST = exports.DEFAULT_PORT = exports.getServerPort = exports.isServerRunning = exports.getServerStatus = exports.getEmbeddingFromServer = exports.EmbeddingCache = exports.MODEL_NAME = exports.EMBEDDING_DIM = exports.embeddingCache = exports.cosineSimilarity = exports.generateBatchEmbeddings = exports.generateEnhancedEmbedding = exports.generateEmbedding = void 0;
-exports.logComplete = exports.logProgress = exports.getTierBanner = exports.getTierDescription = exports.checkDatabase = exports.checkEmbeddings = exports.checkSQLite = exports.checkNodeVersion = exports.validateTier = exports.VALID_EDGE_TYPES = exports.updateConfidence = exports.getSupersededChainDepth = exports.createEdgesFromReasoning = exports.parseReasoningForRelationships = exports.detectRefinement = exports.calculateCombinedConfidence = exports.markSuperseded = exports.createSupersedesEdge = exports.createEdge = exports.getPreviousDecision = exports.generateDecisionId = exports.learnDecision = exports.testRelevanceScoring = exports.formatTopNContext = exports.selectTopDecisions = exports.calculateRelevance = exports.DEFAULT_CONFIG = exports.getConfigPath = exports.updateConfig = exports.getCacheDir = exports.getEmbeddingDim = exports.getModelName = exports.loadConfig = exports.CanonicalizeError = exports.targetRefHash = exports.canonicalizeJSON = exports.listRecentMemoryEvents = exports.appendMemoryEvent = exports.parseExtractionResponse = exports.buildExtractionPrompt = exports.getChannelSummary = exports.upsertChannelSummary = exports.setExtractionFn = exports.ingestConversation = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestMemory = exports.buildProfile = void 0;
-exports.analyzeIntent = exports.injectDecisionContext = exports.RECENT_WINDOW_MS = exports.PARTIAL_INDICATORS = exports.SUCCESS_INDICATORS = exports.FAILURE_INDICATORS = exports.onUserPromptSubmit = exports.markOutcome = exports.getEvidenceImpact = exports.calculateDurationDays = exports.getRecentDecision = exports.extractFailureReason = exports.matchesPartialIndicators = exports.matchesSuccessIndicators = exports.matchesFailureIndicators = exports.analyzeOutcome = exports.extractCodeExample = exports.extractQuickAnswer = exports.estimateTokens = exports.ensureTokenBudget = exports.formatTrustContext = exports.formatInstantAnswer = exports.formatTeaser = exports.formatList = exports.formatRecall = exports.formatLegacyContext = exports.formatContext = exports.isMAMAError = exports.wrapError = exports.ErrorCodes = exports.TimeoutError = exports.RateLimitError = exports.LinkError = exports.ConfigurationError = exports.EmbeddingError = exports.DatabaseError = exports.ValidationError = exports.NotFoundError = exports.MAMAError = exports.formatTimeAgo = exports.DebugLogger = exports.error = exports.warn = exports.info = exports.debug = exports.logSearching = exports.logLoading = exports.logInfo = exports.logError = exports.logFailed = void 0;
-exports.notifyInsight = exports.FALLBACK_MODEL = exports.DEFAULT_MODEL = exports.listModels = exports.isAvailable = exports.analyzeQueryIntent = exports.analyzeDecision = exports.generate = exports.extractTopicKeywords = void 0;
+exports.saveMemoryWithTrustedProvenance = exports.saveMemory = exports.createEmptyRecallBundle = exports.MEMORY_EDGE_TYPES = exports.MEMORY_STATUSES = exports.MEMORY_KINDS = exports.MEMORY_SCOPE_KINDS = exports.mama = exports.DEFAULT_DB_PATH = exports.LEGACY_DB_PATH = exports.DB_DIR = exports.DB_PATH = exports.traverseDecisionChain = exports.getDecisionById = exports.incrementUsageFailure = exports.incrementUsageSuccess = exports.getSessionDecisions = exports.SQLiteAdapter = exports.DatabaseAdapter = exports.createAdapter = exports.reindexEmbeddings = exports.fts5Search = exports.getDbPath = exports.getPreparedStmt = exports.updateDecisionOutcome = exports.querySemanticEdges = exports.queryDecisionGraph = exports.insertDecisionWithEmbedding = exports.queryVectorSearch = exports.vectorSearch = exports.insertEmbedding = exports.closeDB = exports.getAdapter = exports.getDB = exports.initDB = exports.TIMEOUT_MS = exports.HOST = exports.DEFAULT_PORT = exports.getServerPort = exports.isServerRunning = exports.getServerStatus = exports.getEmbeddingFromServer = exports.EmbeddingCache = exports.MODEL_NAME = exports.EMBEDDING_DIM = exports.embeddingCache = exports.cosineSimilarity = exports.generateBatchEmbeddings = exports.generateEnhancedEmbedding = exports.generateEmbedding = void 0;
+exports.canonicalizeJSON = exports.listVisibleTwinEdgesForRefs = exports.assertTwinRefsVisibleToScopes = exports.mapTwinEdgeRow = exports.listTwinEdgesForRefs = exports.insertTwinEdge = exports.getTwinEdge = exports.TWIN_REF_KINDS = exports.TWIN_EDGE_TYPES = exports.TWIN_EDGE_SOURCES = exports.listToolTracesForRun = exports.appendToolTrace = exports.getModelRunInAdapter = exports.getModelRun = exports.failModelRunInAdapter = exports.failModelRun = exports.commitModelRunInAdapter = exports.commitModelRun = exports.beginModelRunInAdapter = exports.beginModelRun = exports.MODEL_RUN_STATUSES = exports.listMemoryProvenanceAudit = exports.getMemoryProvenanceAudit = exports.backfillConnectorEventScopeMetadata = exports.backfillLegacyMemoryProvenance = exports.listMemoriesByModelRunId = exports.listMemoriesByGatewayCallId = exports.listMemoriesByEnvelopeHash = exports.getMemoryProvenance = exports.assertTrustedProvenanceCapability = exports.createTrustedProvenanceCapability = exports.listRecentMemoryEvents = exports.listMemoryEventsForMemory = exports.insertMemoryEventInTransaction = exports.appendMemoryEvent = exports.parseExtractionResponse = exports.buildExtractionPrompt = exports.getChannelSummary = exports.upsertChannelSummary = exports.setExtractionFn = exports.ingestConversationWithTrustedProvenance = exports.ingestConversation = exports.recordMemoryAudit = exports.createAuditAck = exports.buildMemoryBootstrap = exports.evolveMemory = exports.ingestWithTrustedProvenance = exports.ingestMemory = exports.buildProfile = exports.recallMemory = void 0;
+exports.DatabaseError = exports.ValidationError = exports.NotFoundError = exports.MAMAError = exports.formatTimeAgo = exports.DebugLogger = exports.error = exports.warn = exports.info = exports.debug = exports.logSearching = exports.logLoading = exports.logInfo = exports.logError = exports.logFailed = exports.logComplete = exports.logProgress = exports.getTierBanner = exports.getTierDescription = exports.checkDatabase = exports.checkEmbeddings = exports.checkSQLite = exports.checkNodeVersion = exports.validateTier = exports.VALID_EDGE_TYPES = exports.updateConfidence = exports.getSupersededChainDepth = exports.createEdgesFromReasoning = exports.parseReasoningForRelationships = exports.detectRefinement = exports.calculateCombinedConfidence = exports.markSuperseded = exports.createSupersedesEdge = exports.createEdge = exports.getPreviousDecision = exports.generateDecisionId = exports.learnDecision = exports.testRelevanceScoring = exports.formatTopNContext = exports.selectTopDecisions = exports.calculateRelevance = exports.DEFAULT_CONFIG = exports.getConfigPath = exports.updateConfig = exports.getCacheDir = exports.getEmbeddingDim = exports.getModelName = exports.loadConfig = exports.CanonicalizeError = exports.targetRefHash = void 0;
+exports.notifyInsight = exports.FALLBACK_MODEL = exports.DEFAULT_MODEL = exports.listModels = exports.isAvailable = exports.analyzeQueryIntent = exports.analyzeDecision = exports.generate = exports.extractTopicKeywords = exports.analyzeIntent = exports.injectDecisionContext = exports.RECENT_WINDOW_MS = exports.PARTIAL_INDICATORS = exports.SUCCESS_INDICATORS = exports.FAILURE_INDICATORS = exports.onUserPromptSubmit = exports.markOutcome = exports.getEvidenceImpact = exports.calculateDurationDays = exports.getRecentDecision = exports.extractFailureReason = exports.matchesPartialIndicators = exports.matchesSuccessIndicators = exports.matchesFailureIndicators = exports.analyzeOutcome = exports.extractCodeExample = exports.extractQuickAnswer = exports.estimateTokens = exports.ensureTokenBudget = exports.formatTrustContext = exports.formatInstantAnswer = exports.formatTeaser = exports.formatList = exports.formatRecall = exports.formatLegacyContext = exports.formatContext = exports.isMAMAError = exports.wrapError = exports.ErrorCodes = exports.TimeoutError = exports.RateLimitError = exports.LinkError = exports.ConfigurationError = exports.EmbeddingError = void 0;
 var embeddings_js_1 = require("./embeddings.js");
 Object.defineProperty(exports, "generateEmbedding", { enumerable: true, get: function () { return embeddings_js_1.generateEmbedding; } });
 Object.defineProperty(exports, "generateEnhancedEmbedding", { enumerable: true, get: function () { return embeddings_js_1.generateEnhancedEmbedding; } });
@@ -88,14 +88,17 @@ Object.defineProperty(exports, "MEMORY_EDGE_TYPES", { enumerable: true, get: fun
 Object.defineProperty(exports, "createEmptyRecallBundle", { enumerable: true, get: function () { return types_js_1.createEmptyRecallBundle; } });
 var 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, "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; } });
 Object.defineProperty(exports, "recordMemoryAudit", { enumerable: true, get: function () { return api_js_1.recordMemoryAudit; } });
 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, "setExtractionFn", { enumerable: true, get: function () { return api_js_1.setExtractionFn; } });
 Object.defineProperty(exports, "upsertChannelSummary", { enumerable: true, get: function () { return api_js_1.upsertChannelSummary; } });
 Object.defineProperty(exports, "getChannelSummary", { enumerable: true, get: function () { return api_js_1.getChannelSummary; } });
@@ -104,7 +107,51 @@ Object.defineProperty(exports, "buildExtractionPrompt", { enumerable: true, get:
 Object.defineProperty(exports, "parseExtractionResponse", { enumerable: true, get: function () { return extraction_prompt_js_1.parseExtractionResponse; } });
 var event_store_js_1 = require("./memory/event-store.js");
 Object.defineProperty(exports, "appendMemoryEvent", { enumerable: true, get: function () { return event_store_js_1.appendMemoryEvent; } });
+Object.defineProperty(exports, "insertMemoryEventInTransaction", { enumerable: true, get: function () { return event_store_js_1.insertMemoryEventInTransaction; } });
+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; } });
+var provenance_js_1 = require("./memory/provenance.js");
+Object.defineProperty(exports, "createTrustedProvenanceCapability", { enumerable: true, get: function () { return provenance_js_1.createTrustedProvenanceCapability; } });
+Object.defineProperty(exports, "assertTrustedProvenanceCapability", { enumerable: true, get: function () { return provenance_js_1.assertTrustedProvenanceCapability; } });
+var 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; } });
+var scope_backfill_js_1 = require("./memory/scope-backfill.js");
+Object.defineProperty(exports, "backfillLegacyMemoryProvenance", { enumerable: true, get: function () { return scope_backfill_js_1.backfillLegacyMemoryProvenance; } });
+Object.defineProperty(exports, "backfillConnectorEventScopeMetadata", { enumerable: true, get: function () { return scope_backfill_js_1.backfillConnectorEventScopeMetadata; } });
+var provenance_audit_js_1 = require("./memory/provenance-audit.js");
+Object.defineProperty(exports, "getMemoryProvenanceAudit", { enumerable: true, get: function () { return provenance_audit_js_1.getMemoryProvenanceAudit; } });
+Object.defineProperty(exports, "listMemoryProvenanceAudit", { enumerable: true, get: function () { return provenance_audit_js_1.listMemoryProvenanceAudit; } });
+var types_js_2 = require("./model-runs/types.js");
+Object.defineProperty(exports, "MODEL_RUN_STATUSES", { enumerable: true, get: function () { return types_js_2.MODEL_RUN_STATUSES; } });
+var 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; } });
+var 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; } });
+var types_js_3 = require("./edges/types.js");
+Object.defineProperty(exports, "TWIN_EDGE_SOURCES", { enumerable: true, get: function () { return types_js_3.TWIN_EDGE_SOURCES; } });
+Object.defineProperty(exports, "TWIN_EDGE_TYPES", { enumerable: true, get: function () { return types_js_3.TWIN_EDGE_TYPES; } });
+Object.defineProperty(exports, "TWIN_REF_KINDS", { enumerable: true, get: function () { return types_js_3.TWIN_REF_KINDS; } });
+var store_js_2 = require("./edges/store.js");
+Object.defineProperty(exports, "getTwinEdge", { enumerable: true, get: function () { return store_js_2.getTwinEdge; } });
+Object.defineProperty(exports, "insertTwinEdge", { enumerable: true, get: function () { return store_js_2.insertTwinEdge; } });
+Object.defineProperty(exports, "listTwinEdgesForRefs", { enumerable: true, get: function () { return store_js_2.listTwinEdgesForRefs; } });
+Object.defineProperty(exports, "mapTwinEdgeRow", { enumerable: true, get: function () { return store_js_2.mapTwinEdgeRow; } });
+var ref_validation_js_1 = require("./edges/ref-validation.js");
+Object.defineProperty(exports, "assertTwinRefsVisibleToScopes", { enumerable: true, get: function () { return ref_validation_js_1.assertTwinRefsVisibleToScopes; } });
+Object.defineProperty(exports, "listVisibleTwinEdgesForRefs", { enumerable: true, get: function () { return ref_validation_js_1.listVisibleTwinEdgesForRefs; } });
+__exportStar(require("./agent-situation/index.js"), exports);
+__exportStar(require("./agent-graph/index.js"), exports);
 __exportStar(require("./entities/types.js"), exports);
 __exportStar(require("./entities/errors.js"), exports);
 __exportStar(require("./entities/store.js"), exports);
@@ -253,10 +300,12 @@ __exportStar(require("./cases/composition-overrides.js"), exports);
 __exportStar(require("./cases/freshness.js"), exports);
 __exportStar(require("./cases/membership-explain.js"), exports);
 __exportStar(require("./connectors/event-index.js"), exports);
+__exportStar(require("./connectors/raw-query.js"), exports);
 __exportStar(require("./connectors/types.js"), exports);
 __exportStar(require("./search/question-type.js"), exports);
 __exportStar(require("./search/feedback-store.js"), exports);
 __exportStar(require("./search/ranker-features.js"), exports);
 __exportStar(require("./search/ranker-trainer.js"), exports);
 __exportStar(require("./search/ranker-rescore.js"), exports);
+__exportStar(require("./search/search-quality.js"), exports);
 //# sourceMappingURL=index.js.map

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