@jungjaehoon/mama-core 1.3.2 → 1.4.0

package/dist/memory/api.js

@@ -0,0 +1,972 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getChannelSummary = exports.upsertChannelSummary = exports.LEXICAL_STOPWORDS = void 0;
+exports.getLexicalQueryTokens = getLexicalQueryTokens;
+exports.loadEdgesForIds = loadEdgesForIds;
+exports.saveMemory = saveMemory;
+exports.buildProfile = buildProfile;
+exports.recallMemory = recallMemory;
+exports.ingestMemory = ingestMemory;
+exports.evolveMemory = evolveMemory;
+exports.buildMemoryBootstrap = buildMemoryBootstrap;
+exports.createAuditAck = createAuditAck;
+exports.recordMemoryAudit = recordMemoryAudit;
+exports.setExtractionFn = setExtractionFn;
+exports.ingestConversation = ingestConversation;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const db_manager_js_1 = require("../db-manager.js");
+const embeddings_js_1 = require("../embeddings.js");
+const profile_builder_js_1 = require("./profile-builder.js");
+const bootstrap_builder_js_1 = require("./bootstrap-builder.js");
+const evolution_engine_js_1 = require("./evolution-engine.js");
+const channel_summary_state_store_js_1 = require("./channel-summary-state-store.js");
+const debug_logger_js_1 = require("../debug-logger.js");
+const truth_store_js_1 = require("./truth-store.js");
+const extraction_prompt_js_1 = require("./extraction-prompt.js");
+const types_js_1 = require("./types.js");
+const channel_summary_store_js_1 = require("./channel-summary-store.js");
+Object.defineProperty(exports, "getChannelSummary", { enumerable: true, get: function () { return channel_summary_store_js_1.getChannelSummary; } });
+Object.defineProperty(exports, "upsertChannelSummary", { enumerable: true, get: function () { return channel_summary_store_js_1.upsertChannelSummary; } });
+function buildDecisionId(topic) {
+    const safeTopic = topic.replace(/[^a-z0-9_]+/gi, '_').toLowerCase();
+    return `decision_${safeTopic}_${Date.now()}_${node_crypto_1.default.randomUUID().slice(0, 8)}`;
+}
+function toMemoryRecord(row, scopes, fallbackSource) {
+    let trustContext = null;
+    if (typeof row.trust_context === 'string') {
+        try {
+            trustContext = JSON.parse(row.trust_context);
+        }
+        catch {
+            /* malformed */
+        }
+    }
+    const savedSource = trustContext?.source;
+    return {
+        id: String(row.id),
+        topic: String(row.topic),
+        kind: row.kind ?? 'decision',
+        summary: String(row.summary ?? row.decision ?? ''),
+        details: String(row.reasoning ?? row.decision ?? ''),
+        confidence: Number(row.confidence ?? 0.5),
+        status: row.status ?? 'active',
+        scopes,
+        source: savedSource ?? fallbackSource,
+        created_at: row.created_at,
+        updated_at: row.updated_at ?? row.created_at,
+        event_date: row.event_date ?? null,
+    };
+}
+function batchLoadScopes(adapter, memoryIds) {
+    const scopeMap = new Map();
+    if (memoryIds.length === 0)
+        return scopeMap;
+    const placeholders = memoryIds.map(() => '?').join(', ');
+    const rows = adapter
+        .prepare(`
+        SELECT msb.memory_id, ms.kind, ms.external_id
+        FROM memory_scope_bindings msb
+        JOIN memory_scopes ms ON ms.id = msb.scope_id
+        WHERE msb.memory_id IN (${placeholders})
+        ORDER BY msb.is_primary DESC
+      `)
+        .all(...memoryIds);
+    for (const row of rows) {
+        const existing = scopeMap.get(row.memory_id) ?? [];
+        existing.push({ kind: row.kind, id: row.external_id });
+        scopeMap.set(row.memory_id, existing);
+    }
+    return scopeMap;
+}
+async function loadScopedMemories(scopes) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const fallbackSource = { package: 'mama-core', source_type: 'db' };
+    let rows;
+    if (scopes.length === 0) {
+        rows = adapter
+            .prepare(`
+          SELECT id, topic, decision, reasoning, confidence, created_at, updated_at, trust_context,
+                 kind, status, summary, event_date
+          FROM decisions
+          ORDER BY created_at DESC
+        `)
+            .all();
+    }
+    else {
+        const scopeIds = await Promise.all(scopes.map((scope) => (0, db_manager_js_1.ensureMemoryScope)(scope.kind, scope.id)));
+        const placeholders = scopeIds.map(() => '?').join(', ');
+        rows = adapter
+            .prepare(`
+          SELECT DISTINCT d.id, d.topic, d.decision, d.reasoning, d.confidence, d.created_at,
+                 d.updated_at, d.trust_context, d.kind, d.status, d.summary, d.event_date
+          FROM decisions d
+          JOIN memory_scope_bindings msb ON msb.memory_id = d.id
+          WHERE msb.scope_id IN (${placeholders})
+          ORDER BY d.created_at DESC
+        `)
+            .all(...scopeIds);
+    }
+    const memoryIds = rows.map((row) => String(row.id));
+    const scopeMap = batchLoadScopes(adapter, memoryIds);
+    return rows.map((row) => toMemoryRecord(row, scopeMap.get(String(row.id)) ?? [], fallbackSource));
+}
+exports.LEXICAL_STOPWORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'are',
+    'as',
+    'at',
+    'be',
+    'by',
+    'did',
+    'do',
+    'does',
+    'for',
+    'from',
+    'had',
+    'has',
+    'have',
+    'how',
+    'i',
+    'in',
+    'is',
+    'it',
+    'my',
+    'of',
+    'on',
+    'or',
+    'that',
+    'the',
+    'their',
+    'to',
+    'was',
+    'were',
+    'what',
+    'when',
+    'where',
+    'which',
+    'who',
+    'why',
+    'with',
+    'you',
+    'your',
+]);
+/**
+ * Intentionally minimal English suffix stemmer for fuzzy lexical matching.
+ * Not a full Porter/Snowball implementation — imperfect stems (e.g., "running" → "runn")
+ * are acceptable for scoring/recall. Avoids pulling in a heavier stemming dependency.
+ */
+function stemToken(token) {
+    if (token.length <= 4)
+        return token;
+    // Order matters: try longest suffix first
+    if (token.endsWith('ies') && token.length > 4)
+        return token.slice(0, -3) + 'y';
+    if (token.endsWith('ing') && token.length > 5)
+        return token.slice(0, -3);
+    if (token.endsWith('ed') && token.length > 4)
+        return token.slice(0, -2);
+    if (token.endsWith('s') && !token.endsWith('ss'))
+        return token.slice(0, -1);
+    return token;
+}
+function getLexicalQueryTokens(query) {
+    return query
+        .toLowerCase()
+        .split(/[\s,.!?;:()[\]{}"']+/)
+        .filter((token) => token.length > 2 && !exports.LEXICAL_STOPWORDS.has(token));
+}
+function buildLexicalCandidates(records, query) {
+    const tokens = getLexicalQueryTokens(query);
+    const normalizedQuery = query.toLowerCase();
+    return records
+        .map((record) => {
+        const haystack = [record.topic, record.summary, record.details].join(' ').toLowerCase();
+        const tokenMatches = tokens.reduce((count, token) => {
+            const stem = stemToken(token);
+            if (!haystack.includes(token) && !haystack.includes(stem)) {
+                return count;
+            }
+            if (token.length >= 8) {
+                return count + 3;
+            }
+            if (token.length >= 5) {
+                return count + 2;
+            }
+            return count + 1;
+        }, 0);
+        const phraseBoost = haystack.includes(normalizedQuery) ? 2 : 0;
+        const score = tokenMatches + phraseBoost;
+        return { memory: record, score };
+    })
+        .filter((candidate) => candidate.score > 0)
+        .sort((left, right) => {
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return Number(right.memory.created_at) - Number(left.memory.created_at);
+    });
+}
+function lexicalScoreToConfidence(score) {
+    return Math.min(0.95, 0.45 + score * 0.05);
+}
+// Retained for potential future use in non-RRF recall paths
+function _mergeRecallCandidates(primary, lexical) {
+    const merged = new Map();
+    for (const memory of primary) {
+        merged.set(memory.id, {
+            memory,
+            sortScore: memory.confidence ?? 0.5,
+            lexicalScore: 0,
+        });
+    }
+    // Determine the lowest vector confidence to cap lexical-only candidates below it
+    const minVectorConfidence = primary.length > 0 ? Math.min(...primary.map((m) => m.confidence ?? 0.5)) : 1.0;
+    const LEXICAL_ONLY_CAP = Math.max(0, minVectorConfidence - 0.01);
+    for (const candidate of lexical) {
+        const lexicalConfidence = lexicalScoreToConfidence(candidate.score);
+        const existing = merged.get(candidate.memory.id);
+        if (existing) {
+            // Already has a vector hit — safe to boost with lexical score
+            existing.sortScore = Math.max(existing.sortScore, lexicalConfidence);
+            existing.lexicalScore = Math.max(existing.lexicalScore, candidate.score);
+            existing.memory = {
+                ...existing.memory,
+                confidence: Math.max(existing.memory.confidence ?? 0.5, lexicalConfidence),
+            };
+            merged.set(candidate.memory.id, existing);
+            continue;
+        }
+        // Lexical-only candidate — cap below the lowest vector hit
+        const cappedConfidence = Math.min(lexicalConfidence, LEXICAL_ONLY_CAP);
+        merged.set(candidate.memory.id, {
+            memory: {
+                ...candidate.memory,
+                confidence: Math.max(candidate.memory.confidence ?? 0.5, cappedConfidence),
+            },
+            sortScore: cappedConfidence,
+            lexicalScore: candidate.score,
+        });
+    }
+    return Array.from(merged.values())
+        .sort((left, right) => {
+        if (right.sortScore !== left.sortScore) {
+            return right.sortScore - left.sortScore;
+        }
+        if (right.lexicalScore !== left.lexicalScore) {
+            return right.lexicalScore - left.lexicalScore;
+        }
+        return Number(right.memory.created_at) - Number(left.memory.created_at);
+    })
+        .map((candidate) => candidate.memory);
+}
+async function loadEdgesForIds(ids) {
+    if (ids.length === 0)
+        return [];
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const placeholders = ids.map(() => '?').join(', ');
+    const rows = adapter
+        .prepare(`SELECT from_id, to_id, relationship AS type, reason
+       FROM decision_edges
+       WHERE (from_id IN (${placeholders}) OR to_id IN (${placeholders}))
+         AND (approved_by_user != 0 OR approved_by_user IS NULL)`)
+        .all(...ids, ...ids);
+    return rows.map((row) => ({
+        from_id: row.from_id,
+        to_id: row.to_id,
+        type: row.type,
+        reason: row.reason ?? undefined,
+    }));
+}
+async function saveMemory(input) {
+    await (0, db_manager_js_1.initDB)();
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const id = buildDecisionId(input.topic);
+    const now = Date.now();
+    // Find evolution candidates: exact topic match first, then semantic search fallback
+    const primaryScope = input.scopes.length > 0 ? input.scopes[0] : null;
+    const excludeIds = new Set(input.excludeIds ?? []);
+    let existingCandidates;
+    if (primaryScope) {
+        const scopeId = await (0, db_manager_js_1.ensureMemoryScope)(primaryScope.kind, primaryScope.id);
+        existingCandidates = adapter
+            .prepare(`
+          SELECT d.id, d.topic, d.summary, d.kind
+          FROM decisions d
+          JOIN memory_scope_bindings msb ON msb.memory_id = d.id
+          WHERE d.topic = ? AND msb.scope_id = ?
+            AND (d.status = 'active' OR d.status IS NULL)
+            AND d.superseded_by IS NULL
+          ORDER BY d.created_at DESC
+          LIMIT 5
+        `)
+            .all(input.topic, scopeId).filter((c) => !excludeIds.has(c.id));
+    }
+    else {
+        existingCandidates = adapter
+            .prepare(`
+          SELECT id, topic, summary, kind
+          FROM decisions
+          WHERE topic = ?
+            AND (status = 'active' OR status IS NULL)
+            AND superseded_by IS NULL
+          ORDER BY created_at DESC
+          LIMIT 5
+        `)
+            .all(input.topic).filter((c) => !excludeIds.has(c.id));
+    }
+    // Semantic fallback: if no exact topic match, find similar memories via vector search
+    if (existingCandidates.length === 0) {
+        try {
+            const queryText = `${input.topic} ${input.summary}`;
+            const embedding = await (0, embeddings_js_1.generateEmbedding)(queryText);
+            const semanticResults = await (0, db_manager_js_1.vectorSearch)(embedding, 3, 0.82);
+            // Scope-filter semantic candidates when a primary scope is available
+            let scopeFiltered = semanticResults;
+            if (primaryScope) {
+                const semIds = semanticResults.map((r) => String(r.id));
+                const semScopeMap = batchLoadScopes(adapter, semIds);
+                const scopeKey = `${primaryScope.kind}:${primaryScope.id}`;
+                scopeFiltered = semanticResults.filter((r) => {
+                    const scopes = semScopeMap.get(String(r.id)) ?? [];
+                    return scopes.length === 0 || scopes.some((s) => `${s.kind}:${s.id}` === scopeKey);
+                });
+            }
+            existingCandidates = scopeFiltered
+                .filter((r) => {
+                const status = String(r.status || '');
+                return !status || status === 'active' || status === '';
+            })
+                .filter((c) => !excludeIds.has(String(c.id)))
+                .map((r) => ({
+                id: String(r.id),
+                topic: String(r.topic || ''),
+                summary: String(r.decision || ''),
+                kind: 'fact',
+                _semanticMatch: true,
+            }));
+        }
+        catch {
+            // Semantic search unavailable — proceed with empty candidates
+        }
+    }
+    const evolution = (0, evolution_engine_js_1.resolveMemoryEvolution)({
+        incoming: { topic: input.topic, summary: input.summary, kind: input.kind },
+        existing: existingCandidates.map((c) => ({
+            ...c,
+            kind: (c.kind || 'fact'),
+        })),
+    });
+    const supersedesTarget = evolution.edges.find((edge) => edge.type === 'supersedes')?.to_id ?? null;
+    await (0, db_manager_js_1.insertDecisionWithEmbedding)({
+        id,
+        topic: input.topic,
+        decision: input.summary,
+        reasoning: input.details,
+        confidence: input.confidence ?? 0.5,
+        supersedes: supersedesTarget,
+        created_at: now,
+        updated_at: now,
+        trust_context: JSON.stringify({ source: input.source }),
+        event_date: input.eventDate ?? null,
+    });
+    // Pre-resolve scope IDs before the synchronous transaction
+    const resolvedScopeIds = [];
+    for (const [index, scope] of input.scopes.entries()) {
+        const scopeId = await (0, db_manager_js_1.ensureMemoryScope)(scope.kind, scope.id);
+        resolvedScopeIds.push({ scopeId, isPrimary: index === 0 });
+    }
+    // Wrap all post-insert mutations in a transaction for atomicity
+    adapter.transaction(() => {
+        adapter
+            .prepare(`
+          UPDATE decisions
+          SET kind = ?, status = ?, summary = ?, is_static = ?, trust_context = ?, updated_at = ?
+          WHERE id = ?
+        `)
+            .run(input.kind, input.status ?? 'active', input.summary, input.kind === 'preference' || input.kind === 'constraint' ? 1 : 0, JSON.stringify({ source: input.source }), now, id);
+        for (const { scopeId, isPrimary } of resolvedScopeIds) {
+            adapter
+                .prepare(`
+            INSERT OR REPLACE INTO memory_scope_bindings (memory_id, scope_id, is_primary)
+            VALUES (?, ?, ?)
+          `)
+                .run(id, scopeId, isPrimary ? 1 : 0);
+        }
+        for (const edge of evolution.edges) {
+            if (edge.type === 'supersedes') {
+                adapter
+                    .prepare(`UPDATE decisions SET superseded_by = ?, status = 'superseded', updated_at = ? WHERE id = ?`)
+                    .run(id, now, edge.to_id);
+            }
+            adapter
+                .prepare(`
+            INSERT OR REPLACE INTO decision_edges (from_id, to_id, relationship, reason, weight, created_at)
+            VALUES (?, ?, ?, ?, ?, ?)
+          `)
+                .run(id, edge.to_id, edge.type, edge.reason ?? null, 1.0, now);
+        }
+    });
+    // Project to memory_truth table (best-effort; failure should not break save)
+    try {
+        await (0, truth_store_js_1.projectMemoryTruth)({
+            memory_id: id,
+            topic: input.topic,
+            truth_status: (input.status ?? 'active'),
+            effective_summary: input.summary,
+            effective_details: input.details,
+            trust_score: input.confidence ?? 0.5,
+            scope_refs: input.scopes,
+            supporting_event_ids: [],
+            superseded_by: undefined,
+        });
+    }
+    catch {
+        // Truth projection is best-effort; do not fail the save
+    }
+    return { success: true, id };
+}
+async function buildProfile(scopes) {
+    const records = await loadScopedMemories(scopes);
+    return (0, profile_builder_js_1.classifyProfileEntries)(records);
+}
+const EXCLUDED_STATUSES = new Set([
+    'superseded',
+    'quarantined',
+    'contradicted',
+    'stale',
+]);
+async function recallMemory(query, options = {}) {
+    const bundle = (0, types_js_1.createEmptyRecallBundle)(query);
+    let matched = [];
+    let retrievalSource = 'none';
+    let _lexicalRecords = null;
+    const loadLexical = async () => {
+        if (_lexicalRecords === null) {
+            _lexicalRecords = await loadScopedMemories(options.scopes ?? []);
+        }
+        return _lexicalRecords;
+    };
+    // Query analysis: detect aggregation patterns and extract sub-queries
+    const lowerQuery = query.toLowerCase();
+    const isAggregation = /\b(how many|how much|total|all|every|each|count|number of)\b/.test(lowerQuery);
+    const hasMultipleEntities = /\b(and|or|vs|versus|compared|between)\b/.test(lowerQuery);
+    const vectorLimit = isAggregation ? 50 : 20;
+    // Multi-query decomposition: extract sub-queries for complex questions
+    const subQueries = [query];
+    if (hasMultipleEntities) {
+        // Split on "or"/"and" to create focused sub-queries
+        const parts = query
+            .split(/\b(?:or|vs|versus|and|,)\b/i)
+            .map((p) => p.trim())
+            .filter((p) => p.length > 10);
+        if (parts.length > 1) {
+            subQueries.push(...parts);
+        }
+    }
+    // Hybrid search: vector + BM25/lexical in parallel, fused with RRF
+    await (0, db_manager_js_1.initDB)();
+    // Channel 1: Vector search (semantic similarity) — run all sub-queries
+    const vectorMatched = [];
+    try {
+        for (const sq of subQueries) {
+            const queryEmbedding = await (0, embeddings_js_1.generateEmbedding)(sq);
+            const vectorResults = await (0, db_manager_js_1.vectorSearch)(queryEmbedding, vectorLimit, 0.3, options.topicPrefix);
+            let filtered = vectorResults;
+            if (options.scopes && options.scopes.length > 0) {
+                const vectorIds = vectorResults.map((r) => String(r.id));
+                const scopeMap = batchLoadScopes((0, db_manager_js_1.getAdapter)(), vectorIds);
+                const requestedScopes = new Set(options.scopes.map((s) => `${s.kind}:${s.id}`));
+                filtered = vectorResults.filter((r) => {
+                    const scopes = scopeMap.get(String(r.id)) ?? [];
+                    // When scopes are requested, zero-binding results must NOT pass through
+                    if (scopes.length === 0)
+                        return false;
+                    return scopes.some((s) => requestedScopes.has(`${s.kind}:${s.id}`));
+                });
+            }
+            for (const result of filtered) {
+                const effectiveStatus = result.status || result.outcome || '';
+                if (!options.includeHistory && effectiveStatus && EXCLUDED_STATUSES.has(effectiveStatus)) {
+                    continue;
+                }
+                vectorMatched.push({
+                    id: String(result.id),
+                    topic: String(result.topic || ''),
+                    kind: 'decision',
+                    summary: String(result.decision || ''),
+                    details: String(result.reasoning || ''),
+                    confidence: result.similarity ?? 0.5,
+                    status: effectiveStatus || 'active',
+                    scopes: [],
+                    source: { package: 'mama-core', source_type: 'vector_search' },
+                    created_at: result.created_at ?? Date.now(),
+                    updated_at: result.created_at ?? Date.now(),
+                });
+            }
+        } // end sub-query loop
+    }
+    catch (vectorErr) {
+        (0, debug_logger_js_1.warn)(`[recallMemory] Vector search failed: ${vectorErr instanceof Error ? vectorErr.message : String(vectorErr)}`);
+    }
+    // Deduplicate vector results from multiple sub-queries
+    const seenIds = new Set();
+    const dedupedVector = [];
+    for (const r of vectorMatched) {
+        if (!seenIds.has(r.id)) {
+            seenIds.add(r.id);
+            dedupedVector.push(r);
+        }
+    }
+    vectorMatched.length = 0;
+    vectorMatched.push(...dedupedVector);
+    // Channel 2: FTS5 BM25 search (preferred) with in-memory lexical fallback
+    // Lazy lexical: skip expensive FTS5/lexical when vector already returned enough results,
+    // unless this is an aggregation query that benefits from broader coverage.
+    const VECTOR_SUFFICIENT_THRESHOLD = 5;
+    const needsLexical = isAggregation || vectorMatched.length < VECTOR_SUFFICIENT_THRESHOLD;
+    let lexicalCandidates = [];
+    const lexicalLimit = isAggregation ? 100 : 50;
+    if (needsLexical) {
+        try {
+            // Try FTS5 first — proper BM25 ranking, much better than in-memory .includes()
+            // FTS5 MATCH treats spaces as AND; convert to OR so partial matches still surface.
+            // Use all non-stopword tokens for FTS5 (stopwords already removed by getLexicalQueryTokens).
+            // Additional high-frequency words that cause too many FTS5 matches are filtered separately.
+            const FTS5_NOISE_WORDS = new Set([
+                'this',
+                'that',
+                'also',
+                'just',
+                'like',
+                'some',
+                'many',
+                'much',
+                'very',
+                'more',
+                'most',
+                'such',
+                'each',
+                'every',
+                'been',
+                'being',
+                'about',
+                'would',
+                'could',
+                'should',
+                'will',
+                'year',
+                'years',
+                'time',
+                'know',
+                'think',
+                'want',
+                'need',
+                'make',
+                'made',
+            ]);
+            const ftsTokens = getLexicalQueryTokens(query)
+                .map((t) => stemToken(t))
+                .filter((t) => !FTS5_NOISE_WORDS.has(t));
+            const ftsQuery = ftsTokens.length > 0 ? ftsTokens.join(' OR ') : query;
+            const ftsResults = await (0, db_manager_js_1.fts5Search)(ftsQuery, lexicalLimit);
+            if (ftsResults.length > 0) {
+                const adapter = (0, db_manager_js_1.getAdapter)();
+                const fallbackSource = {
+                    package: 'mama-core',
+                    source_type: 'fts5',
+                };
+                // Normalize BM25 ranks (negative values, closer to 0 = better match)
+                const maxRank = Math.max(...ftsResults.map((r) => Math.abs(r.rank)));
+                for (const ftsRow of ftsResults) {
+                    const row = adapter
+                        .prepare(`SELECT id, topic, decision, reasoning, confidence, created_at, updated_at,
+                    trust_context, kind, status, summary, event_date
+             FROM decisions WHERE id = ?`)
+                        .get(ftsRow.id);
+                    if (!row)
+                        continue;
+                    const effectiveStatus = row.status || '';
+                    if (!options.includeHistory &&
+                        effectiveStatus &&
+                        EXCLUDED_STATUSES.has(effectiveStatus)) {
+                        continue;
+                    }
+                    const memoryIds = [String(row.id)];
+                    const scopeMap = batchLoadScopes(adapter, memoryIds);
+                    const record = toMemoryRecord(row, scopeMap.get(String(row.id)) ?? [], fallbackSource);
+                    // Topic prefix filtering (matches vectorSearch behavior)
+                    if (options.topicPrefix && !record.topic.startsWith(options.topicPrefix))
+                        continue;
+                    // Scope filtering
+                    if (options.scopes && options.scopes.length > 0) {
+                        const requestedScopes = new Set(options.scopes.map((s) => `${s.kind}:${s.id}`));
+                        const scopes = scopeMap.get(record.id) ?? [];
+                        if (scopes.length === 0)
+                            continue;
+                        if (!scopes.some((s) => requestedScopes.has(`${s.kind}:${s.id}`)))
+                            continue;
+                    }
+                    const bm25Score = maxRank > 0 ? 1 - Math.abs(ftsRow.rank) / maxRank : 0.5;
+                    lexicalCandidates.push({ memory: record, score: bm25Score });
+                }
+            }
+        }
+        catch {
+            // FTS5 not available — fall through to in-memory lexical
+        }
+        // Fallback: in-memory lexical if FTS5 returned nothing
+        if (lexicalCandidates.length === 0) {
+            let lexicalRecords = await loadLexical();
+            if (options.scopes && options.scopes.length > 0) {
+                const lexicalIds = lexicalRecords.map((r) => r.id);
+                const scopeMap = batchLoadScopes((0, db_manager_js_1.getAdapter)(), lexicalIds);
+                const requestedScopes = new Set(options.scopes.map((s) => `${s.kind}:${s.id}`));
+                lexicalRecords = lexicalRecords.filter((r) => {
+                    const scopes = scopeMap.get(r.id) ?? [];
+                    if (scopes.length === 0)
+                        return false;
+                    return scopes.some((s) => requestedScopes.has(`${s.kind}:${s.id}`));
+                });
+            }
+            // Topic prefix filtering for in-memory lexical (matches vectorSearch behavior)
+            if (options.topicPrefix) {
+                lexicalRecords = lexicalRecords.filter((r) => r.topic.startsWith(options.topicPrefix));
+            }
+            lexicalCandidates = buildLexicalCandidates(lexicalRecords, query);
+            if (subQueries.length > 1) {
+                for (const sq of subQueries.slice(1)) {
+                    const subCandidates = buildLexicalCandidates(lexicalRecords, sq);
+                    for (const c of subCandidates) {
+                        if (!lexicalCandidates.some((existing) => existing.memory.id === c.memory.id)) {
+                            lexicalCandidates.push(c);
+                        }
+                    }
+                }
+                lexicalCandidates.sort((a, b) => b.score - a.score);
+            }
+        }
+    } // end needsLexical
+    // RRF Fusion: combine vector and lexical/FTS5 results by reciprocal rank
+    // FTS5 BM25 gets 2x weight — it naturally demotes records where query terms
+    // appear only in passing (e.g. "wedding" mentioned once in a dating record),
+    // so weighting it higher filters topical noise better than equal weighting.
+    // Additionally, vector-only results (no lexical support) are penalized to
+    // reduce semantic-but-off-topic noise.
+    // Lexical-first fusion: FTS5 BM25 provides the primary ranking (topic relevance),
+    // vector similarity acts as a secondary boost (semantic depth).
+    // This prevents off-topic records that are semantically similar from ranking high.
+    const RRF_K = 60;
+    const rrfScores = new Map();
+    // Vector rank map for boosting lexical results
+    const vectorRankMap = new Map();
+    for (let i = 0; i < vectorMatched.length; i++) {
+        vectorRankMap.set(vectorMatched[i].id, i);
+    }
+    // Primary: lexical/FTS5 results with vector boost
+    for (let i = 0; i < lexicalCandidates.length; i++) {
+        const r = lexicalCandidates[i];
+        if (!options.includeHistory && EXCLUDED_STATUSES.has(r.memory.status))
+            continue;
+        const lexScore = 1 / (RRF_K + i + 1);
+        const vecRank = vectorRankMap.get(r.memory.id);
+        const vecBoost = vecRank !== undefined ? 0.2 * (1 / (RRF_K + vecRank + 1)) : 0;
+        rrfScores.set(r.memory.id, { record: r.memory, score: lexScore + vecBoost });
+    }
+    // Secondary: vector-only results (no lexical backing) get heavily discounted
+    for (let i = 0; i < vectorMatched.length; i++) {
+        const r = vectorMatched[i];
+        if (rrfScores.has(r.id))
+            continue; // Already included via lexical
+        const rrfScore = 0.15 * (1 / (RRF_K + i + 1));
+        rrfScores.set(r.id, { record: r, score: rrfScore });
+    }
+    const sortedRrf = Array.from(rrfScores.values()).sort((a, b) => b.score - a.score);
+    // Normalize RRF scores to 0-1 range so downstream consumers (threshold filters,
+    // similarity displays) get meaningful values.  The raw RRF score for K=60 tops out
+    // around 0.033, which is misleading when compared against similarity thresholds.
+    const maxRrf = sortedRrf.length > 0 ? sortedRrf[0].score : 1;
+    matched = sortedRrf.map((entry) => ({
+        ...entry.record,
+        confidence: maxRrf > 0 ? entry.score / maxRrf : 0,
+    }));
+    if (vectorMatched.length > 0 && lexicalCandidates.length > 0) {
+        retrievalSource = 'hybrid_rrf';
+    }
+    else if (vectorMatched.length > 0) {
+        retrievalSource = 'vector_search';
+    }
+    else if (lexicalCandidates.length > 0) {
+        retrievalSource = 'lexical_search';
+    }
+    // Enrich active records with summaries from their superseded predecessors.
+    // When ingestConversation extracts multiple facts under the same topic, only
+    // the last survives as "active" — the earlier ones become superseded and are
+    // excluded from search.  This recovers their key information so it is not lost.
+    if (matched.length > 0) {
+        const adapter = (0, db_manager_js_1.getAdapter)();
+        const stmtChain = adapter.prepare(`SELECT id, summary, decision FROM decisions WHERE superseded_by = ?`);
+        for (const record of matched) {
+            const predecessors = stmtChain.all(record.id);
+            if (predecessors.length > 0) {
+                const extra = predecessors
+                    .map((p) => String(p.summary ?? p.decision ?? ''))
+                    .filter(Boolean)
+                    .join(' | ');
+                if (extra) {
+                    record.details = record.details
+                        ? `${record.details}\n[Prior context] ${extra}`
+                        : `[Prior context] ${extra}`;
+                }
+            }
+        }
+    }
+    bundle.memories = matched;
+    bundle.graph_context.primary = matched;
+    bundle.graph_context.expanded = [];
+    bundle.graph_context.edges = [];
+    if (matched.length > 0 && !options.skipGraphExpansion) {
+        try {
+            const candidates = matched.map((m) => ({
+                id: m.id,
+                topic: m.topic,
+                decision: m.summary,
+                confidence: m.confidence,
+                created_at: m.created_at,
+                similarity: m.confidence ?? 0.5,
+            }));
+            const mamaApiModule = await import('../mama-api.js');
+            const mamaDefault = mamaApiModule.default;
+            const expanded = await mamaDefault.expandWithGraph(candidates);
+            const primaryIds = new Set(matched.map((m) => m.id));
+            let expandedOnly = expanded.filter((e) => !primaryIds.has(e.id));
+            // Re-filter expanded results: apply status and scope checks
+            if (!options.includeHistory) {
+                expandedOnly = expandedOnly.filter((e) => {
+                    const adapter = (0, db_manager_js_1.getAdapter)();
+                    const row = adapter.prepare(`SELECT status FROM decisions WHERE id = ?`).get(e.id);
+                    const status = row?.status || '';
+                    return !status || !EXCLUDED_STATUSES.has(status);
+                });
+            }
+            if (options.scopes && options.scopes.length > 0) {
+                const expandedIds = expandedOnly.map((e) => e.id);
+                const scopeMap = batchLoadScopes((0, db_manager_js_1.getAdapter)(), expandedIds);
+                const requestedScopes = new Set(options.scopes.map((s) => `${s.kind}:${s.id}`));
+                expandedOnly = expandedOnly.filter((e) => {
+                    const scopes = scopeMap.get(e.id) ?? [];
+                    if (scopes.length === 0)
+                        return false;
+                    return scopes.some((s) => requestedScopes.has(`${s.kind}:${s.id}`));
+                });
+            }
+            bundle.graph_context.expanded = expandedOnly.map((e) => ({
+                id: String(e.id),
+                topic: String(e.topic || ''),
+                kind: 'decision',
+                summary: String(e.decision || ''),
+                details: '',
+                confidence: e.graph_rank ?? 0.5,
+                status: 'active',
+                scopes: [],
+                source: {
+                    package: 'mama-core',
+                    source_type: String(e.graph_source || 'graph_expansion'),
+                },
+                created_at: e.created_at ?? Date.now(),
+                updated_at: e.created_at ?? Date.now(),
+            }));
+            const allIds = [...matched.map((m) => m.id), ...expandedOnly.map((e) => e.id)];
+            const allEdges = await loadEdgesForIds(allIds);
+            // Filter out edges pointing to decisions with excluded statuses
+            const activeIds = new Set(allIds);
+            const edgesToCheck = allEdges.filter((e) => !activeIds.has(e.to_id) || !activeIds.has(e.from_id));
+            if (edgesToCheck.length > 0) {
+                const adapter = (0, db_manager_js_1.getAdapter)();
+                const checkIds = [
+                    ...new Set(edgesToCheck.flatMap((e) => [e.from_id, e.to_id]).filter((id) => !activeIds.has(id))),
+                ];
+                const placeholders = checkIds.map(() => '?').join(', ');
+                const statusRows = adapter
+                    .prepare(`SELECT id, status FROM decisions WHERE id IN (${placeholders})`)
+                    .all(...checkIds);
+                const excludedIds = new Set(statusRows.filter((r) => r.status && EXCLUDED_STATUSES.has(r.status)).map((r) => r.id));
+                bundle.graph_context.edges = allEdges.filter((e) => !excludedIds.has(e.from_id) && !excludedIds.has(e.to_id));
+            }
+            else {
+                bundle.graph_context.edges = allEdges;
+            }
+        }
+        catch {
+            // Graph expansion is best-effort; do not fail recall
+        }
+    }
+    bundle.search_meta.scope_order = (options.scopes ?? []).map((scope) => scope.kind);
+    bundle.search_meta.retrieval_sources = [retrievalSource];
+    if (options.includeProfile) {
+        bundle.profile = await buildProfile(options.scopes ?? []);
+    }
+    return bundle;
+}
+async function ingestMemory(input) {
+    const normalized = input.content.trim();
+    return saveMemory({
+        topic: normalized
+            .slice(0, 40)
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, '_')
+            .replace(/^_+|_+$/g, '') || 'ingested_memory',
+        kind: 'fact',
+        summary: normalized.slice(0, 200),
+        details: normalized,
+        scopes: input.scopes ?? [],
+        source: input.source,
+        eventDate: input.eventDate,
+    });
+}
+async function evolveMemory(input) {
+    return (0, evolution_engine_js_1.resolveMemoryEvolution)(input);
+}
+async function buildMemoryBootstrap(params) {
+    return (0, bootstrap_builder_js_1.buildMemoryAgentBootstrap)(params);
+}
+function createAuditAck(input) {
+    return (0, types_js_1.createMemoryAuditAck)(input);
+}
+async function recordMemoryAudit(input) {
+    return (0, channel_summary_state_store_js_1.recordChannelAudit)(input);
+}
+async function callExtractionLLM(prompt, options) {
+    const model = options.model ?? 'claude-sonnet-4-6';
+    const baseUrl = options.baseUrl ?? 'https://api.anthropic.com';
+    // Security: only send ANTHROPIC_API_KEY to Anthropic's own domain
+    const isAnthropicDomain = /^https?:\/\/([^/]*\.)?anthropic\.com(\/|$)/i.test(baseUrl);
+    const apiKey = isAnthropicDomain
+        ? (options.apiKey ?? process.env.ANTHROPIC_API_KEY)
+        : options.apiKey; // custom baseUrl must supply its own key explicitly
+    if (!apiKey) {
+        throw new Error(isAnthropicDomain
+            ? 'ANTHROPIC_API_KEY is required for extraction'
+            : 'apiKey must be provided explicitly when using a custom baseUrl');
+    }
+    const res = await fetch(`${baseUrl}/v1/messages`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            'x-api-key': apiKey,
+            'anthropic-version': '2023-06-01',
+        },
+        body: JSON.stringify({
+            model,
+            max_tokens: 4096,
+            messages: [{ role: 'user', content: prompt }],
+        }),
+    });
+    if (!res.ok) {
+        const errorBody = await res.text().catch(() => 'unknown');
+        throw new Error(`Anthropic API error ${res.status}: ${errorBody}`);
+    }
+    const data = (await res.json());
+    const text = data.content?.find((c) => c.type === 'text')?.text ?? '';
+    return (0, extraction_prompt_js_1.parseExtractionResponse)(text);
+}
+let extractionFn = callExtractionLLM;
+function setExtractionFn(fn) {
+    extractionFn = fn ?? callExtractionLLM;
+}
+async function ingestConversation(input) {
+    if (!input.messages || input.messages.length === 0) {
+        throw new Error('messages array must not be empty');
+    }
+    const conversationText = input.messages.map((m) => `${m.role}: ${m.content}`).join('\n');
+    const topicPrefix = input.topicPrefix || '';
+    const rawResult = await ingestMemory({
+        content: topicPrefix ? `${topicPrefix}${conversationText}` : conversationText,
+        scopes: input.scopes,
+        source: input.source,
+        eventDate: input.sessionDate,
+    });
+    const result = {
+        rawId: rawResult.id,
+        extractedMemories: [],
+    };
+    if (!input.extract?.enabled) {
+        return result;
+    }
+    let units;
+    try {
+        // Fetch existing topics so LLM can reuse them (enables supersedes edges)
+        await (0, db_manager_js_1.initDB)();
+        const adapter = (0, db_manager_js_1.getAdapter)();
+        let existingTopics;
+        if (input.scopes && input.scopes.length > 0) {
+            const scopeIds = await Promise.all(input.scopes.map((scope) => (0, db_manager_js_1.ensureMemoryScope)(scope.kind, scope.id)));
+            const placeholders = scopeIds.map(() => '?').join(', ');
+            existingTopics = adapter
+                .prepare(`SELECT DISTINCT d.topic FROM decisions d
+           JOIN memory_scope_bindings msb ON msb.memory_id = d.id
+           WHERE msb.scope_id IN (${placeholders})
+             AND (d.status = 'active' OR d.status IS NULL)
+           ORDER BY d.created_at DESC LIMIT 200`)
+                .all(...scopeIds);
+        }
+        else {
+            existingTopics = adapter
+                .prepare(`SELECT DISTINCT topic FROM decisions
+           WHERE (status = 'active' OR status IS NULL)
+           ORDER BY created_at DESC LIMIT 200`)
+                .all();
+        }
+        const topicList = existingTopics.map((r) => r.topic);
+        const prompt = (0, extraction_prompt_js_1.buildExtractionPrompt)(input.messages, topicList);
+        units = await extractionFn(prompt, input.extract);
+    }
+    catch (err) {
+        (0, debug_logger_js_1.warn)(`[memory] extraction failed: ${err instanceof Error ? err.message : String(err)}`);
+        return result;
+    }
+    const adapter = (0, db_manager_js_1.getAdapter)();
+    const EXTRACTION_EDGE_RELATIONSHIP = 'builds_on';
+    const EXTRACTION_EDGE_REASON = 'Extracted from conversation';
+    // Track IDs saved in this batch so sibling facts don't supersede each other.
+    // Without this, when ingestConversation extracts multiple facts under the same topic,
+    // each subsequent save supersedes the previous one, losing independent information.
+    const batchSavedIds = [];
+    for (const unit of units) {
+        try {
+            const saved = await saveMemory({
+                topic: topicPrefix ? `${topicPrefix}${unit.topic}` : unit.topic,
+                kind: unit.kind,
+                summary: unit.summary,
+                details: unit.details,
+                confidence: unit.confidence,
+                scopes: input.scopes,
+                source: input.source,
+                excludeIds: batchSavedIds,
+                eventDate: input.sessionDate,
+            });
+            const now = Date.now();
+            adapter
+                .prepare(`INSERT OR REPLACE INTO decision_edges (from_id, to_id, relationship, reason, weight, created_at)
+           VALUES (?, ?, ?, ?, ?, ?)`)
+                .run(saved.id, rawResult.id, EXTRACTION_EDGE_RELATIONSHIP, EXTRACTION_EDGE_REASON, 1.0, now);
+            batchSavedIds.push(saved.id);
+            result.extractedMemories.push({
+                id: saved.id,
+                kind: unit.kind,
+                topic: unit.topic,
+            });
+        }
+        catch (err) {
+            (0, debug_logger_js_1.warn)(`[memory] failed to save extracted unit topic=${unit.topic} kind=${unit.kind}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=api.js.map