@shadowforge0/aquifer-memory 1.5.12 → 1.7.0

package/core/storage.js

@@ -32,6 +32,33 @@ const TURN_NOISE_RE = [
 ];
 
 const VALID_STATUSES = new Set(['pending', 'processing', 'succeeded', 'partial', 'failed', 'skipped']);
+const FINALIZATION_STATUSES = new Set([
+  'pending',
+  'processing',
+  'finalized',
+  'failed',
+  'skipped',
+  'declined',
+  'deferred',
+]);
+const FINALIZATION_TERMINAL_STATUSES = new Set(['finalized', 'skipped', 'declined', 'deferred']);
+const FINALIZATION_MODES = new Set([
+  'handoff',
+  'session_end',
+  'session_start_recovery',
+  'afterburn',
+  'manual',
+]);
+
+function requireField(obj, field) {
+  if (!obj || obj[field] === undefined || obj[field] === null || obj[field] === '') {
+    throw new Error(`${field} is required`);
+  }
+}
+
+function toJson(value, fallback) {
+  return JSON.stringify(value === undefined ? fallback : value);
+}
 
 // ---------------------------------------------------------------------------
 // upsertSession
@@ -127,7 +154,7 @@ async function upsertSummary(pool, sessionRowId, {
       tenant_id = EXCLUDED.tenant_id,
       agent_id = EXCLUDED.agent_id,
       session_id = EXCLUDED.session_id,
-      model = COALESCE(EXCLUDED.model, ${qi(schema)}.session_summaries.model),
+      model = COALESCE(NULLIF(EXCLUDED.model, 'unknown'), ${qi(schema)}.session_summaries.model),
       source_hash = COALESCE(EXCLUDED.source_hash, ${qi(schema)}.session_summaries.source_hash),
       message_count = COALESCE(EXCLUDED.message_count, ${qi(schema)}.session_summaries.message_count),
       user_message_count = COALESCE(EXCLUDED.user_message_count, ${qi(schema)}.session_summaries.user_message_count),
@@ -141,7 +168,7 @@ async function upsertSummary(pool, sessionRowId, {
     RETURNING session_row_id, tenant_id, agent_id, session_id, model`,
     [
       sessionRowId, tenantId, agentId || null, sessionId || null,
-      model || null, sourceHash || null,
+      model || 'unknown', sourceHash || null,
       msgCount || 0, userCount || 0, assistantCount || 0,
       startedAt || null, endedAt || null,
       structuredSummary ? JSON.stringify(structuredSummary) : null,
@@ -314,6 +341,357 @@ async function recordAccess(pool, sessionRowIds, { schema } = {}) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Session finalization ledger
+// ---------------------------------------------------------------------------
+
+function normalizeFinalizationStatus(status) {
+  const out = status || 'pending';
+  if (!FINALIZATION_STATUSES.has(out)) throw new Error(`Invalid finalization status: ${out}`);
+  return out;
+}
+
+function finalizationTerminalSql(alias) {
+  const values = [...FINALIZATION_TERMINAL_STATUSES].map(value => `'${value}'`).join(',');
+  return `${alias}.status IN (${values})`;
+}
+
+function normalizeFinalizationMode(mode) {
+  const out = mode || 'handoff';
+  if (!FINALIZATION_MODES.has(out)) throw new Error(`Invalid finalization mode: ${out}`);
+  return out;
+}
+
+async function upsertSessionFinalization(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  requireField(input, 'sessionRowId');
+  requireField(input, 'sessionId');
+  requireField(input, 'agentId');
+  requireField(input, 'source');
+  requireField(input, 'transcriptHash');
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const status = normalizeFinalizationStatus(input.status || 'pending');
+  const mode = normalizeFinalizationMode(input.mode || 'handoff');
+  const phase = input.phase || 'curated_memory_v1';
+  const preserveTerminal = `${finalizationTerminalSql(qi(schema) + '.session_finalizations')}
+          AND ${qi(schema)}.session_finalizations.status <> EXCLUDED.status`;
+  const result = await pool.query(
+    `INSERT INTO ${qi(schema)}.session_finalizations (
+       tenant_id, session_row_id, source, host, agent_id, session_id,
+       transcript_hash, phase, mode, status, finalizer_model, scope_kind,
+       scope_key, context_key, topic_key, summary_row_id, memory_result,
+       summary_text, structured_summary, human_review_text, session_start_text,
+       error, metadata, claimed_at, finalized_at
+     )
+     VALUES (
+       $1,$2,$3,COALESCE($4,'codex'),$5,$6,$7,COALESCE($8,'curated_memory_v1'),
+       $9,$10,$11,$12,$13,$14,$15,$16,COALESCE($17::jsonb,'{}'::jsonb),
+       $18,COALESCE($19::jsonb,'{}'::jsonb),$20,$21,
+       $22,COALESCE($23::jsonb,'{}'::jsonb),$24,$25
+     )
+     ON CONFLICT (tenant_id, source, agent_id, session_id, transcript_hash, phase)
+     DO UPDATE SET
+       session_row_id = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.session_row_id
+         ELSE EXCLUDED.session_row_id
+       END,
+       host = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.host
+         ELSE EXCLUDED.host
+       END,
+       mode = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.mode
+         ELSE EXCLUDED.mode
+       END,
+       status = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.status
+         ELSE EXCLUDED.status
+       END,
+       finalizer_model = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.finalizer_model
+         ELSE COALESCE(EXCLUDED.finalizer_model, ${qi(schema)}.session_finalizations.finalizer_model)
+       END,
+       scope_kind = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.scope_kind
+         ELSE COALESCE(EXCLUDED.scope_kind, ${qi(schema)}.session_finalizations.scope_kind)
+       END,
+       scope_key = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.scope_key
+         ELSE COALESCE(EXCLUDED.scope_key, ${qi(schema)}.session_finalizations.scope_key)
+       END,
+       context_key = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.context_key
+         ELSE COALESCE(EXCLUDED.context_key, ${qi(schema)}.session_finalizations.context_key)
+       END,
+       topic_key = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.topic_key
+         ELSE COALESCE(EXCLUDED.topic_key, ${qi(schema)}.session_finalizations.topic_key)
+       END,
+       summary_row_id = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.summary_row_id
+         ELSE COALESCE(EXCLUDED.summary_row_id, ${qi(schema)}.session_finalizations.summary_row_id)
+       END,
+       memory_result = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.memory_result
+         ELSE COALESCE(NULLIF(EXCLUDED.memory_result, '{}'::jsonb), ${qi(schema)}.session_finalizations.memory_result)
+       END,
+       summary_text = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.summary_text
+         ELSE COALESCE(EXCLUDED.summary_text, ${qi(schema)}.session_finalizations.summary_text)
+       END,
+       structured_summary = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.structured_summary
+         ELSE COALESCE(NULLIF(EXCLUDED.structured_summary, '{}'::jsonb), ${qi(schema)}.session_finalizations.structured_summary)
+       END,
+       human_review_text = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.human_review_text
+         ELSE COALESCE(EXCLUDED.human_review_text, ${qi(schema)}.session_finalizations.human_review_text)
+       END,
+       session_start_text = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.session_start_text
+         ELSE COALESCE(EXCLUDED.session_start_text, ${qi(schema)}.session_finalizations.session_start_text)
+       END,
+       error = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.error
+         ELSE EXCLUDED.error
+       END,
+       metadata = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.metadata
+         ELSE COALESCE(NULLIF(EXCLUDED.metadata, '{}'::jsonb), ${qi(schema)}.session_finalizations.metadata)
+       END,
+       claimed_at = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.claimed_at
+         ELSE COALESCE(EXCLUDED.claimed_at, ${qi(schema)}.session_finalizations.claimed_at)
+       END,
+       finalized_at = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.finalized_at
+         ELSE COALESCE(EXCLUDED.finalized_at, ${qi(schema)}.session_finalizations.finalized_at)
+       END,
+       updated_at = CASE
+         WHEN ${preserveTerminal}
+         THEN ${qi(schema)}.session_finalizations.updated_at
+         ELSE now()
+       END
+     RETURNING *`,
+    [
+      tenantId,
+      input.sessionRowId,
+      input.source,
+      input.host || 'codex',
+      input.agentId,
+      input.sessionId,
+      input.transcriptHash,
+      phase,
+      mode,
+      status,
+      input.finalizerModel || null,
+      input.scopeKind || null,
+      input.scopeKey || null,
+      input.contextKey || null,
+      input.topicKey || null,
+      input.summaryRowId || null,
+      toJson(input.memoryResult, {}),
+      input.summaryText || null,
+      toJson(input.structuredSummary, {}),
+      input.humanReviewText || null,
+      input.sessionStartText || null,
+      input.error || null,
+      toJson(input.metadata, {}),
+      input.claimedAt || (status === 'processing' ? new Date().toISOString() : null),
+      input.finalizedAt || (status === 'finalized' ? new Date().toISOString() : null),
+    ]
+  );
+  return result.rows[0] || null;
+}
+
+async function getSessionFinalization(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  requireField(input, 'sessionId');
+  requireField(input, 'agentId');
+  requireField(input, 'source');
+  requireField(input, 'transcriptHash');
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const phase = input.phase || 'curated_memory_v1';
+  const result = await pool.query(
+    `SELECT *
+       FROM ${qi(schema)}.session_finalizations
+      WHERE tenant_id = $1
+        AND source = $2
+        AND agent_id = $3
+        AND session_id = $4
+        AND transcript_hash = $5
+        AND phase = $6
+      LIMIT 1`,
+    [tenantId, input.source, input.agentId, input.sessionId, input.transcriptHash, phase]
+  );
+  return result.rows[0] || null;
+}
+
+async function updateSessionFinalizationStatus(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  const status = normalizeFinalizationStatus(input.status);
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const params = [
+    tenantId,
+    status,
+    input.error || null,
+    input.finalizerModel || null,
+    toJson(input.memoryResult, {}),
+    toJson(input.metadata, {}),
+  ];
+  let where;
+  if (input.id) {
+    params.push(input.id);
+    where = `id = $${params.length}`;
+  } else {
+    requireField(input, 'sessionId');
+    requireField(input, 'agentId');
+    requireField(input, 'source');
+    requireField(input, 'transcriptHash');
+    params.push(input.source, input.agentId, input.sessionId, input.transcriptHash, input.phase || 'curated_memory_v1');
+    where = `source = $7 AND agent_id = $8 AND session_id = $9 AND transcript_hash = $10 AND phase = $11`;
+  }
+  const result = await pool.query(
+    `UPDATE ${qi(schema)}.session_finalizations
+        SET status = $2,
+            error = $3,
+            finalizer_model = COALESCE($4, finalizer_model),
+            memory_result = COALESCE(NULLIF($5::jsonb, '{}'::jsonb), memory_result),
+            metadata = COALESCE(NULLIF($6::jsonb, '{}'::jsonb), metadata),
+            finalized_at = CASE WHEN $2 = 'finalized' THEN COALESCE(finalized_at, now()) ELSE finalized_at END,
+            updated_at = now()
+      WHERE tenant_id = $1
+        AND ${where}
+        AND (
+          status NOT IN (${[...FINALIZATION_TERMINAL_STATUSES].map(value => `'${value}'`).join(',')})
+          OR status = $2
+        )
+      RETURNING *`,
+    params
+  );
+  return result.rows[0] || null;
+}
+
+async function listSessionFinalizations(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const params = [tenantId];
+  const where = [`tenant_id = $1`];
+  if (input.host) {
+    params.push(input.host);
+    where.push(`host = $${params.length}`);
+  }
+  if (input.status) {
+    const statuses = Array.isArray(input.status) ? input.status : [input.status];
+    for (const status of statuses) normalizeFinalizationStatus(status);
+    params.push(statuses);
+    where.push(`status = ANY($${params.length}::text[])`);
+  }
+  if (input.agentId) {
+    params.push(input.agentId);
+    where.push(`agent_id = $${params.length}`);
+  }
+  if (input.source) {
+    params.push(input.source);
+    where.push(`source = $${params.length}`);
+  }
+  params.push(Math.max(1, Math.min(200, input.limit || 50)));
+  const result = await pool.query(
+    `SELECT *
+       FROM ${qi(schema)}.session_finalizations
+      WHERE ${where.join(' AND ')}
+      ORDER BY updated_at DESC, id DESC
+      LIMIT $${params.length}`,
+    params
+  );
+  return result.rows;
+}
+
+function candidateText(candidate = {}) {
+  if (typeof candidate === 'string') return candidate.trim();
+  const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : null;
+  for (const key of ['summary', 'title', 'decision', 'item', 'conclusion', 'statement', 'fact', 'text', 'note']) {
+    const text = String(candidate[key] || '').trim();
+    if (text) return text;
+  }
+  if (payload) {
+    for (const key of ['summary', 'title', 'decision', 'item', 'conclusion', 'statement', 'fact', 'text', 'note']) {
+      const text = String(payload[key] || '').trim();
+      if (text) return text;
+    }
+  }
+  return '';
+}
+
+async function upsertFinalizationCandidates(pool, rows = [], input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  if (!Array.isArray(rows) || rows.length === 0) return [];
+  requireField(input, 'finalizationId');
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const out = [];
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i] || {};
+    const candidate = row.candidate || {};
+    const memory = row.memory || {};
+    const backingFact = row.backingFact || {};
+    const evidenceRefs = candidate.evidenceRefs || candidate.evidence_refs || [];
+    const result = await pool.query(
+      `INSERT INTO ${qi(schema)}.finalization_candidates (
+         tenant_id, finalization_id, session_id, candidate_index, action, reason,
+         memory_type, canonical_key, summary, payload, provenance,
+         memory_record_id, fact_assertion_id
+       )
+       VALUES (
+         $1,$2,$3,$4,$5,$6,$7,$8,$9,COALESCE($10::jsonb,'{}'::jsonb),COALESCE($11::jsonb,'{}'::jsonb),$12,$13
+       )
+       ON CONFLICT (tenant_id, finalization_id, candidate_index)
+       DO UPDATE SET
+         action = EXCLUDED.action,
+         reason = EXCLUDED.reason,
+         memory_type = COALESCE(EXCLUDED.memory_type, ${qi(schema)}.finalization_candidates.memory_type),
+         canonical_key = COALESCE(EXCLUDED.canonical_key, ${qi(schema)}.finalization_candidates.canonical_key),
+         summary = COALESCE(EXCLUDED.summary, ${qi(schema)}.finalization_candidates.summary),
+         payload = COALESCE(NULLIF(EXCLUDED.payload, '{}'::jsonb), ${qi(schema)}.finalization_candidates.payload),
+         provenance = COALESCE(NULLIF(EXCLUDED.provenance, '{}'::jsonb), ${qi(schema)}.finalization_candidates.provenance),
+         memory_record_id = COALESCE(EXCLUDED.memory_record_id, ${qi(schema)}.finalization_candidates.memory_record_id),
+         fact_assertion_id = COALESCE(EXCLUDED.fact_assertion_id, ${qi(schema)}.finalization_candidates.fact_assertion_id),
+         updated_at = now()
+       RETURNING *`,
+      [
+        tenantId,
+        input.finalizationId,
+        input.sessionId || null,
+        i,
+        row.action || 'skipped',
+        row.reason || null,
+        candidate.memoryType || candidate.memory_type || memory.memory_type || memory.memoryType || null,
+        candidate.canonicalKey || candidate.canonical_key || memory.canonical_key || memory.canonicalKey || null,
+        candidateText(candidate) || candidateText(memory) || null,
+        toJson(candidate.payload || candidate, {}),
+        toJson({ evidenceRefs }, {}),
+        memory.id || memory.memory_id || null,
+        backingFact.id || memory.backing_fact_id || null,
+      ]
+    );
+    out.push(result.rows[0] || null);
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // extractUserTurns
 // ---------------------------------------------------------------------------
@@ -748,6 +1126,11 @@ module.exports = {
   getMessages,
   searchSessions,
   recordAccess,
+  upsertSessionFinalization,
+  getSessionFinalization,
+  updateSessionFinalizationStatus,
+  listSessionFinalizations,
+  upsertFinalizationCandidates,
   extractUserTurns,
   upsertTurnEmbeddings,
   searchTurnEmbeddings,

package/docs/getting-started.md

@@ -0,0 +1,105 @@
+# Aquifer Getting Started
+
+This guide is the shortest path from zero to a working Aquifer memory backend.
+
+By the end, you will have verified a full write -> enrich -> recall cycle and connected Aquifer to an MCP client.
+
+## What you need
+
+- Node.js 18+
+- PostgreSQL 15+ with `pgvector`
+- An embedding endpoint such as Ollama or OpenAI
+
+If you just want the default local path, the repo already includes a Docker stack for PostgreSQL + pgvector and Ollama.
+
+## Fast path: local Docker stack
+
+From the repo root:
+
+```bash
+docker compose up -d
+npx --yes @shadowforge0/aquifer-memory quickstart
+```
+
+`quickstart` runs migrations, writes a test session, embeds it, recalls it, and removes the test data.
+
+If you see `✓ Aquifer is working`, the backend is ready.
+
+## If you already have PostgreSQL and embeddings
+
+Set the minimum environment variables and run the same verification command:
+
+```bash
+export DATABASE_URL="postgresql://aquifer:aquifer@localhost:5432/aquifer"
+export AQUIFER_EMBED_BASE_URL="http://localhost:11434/v1"
+export AQUIFER_EMBED_MODEL="bge-m3"
+
+npx --yes @shadowforge0/aquifer-memory quickstart
+```
+
+If you prefer OpenAI embeddings:
+
+```bash
+export DATABASE_URL="postgresql://aquifer:aquifer@localhost:5432/aquifer"
+export EMBED_PROVIDER="openai"
+export OPENAI_API_KEY="sk-..."
+
+npx --yes @shadowforge0/aquifer-memory quickstart
+```
+
+## Connect an MCP client
+
+Once `quickstart` passes, point your MCP client at Aquifer:
+
+```json
+{
+  "mcpServers": {
+    "aquifer": {
+      "command": "npx",
+      "args": ["--yes", "@shadowforge0/aquifer-memory", "mcp"],
+      "env": {
+        "DATABASE_URL": "postgresql://aquifer:aquifer@localhost:5432/aquifer",
+        "EMBED_PROVIDER": "ollama",
+        "AQUIFER_MEMORY_SERVING_MODE": "legacy"
+      }
+    }
+  }
+}
+```
+
+Or run the server directly:
+
+```bash
+DATABASE_URL=... EMBED_PROVIDER=ollama npx aquifer mcp
+```
+
+For first rollout, keep `AQUIFER_MEMORY_SERVING_MODE=legacy`. Switch to `curated` only when you want `session_recall` and `session_bootstrap` to serve active curated memory; `evidence_recall` remains the explicit evidence/debug tool in both modes. Rollback is just setting env or config back to `legacy`.
+
+## Most common commands
+
+| Goal | Command |
+|---|---|
+| Verify setup | `npx aquifer quickstart` |
+| Start MCP server | `npx aquifer mcp` |
+| Search memory | `npx aquifer recall "auth middleware"` |
+| Plan curated 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` |
+| Show stats | `npx aquifer stats` |
+| Enrich pending sessions | `npx aquifer backfill` |
+
+Timer synthesis is an operator-reviewed candidate workflow. The prompt output
+and summary JSON do not become active curated memory unless the apply step is
+run with `--promote-candidates`.
+
+The default public serving mode is `legacy`. To test scoped curated memory serving, set `AQUIFER_MEMORY_SERVING_MODE=curated` plus `AQUIFER_MEMORY_ACTIVE_SCOPE_KEY` or `AQUIFER_MEMORY_ACTIVE_SCOPE_PATH`. Rollback is config-only: set the serving mode back to `legacy` and restart the MCP/CLI process.
+
+## If something fails
+
+If `quickstart` cannot connect to PostgreSQL, make sure the database is running and `DATABASE_URL` is correct.
+
+If you see `type "vector" does not exist`, `pgvector` is not installed.
+
+If recall returns no results, the embedding endpoint is usually unreachable or misconfigured.
+
+If you want the full setup matrix, host-specific examples, and advanced configuration for summarization, entities, reranking, or operations, continue to [docs/setup.md](setup.md).

package/docs/postprocess-contract.md

@@ -21,7 +21,7 @@ postProcess?: (ctx: PostProcessContext) => Promise<void>
 ```ts
 interface PostProcessContext {
   session: {
-    id: number;              // DB primary key (miranda.sessions.id)
+    id: number;              // DB primary key (<schema>.sessions.id)
     sessionId: string;       // caller-provided session key
     agentId: string;
     model: string | null;
@@ -123,7 +123,7 @@ if (result.postProcessError) {
 
 - Don't throw as a signal of "enrich should have failed" — enrich is already committed. Use warnings or a separate audit table.
 - Don't mutate `ctx.normalized`, `ctx.parsedEntities`, or `ctx.warnings`. They're shared-reference with the enrich return; defensive copy if you need to modify.
-- Don't rely on postProcess running quickly — it's outside the tx. Long-running work should be fire-and-forget (see Miranda's `setImmediate` consolidation) or queued.
+- Don't rely on postProcess running quickly — it's outside the tx. Long-running work should be fire-and-forget or queued by the consumer.
 
 ## What Aquifer guarantees
 

package/docs/setup.md

@@ -49,12 +49,34 @@ Aquifer reads configuration from three sources (in priority order):
 2. Environment variables (see below)
 3. Programmatic overrides via `createAquifer()`
 
+Default public serving mode is `legacy`. Opt into `curated` only when you want `session_recall` and `session_bootstrap` to read active curated memory. `evidence_recall` remains the explicit audit/debug lane in both modes, and rollback is just setting env or config back to `legacy`.
+
+### Example config file
+
+```json
+{
+  "db": {
+    "url": "postgresql://aquifer:aquifer@localhost:5432/aquifer"
+  },
+  "memory": {
+    "servingMode": "legacy",
+    "activeScopeKey": "project:aquifer",
+    "activeScopePath": ["global", "project:aquifer"]
+  },
+  "embed": {
+    "baseUrl": "http://localhost:11434/v1",
+    "model": "bge-m3"
+  }
+}
+```
+
 ### Minimum env vars for MCP recall
 
 ```bash
 export DATABASE_URL="postgresql://aquifer:aquifer@localhost:5432/aquifer"
 export AQUIFER_EMBED_BASE_URL="http://localhost:11434/v1"
 export AQUIFER_EMBED_MODEL="bge-m3"
+export AQUIFER_MEMORY_SERVING_MODE="legacy"
 ```
 
 ### Optional but common
@@ -69,6 +91,12 @@ export AQUIFER_LLM_MODEL="llama3.1"
 
 # Knowledge graph
 export AQUIFER_ENTITIES_ENABLED="true"
+
+# Optional curated serving rollout. Default remains legacy.
+export AQUIFER_MEMORY_SERVING_MODE="legacy"
+# export AQUIFER_MEMORY_SERVING_MODE="curated"
+# export AQUIFER_MEMORY_ACTIVE_SCOPE_KEY="project:aquifer"
+# export AQUIFER_MEMORY_ACTIVE_SCOPE_PATH="global,project:aquifer"
 ```
 
 Copy `.env.example` from the repo root for a full annotated list.
@@ -153,7 +181,9 @@ Add to `.claude.json` (project-level) or user-level MCP config:
 }
 ```
 
-Tools appear as `mcp__aquifer__session_recall`, `mcp__aquifer__session_feedback`, `mcp__aquifer__memory_stats`, `mcp__aquifer__memory_pending`.
+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`.
+
+`evidence_recall` is an explicit audit/debug tool. Use `session_recall` for normal memory lookup; broad evidence searches require an audit boundary filter such as `agentId`, `source`, or `dateFrom/dateTo`, unless the caller explicitly opts into unsafe debug mode.
 
 ### OpenClaw
 
@@ -177,10 +207,70 @@ Add to `openclaw.json`:
 }
 ```
 
-Tools materialize as `aquifer__session_recall`, `aquifer__session_feedback`, `aquifer__memory_stats`, `aquifer__memory_pending`.
+Tools materialize as `aquifer__session_recall`, `aquifer__evidence_recall`, `aquifer__session_bootstrap`, `aquifer__session_feedback`, `aquifer__memory_feedback`, `aquifer__feedback_stats`, `aquifer__memory_stats`, `aquifer__memory_pending`.
 
 Do **not** use the OpenClaw plugin (`consumers/openclaw-plugin.js`) for tool delivery. The plugin is retained for session capture via `before_reset` only.
 
+Curated serving rollback is config-only: set `AQUIFER_MEMORY_SERVING_MODE=legacy` and restart the MCP/CLI process. No destructive database rollback is required.
+
+## Operator compaction and timer synthesis
+
+Compaction jobs are operator-safe by default. A dry-run plans lifecycle updates
+and candidate output without writing active memory:
+
+```bash
+npx aquifer operator compaction daily --include-synthesis-prompt --json
+```
+
+If an operator or external model reviews that prompt and returns timer synthesis
+JSON, attach it back to the plan with:
+
+```bash
+npx aquifer operator compaction daily \
+  --synthesis-summary-file /tmp/timer-summary.json \
+  --apply \
+  --promote-candidates \
+  --json
+```
+
+The summary file must match the normal structured summary shape, for example:
+
+```json
+{
+  "summaryText": "Reviewed timer synthesis.",
+  "structuredSummary": {
+    "states": [
+      { "state": "The reviewed state that should continue into current memory." }
+    ],
+    "decisions": [],
+    "open_loops": []
+  }
+}
+```
+
+Without `--promote-candidates`, synthesis output is recorded as candidate
+ledger material only. The prompt and summary file are producer material; active
+curated memory still requires the explicit promotion gate.
+
+## Release verification gates
+
+For the publish-surface checks:
+
+```bash
+node --test test/package-surface.test.js test/mcp-manifest.test.js
+npm pack --dry-run --json
+```
+
+For the real DB-backed release gate:
+
+```bash
+AQUIFER_TEST_DB_URL="postgresql://..." npm run test:release:db
+```
+
+That DB-backed test is the release proof that the stdio MCP server, CLI
+consumer, Codex finalization serving path, current MCP manifest, and PostgreSQL
+path still line up on a live database.
+
 ## Troubleshooting
 
 **`error: type "vector" does not exist`** — pgvector is not installed. Use the `pgvector/pgvector` Docker image, or install the extension manually: `CREATE EXTENSION IF NOT EXISTS vector;` (requires superuser).