@jungjaehoon/mama-core 1.4.2 → 1.5.0

package/dist/mama-api.js

@@ -80,6 +80,9 @@ 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, "listRecentMemoryEvents", { enumerable: true, get: function () { return event_store_js_1.listRecentMemoryEvents; } });
+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");
 // Session-level warning cooldown cache (Story 1.1, 1.2)
 // Prevents spam by tracking warned topics per session
 const warnedTopicsCache = new Map();
@@ -111,7 +114,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, }) {
+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, }) {
     // Validate required fields
     if (!topic || typeof topic !== 'string') {
         throw new Error('mama.save() requires topic (string)');
@@ -161,7 +164,7 @@ 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 } = await (0, api_js_1.saveMemory)({
+    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,
@@ -173,6 +176,7 @@ async function save({ topic, decision, reasoning, confidence = 0.5, type = 'user
             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
@@ -255,13 +259,17 @@ async function save({ topic, decision, reasoning, confidence = 0.5, type = 'user
                 if (searchResults && typeof searchResults === 'object' && 'results' in searchResults) {
                     // Filter out the decision we just saved
                     similar_decisions = searchResults.results
+                        .filter((d) => d.source_type === 'decision')
                         .filter((d) => d.id !== decisionId)
                         .map((d) => ({
                         id: d.id,
                         topic: d.topic,
                         decision: d.decision,
                         similarity: d.similarity,
+                        retrieval_score: d.retrieval_score ?? null,
                         created_at: d.created_at,
+                        event_date: d.event_date ?? null,
+                        event_datetime: d.event_datetime ?? null,
                     }));
                     if (similar_decisions.length > 0) {
                         (0, progress_indicator_js_1.logComplete)(`Found ${similar_decisions.length} related decision(s)`);
@@ -308,6 +316,9 @@ async function save({ topic, decision, reasoning, confidence = 0.5, type = 'user
     return {
         success: true,
         id: decisionId,
+        saved_decision_id: decisionId,
+        timeline_event_id: timelineEventId ?? null,
+        timeline_event_ids: timelineEventIds ?? [],
         ...(similar_decisions.length > 0 && { similar_decisions }),
         ...(warning && { warning }),
         ...(collaboration_hint && { collaboration_hint }),
@@ -698,60 +709,260 @@ function applyRecencyBoost(results, options = {}) {
     })
         .sort((a, b) => (b.final_score ?? 0) - (a.final_score ?? 0));
 }
+/** Phase 3 Task 33: learned-ranker meta attached to mama.suggest response. */
+function buildRankerMeta(applied, modelId, skippedReason) {
+    const meta = {
+        model_id: modelId,
+        feature_set_version: ranker_features_js_1.SEARCH_RANKER_FEATURE_SET_VERSION,
+        applied,
+        mode: 'offline',
+    };
+    if (skippedReason) {
+        meta.skipped_reason = skippedReason;
+    }
+    return meta;
+}
+function resultRecord(result) {
+    if (typeof result.record === 'object' &&
+        result.record !== null &&
+        !Array.isArray(result.record)) {
+        return result.record;
+    }
+    return {};
+}
+function stringOrNull(value) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    return String(value);
+}
+function numberOrNull(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        return null;
+    }
+    return value;
+}
+function confidenceValue(record, fallback) {
+    const numeric = numberOrNull(record.confidence);
+    if (numeric !== null) {
+        return numeric;
+    }
+    switch (record.confidence) {
+        case 'high':
+            return 0.9;
+        case 'medium':
+            return 0.6;
+        case 'low':
+            return 0.3;
+        default:
+            return fallback;
+    }
+}
+function mapRolledUpResult(result) {
+    const record = resultRecord(result);
+    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.
+    // Decision/checkpoint records use their own fields (summary/decision).
+    const isWikiPageLeaf = result.source_type === 'wiki_page';
+    const decision = isWikiPageLeaf
+        ? (stringOrNull(record.content ?? record.summary ?? record.decision ?? record.title) ??
+            result.source_id)
+        : (stringOrNull(record.summary ?? record.decision ?? record.title ?? record.content) ??
+            result.source_id);
+    const reasoning = stringOrNull(record.details ?? record.reasoning ?? record.status_reason ?? record.content) ??
+        '';
+    return {
+        id: result.source_id,
+        topic,
+        decision,
+        reasoning,
+        confidence: confidenceValue(record, result.score),
+        // Back-compat with pre-rollup consumers (swarm-mama-adapter tests,
+        // older callers): similarity mirrors the retrieval score when we don't
+        // have a separate similarity measure. retrieval_score remains the
+        // authoritative field for Phase 3 code paths.
+        similarity: result.score,
+        retrieval_score: result.score,
+        created_at: record.created_at ?? null,
+        event_date: record.event_date ?? null,
+        event_datetime: record.event_datetime ?? null,
+        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,
+    };
+}
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 async function suggest(userQuestion, options = {}) {
     if (!userQuestion || typeof userQuestion !== 'string') {
         throw new Error('mama.suggest() requires userQuestion (string)');
     }
-    const { format = 'json', limit = 5, threshold, useReranking = false, 
+    const { format = 'json', limit = 5, threshold, useReranking = false, rerankWithLearned = false, 
     // Recency boosting parameters (Gaussian Decay - Elasticsearch style)
     recencyWeight = 0.3, // 0-1: How much to weight recency (0.3 = 70% semantic, 30% recency)
     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;
+    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,
             ...(options.scopes && { scopes: options.scopes }),
         });
+        const fusedHits = bundle.fused_hits ?? [];
+        const rolledUp = fusedHits.length > 0 ? (0, search_rollup_js_1.rollUpSearchHits)({ fusedHits, adapter: (0, memory_store_js_1.getAdapter)() }) : [];
+        // 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
+        // that match the ranker's expected shape (id + source_type + case_id).
+        const baseRankerMeta = useReranking
+            ? buildRankerMeta(false, null, 'llm_reranking_requested')
+            : rerankWithLearned
+                ? null // marker: rescoring requested, actual meta set per-path after rescore
+                : buildRankerMeta(false, null, 'feature_disabled');
+        const applyLearnedRanker = (results) => {
+            if (baseRankerMeta !== null) {
+                return { results, meta: baseRankerMeta };
+            }
+            // Phase 3 Task 33: the caller opted in via rerankWithLearned, but the
+            // runtime `search_ranker_enabled` gate still has final say. This lets
+            // operators disable the learned ranker globally during rollback without
+            // touching any caller code.
+            let runtimeEnabled = true;
+            try {
+                runtimeEnabled = (0, ranker_rescore_js_1.isSearchRankerEnabled)((0, memory_store_js_1.getAdapter)());
+            }
+            catch (err) {
+                (0, debug_logger_js_1.warn)(`[mama.suggest] isSearchRankerEnabled check failed: ${String(err)}`);
+            }
+            if (!runtimeEnabled) {
+                return { results, meta: buildRankerMeta(false, null, 'feature_disabled') };
+            }
+            try {
+                const rescored = (0, ranker_rescore_js_1.rescoreSearchResults)((0, memory_store_js_1.getAdapter)(), {
+                    query: userQuestion,
+                    results,
+                });
+                return {
+                    results: rescored.results,
+                    meta: buildRankerMeta(rescored.skipped_reason === undefined, rescored.model_id, rescored.skipped_reason),
+                };
+            }
+            catch (err) {
+                (0, debug_logger_js_1.warn)(`[mama.suggest] learned-ranker rescore failed: ${String(err)}`);
+                return { results, meta: buildRankerMeta(false, null, 'rescore_error') };
+            }
+        };
+        const summarizeGraphExpansion = (rows) => {
+            const sources = {
+                primary: 0,
+                supersedes_chain: 0,
+                refines: 0,
+                refined_by: 0,
+                contradicts: 0,
+            };
+            let expandedCount = 0;
+            for (const row of rows) {
+                const graphSource = row.graph_source ?? 'primary';
+                if (graphSource === 'primary') {
+                    sources.primary += 1;
+                    continue;
+                }
+                expandedCount += 1;
+                if (graphSource in sources) {
+                    const key = graphSource;
+                    sources[key] += 1;
+                }
+            }
+            return {
+                total_results: rows.length,
+                primary_count: sources.primary,
+                expanded_count: expandedCount,
+                sources,
+            };
+        };
+        if (rolledUp.length > 0) {
+            const filteredResults = rolledUp.slice(0, rerankPoolLimit);
+            const { results: mappedResults, meta: rankerMeta } = applyLearnedRanker(filteredResults.map(mapRolledUpResult));
+            const limitedResults = mappedResults.slice(0, limit);
+            if (format === 'markdown') {
+                const context = limitedResults
+                    .map((result, index) => `${index + 1}. [${result.topic}] ${result.decision}\n   ${result.reasoning}`)
+                    .join('\n');
+                return `🔍 Search method: memory_v2\n${context}`;
+            }
+            return {
+                query: userQuestion,
+                results: limitedResults,
+                meta: {
+                    count: limitedResults.length,
+                    search_method: 'memory_v2',
+                    threshold: threshold || 'adaptive',
+                    recency_boost: disableRecency
+                        ? null
+                        : {
+                            weight: recencyWeight,
+                            scale: recencyScale,
+                            decay: recencyDecay,
+                        },
+                    graph_expansion: summarizeGraphExpansion(limitedResults),
+                    ranker: rankerMeta,
+                },
+            };
+        }
         if (bundle.memories.length > 0) {
             // recallMemory uses RRF fusion — confidence is overwritten with the normalized
             // retrieval score (0-1 range, where 1.0 = best match in this result set).
             // The original stored confidence is lost after RRF normalization.
             // We capture the retrieval score separately so `similarity` reflects search
             // relevance while `confidence` is passed through as-is from the bundle.
-            let filteredMemories = bundle.memories;
-            // Apply limit
-            filteredMemories = filteredMemories.slice(0, limit);
+            const filteredMemories = bundle.memories.slice(0, rerankPoolLimit);
+            const baseRows = filteredMemories.map((memory) => ({
+                id: memory.id,
+                topic: memory.topic,
+                decision: memory.summary,
+                reasoning: memory.details,
+                confidence: memory.confidence,
+                // recallMemory currently normalizes fused retrieval rank into `confidence`.
+                // Keep that value visible as retrieval_score, but do not pretend it is
+                // semantic similarity; save-time warning logic keys off `similarity`.
+                similarity: null,
+                retrieval_score: memory.confidence ?? null,
+                final_score: memory.confidence ?? null,
+                created_at: memory.created_at,
+                event_date: memory.event_date ?? null,
+                event_datetime: memory.event_datetime ?? null,
+                graph_source: 'primary',
+                graph_rank: 1,
+                related_to: null,
+                edge_reason: null,
+                case_id: null,
+                source_type: memory.kind ??
+                    memory.source?.source_type ??
+                    memory.source_type ??
+                    memory.type ??
+                    'decision',
+            }));
+            const { results: rankedRows, meta: rankerMeta } = applyLearnedRanker(baseRows);
+            const limitedRows = rankedRows.slice(0, limit);
             if (format === 'markdown') {
-                const context = filteredMemories
-                    .map((memory, index) => `${index + 1}. [${memory.topic}] ${memory.summary}\n   ${memory.details}`)
+                const context = limitedRows
+                    .map((row, index) => `${index + 1}. [${row.topic}] ${row.decision}\n   ${row.reasoning}`)
                     .join('\n');
                 return `🔍 Search method: memory_v2\n${context}`;
             }
             return {
                 query: userQuestion,
-                results: filteredMemories.map((memory, idx) => ({
-                    id: memory.id,
-                    topic: memory.topic,
-                    decision: memory.summary,
-                    reasoning: memory.details,
-                    confidence: memory.confidence,
-                    // memory.confidence is the normalized RRF retrieval score (0-1) after
-                    // recallMemory.  Use it as similarity so the field reflects search relevance
-                    // rather than the original stored trust score.
-                    similarity: memory.confidence ?? 1 - idx * 0.01,
-                    created_at: memory.created_at,
-                    event_date: memory.event_date ?? null,
-                    graph_source: 'primary',
-                    graph_rank: 1,
-                    related_to: null,
-                    edge_reason: null,
-                })),
+                results: limitedRows,
                 meta: {
-                    count: filteredMemories.length,
+                    count: limitedRows.length,
                     search_method: 'memory_v2',
                     threshold: threshold || 'adaptive',
                     recency_boost: disableRecency
@@ -761,18 +972,8 @@ async function suggest(userQuestion, options = {}) {
                             scale: recencyScale,
                             decay: recencyDecay,
                         },
-                    graph_expansion: {
-                        total_results: filteredMemories.length,
-                        primary_count: bundle.graph_context.primary.length,
-                        expanded_count: bundle.graph_context.expanded.length,
-                        sources: {
-                            primary: bundle.graph_context.primary.length,
-                            supersedes_chain: 0,
-                            refines: 0,
-                            refined_by: 0,
-                            contradicts: 0,
-                        },
-                    },
+                    graph_expansion: summarizeGraphExpansion(limitedRows),
+                    ranker: rankerMeta,
                 },
             };
         }
@@ -791,7 +992,7 @@ async function suggest(userQuestion, options = {}) {
             const wordCount = userQuestion.split(/\s+/).length;
             const adaptiveThreshold = threshold !== undefined ? threshold : wordCount < 3 ? 0.7 : 0.6;
             // Vector search
-            results = await (0, memory_store_js_1.vectorSearch)(queryEmbedding, limit * 2, 0.5); // Get more candidates
+            results = await (0, memory_store_js_1.vectorSearch)(queryEmbedding, rerankPoolLimit * 2, 0.5); // Get more candidates
             // Filter by adaptive threshold
             results = results.filter((r) => r.similarity >= adaptiveThreshold);
             // Stage 1.4: Temporal boost — detect time-related queries and boost matching results
@@ -839,7 +1040,7 @@ async function suggest(userQuestion, options = {}) {
             // Stage 1.7: FTS5 hybrid merge (Haiku Memory Layer)
             {
                 try {
-                    const ftsResults = await (0, db_manager_js_1.fts5Search)(userQuestion, limit * 2);
+                    const ftsResults = await (0, db_manager_js_1.fts5Search)(userQuestion, rerankPoolLimit * 2);
                     if (ftsResults.length > 0) {
                         // Normalize FTS5 ranks (BM25 returns negative values, closer to 0 = better)
                         const maxRank = Math.max(...ftsResults.map((r) => Math.abs(r.rank)));
@@ -924,7 +1125,7 @@ async function suggest(userQuestion, options = {}) {
         ORDER BY created_at DESC
         LIMIT ?
       `);
-            const rows = (await stmt.all(...likeParams, limit));
+            const rows = (await stmt.all(...likeParams, rerankPoolLimit));
             results = rows.map((row) => ({
                 ...row,
                 similarity: 0.75, // Assign moderate similarity for keyword matches
@@ -949,8 +1150,32 @@ async function suggest(userQuestion, options = {}) {
         if (useReranking) {
             results = await rerankWithLLM(userQuestion, results);
         }
-        // Slice to limit
-        const finalResults = results.slice(0, limit);
+        const rerankCandidateResults = results.slice(0, rerankPoolLimit);
+        const vectorRows = rerankCandidateResults.map((r) => ({
+            id: r.id,
+            topic: r.topic,
+            decision: r.decision,
+            reasoning: r.reasoning,
+            confidence: r.confidence,
+            similarity: r.similarity,
+            created_at: r.created_at,
+            event_date: r.event_date ?? null,
+            event_datetime: r.event_datetime ?? null,
+            // Recency metadata (NEW - Gaussian Decay)
+            recency_score: r.recency_score,
+            recency_age_days: r.recency_age_days,
+            final_score: r.final_score || r.similarity, // Falls back to similarity if no recency
+            retrieval_score: r.similarity ?? null,
+            // Graph metadata (NEW - Phase 1)
+            graph_source: r.graph_source || 'primary',
+            graph_rank: r.graph_rank || 1.0,
+            related_to: r.related_to || null,
+            edge_reason: r.edge_reason || null,
+            case_id: null,
+            source_type: 'decision',
+        }));
+        const { results: rankedVectorRows, meta: rankerMeta } = applyLearnedRanker(vectorRows);
+        const finalResults = rankedVectorRows.slice(0, limit);
         // Markdown format (for human display)
         if (format === 'markdown') {
             const context = (0, decision_formatter_js_1.formatContext)(finalResults, { maxTokens: 500 });
@@ -976,27 +1201,9 @@ async function suggest(userQuestion, options = {}) {
                 contradicts: finalResults.filter((r) => r.graph_source === 'contradicts').length,
             },
         };
-        // JSON format (default - LLM-first)
         return {
             query: userQuestion,
-            results: finalResults.map((r) => ({
-                id: r.id,
-                topic: r.topic,
-                decision: r.decision,
-                reasoning: r.reasoning,
-                confidence: r.confidence,
-                similarity: r.similarity,
-                created_at: r.created_at,
-                // Recency metadata (NEW - Gaussian Decay)
-                recency_score: r.recency_score,
-                recency_age_days: r.recency_age_days,
-                final_score: r.final_score || r.similarity, // Falls back to similarity if no recency
-                // Graph metadata (NEW - Phase 1)
-                graph_source: r.graph_source || 'primary',
-                graph_rank: r.graph_rank || 1.0,
-                related_to: r.related_to || null,
-                edge_reason: r.edge_reason || null,
-            })),
+            results: finalResults,
             meta: {
                 count: finalResults.length,
                 search_method: searchMethod,
@@ -1011,6 +1218,7 @@ async function suggest(userQuestion, options = {}) {
                     },
                 // Graph expansion stats (NEW - Phase 1)
                 graph_expansion: searchMethod.includes('graph') ? graphStats : null,
+                ranker: rankerMeta,
             },
         };
     }
@@ -1068,7 +1276,7 @@ async function listDecisions(options = {}) {
         JOIN memory_scope_bindings msb ON msb.memory_id = d.id
         WHERE msb.scope_id IN (${placeholders})
           AND d.superseded_by IS NULL
-        ORDER BY d.created_at DESC
+        ORDER BY COALESCE(d.event_datetime, d.created_at) DESC, d.created_at DESC
         LIMIT ?
       `);
             decisions = await stmt.all(...scopeIds, limit);
@@ -1077,7 +1285,7 @@ async function listDecisions(options = {}) {
             const stmt = adapter.prepare(`
         SELECT * FROM decisions
         WHERE superseded_by IS NULL
-        ORDER BY created_at DESC
+        ORDER BY COALESCE(event_datetime, created_at) DESC, created_at DESC
         LIMIT ?
       `);
             decisions = await stmt.all(limit);

package/dist/memory/api.d.ts

@@ -1,6 +1,7 @@
+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, MemoryScopeRef, MemoryStatus, ProfileSnapshot, RecallBundle, IngestConversationInput, ExtractedMemoryUnit, IngestConversationResult } from './types.js';
+import type { MemoryKind, MemoryAgentBootstrap, MemoryAuditAck, MemoryEdge, MemoryRecord, MemoryScopeRef, MemoryStatus, ProfileSnapshot, RecallBundle, IngestConversationInput, ExtractedMemoryUnit, IngestConversationResult } from './types.js';
 interface SaveMemoryInput {
     topic: string;
     kind: MemoryKind;
@@ -23,6 +24,21 @@ interface SaveMemoryInput {
      * 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[];
@@ -30,12 +46,20 @@ interface RecallMemoryOptions {
     includeHistory?: boolean;
     skipGraphExpansion?: boolean;
     topicPrefix?: string;
+    limit?: number;
 }
 interface IngestMemoryInput {
     content: string;
     scopes?: MemoryScopeRef[];
     source: SaveMemoryInput['source'];
     eventDate?: string;
+    eventDateTime?: number;
+}
+export interface FusedHit {
+    source_type: 'decision' | 'wiki_page';
+    source_id: string;
+    record: MemoryRecord | WikiPageIndexRecord;
+    fused_rank_score: number;
 }
 export declare const LEXICAL_STOPWORDS: Set<string>;
 export declare function getLexicalQueryTokens(query: string): string[];
@@ -43,6 +67,9 @@ export declare function loadEdgesForIds(ids: string[]): Promise<MemoryEdge[]>;
 export declare function saveMemory(input: SaveMemoryInput): Promise<{
     success: boolean;
     id: string;
+    saved_decision_id?: string;
+    timeline_event_id?: string | null;
+    timeline_event_ids?: string[];
 }>;
 export declare function buildProfile(scopes: MemoryScopeRef[]): Promise<ProfileSnapshot>;
 export declare function recallMemory(query: string, options?: RecallMemoryOptions): Promise<RecallBundle>;