@shadowforge0/aquifer-memory 1.6.0 → 1.8.0

package/.env.example

@@ -1,4 +1,7 @@
 DATABASE_URL=postgresql://aquifer:aquifer@localhost:5432/aquifer
+AQUIFER_BACKEND=postgres
+# AQUIFER_BACKEND=local
+# AQUIFER_LOCAL_PATH=.aquifer/aquifer.local.json
 AQUIFER_SCHEMA=aquifer
 AQUIFER_TENANT_ID=default
 
@@ -9,6 +12,11 @@ AQUIFER_MEMORY_SERVING_MODE=legacy
 # AQUIFER_MEMORY_ACTIVE_SCOPE_KEY=project:example
 # AQUIFER_MEMORY_ACTIVE_SCOPE_PATH=global,project:example
 
+# Optional Codex active-session checkpoint heartbeat policy.
+# AQUIFER_CODEX_CHECKPOINT_CHECK_INTERVAL_MINUTES=10
+# AQUIFER_CODEX_CHECKPOINT_EVERY_MESSAGES=20
+# AQUIFER_CODEX_CHECKPOINT_QUIET_MS=3000
+
 AQUIFER_EMBED_BASE_URL=http://localhost:11434/v1
 AQUIFER_EMBED_MODEL=bge-m3
 # EMBED_PROVIDER=ollama

package/README.md

@@ -74,12 +74,31 @@ Keep `AQUIFER_MEMORY_SERVING_MODE=legacy` for first rollout. Switch to `curated`
 | Goal | Command |
 |---|---|
 | Verify setup | `npx aquifer quickstart` |
