@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

package/core/session-checkpoint-producer.js

@@ -2,11 +2,12 @@
 
 const crypto = require('node:crypto');
 const { sanitizeSummaryResult } = require('./memory-safety-gate');
+const { assistantShapingPromptLines } = require('./memory-type-policy');
 const { buildScopeEnvelope, getScopeByEnvelopeId } = require('./scope-attribution');
 
 const DEFAULT_POLICY_VERSION = 'session_checkpoint_producer_v1';
 const DEFAULT_COVERAGE_COORDINATE_SYSTEM = 'codex_sanitized_view_v1';
-const STRUCTURED_SUMMARY_SHAPE = '{"summaryText":"...","structuredSummary":{"facts":[],"decisions":[],"open_loops":[],"preferences":[],"constraints":[],"conclusions":[],"entity_notes":[],"states":[]},"coverage":{"coordinateSystem":"codex_sanitized_view_v1","coveredUntilMessageIndex":0,"coveredUntilChar":0}}';
+const STRUCTURED_SUMMARY_SHAPE = '{"summaryText":"...","structuredSummary":{"assistant_shaping":[],"facts":[],"decisions":[],"open_loops":[],"preferences":[],"constraints":[],"conclusions":[],"entity_notes":[],"states":[]},"coverage":{"coordinateSystem":"codex_sanitized_view_v1","coveredUntilMessageIndex":0,"coveredUntilChar":0}}';
 
 function stableJson(value) {
   if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
@@ -318,6 +319,7 @@ function buildCheckpointSynthesisPrompt(synthesisInput = {}, opts = {}) {
     'Return compact JSON with this shape:',
     STRUCTURED_SUMMARY_SHAPE,
     `Keep facts/decisions/open_loops concrete and scoped. Use at most ${maxFacts} facts.`,
+    ...assistantShapingPromptLines(),
     'Preserve the coverage object so handoff can skip only the already-covered transcript range.',
     '',
     '<checkpoint_synthesis_input>',

package/core/session-checkpoints.js

@@ -44,7 +44,7 @@ function parsePositiveInt(value, fallback = 10, max = 200) {
 function compactStructuredSummary(value = {}) {
   if (!value || typeof value !== 'object') return {};
   const out = {};
-  for (const key of ['facts', 'decisions', 'open_loops', 'openLoops', 'preferences', 'constraints', 'conclusions', 'entity_notes', 'entityNotes', 'states']) {
+  for (const key of ['assistant_shaping', 'assistant_shaping_memories', 'facts', 'decisions', 'open_loops', 'openLoops', 'preferences', 'constraints', 'conclusions', 'entity_notes', 'entityNotes', 'states']) {
     const rows = Array.isArray(value[key]) ? value[key] : [];
     if (rows.length > 0) out[key] = rows.slice(0, 8);
   }

package/core/session-finalization.js

@@ -3,9 +3,10 @@
 const crypto = require('crypto');
 const storage = require('./storage');
 const { createMemoryRecords } = require('./memory-records');
-const { createMemoryPromotion } = require('./memory-promotion');
+const { createMemoryPromotion, sanitizePromotionCandidate } = require('./memory-promotion');
 const { sanitizeSummaryResult } = require('./memory-safety-gate');
 const { buildFinalizationReview, buildSessionStartContext } = require('./finalization-review');
+const { buildFinalizationInspection } = require('./finalization-inspector');
 
 function qi(identifier) { return `"${identifier}"`; }
 
@@ -15,6 +16,13 @@ function requireField(obj, field) {
   }
 }
 
+function finalizationReadError(error) {
+  if (error && error.code === '42P01') {
+    return new Error('Finalization observability tables are not available. Run `aquifer migrate`, then retry this read-only command.');
+  }
+  return error;
+}
+
 function hasStructuredContent(value) {
   return value && typeof value === 'object' && Object.keys(value).length > 0;
 }
@@ -190,7 +198,73 @@ function createSessionFinalization({
 
   async function list(input = {}) {
     const tenantId = input.tenantId || defaultTenantId || 'default';
-    return storage.listSessionFinalizations(pool, input, { schema, tenantId });
+    try {
+      return await storage.listSessionFinalizations(pool, input, { schema, tenantId });
+    } catch (error) {
+      throw finalizationReadError(error);
+    }
+  }
+
+  async function inspect(input = {}) {
+    const tenantId = input.tenantId || defaultTenantId || 'default';
+    let row = null;
+
+    try {
+      if (input.id) {
+        row = await storage.getSessionFinalizationById(pool, {
+          tenantId,
+          id: input.id,
+        }, { schema, tenantId });
+      } else {
+        requireField(input, 'sessionId');
+        requireField(input, 'agentId');
+        requireField(input, 'source');
+        const phase = input.phase || 'curated_memory_v1';
+        if (input.transcriptHash) {
+          row = await storage.getSessionFinalization(pool, {
+            tenantId,
+            sessionId: input.sessionId,
+            agentId: input.agentId,
+            source: input.source,
+            transcriptHash: input.transcriptHash,
+            phase,
+          }, { schema, tenantId });
+        } else {
+          const rows = await storage.listSessionFinalizations(pool, {
+            tenantId,
+            sessionId: input.sessionId,
+            agentId: input.agentId,
+            source: input.source,
+            phase,
+            limit: 2,
+          }, { schema, tenantId });
+          if (rows.length > 1) {
+            const matches = rows.map(match => {
+              const hash = match.transcript_hash ? String(match.transcript_hash).slice(0, 12) : '?';
+              const updatedAt = match.updated_at || '?';
+              return `#${match.id} status=${match.status} phase=${match.phase} hash=${hash} updated=${updatedAt}`;
+            }).join('; ');
+            throw new Error(`Multiple finalizations matched. Add --transcript-hash or --id to inspect one row. Matches: ${matches}`);
+          }
+          row = rows[0] || null;
+        }
+      }
+
+      if (!row) throw new Error('Finalization not found');
+      const [candidates, lineage] = await Promise.all([
+        storage.listFinalizationCandidates(pool, {
+          tenantId,
+          finalizationId: row.id,
+        }, { schema, tenantId }),
+        storage.getFinalizationLineageSummary(pool, {
+          tenantId,
+          finalizationId: row.id,
+        }, { schema, tenantId }),
+      ]);
+      return buildFinalizationInspection(row, candidates, lineage);
+    } catch (error) {
+      throw finalizationReadError(error);
+    }
   }
 
   async function updateStatus(input = {}) {
@@ -323,7 +397,7 @@ function createSessionFinalization({
             authority: input.authority || 'verified_summary',
             evidenceRefs,
           });
-      const candidates = decorateCandidates(rawCandidates, input);
+      const candidates = decorateCandidates(rawCandidates.map(sanitizePromotionCandidate), input);
       const candidateEnvelope = buildCandidateEnvelope(input, candidates, {
         transcriptHash: base.transcriptHash,
       });
@@ -436,6 +510,7 @@ function createSessionFinalization({
     createTask,
     get,
     list,
+    inspect,
     updateStatus,
     finalizeSession,
   };

package/core/storage.js

@@ -614,6 +614,20 @@ async function getSessionFinalization(pool, input = {}, { schema, tenantId: defa
   return result.rows[0] || null;
 }
 
+async function getSessionFinalizationById(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  requireField(input, 'id');
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const result = await pool.query(
+    `SELECT *
+       FROM ${qi(schema)}.session_finalizations
+      WHERE tenant_id = $1
+        AND id = $2
+      LIMIT 1`,
+    [tenantId, input.id]
+  );
+  return result.rows[0] || null;
+}
+
 async function updateSessionFinalizationStatus(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
   const status = normalizeFinalizationStatus(input.status);
   const tenantId = input.tenantId || defaultTenantId || 'default';
@@ -660,38 +674,137 @@ async function updateSessionFinalizationStatus(pool, input = {}, { schema, tenan
 
 async function listSessionFinalizations(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
   const tenantId = input.tenantId || defaultTenantId || 'default';
+  const table = `${qi(schema)}.session_finalizations`;
   const params = [tenantId];
-  const where = [`tenant_id = $1`];
+  const where = [`${table}.tenant_id = $1`];
   if (input.host) {
     params.push(input.host);
-    where.push(`host = $${params.length}`);
+    where.push(`${table}.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[])`);
+    where.push(`${table}.status = ANY($${params.length}::text[])`);
   }
   if (input.agentId) {
     params.push(input.agentId);
-    where.push(`agent_id = $${params.length}`);
+    where.push(`${table}.agent_id = $${params.length}`);
   }
   if (input.source) {
     params.push(input.source);
-    where.push(`source = $${params.length}`);
+    where.push(`${table}.source = $${params.length}`);
+  }
+  if (input.sessionId) {
+    params.push(input.sessionId);
+    where.push(`${table}.session_id = $${params.length}`);
+  }
+  if (input.transcriptHash) {
+    params.push(input.transcriptHash);
+    where.push(`${table}.transcript_hash = $${params.length}`);
+  }
+  if (input.phase) {
+    params.push(input.phase);
+    where.push(`${table}.phase = $${params.length}`);
+  }
+  if (input.mode) {
+    params.push(normalizeFinalizationMode(input.mode));
+    where.push(`${table}.mode = $${params.length}`);
   }
   params.push(Math.max(1, Math.min(200, input.limit || 50)));
   const result = await pool.query(
-    `SELECT *
-       FROM ${qi(schema)}.session_finalizations
+    `SELECT
+        ${table}.id,
+        ${table}.tenant_id,
+        ${table}.source,
+        ${table}.host,
+        ${table}.agent_id,
+        ${table}.session_id,
+        ${table}.transcript_hash,
+        ${table}.phase,
+        ${table}.mode,
+        ${table}.status,
+        ${table}.finalizer_model,
+        ${table}.scope_kind,
+        ${table}.scope_key,
+        ${table}.context_key,
+        ${table}.topic_key,
+        ${table}.candidate_envelope_hash,
+        ${table}.candidate_envelope_version,
+        ${table}.error,
+        ${table}.claimed_at,
+        ${table}.finalized_at,
+        ${table}.created_at,
+        ${table}.updated_at,
+        (
+          SELECT COUNT(*)::int
+            FROM ${qi(schema)}.finalization_candidates fc
+           WHERE fc.tenant_id = ${table}.tenant_id
+             AND fc.finalization_id = ${table}.id
+        ) AS candidate_count
+       FROM ${table}
       WHERE ${where.join(' AND ')}
-      ORDER BY updated_at DESC, id DESC
+      ORDER BY ${table}.updated_at DESC, ${table}.id DESC
       LIMIT $${params.length}`,
     params
   );
   return result.rows;
 }
 
+async function getFinalizationLineageSummary(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  requireField(input, 'finalizationId');
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const result = await pool.query(
+    `SELECT
+       COALESCE((
+         SELECT array_agg(id ORDER BY id)
+           FROM ${qi(schema)}.memory_records
+          WHERE tenant_id = $1
+            AND created_by_finalization_id = $2
+       ), ARRAY[]::bigint[]) AS memory_record_ids,
+       COALESCE((
+         SELECT array_agg(id ORDER BY id)
+           FROM ${qi(schema)}.fact_assertions_v1
+          WHERE tenant_id = $1
+            AND created_by_finalization_id = $2
+       ), ARRAY[]::bigint[]) AS fact_assertion_ids,
+       COALESCE((
+         SELECT COUNT(*)::int
+           FROM ${qi(schema)}.evidence_refs
+          WHERE tenant_id = $1
+            AND created_by_finalization_id = $2
+       ), 0) AS evidence_ref_count,
+       COALESCE((
+         SELECT COUNT(*)::int
+           FROM ${qi(schema)}.evidence_items
+          WHERE tenant_id = $1
+            AND created_by_finalization_id = $2
+       ), 0) AS evidence_item_count`,
+    [tenantId, input.finalizationId]
+  );
+  const row = result.rows[0] || {};
+  return {
+    memoryRecordIds: row.memory_record_ids || [],
+    factAssertionIds: row.fact_assertion_ids || [],
+    evidenceRefCount: row.evidence_ref_count || 0,
+    evidenceItemCount: row.evidence_item_count || 0,
+  };
+}
+
+async function listFinalizationCandidates(pool, input = {}, { schema, tenantId: defaultTenantId } = {}) {
+  requireField(input, 'finalizationId');
+  const tenantId = input.tenantId || defaultTenantId || 'default';
+  const result = await pool.query(
+    `SELECT *
+       FROM ${qi(schema)}.finalization_candidates
+      WHERE tenant_id = $1
+        AND finalization_id = $2
+      ORDER BY candidate_index ASC, id ASC`,
+    [tenantId, input.finalizationId]
+  );
+  return result.rows;
+}
+
 function candidateText(candidate = {}) {
   if (typeof candidate === 'string') return candidate.trim();
   const payload = candidate.payload && typeof candidate.payload === 'object' ? candidate.payload : null;
@@ -1236,8 +1349,11 @@ module.exports = {
   recordAccess,
   upsertSessionFinalization,
   getSessionFinalization,
+  getSessionFinalizationById,
   updateSessionFinalizationStatus,
   listSessionFinalizations,
+  getFinalizationLineageSummary,
+  listFinalizationCandidates,
   upsertCheckpointRun,
   updateCheckpointRunStatus,
   listCheckpointRuns,

package/docs/getting-started.md

@@ -73,24 +73,57 @@ Or run the server directly:
 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`.
+For first rollout, keep `AQUIFER_MEMORY_SERVING_MODE=legacy`. Switch to `curated` only when you want compatibility `session_recall` and `session_bootstrap` to serve active curated memory. Use `memory_recall` for explicit current-memory lookup, `historical_recall` for the historical/session plane, and `evidence_recall` for the audit/debug lane. Rollback is just setting env or config back to `legacy`.
+
+## Connect OpenClaw
+
+For OpenClaw, use the host installer instead of wiring each consumer by hand:
+
+```bash
+npm install --prefix "$OPENCLAW_HOME" @shadowforge0/aquifer-memory@latest
+node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"
+```
+
+The installer links and enables the optional OpenClaw extension, updates `plugins.load.paths` / `plugins.entries["aquifer-memory"]`, and points `mcp.servers.aquifer` at the package's `consumers/mcp.js` while preserving existing MCP env values. For source checkouts, `scripts/install-openclaw.sh` first installs the current package into `$OPENCLAW_HOME/node_modules`, then runs the same packaged installer.
+
+Run with `--dry-run --json` to verify the active package version, extension path, plugin config, and MCP target without changing files.
 
 ## Most common commands
 
 | Goal | Command |
 |---|---|
 | Verify setup | `npx aquifer quickstart` |
+| Run read-only diagnostics | `npx aquifer doctor --json` |
 | Start MCP server | `npx aquifer mcp` |
+| Install/update OpenClaw wiring | `node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"` |
 | Search memory | `npx aquifer recall "auth middleware"` |
+| Explain current-memory selection | `npx aquifer explain bootstrap --active-scope-key project:aquifer --json` |
+| Inspect finalization ledger | `npx aquifer finalization list --status finalized --json` |
+| Inspect operator ledgers | `npx aquifer operator status --json` |
+| Review current-memory feedback issues | `npx aquifer review queue --scope-key project:aquifer --json` |
 | 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` |
+| Check memory readiness | `npx aquifer stats` |
+| Check saved-content preparation | `npx aquifer backlog --json` |
+| Prepare saved content | `npx aquifer backfill` |
+| Resolve a reviewed memory issue | `npx aquifer review resolve --memory-id 42 --resolution resolved --reason "verified current" --expected-latest-issue-feedback-id 9 --json` |
+
+`stats`, `backlog`, MCP `memory_stats`, and MCP `memory_pending` default to the
+same public status surface: `Aquifer status` or `Saved content status`, plus
+`Available`, `Attention`, and `Action` where relevant. Use CLI `--diagnostics`
+or MCP `diagnostics: true` when a host needs raw counters, buckets, guidance,
+or samples.
 
 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`.
+run with `--promote-candidates`. Daily/weekly/monthly aggregate proposals are
+source-rollup material for review and lineage only; normal promotion is blocked
+until a reviewed synthesis summary is attached. Reviewed synthesis items must
+also pass the temporal distillation standard: each item needs `mergeKey`,
+`scopeClass`, `durability`, `promotionTarget`, and `sourceCanonicalKeys` from
+the prompt's `sourceCurrentMemory`, and runtime state also needs `staleAfter`
+or `validTo`.
 
 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.
 
@@ -102,4 +135,17 @@ 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.
 
+For continuity or operator questions, use the read-only governance commands
+first: `doctor`, `finalization list|inspect`, `explain bootstrap|memory`, and
+`operator status|inspect`. Use `review queue|inspect` when curated memory
+feedback has marked visible current-memory rows as `incorrect`, `stale`,
+`scope_mismatch`, or similar issue types. These commands diagnose the DB and
+serving state without changing memory truth, finalization status, MCP tools, or
+operator leases. The review surface does not print raw transcripts, feedback
+notes, feedback metadata, or memory payloads; `review queue|inspect` still uses
+the normal Aquifer migration gate because it depends on the resolution ledger
+schema. After human review, `review resolve` appends a resolution ledger row
+only; it does not edit current memory truth, and newer issue feedback makes the
+item show up in the queue again.
+
 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/setup.md

@@ -49,7 +49,7 @@ 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`.
+Default public serving mode is `legacy`. Opt into `curated` only when you want compatibility `session_recall` and `session_bootstrap` to read active curated memory. Use `memory_recall` for explicit current-memory lookup, `historical_recall` for the historical/session plane, and `evidence_recall` for the audit/debug lane. Rollback is just setting env or config back to `legacy`.
 
 Backend profiles are explicit. `postgres` is the full backend and remains required for semantic recall, migrations, curated memory, and operator workflows. `local` is a zero-config starter profile with JSON-file persistence, raw session writes, lexical recall, bootstrap, stats, and export. It is intentionally degraded and does not create embeddings or run operator workflows:
 
@@ -76,7 +76,8 @@ AQUIFER_BACKEND=local npx aquifer backend-info --json
   "memory": {
     "servingMode": "legacy",
     "activeScopeKey": "project:aquifer",
-    "activeScopePath": ["global", "project:aquifer"]
+    "activeScopePath": ["global", "project:aquifer"],
+    "allowedScopeKeys": ["global", "project:aquifer"]
   },
   "embed": {
     "baseUrl": "http://localhost:11434/v1",
@@ -113,6 +114,7 @@ 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"
+# export AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS="global,project:aquifer"
 
 # Optional Codex active-session checkpoint heartbeat policy.
 # Command flags still take precedence over these env vars.
@@ -123,6 +125,34 @@ export AQUIFER_MEMORY_SERVING_MODE="legacy"
 
 Copy `.env.example` from the repo root for a full annotated list.
 
+### Curated scope contract
+
+Current-memory serving uses two separate scope concepts. `activeScopePath` is
+the ordered inheritance path used by bootstrap, recall, and explain. Broader
+entries can feed defaults into narrower scopes only when they appear in that
+path. `allowedScopeKeys` is the caller boundary. If a runtime request asks for
+an `activeScopeKey`, `activeScopePath`, `scopeKey`, or resolved `scopeId`
+outside `allowedScopeKeys`, Aquifer rejects the request before reading current
+memory rows. When `activeScopePath` is omitted, it defaults to `global` plus the
+configured `activeScopeKey`, or to `global` alone when no active scope is
+configured. When `allowedScopeKeys` is omitted, it defaults to that active scope
+path.
+
+Serving inheritance is deterministic:
+
+- `defaultable`: broader rows are defaults, narrower rows with the same
+  `canonicalKey` win.
+- `exclusive`: currently an explicit narrowest-wins alias for serving. It keeps
+  the producer label visible in explain output but does not add a separate
+  runtime behavior.
+- `additive`: all applicable rows are merged after scope filtering.
+- `non_inheritable`: only the exact active scope can serve the row.
+
+`aquifer explain bootstrap|memory --json` returns selected/excluded reasons
+and a `scopeInheritance` block for each row. Non-selected rows retain safe
+identity and reason fields but redact `canonicalKey`, `title`, and `summary`,
+so explain remains diagnostic instead of becoming a cross-scope content probe.
+
 ## Step 4: Verify everything works
 
 ```bash
@@ -141,6 +171,25 @@ npx aquifer mcp
 
 The server starts on stdio and waits for MCP client connections. There is no visible output on success — the server is ready when the process stays running without error.
 
+### OpenClaw host install/update
+
+OpenClaw should be updated through one host-level installer, not by editing each Aquifer consumer path separately:
+
+```bash
+npm install --prefix "$OPENCLAW_HOME" @shadowforge0/aquifer-memory@latest
+node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"
+```
+
+The command links `$OPENCLAW_HOME/extensions/aquifer-memory` to the package's OpenClaw extension, enables `plugins.entries["aquifer-memory"]`, adds the extension to `plugins.load.paths`, and updates `openclaw.json` so `mcp.servers.aquifer` runs the same package's `consumers/mcp.js`. Existing `mcp.servers.aquifer.env` values are preserved, and `openclaw.json` is backed up before writing.
+
+For a source checkout, run the repo wrapper:
+
+```bash
+bash scripts/install-openclaw.sh "$OPENCLAW_HOME"
+```
+
+That wrapper installs the current package into `$OPENCLAW_HOME/node_modules` before delegating to the packaged installer. Use `--dry-run --json` to inspect the package version, extension link, plugin config, and MCP target without changing files. `--link-current-package` is a development-only escape hatch for wiring a source checkout directly.
+
 ### Verify with the library API (optional)
 
 If you want to test the library directly instead of the CLI:
@@ -203,33 +252,25 @@ Add to `.claude.json` (project-level) 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`.
+Tools appear as `mcp__aquifer__memory_recall`, `mcp__aquifer__historical_recall`, `mcp__aquifer__session_recall`, `mcp__aquifer__evidence_recall`, `mcp__aquifer__session_feedback`, `mcp__aquifer__memory_feedback`, `mcp__aquifer__memory_stats`, `mcp__aquifer__memory_pending`, `mcp__aquifer__feedback_stats`, `mcp__aquifer__session_bootstrap`.
 
-`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.
+Use `memory_recall` for explicit current-memory lookup, `historical_recall` for older session detail, and compatibility `session_recall` when the host should follow the configured serving mode. `evidence_recall` is the explicit audit/debug tool; 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
 
-Add to `openclaw.json`:
+Install or update Aquifer inside the OpenClaw host root, then let the installer
+wire both the MCP server and the optional extension from the same package root:
 
-```json
-{
-  "mcp": {
-    "servers": {
-      "aquifer": {
-        "command": "node",
-        "args": ["/absolute/path/to/aquifer/consumers/mcp.js"],
-        "env": {
-          "DATABASE_URL": "postgresql://...",
-          "AQUIFER_EMBED_BASE_URL": "http://localhost:11434/v1",
-          "AQUIFER_EMBED_MODEL": "bge-m3"
-        }
-      }
-    }
-  }
-}
+```bash
+npm install --prefix "$OPENCLAW_HOME" @shadowforge0/aquifer-memory@latest
+node "$OPENCLAW_HOME/node_modules/@shadowforge0/aquifer-memory/consumers/cli.js" install-openclaw --openclaw-home "$OPENCLAW_HOME"
 ```
 
-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`.
+The installer preserves existing `mcp.servers.aquifer.env` values and backs up
+`openclaw.json` before writing. Use `--dry-run --json` to inspect package
+version, MCP target, and extension link without changing files.
+
+Tools materialize as `aquifer__memory_recall`, `aquifer__historical_recall`, `aquifer__session_recall`, `aquifer__evidence_recall`, `aquifer__session_feedback`, `aquifer__memory_feedback`, `aquifer__memory_stats`, `aquifer__memory_pending`, `aquifer__feedback_stats`, `aquifer__session_bootstrap`.
 
 Do **not** use the OpenClaw plugin (`consumers/openclaw-plugin.js`) for tool delivery. The plugin is retained for session capture via `before_reset` only.
 
@@ -262,7 +303,14 @@ The summary file must match the normal structured summary shape, for example:
   "summaryText": "Reviewed timer synthesis.",
   "structuredSummary": {
     "states": [
-      { "state": "The reviewed state that should continue into current memory." }
+      {
+        "state": "The reviewed state that should continue into current memory.",
+        "mergeKey": "product-state:example",
+        "scopeClass": "product_memory",
+        "durability": "durable",
+        "promotionTarget": "project_current_memory",
+        "sourceCanonicalKeys": ["memory:canonical:key-from-prompt"]
+      }
     ],
     "decisions": [],
     "open_loops": []
@@ -270,9 +318,100 @@ The summary file must match the normal structured summary shape, for example:
 }
 ```
 
+Assistant behavior memory uses the same reviewed synthesis path, but the
+serving text must be behavior-level rather than project-specific wording:
+
+```json
+{
+  "summaryText": "Reviewed assistant behavior synthesis.",
+  "structuredSummary": {
+    "assistant_shaping": [
+      {
+        "guidance": "The user dislikes paying time and token cost for rediscovery. On continuation work, start from known state before broad exploration.",
+        "shapingKind": "tool_routing",
+        "servingImpact": "changes_tool_routing",
+        "userRelevance": "This reduces repeated context work and keeps collaboration moving.",
+        "temporalSupport": { "observationCount": 3 },
+        "abstraction": {
+          "languageLevel": "user_behavior",
+          "appliesBeyondSource": true,
+          "sourceBound": false,
+          "principle": "The user values avoiding repeated context work."
+        },
+        "mergeKey": "mk_hates_repeating_context_work",
+        "scopeClass": "assistant_behavior",
+        "durability": "durable",
+        "promotionTarget": "assistant_behavior_memory",
+        "sourceCanonicalKeys": ["memory:canonical:key-from-prompt"]
+      }
+    ]
+  }
+}
+```
+
 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.
+curated memory still requires the explicit promotion gate. The deterministic
+aggregate proposals from a daily/weekly/monthly dry-run are source-rollup
+review material, not active temporal memory; the normal product path blocks
+their promotion unless a reviewed synthesis summary is attached.
+
+Reviewed synthesis items must pass the temporal distillation standard before
+they become promotable candidates. Each item needs `mergeKey`, `scopeClass`,
+`durability`, `promotionTarget`, and `sourceCanonicalKeys` that point to
+canonical keys from the prompt's `sourceCurrentMemory`; runtime state also needs
+`staleAfter` or `validTo`. Workspace/operator policy, transient material,
+runtime state without expiry, duplicate merge keys, invalid or missing source
+lineage, and unsupported promotion targets are rejected before promotion.
+`assistant_behavior_memory` additionally requires generalized user-behavior
+abstraction metadata and normalizes serving text to the abstraction principle.
+Candidate payloads keep only compact lineage references; per-candidate source
+lineage stays on the candidate trace and in the compaction ledger for audit.
+
+Consumers that should inherit user-level assistant behavior together with a
+project scope should include the user scope in the active path, for example
+`AQUIFER_MEMORY_ACTIVE_SCOPE_PATH=global,user:user,project:aquifer` and matching
+`AQUIFER_MEMORY_ALLOWED_SCOPE_KEYS`. Applicable `assistant_shaping` records are
+pinned ahead of ordinary project current memory during bootstrap.
+
+## Read-only governance diagnostics
+
+Use the governance commands before running write paths when continuity or
+operator state looks wrong:
+
+```bash
+npx aquifer doctor --json
+npx aquifer finalization list --status failed --json
+npx aquifer finalization inspect --id 42 --json
+npx aquifer explain bootstrap --active-scope-key project:aquifer --json
+npx aquifer explain memory --query "serving contract" --active-scope-key project:aquifer --json
+npx aquifer review queue --scope-key project:aquifer --json
+npx aquifer review inspect --memory-id 42 --json
+npx aquifer review resolve --memory-id 42 --resolution resolved --reason "verified current" --expected-latest-issue-feedback-id 9 --json
+npx aquifer operator status --json
+npx aquifer operator inspect --run-id 42 --kind compaction --json
+```
+
+`doctor` reports package/runtime, backend, DB/schema/tenant readiness,
+migration readiness, serving mode, MCP tool count, session/finalization
+backlog, and stale operator claims. Host checks are scoped: OpenClaw wiring is
+checked only with `--host openclaw` or `--openclaw-home`, and Codex checkpoint
+hook state is checked only with `--host codex`.
+
+The finalization, explain, review queue/inspect, and operator inspect commands
+read committed ledger and current-memory projection material only. `review
+queue|inspect` derives its worklist from curated memory feedback events on
+active visible memory records and uses the normal Aquifer migration gate because
+it depends on the resolution ledger schema. It summarizes feedback counts and
+safe identity fields; it does not print raw transcripts, feedback notes,
+feedback metadata, evidence text, or memory payloads. `review resolve` is
+append-only: it records a resolution snapshot through the latest issue feedback
+id, leaves `memory_records` and feedback history untouched, and lets newer
+issue feedback reopen the item. These commands do not promote memory, mutate
+finalization status, reclaim leases, or change the ten-tool MCP surface.
+Explain output is also redacted for non-selected rows: it reports safe identity,
+selection reason, and scope inheritance details, but not hidden, shadowed,
+out-of-scope, inactive, or trimmed row content.
 
 ## Release verification gates