@shadowforge0/aquifer-memory 1.6.0 → 1.8.0

package/consumers/codex.js

@@ -22,6 +22,16 @@ const crypto = require('crypto');
 const DEFAULT_CODEX_HOME = path.join(os.homedir(), '.codex');
 const { normalizeMessages } = require('./shared/normalize');
 const { applyEnrichSafetyGate } = require('../core/memory-safety-gate');
+const {
+    buildActiveSessionCheckpointInput,
+    buildActiveSessionCheckpointPrompt,
+    prepareActiveSessionCheckpoint: prepareActiveSessionCheckpointImpl,
+} = require('./codex-active-checkpoint');
+const {
+    formatCurrentMemoryPromptBlock,
+    compactCurrentMemorySnapshot,
+    resolveCurrentMemoryForFinalization,
+} = require('./codex-current-memory');
 const DEFAULT_IDLE_MS = 5 * 60 * 1000;
 const DEFAULT_CLAIM_TTL_MS = 5 * 60 * 1000;
 const DEFAULT_MIN_BYTES = 1000;
@@ -323,11 +333,10 @@ function matchesRecoveryProvenance(metadata = {}, opts = {}, defaults = {}) {
         repoPath: opts.repoPath || null,
     };
     for (const [key, expectedValue] of Object.entries(expected)) {
-        if (!expectedValue || !metadata[key]) continue;
+        if (!expectedValue) continue;
+        if (!metadata[key]) return false;
         if (String(metadata[key]) !== String(expectedValue)) return false;
     }
-    if (metadata.source && metadata.source !== expected.source) return false;
-    if (metadata.agentId && metadata.agentId !== expected.agentId) return false;
     return true;
 }
 