+| Inspect selected backend capabilities without DB connection | `AQUIFER_BACKEND=local npx aquifer backend-info --json` |
 | 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` |
+| Generate a finalized-session checkpoint prompt | `npx aquifer operator checkpoint --scope-key project:aquifer --min-finalizations 10 --include-synthesis-prompt --json` |
+| Heartbeat-check an active Codex session for checkpoint work | `npx aquifer codex-recovery checkpoint-heartbeat --hook-stdin --scope-key project:aquifer` |
+| Preview a Codex UserPromptSubmit heartbeat hook install | `npx aquifer codex-recovery checkpoint-heartbeat-hook --scope-key project:aquifer --hooks-path "$CODEX_HOME/hooks.json" --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.
+
+Checkpoint output follows the same boundary. `operator checkpoint` plans from
+finalized session summaries and only writes `checkpoint_runs` when you pass an
+explicit reviewed synthesis summary with `--apply`. `codex-recovery
+checkpoint-heartbeat` is the active-session hook heartbeat for Codex JSONL
+files: it first checks a tiny local scheduler marker, reads the transcript only
+when the time window is due, then writes local spool process material only when
+the message threshold is also due. It does not print prompt text by default and
+does not write DB memory.
+
 Need LLM summarization, the knowledge graph, OpenAI embeddings, reranking, or operations details? See [docs/setup.md](docs/setup.md) and [Environment Variables](#environment-variables).
 
 ---
@@ -133,6 +152,8 @@ Sessions, summaries, turn-level embeddings, entity graph — all live in one dat
 | Variable | Required? | Purpose | Example |
 |----------|-----------|---------|---------|
 | `DATABASE_URL` | Yes | PostgreSQL connection string | `postgresql://user:pass@localhost:5432/mydb` |
+| `AQUIFER_BACKEND` | No | Backend profile selector: `postgres` full backend or explicit degraded `local` starter | `postgres` |
+| `AQUIFER_LOCAL_PATH` | No | Local starter JSON store path | `.aquifer/aquifer.local.json` |
 | `AQUIFER_SCHEMA` | No | PG schema name (default: `aquifer`) | `memory` |
 | `AQUIFER_TENANT_ID` | No | Multi-tenant key (default: `default`) | `my-app` |
 | `AQUIFER_EMBED_BASE_URL` | Yes (for recall) | Embedding API base URL | `http://localhost:11434/v1` |
@@ -151,6 +172,10 @@ Sessions, summaries, turn-level embeddings, entity graph — all live in one dat
 | `AQUIFER_MEMORY_SERVING_MODE` | No | Public serving mode: `legacy` default, or opt-in `curated` | `curated` |
 | `AQUIFER_MEMORY_ACTIVE_SCOPE_KEY` | No | Default active curated scope for recall/bootstrap | `project:aquifer` |
 | `AQUIFER_MEMORY_ACTIVE_SCOPE_PATH` | No | Ordered curated scope path for inheritance | `global,project:aquifer` |
+| `AQUIFER_CODEX_CHECKPOINT_CHECK_INTERVAL_MINUTES` | No | Active Codex checkpoint heartbeat time gate (default: `10`) | `10` |
+| `AQUIFER_CODEX_CHECKPOINT_EVERY_MESSAGES` | No | Active Codex checkpoint message delta gate (default: `20`) | `20` |
+| `AQUIFER_CODEX_CHECKPOINT_EVERY_USER_MESSAGES` | No | Optional user-message delta gate | `10` |
+| `AQUIFER_CODEX_CHECKPOINT_QUIET_MS` | No | Quiet period before reading due transcripts (default: `3000`) | `3000` |
 | `AQUIFER_MIGRATIONS_MODE` | No | Startup handshake mode: `apply` (default), `check`, `off` | `apply` |
 | `AQUIFER_MIGRATION_LOCK_TIMEOUT_MS` | No | Advisory-lock wait before `AQ_MIGRATION_LOCK_TIMEOUT` (default 30000) | `30000` |
 | `AQUIFER_INSIGHTS_DEDUP_MODE` | No | Insights semantic dedup mode: `off` (default), `shadow`, `enforce` — env wins over code for this field only, so operators can kill-switch without redeploy | `shadow` |
@@ -213,6 +238,53 @@ Add to your project's `.claude.json` or user-level MCP config:
 
 Tools appear as `mcp__aquifer__session_recall`, `mcp__aquifer__evidence_recall`, `mcp__aquifer__session_bootstrap`, `mcp__aquifer__session_feedback`, `mcp__aquifer__memory_feedback`, `mcp__aquifer__feedback_stats`, `mcp__aquifer__memory_stats`, `mcp__aquifer__memory_pending`.
 
+For Codex long sessions, Aquifer exposes a UserPromptSubmit-friendly heartbeat
+command instead of installing a daemon:
+
+```bash
+npx aquifer codex-recovery checkpoint-heartbeat \
+  --hook-stdin \
+  --scope-key project:aquifer
+```
+
+Run that from a host hook with Codex hook JSON on stdin. The heartbeat uses a
+time-first gate: if the local marker says the next check is not due, it exits
+without validating or reading the transcript. When due, it validates the
+`transcript_path` realpath under the Codex sessions directory, waits for the
+quiet period, checks the configured message delta, and writes a local spool file
+for later review. Scheduler, claim, and spool files live under the Codex state
+directory by default; they are process-control files, not DB memory.
+
+Heartbeat policy resolves as command flags first, then Aquifer env/config, then
+defaults. The default policy is 10 minutes, 20 safe messages, no user-message
+gate, 3000 ms quiet period, and 60000 ms claim TTL. In config files this lives at
+`codex.checkpoint`:
+
+```json
+{
+  "codex": {
+    "checkpoint": {
+      "checkIntervalMinutes": 10,
+      "everyMessages": 20,
+      "quietMs": 3000
+    }
+  }
+}
+```
+
+To prepare the Codex hook entry, generate or apply the merged `hooks.json`:
+
+```bash
+npx aquifer codex-recovery checkpoint-heartbeat-hook \
+  --scope-key project:aquifer \
+  --hooks-path "$CODEX_HOME/hooks.json" \
+  --json
+```
+
+The hook installer is dry-run by default. Add `--apply` only after reviewing the
+merged `UserPromptSubmit` command. `codex-recovery doctor --json` reports whether
+the heartbeat hook is present.
+
 ### OpenClaw
 
 Add to `openclaw.json` under `mcp.servers`:

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/aquifer.config.example.json

@@ -1,4 +1,14 @@
 {
+  "storage": {
+    "backend": "postgres",
+    "postgres": {
+      "url": "postgresql://user:password@localhost:5432/mydb",
+      "max": 10
+    },
+    "local": {
+      "path": ".aquifer/aquifer.local.json"
+    }
+  },
   "db": {
     "url": "postgresql://user:password@localhost:5432/mydb",
     "max": 10
@@ -14,6 +24,15 @@
     "activeScopeKey": null,
     "activeScopePath": null
   },
+  "codex": {
+    "checkpoint": {
+      "checkIntervalMinutes": 10,
+      "everyMessages": 20,
+      "everyUserMessages": null,
+      "quietMs": 3000,
+      "claimTtlMs": 60000
+    }
+  },
   "embed": {
     "baseUrl": "http://localhost:11434/v1",
     "model": "bge-m3",

package/consumers/cli.js

@@ -10,6 +10,7 @@
  *   aquifer recall <query> [options]    Search sessions
  *   aquifer backfill [options]          Enrich pending sessions
  *   aquifer stats [options]             Show database statistics
+ *   aquifer backend-info [--json]       Show selected backend capabilities
  *   aquifer export [options]            Export sessions
  *   aquifer operator ...                Run operator-safe consolidation jobs
  *   aquifer mcp                         Start MCP server
@@ -17,7 +18,9 @@
 
 const fs = require('fs');
 const { createAquiferFromConfig } = require('./shared/factory');
+const { loadConfig } = require('./shared/config');
 const { formatRecallResults } = require('./shared/recall-format');
+const { backendCapabilities } = require('../core/backends/capabilities');
 
 function formatDate(value, fallback) {
   if (!value) return fallback;
@@ -51,6 +54,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
@@ -77,6 +112,7 @@ function buildQuickstartSetupHints(env, detected, err) {
     if (!hasDb) {
       hints.push('If you expect local defaults, make sure PostgreSQL is running on localhost:5432.');
       hints.push('Otherwise set DATABASE_URL or AQUIFER_DB_URL explicitly and run quickstart again.');
+      hints.push('To inspect the degraded local starter profile without PostgreSQL, run `AQUIFER_BACKEND=local aquifer backend-info --json`.');
     }
     return hints;
   }
@@ -92,6 +128,7 @@ function buildQuickstartSetupHints(env, detected, err) {
     if (!hasDb) hints.push('PostgreSQL was not autodetected and no DATABASE_URL is set.');
     if (!hasEmbed) hints.push('No embedding provider was autodetected and no embed env is set.');
     hints.push('Try `docker compose up -d`, then run `npx aquifer quickstart` again.');
+    hints.push('To inspect the degraded local starter profile without PostgreSQL, run `AQUIFER_BACKEND=local aquifer backend-info --json`.');
   }
 
   hints.push(`Raw error: ${message}`);
@@ -144,7 +181,8 @@ function parseArgs(argv) {
     'verdict', 'feedback-type', 'note', 'db', 'since', 'min-messages', 'lookback-days', 'max-chars',
     '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',
+    'scope-id', 'scope-key', 'scope-keys', 'scope-kind', 'context-key', 'topic-key', 'authority', 'input',
+    'synthesis-summary', 'synthesis-summary-file', 'min-finalizations', 'checkpoint-key',
   ]);
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--') { args._.push(...argv.slice(i + 1)); break; }
@@ -348,15 +386,122 @@ async function cmdStats(aquifer, args) {
   if (args.flags.json) {
     console.log(JSON.stringify(stats, null, 2));
   } else {
+    console.log(`Backend: ${stats.backendKind || 'unknown'} (${stats.backendProfile || 'unknown'})`);
+    console.log(`Serving mode: ${stats.serving?.mode || 'legacy'}`);
+    console.log(`Active scope: ${stats.serving?.activeScopePath?.join(' > ') || stats.serving?.activeScopeKey || 'none'}`);
     console.log(`Sessions: ${stats.sessionTotal} (${Object.entries(stats.sessions).map(([k, v]) => `${k}: ${v}`).join(', ')})`);
     console.log(`Summaries: ${stats.summaries}`);
     console.log(`Turn embeddings: ${stats.turnEmbeddings}`);
     console.log(`Entities: ${stats.entities}`);
+    if (stats.memoryRecords) {
+      console.log(`Memory records: ${stats.memoryRecords.total} (${stats.memoryRecords.active} active, ${stats.memoryRecords.visibleInRecall} recall-visible, ${stats.memoryRecords.visibleInBootstrap} bootstrap-visible)`);
+      if (stats.memoryRecords.latest) console.log(`Memory record range: ${formatDate(stats.memoryRecords.earliest, '?')} — ${formatDate(stats.memoryRecords.latest, '?')}`);
+    }
+    if (stats.sessionFinalizations?.available) {
+      const statusText = Object.entries(stats.sessionFinalizations.statuses || {})
+        .map(([status, count]) => `${status}: ${count}`)
+        .join(', ') || 'none';
+      console.log(`Session finalizations: ${stats.sessionFinalizations.total} (${statusText})`);
+      if (stats.sessionFinalizations.latestFinalizedAt) console.log(`Latest finalization: ${formatDate(stats.sessionFinalizations.latestFinalizedAt, '?')}`);
+    }
     if (stats.earliest) console.log(`Range: ${formatDate(stats.earliest, '?')} — ${formatDate(stats.latest, '?')}`);
+    if ((stats.serving?.mode || 'legacy') !== 'curated') {
+      console.log('Warning: legacy serving returns session/evidence material; configure curated serving with an active scope for current-memory answers.');
+    }
+  }
+}
+
+function selectedBackendInfo(opts = {}) {
+  const config = loadConfig(opts);
+  const backendKind = config.storage.backend;
+  const capabilities = backendCapabilities(backendKind);
+  return {
+    backendKind,
+    backendProfile: capabilities.profile,
+    label: capabilities.label,
+    summary: capabilities.summary,
+    capabilities: capabilities.capabilities,
+    storage: {
+      localPath: config.storage.local.path,
+      postgresUrlConfigured: Boolean(config.storage.postgres.url || config.db.url),
+    },
+    upgradeHint: capabilities.upgradeHint,
+  };
+}
+
+async function cmdBackendInfo(args) {
+  const info = selectedBackendInfo();
+  if (args.flags.json) {
+    console.log(JSON.stringify(info, null, 2));
+    return;
+  }
+
+  console.log(`Backend: ${info.label} (${info.backendKind}/${info.backendProfile})`);
+  console.log(info.summary);
+  console.log(`PostgreSQL URL configured: ${info.storage.postgresUrlConfigured ? 'yes' : 'no'}`);
+  if (info.backendKind === 'local') {
+    console.log(`Local path: ${info.storage.localPath}`);
+  }
+  if (info.upgradeHint) {
+    console.log(`Upgrade: ${info.upgradeHint}`);
+  }
+  console.log('Capabilities:');
+  for (const [name, status] of Object.entries(info.capabilities)) {
+    console.log(`  ${name}: ${status}`);
   }
 }
 
+async function cmdLocalQuickstart(aquifer) {
+  const cfg = aquifer.getConfig();
+  console.log('Aquifer quickstart — verifying local starter backend.\n');
+
+  console.log('1/5  Preparing local store...');
+  await aquifer.init();
+  console.log(`     OK — ${cfg.backendPath}\n`);
+
+  const sessionId = `quickstart-local-${Date.now()}`;
+  console.log('2/5  Committing test session...');
+  await aquifer.commit(sessionId, [
+    { role: 'user', content: 'Aquifer local starter can store a session without PostgreSQL.' },
+    { role: 'assistant', content: 'Local starter uses JSON persistence and degraded lexical recall.' },
+  ], { agentId: 'quickstart', source: 'quickstart' });
+  console.log('     OK\n');
+
+  console.log('3/5  Checking degraded enrich path...');
+  const enrichResult = await aquifer.enrich(sessionId, {
+    agentId: 'quickstart',
+    skipSummary: true,
+    skipEntities: true,
+  });
+  console.log(`     OK — ${enrichResult.turnsEmbedded} turns embedded (local starter is lexical only)\n`);
+
+  console.log('4/5  Recalling "JSON persistence"...');
+  const results = await aquifer.recall('JSON persistence', { agentId: 'quickstart', limit: 3 });
+  if (results.length === 0) {
+    printQuickstartFailure('local starter could not recall its own test session.', [
+      'The write step succeeded, but lexical recall returned no matches.',
+    ]);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`     OK — ${results.length} result(s), top score: ${results[0].score?.toFixed(3)}\n`);
+
+  console.log('5/5  Cleaning up test data...');
+  if (typeof aquifer.deleteSession === 'function') {
+    await aquifer.deleteSession(sessionId, { agentId: 'quickstart' });
+  }
+  console.log('     OK\n');
+
+  console.log('✓ Aquifer local starter is working.');
+  console.log('  This backend is degraded: use PostgreSQL quickstart for semantic recall, migrations, curated memory, and operator workflows.');
+}
+
 async function cmdQuickstart(aquifer) {
+  if (aquifer.getConfig().backendKind === 'local') {
+    await cmdLocalQuickstart(aquifer);
+    return;
+  }
+
   console.log('Aquifer quickstart — verifying end-to-end setup.\n');
 
   // 1. Migrate
@@ -481,6 +626,51 @@ async function cmdOperator(aquifer, args) {
   const operatorVerb = args._[1] || 'compaction';
   const cadenceVerbs = new Set(['manual', 'daily', 'weekly', 'monthly']);
 
+  if (operatorVerb === 'checkpoint') {
+    const synthesisSummary = readSynthesisSummaryFromFlags(args.flags);
+    const result = await aquifer.checkpoints.runProducer({
+      scopeId: args.flags['scope-id'] || undefined,
+      scopeKind: args.flags['scope-kind'] || undefined,
+      scopeKey: args.flags['scope-key'] || undefined,
+      source: args.flags.source || undefined,
+      agentId: args.flags['agent-id'] || undefined,
+      minFinalizations: args.flags['min-finalizations']
+        ? parsePositiveInt(args.flags['min-finalizations'], 10)
+        : undefined,
+      limit: parsePositiveInt(args.flags.limit, 50),
+      checkpointKey: args.flags['checkpoint-key'] || undefined,
+      policyVersion: args.flags['policy-version'] || undefined,
+      force: args.flags.force === true,
+      apply: args.flags.apply === true,
+      finalize: args.flags.finalize === true,
+      includeSynthesisPrompt: args.flags['include-synthesis-prompt'] === true,
+      synthesisSummary,
+    });
+
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    console.log(result.due
+      ? `Checkpoint due for ${result.scope.scopeKey}: ${result.sourceFinalizationCount} finalized source(s).`
+      : `Checkpoint not ready for ${result.scope.scopeKey}: ${result.sourceFinalizationCount}/${result.minFinalizations} finalized source(s).`);
+    if (result.range) {
+      console.log(`Range: finalization ${result.range.fromFinalizationIdExclusive} -> ${result.range.toFinalizationIdInclusive}`);
+    }
+    if (result.synthesisPrompt) {
+      console.log('\nCheckpoint synthesis prompt:\n');
+      console.log(result.synthesisPrompt);
+    }
+    if (result.run) {
+      console.log(`Run: #${result.run.id} status=${result.run.status}`);
+    } else if (result.runInput) {
+      console.log(`Run input prepared: status=${result.runInput.status}`);
+      console.log('Mode: dry-run only. Re-run with --apply and an explicit synthesis summary to write checkpoint_runs.');
+    }
+    return;
+  }
+
   if (operatorVerb === 'archive-distill') {
     const inputPath = args.flags.input || args._[2];
     if (!inputPath) {
@@ -511,13 +701,14 @@ async function cmdOperator(aquifer, args) {
   }
 
   if (operatorVerb !== 'compaction' && operatorVerb !== 'compact' && !cadenceVerbs.has(operatorVerb)) {
-    console.error('Usage: aquifer operator <compaction|archive-distill> [...]');
+    console.error('Usage: aquifer operator <compaction|checkpoint|archive-distill> [...]');
     process.exit(1);
   }
 
   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 +722,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 +742,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;
@@ -600,6 +807,7 @@ async function main() {
 Commands:
    quickstart                  Verify end-to-end setup (migrate → commit → enrich → recall)
    migrate                     Run database migrations
+  backend-info                Show selected backend capabilities without connecting to a database
   recall <query>              Search sessions (requires embed config)
   evidence-recall <query>     Search legacy session/evidence plane explicitly
   feedback                    Record trust feedback on a session
@@ -611,6 +819,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 recovery/checkpoint flows
    ingest-opencode             Import sessions from OpenCode's local SQLite DB
    mcp                         Start MCP server
 
@@ -642,7 +851,15 @@ 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
+  --min-finalizations N       Min finalized session summaries before checkpoint proposal
+  --checkpoint-key KEY        Explicit checkpoint key when applying checkpoint producer output
   --scope-key A,B             Limit compaction snapshot to specific scope keys
+  --scope-id ID               Target scope row id for checkpoint producer
+  --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 +869,14 @@ 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 checkpoint --scope-key project:aquifer --min-finalizations 10 --include-synthesis-prompt --json
+  aquifer operator checkpoint --scope-id 7 --synthesis-summary-file /tmp/checkpoint-summary.json --apply --finalize --json
+  AQUIFER_BACKEND=local aquifer backend-info --json
+  aquifer codex-recovery checkpoint-heartbeat --hook-stdin --scope-key project:aquifer
+  aquifer codex-recovery checkpoint-heartbeat-hook --scope-key project:aquifer --hooks-path "$CODEX_HOME/hooks.json" --json
   aquifer operator archive-distill --input /tmp/archive-snapshot.json --json`);
     process.exit(0);
   }
@@ -661,6 +885,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 => {
@@ -680,6 +909,14 @@ Operator examples:
     return;
   }
 
+  if (command === 'backend-info') {
+    if (args.flags.config) {
+      process.env.AQUIFER_CONFIG = args.flags.config;
+    }
+    await cmdBackendInfo(args);
+    return;
+  }
+
   // All other commands need an Aquifer instance
   const configOverrides = {};
   if (args.flags.config) {
@@ -692,15 +929,18 @@ Operator examples:
   // Production commands (migrate, mcp, recall, ...) stay strict — they expect
   // the operator to have set env explicitly.
   if (command === 'quickstart') {
-    const { autodetectForQuickstart } = require('./shared/autodetect');
-    quickstartDetected = await autodetectForQuickstart(process.env);
-    if (Object.keys(quickstartDetected).length > 0) {
-      console.log('Autodetected localhost services (env not set):');
-      for (const [k, v] of Object.entries(quickstartDetected)) {
-        console.log(`  ${k}=${v}`);
-        process.env[k] = v;
+    const selected = loadConfig({ overrides: configOverrides });
+    if (selected.storage.backend !== 'local') {
+      const { autodetectForQuickstart } = require('./shared/autodetect');
+      quickstartDetected = await autodetectForQuickstart(process.env);
+      if (Object.keys(quickstartDetected).length > 0) {
+        console.log('Autodetected localhost services (env not set):');
+        for (const [k, v] of Object.entries(quickstartDetected)) {
+          console.log(`  ${k}=${v}`);
+          process.env[k] = v;
+        }
+        console.log('  Export these in your shell (or MCP client env) to make them permanent.\n');
       }
-      console.log('  Export these in your shell (or MCP client env) to make them permanent.\n');
     }
   }
 
@@ -772,7 +1012,14 @@ Operator examples:
 }
 
 // Export for testing; execute only when run directly
-module.exports = { parseArgs };
+module.exports = {
+  parseArgs,
+  selectedBackendInfo,
+  cmdBackendInfo,
+  cmdLocalQuickstart,
+  cmdOperator,
+  readSynthesisSummaryFromFlags,
+};
 
 if (require.main === module) {
   main().catch(err => {