@shadowforge0/aquifer-memory 1.6.0 → 1.8.0

package/core/memory-records.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const crypto = require('crypto');
+const { resolveApplicableRecords } = require('./memory-bootstrap');
 
 function requireField(obj, field) {
   if (!obj || obj[field] === undefined || obj[field] === null || obj[field] === '') {
@@ -16,6 +17,14 @@ function toJsonOrNull(value) {
   return value === undefined || value === null ? null : JSON.stringify(value);
 }
 
+function vecToStr(vec) {
+  if (!vec || !Array.isArray(vec) || vec.length === 0) return null;
+  for (let i = 0; i < vec.length; i++) {
+    if (!Number.isFinite(vec[i])) throw new Error(`Vector contains non-finite value at index ${i}`);
+  }
+  return `[${vec.join(',')}]`;
+}
+
 function advisoryLockKeys(namespace, value) {
   const digest = crypto.createHash('sha256').update(`${namespace}:${value}`).digest();
   return [digest.readInt32BE(0), digest.readInt32BE(4)];
@@ -24,10 +33,10 @@ function advisoryLockKeys(namespace, value) {
 const BOOTSTRAP_ORDER_SQL = `
          CASE m.memory_type
            WHEN 'constraint' THEN 0
-           WHEN 'preference' THEN 1
-           WHEN 'state' THEN 2
-           WHEN 'open_loop' THEN 3
-           WHEN 'decision' THEN 4
+           WHEN 'state' THEN 1
+           WHEN 'open_loop' THEN 2
+           WHEN 'decision' THEN 3
+           WHEN 'preference' THEN 4
            WHEN 'fact' THEN 5
            WHEN 'conclusion' THEN 6
            WHEN 'entity_note' THEN 7
@@ -46,12 +55,132 @@ const BOOTSTRAP_ORDER_SQL = `
          m.accepted_at DESC NULLS LAST,
          m.id ASC`;
 
+const CURRENT_TYPE_PRIORITY = {
+  constraint: 0,
+  state: 1,
+  open_loop: 2,
+  decision: 3,
+  preference: 4,
+  fact: 5,
+  conclusion: 6,
+  entity_note: 7,
+};
+
+const CURRENT_AUTHORITY_PRIORITY = {
+  user_explicit: 0,
+  executable_evidence: 1,
+  manual: 2,
+  system: 3,
+  verified_summary: 4,
+  llm_inference: 5,
+  raw_transcript: 6,
+};
+
+function parseTime(value) {
+  const parsed = Date.parse(value || '');
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function normalizeScopePath(activeScopePath, activeScopeKey) {
+  const source = Array.isArray(activeScopePath)
+    ? activeScopePath
+    : (typeof activeScopePath === 'string' ? activeScopePath.split(',') : null);
+  if (source && source.length > 0) {
+    const seen = new Set();
+    const path = [];
+    for (const value of source) {
+      const key = String(value || '').trim();
+      if (!key || seen.has(key)) continue;
+      seen.add(key);
+      path.push(key);
+    }
+    if (path.length > 0) return path;
+  }
+  if (activeScopeKey) return [String(activeScopeKey).trim()].filter(Boolean);
+  return ['global'];
+}
+
+function compareRecordIdAsc(a, b) {
+  const left = a.memoryId ?? a.memory_id ?? a.id ?? null;
+  const right = b.memoryId ?? b.memory_id ?? b.id ?? null;
+  const leftNum = Number(left);
+  const rightNum = Number(right);
+  if (Number.isFinite(leftNum) && Number.isFinite(rightNum) && leftNum !== rightNum) {
+    return leftNum - rightNum;
+  }
+  return String(left ?? '').localeCompare(String(right ?? ''));
+}
+
+function normalizeCurrentMemoryRow(row = {}) {
+  const { embedding: _embedding, ...publicRow } = row;
+  void _embedding;
+  const memoryId = row.memoryId ?? row.memory_id ?? row.id ?? null;
+  const evidenceRefsValue = row.evidenceRefs ?? row.evidence_refs ?? [];
+  const evidenceRefs = Array.isArray(evidenceRefsValue) ? evidenceRefsValue : [];
+  return {
+    ...publicRow,
+    memoryId: memoryId === null ? null : String(memoryId),
+    canonicalKey: row.canonicalKey ?? row.canonical_key ?? null,
+    memoryType: row.memoryType ?? row.memory_type ?? null,
+    scopeKey: row.scopeKey ?? row.scope_key ?? null,
+    scopeKind: row.scopeKind ?? row.scope_kind ?? null,
+    inheritanceMode: row.inheritanceMode ?? row.inheritance_mode ?? row.scope_inheritance_mode ?? null,
+    visibleInBootstrap: row.visibleInBootstrap ?? row.visible_in_bootstrap ?? false,
+    visibleInRecall: row.visibleInRecall ?? row.visible_in_recall ?? false,
+    acceptedAt: row.acceptedAt ?? row.accepted_at ?? null,
+    validFrom: row.validFrom ?? row.valid_from ?? null,
+    validTo: row.validTo ?? row.valid_to ?? null,
+    staleAfter: row.staleAfter ?? row.stale_after ?? null,
+    evidenceRefs,
+    evidence_refs: evidenceRefs,
+  };
+}
+
+function currentScopePriority(record, positions) {
+  return positions.get(record.scopeKey ?? record.scope_key) ?? -1;
+}
+
+function sortCurrentMemoryRecords(a, b, positions) {
+  const leftScope = currentScopePriority(a, positions);
+  const rightScope = currentScopePriority(b, positions);
+  if (rightScope !== leftScope) return rightScope - leftScope;
+
+  const leftType = CURRENT_TYPE_PRIORITY[a.memoryType ?? a.memory_type] ?? 99;
+  const rightType = CURRENT_TYPE_PRIORITY[b.memoryType ?? b.memory_type] ?? 99;
+  if (leftType !== rightType) return leftType - rightType;
+
+  const leftAuthority = CURRENT_AUTHORITY_PRIORITY[a.authority] ?? 99;
+  const rightAuthority = CURRENT_AUTHORITY_PRIORITY[b.authority] ?? 99;
+  if (leftAuthority !== rightAuthority) return leftAuthority - rightAuthority;
+
+  const leftAccepted = parseTime(a.acceptedAt ?? a.accepted_at);
+  const rightAccepted = parseTime(b.acceptedAt ?? b.accepted_at);
+  if (leftAccepted !== rightAccepted) return (rightAccepted ?? 0) - (leftAccepted ?? 0);
+
+  return compareRecordIdAsc(a, b);
+}
+
+function isCurrentProjectionRow(row, asOf) {
+  if ((row.status || 'candidate') !== 'active') return false;
+  if (row.visibleInBootstrap !== true && row.visibleInRecall !== true) return false;
+  const at = parseTime(asOf);
+  if (at === null) return true;
+  const validFrom = parseTime(row.validFrom ?? row.valid_from);
+  const validTo = parseTime(row.validTo ?? row.valid_to);
+  const staleAfter = parseTime(row.staleAfter ?? row.stale_after);
+  if (validFrom !== null && validFrom > at) return false;
+  if (validTo !== null && validTo <= at) return false;
+  if (staleAfter !== null && staleAfter <= at) return false;
+  return true;
+}
+
 function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = false }) {
   const scopes = `${schema}.scopes`;
   const versions = `${schema}.versions`;
   const memories = `${schema}.memory_records`;
   const factAssertions = `${schema}.fact_assertions_v1`;
   const evidenceRefs = `${schema}.evidence_refs`;
+  const evidenceItems = `${schema}.evidence_items`;
   const feedback = `${schema}.feedback`;
   const canTransact = typeof pool.connect === 'function';
 
@@ -133,12 +262,12 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
          valid_to, stale_after, superseded_by, backing_fact_id, observed_at,
          revoked_at, superseded_at, version_id, visible_in_bootstrap,
          visible_in_recall, rank_features, created_by_finalization_id,
-         created_by_compaction_run_id
+         created_by_compaction_run_id, embedding
        )
        VALUES (
          $1,$2,$3,$4,$5,$6,$7,COALESCE($8,''),COALESCE($9::jsonb,'{}'::jsonb),
          COALESCE($10,'candidate'),COALESCE($11,'llm_inference'),$12,$13,$14,$15,
-         $16,$17,$18,$19,$20,$21,COALESCE($22,false),COALESCE($23,false),COALESCE($24::jsonb,'{}'::jsonb),$25,$26
+         $16,$17,$18,$19,$20,$21,COALESCE($22,false),COALESCE($23,false),COALESCE($24::jsonb,'{}'::jsonb),$25,$26,$27::vector
        )
        ON CONFLICT (tenant_id, canonical_key) WHERE status = 'active' DO UPDATE SET
          scope_id = EXCLUDED.scope_id,
@@ -161,7 +290,8 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
          visible_in_recall = EXCLUDED.visible_in_recall,
          rank_features = COALESCE(NULLIF(EXCLUDED.rank_features, '{}'::jsonb), ${memories}.rank_features),
          created_by_finalization_id = COALESCE(${memories}.created_by_finalization_id, EXCLUDED.created_by_finalization_id),
-         created_by_compaction_run_id = COALESCE(${memories}.created_by_compaction_run_id, EXCLUDED.created_by_compaction_run_id)
+         created_by_compaction_run_id = COALESCE(${memories}.created_by_compaction_run_id, EXCLUDED.created_by_compaction_run_id),
+         embedding = COALESCE(EXCLUDED.embedding, ${memories}.embedding)
        RETURNING *`,
       [
         tenantId,
@@ -190,6 +320,7 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
         toJson(input.rankFeatures, {}),
         input.createdByFinalizationId || input.created_by_finalization_id || null,
         input.createdByCompactionRunId || input.created_by_compaction_run_id || null,
+        vecToStr(input.embedding),
       ]
     );
     return result.rows[0] || null;
@@ -276,18 +407,27 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
     requireField(input, 'sourceKind');
     requireField(input, 'sourceRef');
     const tenantId = input.tenantId || defaultTenantId;
+    const evidenceItemId = input.evidenceItemId || input.evidence_item_id || null;
+    const conflictTarget = evidenceItemId
+      ? `(tenant_id, owner_kind, owner_id, evidence_item_id, relation_kind)
+         WHERE evidence_item_id IS NOT NULL`
+      : `(tenant_id, owner_kind, owner_id, source_kind, source_ref, relation_kind)
+         WHERE evidence_item_id IS NULL`;
     const result = await pool.query(
       `INSERT INTO ${evidenceRefs} (
          tenant_id, owner_kind, owner_id, source_kind, source_ref,
          relation_kind, weight, metadata, created_by_finalization_id,
-         created_by_compaction_run_id
+         created_by_compaction_run_id, evidence_item_id
        )
-       VALUES ($1,$2,$3,$4,$5,COALESCE($6,'supporting'),COALESCE($7,1.0),COALESCE($8::jsonb,'{}'::jsonb),$9,$10)
-       ON CONFLICT (tenant_id, owner_kind, owner_id, source_kind, source_ref, relation_kind)
+       VALUES ($1,$2,$3,$4,$5,COALESCE($6,'supporting'),COALESCE($7,1.0),COALESCE($8::jsonb,'{}'::jsonb),$9,$10,$11)
+       ON CONFLICT ${conflictTarget}
        DO UPDATE SET weight = EXCLUDED.weight,
+                     source_kind = EXCLUDED.source_kind,
+                     source_ref = EXCLUDED.source_ref,
                      metadata = COALESCE(NULLIF(EXCLUDED.metadata, '{}'::jsonb), ${evidenceRefs}.metadata),
                      created_by_finalization_id = COALESCE(${evidenceRefs}.created_by_finalization_id, EXCLUDED.created_by_finalization_id),
-                     created_by_compaction_run_id = COALESCE(${evidenceRefs}.created_by_compaction_run_id, EXCLUDED.created_by_compaction_run_id)
+                     created_by_compaction_run_id = COALESCE(${evidenceRefs}.created_by_compaction_run_id, EXCLUDED.created_by_compaction_run_id),
+                     evidence_item_id = COALESCE(${evidenceRefs}.evidence_item_id, EXCLUDED.evidence_item_id)
        RETURNING *`,
       [
         tenantId,
@@ -300,11 +440,55 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
         toJson(input.metadata, {}),
         input.createdByFinalizationId || input.created_by_finalization_id || null,
         input.createdByCompactionRunId || input.created_by_compaction_run_id || null,
+        evidenceItemId,
       ]
     );
     return result.rows[0] || null;
   }
 
+  async function upsertEvidenceItem(input = {}) {
+    requireField(input, 'sourceKind');
+    requireField(input, 'sourceRef');
+    requireField(input, 'excerptText');
+    const tenantId = input.tenantId || defaultTenantId;
+    const excerptText = String(input.excerptText || input.excerpt_text || '').trim();
+    const excerptHash = input.excerptHash || input.excerpt_hash || crypto
+      .createHash('sha256')
+      .update(excerptText)
+      .digest('hex');
+    const result = await pool.query(
+      `INSERT INTO ${evidenceItems} (
+         tenant_id, source_kind, source_ref, session_row_id, turn_embedding_id,
+         summary_row_id, created_by_finalization_id, excerpt_text, excerpt_hash,
+         embedding, metadata
+       )
+       VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10::vector,COALESCE($11::jsonb,'{}'::jsonb))
+       ON CONFLICT (tenant_id, source_kind, source_ref, excerpt_hash)
+       DO UPDATE SET
+         session_row_id = COALESCE(${evidenceItems}.session_row_id, EXCLUDED.session_row_id),
+         turn_embedding_id = COALESCE(${evidenceItems}.turn_embedding_id, EXCLUDED.turn_embedding_id),
+         summary_row_id = COALESCE(${evidenceItems}.summary_row_id, EXCLUDED.summary_row_id),
+         created_by_finalization_id = COALESCE(${evidenceItems}.created_by_finalization_id, EXCLUDED.created_by_finalization_id),
+         embedding = COALESCE(${evidenceItems}.embedding, EXCLUDED.embedding),
+         metadata = COALESCE(NULLIF(EXCLUDED.metadata, '{}'::jsonb), ${evidenceItems}.metadata)
+       RETURNING *`,
+      [
+        tenantId,
+        input.sourceKind || input.source_kind,
+        input.sourceRef || input.source_ref,
+        input.sessionRowId || input.session_row_id || null,
+        input.turnEmbeddingId || input.turn_embedding_id || null,
+        input.summaryRowId || input.summary_row_id || null,
+        input.createdByFinalizationId || input.created_by_finalization_id || null,
+        excerptText,
+        excerptHash,
+        vecToStr(input.embedding),
+        toJson(input.metadata, {}),
+      ],
+    );
+    return result.rows[0] || null;
+  }
+
   async function recordFeedback(input = {}) {
     requireField(input, 'targetKind');
     requireField(input, 'targetId');
@@ -518,6 +702,9 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
       params.push(input.visibleInRecall === true);
       where.push(`m.visible_in_recall = $${params.length}`);
     }
+    if (input.withoutEmbedding === true) {
+      where.push(`m.embedding IS NULL`);
+    }
     params.push(Math.max(1, Math.min(200, input.limit || 50)));
     const orderBy = input.visibleInBootstrap === true
       ? BOOTSTRAP_ORDER_SQL
@@ -534,6 +721,151 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
     return result.rows;
   }
 
+  async function updateMemoryEmbedding(input = {}) {
+    requireField(input, 'memoryId');
+    const tenantId = input.tenantId || defaultTenantId;
+    const embedding = vecToStr(input.embedding);
+    if (!embedding) throw new Error('embedding is required');
+    const result = await pool.query(
+      `UPDATE ${memories}
+       SET embedding = $3::vector,
+           updated_at = now()
+       WHERE tenant_id = $1 AND id = $2
+         AND embedding IS NULL
+       RETURNING *`,
+      [
+        tenantId,
+        input.memoryId,
+        embedding,
+      ]
+    );
+    if (result.rows[0]) {
+      return {
+        status: 'updated',
+        updated: true,
+        skipped: false,
+        memory: result.rows[0],
+      };
+    }
+    const existing = await pool.query(
+      `SELECT * FROM ${memories}
+       WHERE tenant_id = $1 AND id = $2
+       LIMIT 1`,
+      [tenantId, input.memoryId]
+    );
+    if (existing.rows[0]) {
+      return {
+        status: 'skipped_existing_embedding',
+        updated: false,
+        skipped: true,
+        memory: existing.rows[0],
+      };
+    }
+    return {
+      status: 'missing',
+      updated: false,
+      skipped: true,
+      memory: null,
+    };
+  }
+
+  async function currentProjection(input = {}) {
+    const tenantId = input.tenantId || defaultTenantId;
+    let activeScopePath = normalizeScopePath(input.activeScopePath, input.activeScopeKey);
+    let activeScopeKey = input.activeScopeKey || activeScopePath[activeScopePath.length - 1] || null;
+    if (input.scopeId && !input.activeScopeKey && !input.activeScopePath) {
+      const scopeResult = await pool.query(
+        `SELECT scope_key FROM ${scopes} WHERE tenant_id = $1 AND id = $2 LIMIT 1`,
+        [tenantId, input.scopeId],
+      );
+      const scopedKey = scopeResult.rows[0]?.scope_key || null;
+      if (scopedKey) {
+        activeScopePath = [scopedKey];
+        activeScopeKey = scopedKey;
+      }
+    }
+    const limit = Math.max(1, Math.min(100, input.limit || 50));
+    const fetchLimit = Math.max(limit + 1, Math.min(200, Math.max(limit * 4, 40)));
+    const asOf = input.asOf || new Date().toISOString();
+    const params = [tenantId, activeScopePath, asOf];
+    const where = [
+      `m.tenant_id = $1`,
+      `m.status = 'active'`,
+      `s.scope_key = ANY($2::text[])`,
+      `(m.visible_in_bootstrap = true OR m.visible_in_recall = true)`,
+      `(m.valid_from IS NULL OR m.valid_from <= $3::timestamptz)`,
+      `(m.valid_to IS NULL OR m.valid_to > $3::timestamptz)`,
+      `(m.stale_after IS NULL OR m.stale_after > $3::timestamptz)`,
+    ];
+
+    if (input.scopeId) {
+      params.push(input.scopeId);
+      where.push(`m.scope_id = $${params.length}`);
+    }
+
+    params.push(fetchLimit);
+    const limitParam = `$${params.length}`;
+    const evidenceRefsSelect = input.includeEvidenceRefs === true
+      ? `COALESCE((
+           SELECT jsonb_agg(
+             jsonb_build_object(
+               'id', e.id,
+               'sourceKind', e.source_kind,
+               'sourceRef', e.source_ref,
+               'relationKind', e.relation_kind,
+               'weight', e.weight,
+               'metadata', e.metadata
+             )
+             ORDER BY e.id ASC
+           )
+           FROM ${evidenceRefs} e
+           WHERE e.tenant_id = m.tenant_id
+             AND e.owner_kind = 'memory_record'
+             AND e.owner_id = m.id
+         ), '[]'::jsonb)`
+      : `'[]'::jsonb`;
+
+    const result = await pool.query(
+      `SELECT
+         m.*,
+         s.scope_kind,
+         s.scope_key,
+         s.inheritance_mode AS scope_inheritance_mode,
+         ${evidenceRefsSelect} AS evidence_refs
+       FROM ${memories} m
+       JOIN ${scopes} s ON s.id = m.scope_id
+       WHERE ${where.join(' AND ')}
+       ORDER BY array_position($2::text[], s.scope_key) DESC NULLS LAST,
+                ${BOOTSTRAP_ORDER_SQL}
+       LIMIT ${limitParam}`,
+      params,
+    );
+
+    const positions = new Map(activeScopePath.map((key, index) => [key, index]));
+    const applicable = resolveApplicableRecords(
+      result.rows
+        .map(normalizeCurrentMemoryRow)
+        .filter(row => isCurrentProjectionRow(row, asOf)),
+      { activeScopeKey, activeScopePath },
+    ).sort((left, right) => sortCurrentMemoryRecords(left, right, positions));
+
+    const selected = applicable.slice(0, limit);
+    const truncated = applicable.length > limit;
+    return {
+      memories: selected,
+      meta: {
+        source: 'memory_records',
+        servingContract: 'current_memory_v1',
+        count: selected.length,
+        activeScopeKey,
+        activeScopePath,
+        asOf,
+        truncated,
+        degraded: truncated,
+      },
+    };
+  }
+
   async function withTransaction(fn) {
     if (inTransaction) {
       return fn(api, { transactional: true });
@@ -563,6 +895,7 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
     createVersion,
     upsertMemory,
     upsertFactAssertion,
+    upsertEvidenceItem,
     linkEvidence,
     recordFeedback,
     findActiveByCanonicalKey,
@@ -570,8 +903,11 @@ function createMemoryRecords({ pool, schema, defaultTenantId, inTransaction = fa
     lockCanonicalKey,
     updateMemoryStatus,
     updateMemoryStatusIfCurrent,
+    updateMemoryEmbedding,
     updateFactAssertionStatus,
     listActive,
+    currentProjection,
+    normalizeCurrentMemoryRow,
     withTransaction,
   };
 

package/core/memory-serving.js

@@ -0,0 +1,132 @@
+'use strict';
+
+function splitScopePath(value) {
+  if (Array.isArray(value)) return value.map(v => String(v).trim()).filter(Boolean);
+  if (typeof value !== 'string') return null;
+  const parts = value.split(',').map(v => v.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : null;
+}
+
+function hasEvidenceBoundary(opts = {}) {
+  return Boolean(
+    opts.agentId
+    || (Array.isArray(opts.agentIds) && opts.agentIds.length > 0)
+    || opts.source
+    || opts.dateFrom
+    || opts.dateTo
+    || opts.host
+    || opts.sessionId
+    || opts.allowUnsafeDebug === true
+    || opts.unsafeDebug === true
+  );
+}
+
+function assertCuratedRecallOpts(opts = {}) {
+  const unsupported = [];
+  for (const key of ['agentId', 'agentIds', 'source', 'dateFrom', 'dateTo', 'entities', 'entityMode', 'weights', 'rerank', 'allowUnsafeDebug', 'unsafeDebug']) {
+    if (opts[key] !== undefined && opts[key] !== null) unsupported.push(key);
+  }
+  if (unsupported.length > 0) {
+    throw new Error(`curated memory_recall does not support legacy filters: ${unsupported.join(', ')}. Use activeScopeKey/activeScopePath or historical_recall.`);
+  }
+}
+
+function assertCuratedBootstrapOpts(opts = {}) {
+  const unsupported = [];
+  for (const key of ['agentId', 'source', 'lookbackDays', 'dateFrom', 'dateTo']) {
+    if (opts[key] !== undefined && opts[key] !== null) unsupported.push(key);
+  }
+  if (unsupported.length > 0) {
+    throw new Error(`curated session_bootstrap does not support legacy filters: ${unsupported.join(', ')}. Use activeScopeKey/activeScopePath.`);
+  }
+}
+
+function curatedRecallTitle(row = {}) {
+  const title = row.title || row.summary || row.canonical_key || row.canonicalKey || row.memory_type || row.memoryType || 'memory';
+  return String(title).trim();
+}
+
+function curatedRecallSummary(row = {}) {
+  const summary = row.summary || row.title || row.canonical_key || row.canonicalKey || '';
+  return String(summary).trim();
+}
+
+function normalizeCuratedRecallRow(row = {}) {
+  const { embedding: _embedding, ...publicRow } = row;
+  void _embedding;
+  const memoryId = row.memoryId || row.memory_id || row.id || null;
+  const canonicalKey = row.canonicalKey || row.canonical_key || null;
+  const memoryType = row.memoryType || row.memory_type || null;
+  const scopeKey = row.scopeKey || row.scope_key || null;
+  const scopeKind = row.scopeKind || row.scope_kind || null;
+  const summaryText = curatedRecallSummary(row) || null;
+  const title = curatedRecallTitle(row) || null;
+  const scoreValue = row.recall_score ?? row.score ?? row.lexical_rank ?? null;
+  const score = scoreValue === null ? null : Number(scoreValue);
+  return {
+    ...publicRow,
+    memoryId: memoryId === null ? null : String(memoryId),
+    canonicalKey,
+    memoryType,
+    scopeKey,
+    scopeKind,
+    title,
+    summaryText,
+    structuredSummary: {
+      title,
+      overview: summaryText,
+    },
+    startedAt: row.acceptedAt || row.accepted_at || row.observedAt || row.observed_at || null,
+    score: Number.isFinite(score) ? score : null,
+    feedbackTarget: {
+      kind: 'memory_feedback',
+      memoryId: memoryId === null ? null : String(memoryId),
+      canonicalKey,
+    },
+  };
+}
+
+function createMemoryServingRuntime(memoryCfg = {}, env = process.env) {
+  const servingMode = memoryCfg.servingMode || env.AQUIFER_MEMORY_SERVING_MODE || 'legacy';
+  const defaultActiveScopeKey = memoryCfg.activeScopeKey || null;
+  const defaultActiveScopePath = splitScopePath(memoryCfg.activeScopePath || null);
+
+  function resolveMode(opts = {}) {
+    const mode = opts.memoryMode || opts.servingMode || servingMode;
+    if (mode === 'legacy' || mode === 'evidence') return 'legacy';
+    if (mode === 'curated') return 'curated';
+    throw new Error(`Invalid memory serving mode: "${mode}". Must be one of: legacy, curated`);
+  }
+
+  function withDefaultScope(opts = {}) {
+    const next = { ...opts };
+    if (!next.activeScopePath && defaultActiveScopePath) next.activeScopePath = defaultActiveScopePath;
+    if (Array.isArray(next.activeScopePath) && next.activeScopePath.length > 0) {
+      if (!next.activeScopeKey) next.activeScopeKey = next.activeScopePath[next.activeScopePath.length - 1];
+      return next;
+    }
+    if (!next.activeScopeKey && defaultActiveScopeKey) next.activeScopeKey = defaultActiveScopeKey;
+    return next;
+  }
+
+  return {
+    assertCuratedBootstrapOpts,
+    assertCuratedRecallOpts,
+    defaultActiveScopeKey,
+    defaultActiveScopePath,
+    hasEvidenceBoundary,
+    normalizeCuratedRecallRow,
+    resolveMode,
+    servingMode,
+    withDefaultScope,
+  };
+}
+
+module.exports = {
+  assertCuratedBootstrapOpts,
+  assertCuratedRecallOpts,
+  createMemoryServingRuntime,
+  hasEvidenceBoundary,
+  normalizeCuratedRecallRow,
+  splitScopePath,
+};