@@ -770,11 +779,13 @@ async function afterburnCandidate(aquifer, candidate, opts = {}) {
 
     let resolvedSummary = summaryInput;
     if (!hasFinalizationSummary(resolvedSummary) && typeof summaryProvider === 'function') {
+        const currentMemory = await resolveCurrentMemoryForFinalization(aquifer, opts);
         resolvedSummary = await summaryProvider(view.messages, {
             aquifer,
             candidate: recoveryCandidate,
             existing,
             view,
+            currentMemory,
             agentId,
             source,
             sessionKey,
@@ -873,9 +884,18 @@ async function findRecoveryCandidates(aquifer, opts = {}) {
     const {
         agentId = 'main',
         source = 'codex',
+        sessionKey = null,
         maxRecoveryCandidates = 3,
         includeJsonlPreviews = false,
     } = opts;
+    const provenance = {
+        source,
+        agentId,
+        sessionKey,
+        workspace: opts.workspace || opts.workspacePath || null,
+        project: opts.project || opts.projectKey || null,
+        repoPath: opts.repoPath || null,
+    };
     if (!Number.isFinite(maxRecoveryCandidates) || maxRecoveryCandidates <= 0) return [];
     ensureDirs(paths.importedDir, paths.afterburnedDir, paths.claimDir, paths.decisionDir);
 
@@ -961,7 +981,7 @@ async function findRecoveryCandidates(aquifer, opts = {}) {
             transcriptHash: null,
             source,
             agentId,
-            sessionKey: null,
+            sessionKey,
             userCount: null,
             messageCount: null,
             finalizationStatus: null,
@@ -972,8 +992,7 @@ async function findRecoveryCandidates(aquifer, opts = {}) {
                 fileSessionId: safeFileSessionId,
                 size: entry.stat.size,
                 mtimeMs: entry.stat.mtimeMs,
-                source,
-                agentId,
+                ...provenance,
             },
         };
         const localDecision = readRecoveryDecision(paths, candidatePreview);
@@ -1093,6 +1112,92 @@ function approxPromptTokens(text) {
     return Math.ceil(String(text || '').length / 3);
 }
 
+function recoveryPromptBudgetExceeded(text, opts = {}) {
+    const promptTokens = approxPromptTokens(text);
+    const maxChars = opts.maxChars;
+    const maxPromptTokens = opts.maxPromptTokens;
+    return {
+        promptTokens,
+        exceeded: Boolean(
+            (Number.isFinite(maxChars) && maxChars > 0 && text.length > maxChars)
+            || (Number.isFinite(maxPromptTokens) && maxPromptTokens > 0 && promptTokens > maxPromptTokens)
+        ),
+    };
+}
+
+function buildBoundedRecoveryTranscript(safeMessages = [], opts = {}) {
+    const allowTail = opts.allowTail === true;
+    const maxMessages = opts.maxMessages;
+    const maxChars = opts.maxChars;
+    const maxPromptTokens = opts.maxPromptTokens;
+    const fullText = formatRecoveryTranscript(safeMessages);
+    const fullPromptTokens = approxPromptTokens(fullText);
+    let messages = safeMessages;
+    let omittedMessageCount = 0;
+    let truncatedByMessages = false;
+
+    if (Number.isFinite(maxMessages) && maxMessages > 0 && messages.length > maxMessages) {
+        if (!allowTail) {
+            return {
+                status: 'deferred',
+                reason: 'max_messages',
+                messageCount: messages.length,
+            };
+        }
+        omittedMessageCount = messages.length - maxMessages;
+        messages = messages.slice(-maxMessages);
+        truncatedByMessages = true;
+    }
+
+    let text = formatRecoveryTranscript(messages);
+    let budget = recoveryPromptBudgetExceeded(text, { maxChars, maxPromptTokens });
+    let truncatedByBudget = false;
+    while (allowTail && budget.exceeded && messages.length > 1) {
+        messages = messages.slice(1);
+        omittedMessageCount += 1;
+        truncatedByBudget = true;
+        text = formatRecoveryTranscript(messages);
+        budget = recoveryPromptBudgetExceeded(text, { maxChars, maxPromptTokens });
+    }
+
+    if (budget.exceeded) {
+        return {
+            status: 'deferred',
+            reason: 'prompt_budget',
+            charCount: text.length,
+            approxPromptTokens: budget.promptTokens,
+        };
+    }
+
+    return {
+        status: 'ok',
+        messages,
+        text,
+        charCount: text.length,
+        approxPromptTokens: budget.promptTokens,
+        fullCharCount: fullText.length,
+        fullApproxPromptTokens: fullPromptTokens,
+        truncated: truncatedByMessages || truncatedByBudget,
+        transcriptWindow: {
+            mode: allowTail ? 'tail' : 'full',
+            truncated: truncatedByMessages || truncatedByBudget,
+            omittedMessageCount,
+            includedMessageCount: messages.length,
+            totalMessageCount: safeMessages.length,
+            truncatedByMessages,
+            truncatedByBudget,
+        },
+        coverage: {
+            coordinateSystem: 'codex_sanitized_view_v1',
+            messageIndexBase: 0,
+            charIndexBase: 0,
+            semantics: 'coveredUntilChar is the first uncovered zero-based char offset; messages up to coveredUntilMessageIndex are covered.',
+            coveredUntilMessageIndex: safeMessages.length > 0 ? safeMessages.length - 1 : 0,
+            coveredUntilChar: fullText.length,
+        },
+    };
+}
+
 function materializeRecoveryTranscriptView(candidate = {}, opts = {}) {
     const filePath = candidate.filePath || candidate.metadata?.filePath;
     if (!filePath) {
@@ -1106,6 +1211,7 @@ function materializeRecoveryTranscriptView(candidate = {}, opts = {}) {
     const maxMessages = opts.maxRecoveryMessages ?? DEFAULT_RECOVERY_MAX_MESSAGES;
     const maxChars = opts.maxRecoveryChars ?? DEFAULT_RECOVERY_MAX_CHARS;
     const maxPromptTokens = opts.maxRecoveryPromptTokens ?? DEFAULT_RECOVERY_MAX_PROMPT_TOKENS;
+    const allowTail = opts.tailOnMaxBudget === true || opts.tailOnBudget === true || opts.tail === true;
 
     let stat;
     try {
@@ -1113,7 +1219,7 @@ function materializeRecoveryTranscriptView(candidate = {}, opts = {}) {
     } catch {
         return { status: 'not_found', sessionId: candidate.sessionId || null, filePath };
     }
-    if (Number.isFinite(maxBytes) && maxBytes > 0 && stat.size > maxBytes) {
+    if (!allowTail && Number.isFinite(maxBytes) && maxBytes > 0 && stat.size > maxBytes) {
         return { status: 'deferred', reason: 'max_bytes', sessionId: candidate.sessionId || null, filePath, size: stat.size };
     }
 
@@ -1145,7 +1251,13 @@ function materializeRecoveryTranscriptView(candidate = {}, opts = {}) {
             safetyGate: safety.meta,
         };
     }
-    if (Number.isFinite(maxMessages) && maxMessages > 0 && safeMessages.length > maxMessages) {
+    const bounded = buildBoundedRecoveryTranscript(safeMessages, {
+        allowTail,
+        maxMessages,
+        maxChars,
+        maxPromptTokens,
+    });
+    if (bounded.status === 'deferred' && bounded.reason === 'max_messages') {
         return {
             status: 'deferred',
             reason: 'max_messages',
@@ -1157,20 +1269,16 @@ function materializeRecoveryTranscriptView(candidate = {}, opts = {}) {
             safetyGate: safety.meta,
         };
     }
-
-    const text = formatRecoveryTranscript(safeMessages);
-    const promptTokens = approxPromptTokens(text);
-    if ((Number.isFinite(maxChars) && maxChars > 0 && text.length > maxChars)
-        || (Number.isFinite(maxPromptTokens) && maxPromptTokens > 0 && promptTokens > maxPromptTokens)) {
+    if (bounded.status === 'deferred') {
         return {
             status: 'deferred',
-            reason: 'prompt_budget',
+            reason: bounded.reason,
             sessionId: parsed.sessionId,
             fileSessionId: parsed.fileSessionId,
             filePath,
             transcriptHash,
-            charCount: text.length,
-            approxPromptTokens: promptTokens,
+            charCount: bounded.charCount,
+            approxPromptTokens: bounded.approxPromptTokens,
             safetyGate: safety.meta,
         };
     }
@@ -1181,16 +1289,23 @@ function materializeRecoveryTranscriptView(candidate = {}, opts = {}) {
         fileSessionId: parsed.fileSessionId,
         filePath,
         transcriptHash,
-        messages: safeMessages,
-        text,
-        charCount: text.length,
-        approxPromptTokens: promptTokens,
+        messages: bounded.messages,
+        text: bounded.text,
+        charCount: bounded.charCount,
+        approxPromptTokens: bounded.approxPromptTokens,
+        fullCharCount: bounded.fullCharCount,
+        fullApproxPromptTokens: bounded.fullApproxPromptTokens,
+        truncated: bounded.truncated,
+        transcriptWindow: bounded.transcriptWindow,
+        coverage: bounded.coverage,
         safetyGate: safety.meta,
         counts: {
             messageCount: parsed.normalized.messages.length,
             safeMessageCount: safeMessages.length,
             userCount: parsed.normalized.userCount,
             assistantCount: parsed.normalized.assistantCount,
+            fullCharCount: bounded.fullCharCount,
+            fullApproxPromptTokens: bounded.fullApproxPromptTokens,
         },
         metadata: {
             model: parsed.normalized.model,
@@ -1203,12 +1318,20 @@ function materializeRecoveryTranscriptView(candidate = {}, opts = {}) {
     };
 }
 
+async function prepareActiveSessionCheckpoint(aquifer, opts = {}) {
+    return prepareActiveSessionCheckpointImpl(aquifer, opts, {
+        materializeRecoveryTranscriptView,
+        resolveCurrentMemoryForFinalization,
+    });
+}
+
 function buildFinalizationPrompt(view = {}, opts = {}) {
     if (!view || view.status !== 'ok') {
         throw new Error('buildFinalizationPrompt requires an ok transcript view');
     }
     const maxFacts = opts.maxFacts || 8;
-    return [
+    const includeCurrentMemory = opts.includeCurrentMemory !== false;
+    const lines = [
         'You are finalizing an Aquifer memory session for Codex.',
         'Use only the sanitized transcript below. Do not infer from hidden tool output or injected context.',
         'Return compact JSON with this shape:',
@@ -1222,7 +1345,16 @@ function buildFinalizationPrompt(view = {}, opts = {}) {
         '<sanitized_transcript>',
         view.text || '',
         '</sanitized_transcript>',
-    ].join('\n');
+    ];
+    if (includeCurrentMemory) {
+        lines.splice(
+            2,
+            0,
+            'Use current_memory as the already-committed current state. Reconcile the transcript against it: keep valid state, supersede stale state, and mark uncertain items explicitly.',
+        );
+        lines.splice(10, 0, formatCurrentMemoryPromptBlock(opts.currentMemory, opts), '');
+    }
+    return lines.join('\n');
 }
 
 function normalizeFinalizationSummary(summary = {}) {
@@ -1235,6 +1367,30 @@ function normalizeFinalizationSummary(summary = {}) {
     return { summaryText, structuredSummary };
 }
 
+function inferScopeKindFromKey(scopeKey) {
+    const key = String(scopeKey || '').trim();
+    if (!key) return null;
+    if (key === 'global') return 'global';
+    const prefix = key.split(':')[0];
+    return ['user', 'workspace', 'project', 'repo', 'task', 'session', 'host_runtime'].includes(prefix)
+        ? prefix
+        : null;
+}
+
+function resolveFinalizationScope(opts = {}) {
+    const meta = opts.currentMemory && opts.currentMemory.meta ? opts.currentMemory.meta : {};
+    const metaPath = Array.isArray(meta.activeScopePath) ? meta.activeScopePath : null;
+    const scopeKey = opts.scopeKey
+        || opts.activeScopeKey
+        || meta.activeScopeKey
+        || (metaPath && metaPath.length > 0 ? metaPath[metaPath.length - 1] : null)
+        || null;
+    return {
+        scopeKey,
+        scopeKind: opts.scopeKind || inferScopeKindFromKey(scopeKey),
+    };
+}
+
 async function ensureCommittedForFinalization(aquifer, view = {}, opts = {}) {
     const {
         agentId = 'main',
@@ -1304,6 +1460,15 @@ async function finalizeTranscriptView(aquifer, view = {}, summary = {}, opts = {
         trigger: mode,
         ...(opts.metadata || {}),
     };
+    let resolvedCurrentMemory = opts.currentMemory;
+    if (!metadata.currentMemory) {
+        resolvedCurrentMemory = await resolveCurrentMemoryForFinalization(aquifer, opts);
+        if (resolvedCurrentMemory) metadata.currentMemory = compactCurrentMemorySnapshot(resolvedCurrentMemory, opts);
+    }
+    const finalizationScope = resolveFinalizationScope({
+        ...opts,
+        currentMemory: resolvedCurrentMemory,
+    });
     const result = await finalizeSession({
         sessionId: view.sessionId,
         agentId,
@@ -1320,11 +1485,15 @@ async function finalizeTranscriptView(aquifer, view = {}, summary = {}, opts = {
         startedAt: view.metadata?.startedAt || null,
         endedAt: view.metadata?.lastMessageAt || null,
         embedding: opts.embedding || null,
-        scopeKind: opts.scopeKind || null,
-        scopeKey: opts.scopeKey || null,
+        scopeKind: finalizationScope.scopeKind,
+        scopeKey: finalizationScope.scopeKey,
         contextKey: opts.contextKey || null,
         topicKey: opts.topicKey || null,
         authority: opts.authority || 'verified_summary',
+        candidates: Array.isArray(opts.candidates) ? opts.candidates : undefined,
+        candidatePayload: opts.candidatePayload || null,
+        candidateEnvelope: opts.candidateEnvelope || null,
+        coverage: opts.coverage || null,
         metadata,
     });
     const humanReviewText = result.humanReviewText || '';
@@ -1432,11 +1601,13 @@ async function prepareSessionStartRecovery(aquifer, opts = {}) {
         }
         return { status: 'skipped_short', candidate: skippedCandidate, view, userCount };
     }
+    const currentMemory = await resolveCurrentMemoryForFinalization(aquifer, recoveryOpts);
     return {
         status: 'needs_agent_summary',
         candidate,
         view,
-        prompt: buildFinalizationPrompt(view, recoveryOpts),
+        currentMemory,
+        prompt: buildFinalizationPrompt(view, { ...recoveryOpts, currentMemory }),
     };
 }
 
@@ -1470,6 +1641,13 @@ async function finalizeCodexSession(aquifer, input = {}, opts = {}) {
         scopeKey: input.scopeKey || opts.scopeKey || null,
         contextKey: input.contextKey || opts.contextKey || null,
         topicKey: input.topicKey || opts.topicKey || null,
+        activeScopeKey: input.activeScopeKey || opts.activeScopeKey || input.scopeKey || opts.scopeKey || null,
+        activeScopePath: input.activeScopePath || opts.activeScopePath || null,
+        currentMemory: input.currentMemory !== undefined ? input.currentMemory : opts.currentMemory,
+        currentMemoryLimit: input.currentMemoryLimit || opts.currentMemoryLimit || null,
+        includeCurrentMemory: input.includeCurrentMemory !== undefined ? input.includeCurrentMemory : opts.includeCurrentMemory,
+        candidateEnvelope: input.candidateEnvelope || opts.candidateEnvelope || null,
+        coverage: input.coverage || opts.coverage || null,
     });
 }
 
@@ -1530,6 +1708,9 @@ module.exports = {
     findDbEligibleRecoveryCandidates,
     materializeRecoveryTranscriptView,
     buildFinalizationPrompt,
+    buildActiveSessionCheckpointInput,
+    buildActiveSessionCheckpointPrompt,
+    prepareActiveSessionCheckpoint,
     prepareSessionStartRecovery,
     recordRecoveryDecision,
     finalizeTranscriptView,
@@ -1546,4 +1727,7 @@ module.exports = {
     markerPath,
     hashNormalizedTranscript,
     readMarkerMetadataFromContent,
+    formatCurrentMemoryPromptBlock,
+    compactCurrentMemorySnapshot,
+    resolveCurrentMemoryForFinalization,
 };

package/consumers/mcp.js

@@ -7,8 +7,9 @@
  * This is the primary integration surface for Aquifer. Agent hosts (Claude Code,
  * Codex, OpenCode, etc.) should integrate through this MCP server.
  *
- * Tools: session_recall, evidence_recall, session_feedback, memory_feedback,
- * feedback_stats, session_bootstrap, memory_stats, memory_pending
+ * Tools: memory_recall, historical_recall, session_recall, evidence_recall,
+ * session_feedback, memory_feedback, feedback_stats, session_bootstrap,
+ * memory_stats, memory_pending
  *
  * Usage:
  *   npx aquifer mcp
@@ -38,6 +39,32 @@ function formatResults(results, query, explain) {
   return formatRecallResults(results, { query, showScore: true, showExplain: !!explain });
 }
 
+function scopeLabel(config = {}) {
+  if (Array.isArray(config.memoryActiveScopePath) && config.memoryActiveScopePath.length > 0) {
+    return config.memoryActiveScopePath.join(' > ');
+  }
+  return config.memoryActiveScopeKey || 'none';
+}
+
+function sessionRecallLaneHeader(config = {}) {
+  const mode = config.memoryServingMode || 'legacy';
+  if (mode === 'curated') {
+    return `Serving lane: curated current memory (active scope: ${scopeLabel(config)})`;
+  }
+  return 'Serving lane: legacy evidence/session recall (not current memory)';
+}
+
+function memoryRecallLaneHeader(config = {}, params = {}) {
+  const scope = Array.isArray(params.activeScopePath) && params.activeScopePath.length > 0
+    ? params.activeScopePath.join(' > ')
+    : (params.activeScopeKey || scopeLabel(config));
+  return `Serving lane: explicit current memory recall (active scope: ${scope || 'none'})`;
+}
+
+function historicalRecallLaneHeader() {
+  return 'Serving lane: explicit historical/session recall';
+}
+
 // ---------------------------------------------------------------------------
 // Start MCP server
 // ---------------------------------------------------------------------------
@@ -63,9 +90,93 @@ async function main() {
     version: packageVersion,
   });
 
+  server.tool(
+    'memory_recall',
+    'Explicit current-memory recall on the active curated memory corpus. Use this for current state / next-step lookup; use historical_recall for older session detail.',
+    {
+      query: z.string().min(1).describe('Search query (keyword or natural language)'),
+      limit: z.number().int().min(1).max(20).optional().describe('Max results (default 5)'),
+      mode: z.enum(['fts', 'hybrid', 'vector']).optional().describe('Recall mode: "fts" (keyword only), "hybrid" (default, FTS + vector), "vector" (vector only)'),
+      explain: z.boolean().optional().describe('Include per-result score breakdown (diagnostic)'),
+      activeScopeKey: z.string().optional().describe('Active curated memory scope key'),
+      activeScopePath: z.array(z.string()).optional().describe('Ordered curated scope path'),
+    },
+    async (params) => {
+      try {
+        const aquifer = getAquifer();
+        const recallOpts = {
+          limit: params.limit || 5,
+          activeScopeKey: params.activeScopeKey || undefined,
+          activeScopePath: params.activeScopePath || undefined,
+        };
+        if (params.mode) recallOpts.mode = params.mode;
+
+        const results = await aquifer.memoryRecall(params.query, recallOpts);
+        const text = [
+          memoryRecallLaneHeader(aquifer.getConfig ? aquifer.getConfig() : {}, params),
+          '',
+          formatResults(results, params.query, params.explain),
+        ].join('\n');
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `memory_recall error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
+  server.tool(
+    'historical_recall',
+    'Explicit historical/session recall over stored sessions and summaries. Use this for timeline, detail, and session context lookup; use evidence_recall only for audit/debug/provenance.',
+    {
+      query: z.string().min(1).describe('Search query (keyword or natural language)'),
+      limit: z.number().int().min(1).max(20).optional().describe('Max results (default 5)'),
+      agentId: z.string().optional().describe('Filter by agent ID'),
+      source: z.string().optional().describe('Filter by source (e.g., gateway, cc)'),
+      dateFrom: z.string().optional().describe('Start date YYYY-MM-DD'),
+      dateTo: z.string().optional().describe('End date YYYY-MM-DD'),
+      entities: z.array(z.string()).optional().describe('Entity names to match'),
+      entityMode: z.enum(['any', 'all']).optional().describe('"any" (default, boost) or "all" (only sessions with every entity)'),
+      mode: z.enum(['fts', 'hybrid', 'vector']).optional().describe('Recall mode: "fts" (keyword only, no embed needed), "hybrid" (default, FTS + vector), "vector" (vector only)'),
+      explain: z.boolean().optional().describe('Include per-result score breakdown (diagnostic)'),
+    },
+    async (params) => {
+      try {
+        const aquifer = getAquifer();
+        const recallOpts = {
+          limit: params.limit || 5,
+          agentId: params.agentId || undefined,
+          source: params.source || undefined,
+          dateFrom: params.dateFrom || undefined,
+          dateTo: params.dateTo || undefined,
+        };
+        if (params.entities && params.entities.length > 0) {
+          recallOpts.entities = params.entities;
+          recallOpts.entityMode = params.entityMode || 'any';
+        }
+        if (params.mode) recallOpts.mode = params.mode;
+
+        const results = await aquifer.historicalRecall(params.query, recallOpts);
+        const text = [
+          historicalRecallLaneHeader(),
+          '',
+          formatResults(results, params.query, params.explain),
+        ].join('\n');
+        return { content: [{ type: 'text', text }] };
+      } catch (err) {
+        return {
+          content: [{ type: 'text', text: `historical_recall error: ${err.message}` }],
+          isError: true,
+        };
+      }
+    }
+  );
+
   server.tool(
     'session_recall',
-    'Search Aquifer memory. In curated serving mode this searches active curated memory only; use evidence_recall for legacy session/evidence lookup.',
+    'Compatibility recall surface. In curated serving mode this routes to current memory; in legacy serving mode it routes to historical/session recall. Prefer memory_recall for current state and historical_recall for timeline/detail lookup.',
     {
       query: z.string().min(1).describe('Search query (keyword or natural language)'),
       limit: z.number().int().min(1).max(20).optional().describe('Max results (default 5)'),
@@ -100,7 +211,11 @@ async function main() {
         if (params.mode) recallOpts.mode = params.mode;
 
         const results = await aquifer.recall(params.query, recallOpts);
-        const text = formatResults(results, params.query, params.explain);
+        const text = [
+          sessionRecallLaneHeader(aquifer.getConfig ? aquifer.getConfig() : {}),
+          '',
+          formatResults(results, params.query, params.explain),
+        ].join('\n');
         return { content: [{ type: 'text', text }] };
       } catch (err) {
         return {
@@ -146,7 +261,11 @@ async function main() {
         if (params.allowUnsafeDebug) recallOpts.allowUnsafeDebug = true;
 
         const results = await aquifer.evidenceRecall(params.query, recallOpts);
-        const text = formatResults(results, params.query, params.explain);
+        const text = [
+          'Serving lane: explicit legacy/evidence recall',
+          '',
+          formatResults(results, params.query, params.explain),
+        ].join('\n');
         return { content: [{ type: 'text', text }] };
       } catch (err) {
         return {
@@ -255,13 +374,16 @@ async function main() {
 
   server.tool(
     'memory_stats',
-    'Return storage statistics for the Aquifer memory store (session counts by status, summaries, turn embeddings, entities, date range).',
+    'Return storage statistics for the Aquifer memory store, serving mode, current-memory record coverage, and session date range.',
     {},
     async () => {
       try {
         const aquifer = getAquifer();
         const stats = await aquifer.getStats();
         const lines = [
+          `Backend: ${stats.backendKind || 'unknown'} (${stats.backendProfile || 'unknown'})`,
+          `Serving mode: ${stats.serving?.mode || 'legacy'}`,
+          `Active scope: ${stats.serving?.activeScopePath?.join(' > ') || stats.serving?.activeScopeKey || 'none'}`,
           `Sessions: ${stats.sessionTotal} total`,
         ];
         for (const [status, count] of Object.entries(stats.sessions)) {
@@ -270,7 +392,23 @@ async function main() {
         lines.push(`Summaries: ${stats.summaries}`);
         lines.push(`Turn embeddings: ${stats.turnEmbeddings}`);
         lines.push(`Entities: ${stats.entities}`);
+        if (stats.memoryRecords) {
+          lines.push(`Memory records: ${stats.memoryRecords.total} total (${stats.memoryRecords.active} active, ${stats.memoryRecords.visibleInRecall} recall-visible, ${stats.memoryRecords.visibleInBootstrap} bootstrap-visible)`);
+          if (stats.memoryRecords.latest) lines.push(`Memory record range: ${new Date(stats.memoryRecords.earliest).toISOString().slice(0, 10)} → ${new Date(stats.memoryRecords.latest).toISOString().slice(0, 10)}`);
+        }
+        if (stats.sessionFinalizations?.available) {
+          const statusText = Object.entries(stats.sessionFinalizations.statuses || {})
+            .map(([status, count]) => `${status}: ${count}`)
+            .join(', ') || 'none';
+          lines.push(`Session finalizations: ${stats.sessionFinalizations.total} total (${statusText})`);
+          if (stats.sessionFinalizations.latestFinalizedAt) {
+            lines.push(`Latest finalization: ${new Date(stats.sessionFinalizations.latestFinalizedAt).toISOString().slice(0, 10)}`);
+          }
+        }
         if (stats.earliest) lines.push(`Date range: ${new Date(stats.earliest).toISOString().slice(0, 10)} → ${new Date(stats.latest).toISOString().slice(0, 10)}`);
+        if ((stats.serving?.mode || 'legacy') !== 'curated') {
+          lines.push('Warning: legacy serving returns session/evidence material; configure curated serving with an active scope for current-memory answers.');
+        }
         return { content: [{ type: 'text', text: lines.join('\n') }] };
       } catch (err) {
         return {