@shadowforge0/aquifer-memory 1.6.0 → 1.7.0

package/README.md

@@ -77,9 +77,15 @@ Keep `AQUIFER_MEMORY_SERVING_MODE=legacy` for first rollout. Switch to `curated`
 | Start the MCP server | `npx aquifer mcp` |
 | Search memory manually | `npx aquifer recall "auth middleware"` |
 | Plan curated memory compaction | `npx aquifer compact --cadence daily --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z` |
+| Generate a timer synthesis prompt | `npx aquifer operator compaction daily --include-synthesis-prompt --json` |
+| Apply reviewed timer synthesis candidates | `npx aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json` |
 | Inspect storage health | `npx aquifer stats` |
 | Enrich pending sessions | `npx aquifer backfill` |
 
+Timer synthesis output is candidate material until an operator applies it with
+`--promote-candidates`; it does not become active curated memory from the
+prompt or summary file alone.
+
 Need LLM summarization, the knowledge graph, OpenAI embeddings, reranking, or operations details? See [docs/setup.md](docs/setup.md) and [Environment Variables](#environment-variables).
 
 ---

package/README_CN.md

@@ -111,6 +111,23 @@ Claude Code、Claude Desktop 或任何支持 MCP 的 client——放进 `.mcp.js
 
 第一轮 rollout 先保持 `AQUIFER_MEMORY_SERVING_MODE=legacy`。只有在你要让 `session_recall` 和 `session_bootstrap` 提供 active curated memory 时，才切到 `curated`；`evidence_recall` 会保留为显式 audit/debug 路径。要 rollback 只要把 env 或 config 切回 `legacy`。
 
+### Common commands
+
+| Goal | Command |
+|---|---|
+| Verify setup | `npx aquifer quickstart` |
+| Start the MCP server | `npx aquifer mcp` |
+| Search memory manually | `npx aquifer recall "auth middleware"` |
+| Plan curated memory compaction | `npx aquifer compact --cadence daily --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z` |
+| Generate a timer synthesis prompt | `npx aquifer operator compaction daily --include-synthesis-prompt --json` |
+| Apply reviewed timer synthesis candidates | `npx aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json` |
+| Inspect storage health | `npx aquifer stats` |
+| Enrich pending sessions | `npx aquifer backfill` |
+
+Timer synthesis output is candidate material until an operator applies it with
+`--promote-candidates`; it does not become active curated memory from the
+prompt or summary file alone.
+
 需要 LLM 摘要、知识图谱、OpenAI embedding 或 reranker？往下看 [环境变量](#环境变量) 和 [docs/setup.md](docs/setup.md)。
 
 ---

package/README_TW.md

@@ -77,9 +77,13 @@ Claude Code、Claude Desktop 或任何支援 MCP 的 client——放進 `.mcp.js
 | 啟動 MCP server | `npx aquifer mcp` |
 | 手動查記憶 | `npx aquifer recall "auth middleware"` |
 | 規劃 curated memory 壓縮 | `npx aquifer compact --cadence daily --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z` |
+| 產生 timer synthesis prompt | `npx aquifer operator compaction daily --include-synthesis-prompt --json` |
+| 套用已審核的 timer synthesis candidates | `npx aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json` |
 | 看儲存狀態 | `npx aquifer stats` |
 | 補跑 pending session | `npx aquifer backfill` |
 
+Timer synthesis output 在 operator 用 `--promote-candidates` apply 前都只是 candidate material；光有 prompt 或 summary file 不會變成 active curated memory。
+
 需要 LLM 摘要、知識圖譜、OpenAI embedding、reranker 或維運細節，就往下看 [環境變數](#環境變數) 跟 [docs/setup.md](docs/setup.md)。
 
 ---

package/consumers/cli.js

@@ -51,6 +51,38 @@ function parseCsvList(value) {
   return parts.length > 0 ? parts : undefined;
 }
 
+function readJsonFlagValue(value, label) {
+  if (!value || value === true) {
+    throw new Error(`${label} requires a JSON value`);
+  }
+  try {
+    return JSON.parse(String(value));
+  } catch (err) {
+    throw new Error(`${label} must be valid JSON: ${err.message}`);
+  }
+}
+
+function readJsonFlagFile(filePath, label) {
+  if (!filePath || filePath === true) {
+    throw new Error(`${label} requires a file path`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`${label} must point to valid JSON: ${err.message}`);
+  }
+}
+
+function readSynthesisSummaryFromFlags(flags = {}) {
+  if (flags['synthesis-summary-file']) {
+    return readJsonFlagFile(flags['synthesis-summary-file'], '--synthesis-summary-file');
+  }
+  if (flags['synthesis-summary']) {
+    return readJsonFlagValue(flags['synthesis-summary'], '--synthesis-summary');
+  }
+  return undefined;
+}
+
 function hasQuickstartEmbedConfig(env) {
   return !!(
     env.EMBED_PROVIDER
@@ -145,6 +177,7 @@ function parseArgs(argv) {
     'out', 'active-scope-key', 'active-scope-path', 'cadence', 'period-start', 'period-end',
     'policy-version', 'worker-id', 'apply-token', 'claim-lease-seconds', 'snapshot-as-of',
     'scope-key', 'scope-keys', 'scope-kind', 'context-key', 'topic-key', 'authority', 'input',
+    'synthesis-summary', 'synthesis-summary-file',
   ]);
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--') { args._.push(...argv.slice(i + 1)); break; }
@@ -518,6 +551,7 @@ async function cmdOperator(aquifer, args) {
   const cadence = args.flags.cadence
     || (cadenceVerbs.has(operatorVerb) ? operatorVerb : args._[2])
     || 'manual';
+  const synthesisSummary = readSynthesisSummaryFromFlags(args.flags);
   const result = await aquifer.memory.consolidation.runJob({
     job: 'compaction',
     cadence,
@@ -531,8 +565,17 @@ async function cmdOperator(aquifer, args) {
       : undefined,
     snapshotAsOf: args.flags['snapshot-as-of'] || undefined,
     scopeKeys: parseCsvList(args.flags['scope-keys'] || args.flags['scope-key']),
+    scopeKind: args.flags['scope-kind'] || undefined,
+    scopeKey: args.flags['scope-key'] || undefined,
+    contextKey: args.flags['context-key'] || undefined,
+    topicKey: args.flags['topic-key'] || undefined,
+    activeScopeKey: args.flags['active-scope-key'] || undefined,
+    activeScopePath: parseScopePath(args.flags['active-scope-path']),
     limit: parsePositiveInt(args.flags.limit, 1000),
     apply: args.flags.apply === true,
+    promoteCandidates: args.flags['promote-candidates'] === true,
+    includeSynthesisPrompt: args.flags['include-synthesis-prompt'] === true,
+    synthesisSummary,
   });
 
   if (args.flags.json) {
@@ -542,7 +585,14 @@ async function cmdOperator(aquifer, args) {
 
   console.log(`${result.dryRun ? 'Planned' : 'Executed'} ${result.cadence} compaction window ${result.periodStart} -> ${result.periodEnd}`);
   console.log(`Snapshot: ${result.snapshotCount} active rows${result.snapshotTruncated ? ' (snapshot limit reached)' : ''}`);
-  console.log(`Plan: ${result.plan.statusUpdates.length} lifecycle updates, ${result.plan.candidates.length} aggregate candidates`);
+  console.log(`Plan: ${result.plan.statusUpdates.length} lifecycle updates, ${result.plan.candidates.length} candidates`);
+  if (result.synthesisPrompt) {
+    console.log('\nSynthesis prompt:\n');
+    console.log(result.synthesisPrompt);
+  }
+  if (result.promotionReview) {
+    console.log(`\n${result.promotionReview}`);
+  }
   if (result.dryRun) {
     console.log('Mode: dry-run only. Re-run with --apply to write compaction_runs and lifecycle changes.');
     return;
@@ -611,6 +661,7 @@ Commands:
   stats                       Show database statistics
   export                      Export sessions as JSONL
   bootstrap                   Show recent session context (for new session start)
+  codex-recovery ...          Inspect or run Codex SessionStart recovery flow
    ingest-opencode             Import sessions from OpenCode's local SQLite DB
    mcp                         Start MCP server
 
@@ -642,7 +693,12 @@ Options:
   --period-start ISO          Compaction window start
   --period-end ISO            Compaction window end
   --apply                     Apply compaction; default is dry-run
+  --promote-candidates        Promote compaction/synthesis candidates when applying
+  --include-synthesis-prompt  Include timer synthesis prompt in operator output
+  --synthesis-summary JSON    Timer synthesis summary JSON to attach to a compaction plan
+  --synthesis-summary-file P  Read timer synthesis summary JSON from file
   --scope-key A,B             Limit compaction snapshot to specific scope keys
+  --scope-kind KIND           Explicit synthesis target scope kind
   --snapshot-as-of ISO        Read active snapshot as of a specific instant
   --claim-lease-seconds N     Override compaction apply lease
   --input PATH                Archive distill input JSON path
@@ -652,7 +708,9 @@ Options:
 
 Operator examples:
   aquifer operator compaction daily --json
+  aquifer operator compaction daily --include-synthesis-prompt --json
   aquifer operator compaction manual --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z --apply
+  aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json
   aquifer operator archive-distill --input /tmp/archive-snapshot.json --json`);
     process.exit(0);
   }
@@ -661,6 +719,11 @@ Operator examples:
   const args = parseArgs(argv);
   let quickstartDetected = {};
 
+  if (command === 'codex-recovery') {
+    await require('../scripts/codex-recovery').main(argv.slice(1));
+    return;
+  }
+
   // MCP: delegate to mcp.js
   if (command === 'mcp') {
     require('./mcp').main().catch(err => {
@@ -772,7 +835,11 @@ Operator examples:
 }
 
 // Export for testing; execute only when run directly
-module.exports = { parseArgs };
+module.exports = {
+  parseArgs,
+  cmdOperator,
+  readSynthesisSummaryFromFlags,
+};
 
 if (require.main === module) {
   main().catch(err => {

package/consumers/codex-handoff.js

@@ -1,6 +1,11 @@
 'use strict';
 
-const { finalizeTranscriptView } = require('./codex');
+const {
+  buildFinalizationPrompt,
+  finalizeTranscriptView,
+  resolveCurrentMemoryForFinalization,
+  compactCurrentMemorySnapshot,
+} = require('./codex');
 const { buildFinalizationReview } = require('../core/finalization-review');
 
 function normalizeText(value) {
@@ -95,25 +100,123 @@ function buildHandoffMetadata(payload = {}) {
   };
 }
 
+function resolveHandoffSummary(payload = {}, opts = {}) {
+  const synthesisSummary = opts.synthesisSummary
+    || opts.handoffSynthesisSummary
+    || payload.synthesisSummary
+    || payload.handoffSynthesisSummary
+    || null;
+  if (synthesisSummary) {
+    return {
+      summary: synthesisSummary,
+      candidates: Array.isArray(synthesisSummary.candidates) ? synthesisSummary.candidates : undefined,
+      usedSynthesis: true,
+    };
+  }
+  return {
+    summary: opts.summary || payload.summary || {
+      summaryText: opts.summaryText || payload.summaryText,
+      structuredSummary: opts.structuredSummary || payload.structuredSummary,
+    },
+    candidates: Array.isArray(opts.candidates) ? opts.candidates : undefined,
+    usedSynthesis: false,
+  };
+}
+
+function formatHandoffContextBlock(metadata = {}) {
+  const handoff = metadata.handoff || {};
+  const lines = [
+    `<handoff_context source="${metadata.source || 'codex_handoff'}">`,
+    `title: ${handoff.title || 'untitled'}`,
+    `overview: ${handoff.overview || 'none'}`,
+    `status: ${handoff.status || 'unknown'}`,
+    `lastStep: ${handoff.lastStep || 'none'}`,
+    `next: ${handoff.next || 'none'}`,
+  ];
+  for (const decision of handoff.decisions || []) {
+    lines.push(`decision: ${decision.decision}${decision.reason ? ` | ${decision.reason}` : ''}`);
+  }
+  for (const loop of handoff.openLoops || []) {
+    lines.push(`open_loop: ${loop.item}${loop.owner ? ` | owner=${loop.owner}` : ''}`);
+  }
+  for (const topic of handoff.topics || []) {
+    const name = normalizeText(topic && (topic.name || topic.topic || topic.title));
+    const summary = normalizeText(topic && (topic.summary || topic.text));
+    if (name || summary) lines.push(`topic: ${name || 'topic'}${summary ? ` | ${summary}` : ''}`);
+  }
+  lines.push('</handoff_context>');
+  return lines.join('\n');
+}
+
+function buildHandoffSynthesisPrompt(payload = {}, view = {}, opts = {}) {
+  if (!view || view.status !== 'ok') {
+    throw new Error(`Codex handoff synthesis requires an ok normalized transcript view; got ${view && view.status ? view.status : 'missing'}`);
+  }
+  const metadata = buildHandoffMetadata(payload);
+  const basePrompt = buildFinalizationPrompt(view, opts);
+  const handoffBlock = [
+    formatHandoffContextBlock(metadata),
+    '',
+    '<handoff_synthesis_rules>',
+    'Treat handoff_context as producer process material, not current truth by itself.',
+    'Use the sanitized transcript and current_memory to decide what should become current memory candidates.',
+    'Do not copy old current_memory unchanged unless this session confirms it should carry forward.',
+    'Represent resolved, superseded, revoked, or uncertain items explicitly in structuredSummary payload fields when applicable.',
+    'Do not include raw transcript, tool output, debug ids, DB ids, hashes, secrets, or injected context in memory candidates.',
+    '</handoff_synthesis_rules>',
+  ].join('\n');
+  return basePrompt.replace('<sanitized_transcript>', `${handoffBlock}\n\n<sanitized_transcript>`);
+}
+
+async function prepareHandoffSynthesis(aquifer, payload = {}, opts = {}) {
+  const view = opts.view || payload.view;
+  if (!view || view.status !== 'ok') {
+    throw new Error(`Codex handoff synthesis requires an ok normalized transcript view; got ${view && view.status ? view.status : 'missing'}`);
+  }
+  const currentMemory = await resolveCurrentMemoryForFinalization(aquifer, opts);
+  return {
+    status: 'needs_agent_summary',
+    outputSchemaVersion: 'handoff_current_memory_synthesis_v1',
+    view,
+    currentMemory,
+    prompt: buildHandoffSynthesisPrompt(payload, view, { ...opts, currentMemory }),
+  };
+}
+
 async function finalizeHandoff(aquifer, payload = {}, opts = {}) {
   const view = opts.view || payload.view;
   if (!view || view.status !== 'ok') {
     throw new Error(`Codex handoff finalization requires an ok normalized transcript view; got ${view && view.status ? view.status : 'missing'}`);
   }
-  const summary = opts.summary || payload.summary || {
-    summaryText: opts.summaryText || payload.summaryText,
-    structuredSummary: opts.structuredSummary || payload.structuredSummary,
-  };
+  const { summary, candidates, usedSynthesis } = resolveHandoffSummary(payload, opts);
   const metadata = {
     ...buildHandoffMetadata(payload),
     ...(opts.metadata || {}),
   };
+  if (usedSynthesis) {
+    metadata.handoffSynthesis = {
+      kind: 'handoff_current_memory_synthesis_v1',
+      source: 'operator_reviewed_summary',
+      promotionGate: 'core_finalization',
+    };
+  }
+  const currentMemory = await resolveCurrentMemoryForFinalization(aquifer, opts);
+  if (currentMemory) metadata.currentMemory = compactCurrentMemorySnapshot(currentMemory, opts);
   const result = await finalizeTranscriptView(aquifer, view, summary, {
     ...opts,
     mode: 'handoff',
     metadataSource: 'codex_handoff',
     metadata,
-    authority: opts.authority || 'manual',
+    authority: opts.authority || (usedSynthesis ? 'verified_summary' : 'manual'),
+    candidates,
+    candidatePayload: usedSynthesis
+      ? {
+          kind: 'handoff_synthesis',
+          synthesisKind: 'handoff_current_memory_synthesis_v1',
+          currentMemoryRole: 'handoff_synthesis_candidate',
+          promotionGate: 'core_finalization',
+        }
+      : opts.candidatePayload || null,
   });
   const coreResult = result.finalization || {};
   const finalSummary = coreResult.summary || {
@@ -148,5 +251,8 @@ async function finalizeHandoff(aquifer, payload = {}, opts = {}) {
 
 module.exports = {
   buildHandoffMetadata,
+  buildHandoffSynthesisPrompt,
+  prepareHandoffSynthesis,
+  resolveHandoffSummary,
   finalizeHandoff,
 };

package/consumers/codex.js

@@ -323,11 +323,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 +769,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 +874,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 +971,7 @@ async function findRecoveryCandidates(aquifer, opts = {}) {
             transcriptHash: null,
             source,
             agentId,
-            sessionKey: null,
+            sessionKey,
             userCount: null,
             messageCount: null,
             finalizationStatus: null,
@@ -972,8 +982,7 @@ async function findRecoveryCandidates(aquifer, opts = {}) {
                 fileSessionId: safeFileSessionId,
                 size: entry.stat.size,
                 mtimeMs: entry.stat.mtimeMs,
-                source,
-                agentId,
+                ...provenance,
             },
         };
         const localDecision = readRecoveryDecision(paths, candidatePreview);
@@ -1203,12 +1212,105 @@ 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}`;
+    });
+    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 = {}) {
     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 +1324,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 = {}) {
@@ -1304,6 +1415,10 @@ async function finalizeTranscriptView(aquifer, view = {}, summary = {}, opts = {
         trigger: mode,
         ...(opts.metadata || {}),
     };
+    if (!metadata.currentMemory) {
+        const currentMemory = await resolveCurrentMemoryForFinalization(aquifer, opts);
+        if (currentMemory) metadata.currentMemory = compactCurrentMemorySnapshot(currentMemory, opts);
+    }
     const result = await finalizeSession({
         sessionId: view.sessionId,
         agentId,
@@ -1325,6 +1440,8 @@ async function finalizeTranscriptView(aquifer, view = {}, summary = {}, opts = {
         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,
         metadata,
     });
     const humanReviewText = result.humanReviewText || '';
@@ -1432,11 +1549,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 +1589,11 @@ 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,
     });
 }
 
@@ -1546,4 +1670,7 @@ module.exports = {
     markerPath,
     hashNormalizedTranscript,
     readMarkerMetadataFromContent,
+    formatCurrentMemoryPromptBlock,
+    compactCurrentMemorySnapshot,
+    resolveCurrentMemoryForFinalization,
 };

package/core/aquifer.js

@@ -2150,6 +2150,14 @@ function createAquifer(config = {}) {
       await ensureMigrated();
       return memoryBootstrap.bootstrap(opts);
     },
+    current: async (opts = {}) => {
+      await ensureMigrated();
+      return memoryRecords.currentProjection(withDefaultMemoryScope(opts));
+    },
+    listCurrentMemory: async (opts = {}) => {
+      await ensureMigrated();
+      return memoryRecords.currentProjection(withDefaultMemoryScope(opts));
+    },
     recall: async (query, opts = {}) => {
       await ensureMigrated();
       return memoryRecall.recall(query, opts);

package/core/memory-bootstrap.js

@@ -2,10 +2,10 @@
 
 const TYPE_PRIORITY = {
   constraint: 0,
-  preference: 1,
-  state: 2,
-  open_loop: 3,
-  decision: 4,
+  state: 1,
+  open_loop: 2,
+  decision: 3,
+  preference: 4,
   fact: 5,
   conclusion: 6,
   entity_note: 7,
@@ -96,7 +96,13 @@ function resolveApplicableRecords(records = [], opts = {}) {
   return [...winners.values(), ...additive];
 }
 
-function sortForBootstrap(a, b) {
+function sortForBootstrap(a, b, opts = {}) {
+  const activeScopePath = opts.activeScopePath || (opts.activeScopeKey ? [opts.activeScopeKey] : ['global']);
+  const position = new Map(activeScopePath.map((key, idx) => [key, idx]));
+  const aScope = position.get(scopeKey(a)) ?? -1;
+  const bScope = position.get(scopeKey(b)) ?? -1;
+  if (bScope !== aScope) return bScope - aScope;
+
   const aType = TYPE_PRIORITY[a.memoryType || a.memory_type] ?? 99;
   const bType = TYPE_PRIORITY[b.memoryType || b.memory_type] ?? 99;
   if (aType !== bType) return aType - bType;
@@ -129,10 +135,11 @@ function buildText(records, meta) {
 
 function buildMemoryBootstrap(records = [], opts = {}) {
   const maxChars = Math.max(120, opts.maxChars || 4000);
+  const limit = Number.isFinite(opts.limit) ? Math.max(1, Math.min(100, Math.floor(opts.limit))) : null;
   const active = resolveApplicableRecords(
     records.filter(record => isActiveBootstrap(record, opts)),
     opts,
-  ).sort(sortForBootstrap);
+  ).sort((a, b) => sortForBootstrap(a, b, opts));
 
   const meta = {
     overflow: false,
@@ -141,7 +148,11 @@ function buildMemoryBootstrap(records = [], opts = {}) {
     count: active.length,
   };
 
-  let selected = active.slice();
+  let selected = limit ? active.slice(0, limit) : active.slice();
+  if (limit && active.length > limit) {
+    meta.overflow = true;
+    meta.degraded = true;
+  }
   let text = buildText(selected, meta);
   while (text.length > maxChars && selected.length > 1) {
     selected = selected.slice(0, -1);
@@ -167,13 +178,14 @@ function buildMemoryBootstrap(records = [], opts = {}) {
 
 function createMemoryBootstrap({ records }) {
   async function bootstrap(opts = {}) {
+    const requestedLimit = Number.isFinite(opts.limit) ? Math.max(1, Math.floor(opts.limit)) : 50;
     const rows = await records.listActive({
       tenantId: opts.tenantId,
       scopeId: opts.scopeId,
       scopeKeys: opts.activeScopePath || (opts.activeScopeKey ? [opts.activeScopeKey] : undefined),
       visibleInBootstrap: true,
       asOf: opts.asOf,
-      limit: opts.limit || 50,
+      limit: Math.max(50, Math.min(200, requestedLimit * 4)),
     });
     return buildMemoryBootstrap(rows, opts);
   }