@shadowforge0/aquifer-memory 1.5.9 → 1.6.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
 // ---------------------------------------------------------------------------
@@ -666,6 +1044,76 @@ async function recordFeedback(pool, {
   }
 }
 
+// ---------------------------------------------------------------------------
+// getFeedbackStats — aggregate feedback and trust score metrics
+// ---------------------------------------------------------------------------
+
+async function getFeedbackStats(pool, { schema, tenantId, agentId, dateFrom, dateTo }) {
+  const params = [tenantId];
+  let sessionClause = '';
+  if (agentId) {
+    params.push(agentId);
+    sessionClause += ` AND s.agent_id = $${params.length}`;
+  }
+  if (dateFrom) {
+    params.push(dateFrom);
+    sessionClause += ` AND s.started_at >= $${params.length}::date`;
+  }
+  if (dateTo) {
+    params.push(dateTo);
+    sessionClause += ` AND s.started_at < ($${params.length}::date + interval '1 day')`;
+  }
+
+  const fbQuery = `
+    WITH scoped_sessions AS (
+      SELECT s.id
+      FROM ${qi(schema)}.sessions s
+      WHERE s.tenant_id = $1${sessionClause}
+    )
+    SELECT
+      COUNT(sf.*)::int AS total,
+      COUNT(*) FILTER (WHERE sf.verdict = 'helpful')::int AS helpful,
+      COUNT(*) FILTER (WHERE sf.verdict = 'unhelpful')::int AS unhelpful,
+      COUNT(DISTINCT sf.session_row_id)::int AS rated_sessions
+    FROM scoped_sessions ss
+    LEFT JOIN ${qi(schema)}.session_feedback sf
+      ON sf.session_row_id = ss.id`;
+
+  const ssQuery = `
+    WITH scoped_sessions AS (
+      SELECT s.id
+      FROM ${qi(schema)}.sessions s
+      WHERE s.tenant_id = $1${sessionClause}
+    )
+    SELECT
+      COUNT(scoped_sessions.id)::int AS total_sessions,
+      ROUND(AVG(summary.trust_score)::numeric, 3) AS avg_ts,
+      MIN(summary.trust_score) AS min_ts,
+      MAX(summary.trust_score) AS max_ts
+    FROM scoped_sessions
+    LEFT JOIN ${qi(schema)}.session_summaries summary
+      ON summary.session_row_id = scoped_sessions.id`;
+
+  const [fbResult, ssResult] = await Promise.all([
+    pool.query(fbQuery, params),
+    pool.query(ssQuery, params),
+  ]);
+
+  const fb = fbResult.rows[0];
+  const ss = ssResult.rows[0];
+
+  return {
+    totalFeedback: fb.total,
+    helpfulCount: fb.helpful,
+    unhelpfulCount: fb.unhelpful,
+    feedbackSessions: fb.rated_sessions,
+    totalSessions: ss.total_sessions,
+    trustScoreAvg: (ss.avg_ts !== null && ss.avg_ts !== undefined) ? parseFloat(ss.avg_ts) : 0.5,
+    trustScoreMin: (ss.min_ts !== null && ss.min_ts !== undefined) ? parseFloat(ss.min_ts) : 0.5,
+    trustScoreMax: (ss.max_ts !== null && ss.max_ts !== undefined) ? parseFloat(ss.max_ts) : 0.5,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Exports
 // ---------------------------------------------------------------------------
@@ -678,9 +1126,15 @@ module.exports = {
   getMessages,
   searchSessions,
   recordAccess,
+  upsertSessionFinalization,
+  getSessionFinalization,
+  updateSessionFinalizationStatus,
+  listSessionFinalizations,
+  upsertFinalizationCandidates,
   extractUserTurns,
   upsertTurnEmbeddings,
   searchTurnEmbeddings,
   searchSummaryEmbeddings,
   recordFeedback,
+  getFeedbackStats,
 };

package/docs/getting-started.md

@@ -0,0 +1,99 @@
+# 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` |
+| Show stats | `npx aquifer stats` |
+| Enrich pending sessions | `npx aquifer backfill` |
+
+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