@shadowforge0/aquifer-memory 1.7.0 → 1.8.1

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;
@@ -1102,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) {
@@ -1115,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 {
@@ -1122,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 };
     }
 
@@ -1154,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',
@@ -1166,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,
         };
     }
@@ -1190,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,
@@ -1212,96 +1318,11 @@ function materializeRecoveryTranscriptView(candidate = {}, opts = {}) {
     };
 }
 
-function compactCurrentMemoryRow(row = {}) {
-    const payload = row.payload && typeof row.payload === 'object' ? row.payload : {};
-    const confidence = payload.confidence || payload.currentMemoryConfidence || null;
-    return {
-        memoryType: row.memoryType || row.memory_type || 'memory',
-        canonicalKey: row.canonicalKey || row.canonical_key || null,
-        scopeKey: row.scopeKey || row.scope_key || null,
-        summary: String(row.summary || row.title || '').replace(/\s+/g, ' ').trim(),
-        authority: row.authority || null,
-        confidence,
-    };
-}
-
-function formatCurrentMemoryPromptBlock(currentMemory = null, opts = {}) {
-    const maxItems = Math.max(0, Math.min(20, opts.maxCurrentMemoryItems || opts.currentMemoryLimit || 12));
-    const meta = currentMemory && currentMemory.meta ? currentMemory.meta : {};
-    const rows = Array.isArray(currentMemory?.memories)
-        ? currentMemory.memories
-        : (Array.isArray(currentMemory?.items) ? currentMemory.items : []);
-    const compactRows = rows.map(compactCurrentMemoryRow).filter(row => row.summary).slice(0, maxItems);
-    const attrs = [
-        `source="${meta.source || 'memory_records'}"`,
-        `serving_contract="${meta.servingContract || meta.serving_contract || 'current_memory_v1'}"`,
-        `count="${compactRows.length}"`,
-        `truncated="${Boolean(meta.truncated || rows.length > compactRows.length)}"`,
-        `degraded="${Boolean(meta.degraded || currentMemory?.error)}"`,
-    ];
-    const lines = compactRows.map(row => {
-        const scope = row.scopeKey ? ` scope=${row.scopeKey}` : '';
-        const authority = row.authority ? ` authority=${row.authority}` : '';
-        const confidence = row.confidence ? ` confidence=${row.confidence}` : '';
-        return `- ${row.memoryType}${scope}${authority}${confidence}: ${row.summary}`;
+async function prepareActiveSessionCheckpoint(aquifer, opts = {}) {
+    return prepareActiveSessionCheckpointImpl(aquifer, opts, {
+        materializeRecoveryTranscriptView,
+        resolveCurrentMemoryForFinalization,
     });
-    if (currentMemory && currentMemory.error && lines.length === 0) {
-        lines.push(`- degraded: ${String(currentMemory.error).replace(/\s+/g, ' ').trim()}`);
-    }
-    if (lines.length === 0) lines.push('- none');
-    return [
-        `<current_memory ${attrs.join(' ')}>`,
-        ...lines,
-        '</current_memory>',
-    ].join('\n');
-}
-
-function compactCurrentMemorySnapshot(currentMemory = null, opts = {}) {
-    const maxItems = Math.max(0, Math.min(20, opts.maxCurrentMemoryItems || opts.currentMemoryLimit || 12));
-    const meta = currentMemory && currentMemory.meta ? currentMemory.meta : {};
-    const rows = Array.isArray(currentMemory?.memories)
-        ? currentMemory.memories
-        : (Array.isArray(currentMemory?.items) ? currentMemory.items : []);
-    return {
-        memories: rows.map(compactCurrentMemoryRow).filter(row => row.summary).slice(0, maxItems),
-        meta: {
-            source: meta.source || 'memory_records',
-            servingContract: meta.servingContract || meta.serving_contract || 'current_memory_v1',
-            count: Math.min(rows.length, maxItems),
-            truncated: Boolean(meta.truncated || rows.length > maxItems),
-            degraded: Boolean(meta.degraded || currentMemory?.error),
-        },
-    };
-}
-
-async function resolveCurrentMemoryForFinalization(aquifer, opts = {}) {
-    if (opts.includeCurrentMemory === false) return null;
-    if (opts.currentMemory !== undefined) return opts.currentMemory;
-    const currentFn = aquifer?.memory?.current || aquifer?.memory?.listCurrentMemory;
-    if (typeof currentFn !== 'function') return null;
-    const limit = Math.max(1, Math.min(20, opts.currentMemoryLimit || opts.maxCurrentMemoryItems || 12));
-    try {
-        return await currentFn.call(aquifer.memory, {
-            tenantId: opts.tenantId,
-            activeScopeKey: opts.activeScopeKey || opts.scopeKey,
-            activeScopePath: opts.activeScopePath,
-            scopeId: opts.scopeId,
-            asOf: opts.asOf,
-            limit,
-        });
-    } catch (err) {
-        return {
-            memories: [],
-            meta: {
-                source: 'memory_records',
-                servingContract: 'current_memory_v1',
-                count: 0,
-                truncated: false,
-                degraded: true,
-            },
-            error: err.message,
-        };
-    }
 }
 
 function buildFinalizationPrompt(view = {}, opts = {}) {
@@ -1346,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',
@@ -1415,10 +1460,15 @@ async function finalizeTranscriptView(aquifer, view = {}, summary = {}, opts = {
         trigger: mode,
         ...(opts.metadata || {}),
     };
+    let resolvedCurrentMemory = opts.currentMemory;
     if (!metadata.currentMemory) {
-        const currentMemory = await resolveCurrentMemoryForFinalization(aquifer, opts);
-        if (currentMemory) metadata.currentMemory = compactCurrentMemorySnapshot(currentMemory, opts);
+        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,
@@ -1435,13 +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 || '';
@@ -1594,6 +1646,8 @@ async function finalizeCodexSession(aquifer, input = {}, opts = {}) {
         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,
     });
 }
 
@@ -1654,6 +1708,9 @@ module.exports = {
     findDbEligibleRecoveryCandidates,
     materializeRecoveryTranscriptView,
     buildFinalizationPrompt,
+    buildActiveSessionCheckpointInput,
+    buildActiveSessionCheckpointPrompt,
+    prepareActiveSessionCheckpoint,
     prepareSessionStartRecovery,
     recordRecoveryDecision,
     finalizeTranscriptView,

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 {