hippo-memory 1.13.5 → 1.15.0

package/dist/cli.js

@@ -31,7 +31,7 @@ import * as os from 'os';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, execSync, spawn } from 'child_process';
 import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths, detectInstalledTools, defaultSleepLogPath, ensureCodexWrapperInstalled, installCodexWrapper, uninstallCodexWrapper, resolveCodexSessionTranscript, resolveCodexWrapperPaths, installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPath, } from './hooks.js';
-import { createMemory, calculateStrength, calculateRewardFactor, deriveHalfLife, resolveConfidence, computeSchemaFit, Layer, DECISION_HALF_LIFE_DAYS, } from './memory.js';
+import { createMemory, calculateStrength, calculateRewardFactor, deriveHalfLife, resolveConfidence, computeSchemaFit, Layer, } from './memory.js';
 import { getHippoRoot, isInitialized, initStore, writeEntry, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, RECALL_DEFAULT_DENY_SCOPES, } from './store.js';
 import { markRetrieved, hybridSearch, physicsSearch, explainMatch, textOverlap } from './search.js';
 import { renderTraceContent, parseSteps } from './trace.js';
@@ -58,8 +58,10 @@ import { buildCorrectionLatency } from './correction-latency.js';
 import * as api from './api.js';
 import * as predictionsModule from './predictions.js';
 import { computePlanningFallacyOutput } from './predictions.js';
+import * as decisionsModule from './decisions.js';
 import { createHash } from 'node:crypto';
 import { detectAnchoring, hashQueryText, buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, } from './recall-history.js';
+import { detectAvailabilityBias } from './availability.js';
 // v0.33 / J1 — Module-level per-(tenant, session) recall-history ring map.
 // Each CLI process maintains its OWN Map; no IPC / no cross-process sharing
 // (plan v3 decision: per-pipeline rings, see docs/plans/2026-05-26-j1-anchoring-detector.md).
@@ -1106,6 +1108,27 @@ async function cmdRecall(hippoRoot, query, flags) {
             memory_id: cmdAnchoringHint.memoryId,
         });
     }
+    // v1.13.x / J2 — CLI per-pipeline availability/recency-bias detector. Each
+    // pipeline computes its own hint (this one against the CLI's returned top-K
+    // and the full local+global candidate pool). Soft warning only. Gated by
+    // HIPPO_AVAILABILITY=off, which short-circuits BEFORE the detect call so
+    // disabled tenants pay zero work. Audit emission is pipeline-local, lockstep
+    // with the anchoring emitCliAudit calls above. cmdAvailabilityHint is null on
+    // the zero-result branch (topK < minReturned), so the splat is a no-op there.
+    let cmdAvailabilityHint = null;
+    if (process.env.HIPPO_AVAILABILITY !== 'off') {
+        cmdAvailabilityHint = detectAvailabilityBias({
+            topK: results.map((r) => ({ id: r.entry.id, created: r.entry.created })),
+            pool: [...localEntries, ...globalEntries].map((e) => ({ id: e.id, created: e.created })),
+        });
+        if (cmdAvailabilityHint) {
+            emitCliAudit(hippoRoot, 'recall_availability_detected', undefined, {
+                recent_fraction: cmdAvailabilityHint.recentFraction,
+                older_passed_over: cmdAvailabilityHint.olderCandidatesPassedOver,
+                returned_count: cmdAvailabilityHint.returnedCount,
+            });
+        }
+    }
     // v0.32 / J3.2 — auto-injection of reference-class baserate when the
     // CLI query carries a forward-prediction phrase AND a class matches.
     // cmdRecall runs its own pipeline (doesn't go through api.recall for
@@ -1213,6 +1236,7 @@ async function cmdRecall(hippoRoot, query, flags) {
                 ...(cmdPlanningFallacyHint ? { planningFallacyHint: cmdPlanningFallacyHint } : {}),
                 ...(cmdPlanningFallacyWatching ? { planningFallacyWatching: cmdPlanningFallacyWatching } : {}),
                 ...(cmdAnchoringHint ? { anchoringHint: cmdAnchoringHint } : {}),
+                ...(cmdAvailabilityHint ? { availabilityHint: cmdAvailabilityHint } : {}),
             };
             if (includeContinuity) {
                 out.continuity = {
@@ -1230,6 +1254,13 @@ async function cmdRecall(hippoRoot, query, flags) {
         if (cmdAnchoringHint) {
             console.log(`[anchored_on: ${cmdAnchoringHint.memoryId}] ${cmdAnchoringHint.summary}`);
         }
+        // v1.13.x / J2 — render availability/recency-bias hint below anchoring and
+        // above the planning-fallacy hint. Soft warning; absent (env disabled or no
+        // bias detected) is silent. Null on this zero-result branch anyway since
+        // topK < minReturned, so this is effectively a no-op here; wired for parity.
+        if (cmdAvailabilityHint) {
+            console.log(`Availability bias (${cmdAvailabilityHint.recentCount}/${cmdAvailabilityHint.returnedCount} recent): ${cmdAvailabilityHint.summary}`);
+        }
         // v0.32 / J3.2 — render hint BEFORE the no-memories message so the
         // calling agent sees its track record even when the query missed
         // every memory. Same single-line shape + JSON.stringify-safe phrase
@@ -1314,6 +1345,7 @@ async function cmdRecall(hippoRoot, query, flags) {
             ...(cmdPlanningFallacyHint ? { planningFallacyHint: cmdPlanningFallacyHint } : {}),
             ...(cmdPlanningFallacyWatching ? { planningFallacyWatching: cmdPlanningFallacyWatching } : {}),
             ...(cmdAnchoringHint ? { anchoringHint: cmdAnchoringHint } : {}),
+            ...(cmdAvailabilityHint ? { availabilityHint: cmdAvailabilityHint } : {}),
         };
         if (includeContinuity) {
             jsonOut.continuity = {
@@ -1343,6 +1375,13 @@ async function cmdRecall(hippoRoot, query, flags) {
         console.log(`[anchored_on: ${cmdAnchoringHint.memoryId}] ${cmdAnchoringHint.summary}`);
         console.log();
     }
+    // v1.13.x / J2 — render availability/recency-bias hint below anchoring and
+    // above the planning-fallacy hint. Soft warning; absent (env disabled or no
+    // bias detected) is silent.
+    if (cmdAvailabilityHint) {
+        console.log(`Availability bias (${cmdAvailabilityHint.recentCount}/${cmdAvailabilityHint.returnedCount} recent): ${cmdAvailabilityHint.summary}`);
+        console.log();
+    }
     // v0.32 / J3.2 — render planning-fallacy hint ABOVE the result list so
     // the agent sees its track record before scrolling. Hint absent (env
     // disabled or no forward-claim match) is silent. detectedPhrase is
@@ -3264,6 +3303,166 @@ function cmdPredict(hippoRoot, args, flags) {
     if (created.memoryId)
         console.log(`  memory: ${created.memoryId}`);
 }
+function cmdDecide(hippoRoot, args, flags) {
+    requireInit(hippoRoot);
+    const tenantId = resolveTenantId({});
+    const subcommand = args[0] ?? '';
+    if (subcommand === 'list') {
+        const statusRaw = flags['status'];
+        const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
+        const limitRaw = flags['limit'];
+        const limit = limitRaw !== undefined ? parseInt(String(limitRaw), 10) : 100;
+        if (!Number.isFinite(limit) || limit <= 0) {
+            console.error(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
+            process.exit(1);
+        }
+        let results;
+        if (status === 'all') {
+            results = decisionsModule.loadDecisions(hippoRoot, tenantId, { limit });
+        }
+        else {
+            if (!decisionsModule.VALID_DECISION_STATES.has(status)) {
+                console.error(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
+                process.exit(1);
+            }
+            results = decisionsModule.loadDecisions(hippoRoot, tenantId, {
+                status: status,
+                limit,
+            });
+        }
+        if (results.length === 0) {
+            console.log('No decisions.');
+            return;
+        }
+        console.log(`Found ${results.length} decisions:\n`);
+        for (const d of results) {
+            const supPart = d.supersededBy !== null ? ` superseded_by=#${d.supersededBy}` : '';
+            console.log(`#${d.id} [${d.status}]${supPart} memory=${d.memoryId ?? '-'}`);
+            console.log(`    ${d.decisionText}`);
+            if (d.context)
+                console.log(`    context: ${d.context}`);
+        }
+        return;
+    }
+    if (subcommand === 'get') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo decide get <id>');
+            process.exit(1);
+        }
+        const id = parseInt(String(idRaw), 10);
+        if (!Number.isFinite(id) || id <= 0) {
+            console.error(`Invalid decision id: "${idRaw}"`);
+            process.exit(1);
+        }
+        const decision = decisionsModule.loadDecisionById(hippoRoot, tenantId, id);
+        if (!decision) {
+            console.error(`Decision ${id} not found.`);
+            process.exit(1);
+        }
+        console.log(`Decision #${decision.id}`);
+        console.log(`  status: ${decision.status}`);
+        console.log(`  text: ${decision.decisionText}`);
+        if (decision.context)
+            console.log(`  context: ${decision.context}`);
+        if (decision.supersededBy !== null)
+            console.log(`  superseded_by: #${decision.supersededBy}`);
+        if (decision.supersededAt)
+            console.log(`  superseded_at: ${decision.supersededAt}`);
+        if (decision.closedAt)
+            console.log(`  closed_at: ${decision.closedAt}`);
+        if (decision.memoryId)
+            console.log(`  memory: ${decision.memoryId}`);
+        console.log(`  created: ${decision.createdAt}`);
+        return;
+    }
+    if (subcommand === 'close') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo decide close <id>');
+            process.exit(1);
+        }
+        const id = parseInt(String(idRaw), 10);
+        if (!Number.isFinite(id) || id <= 0) {
+            console.error(`Invalid decision id: "${idRaw}"`);
+            process.exit(1);
+        }
+        const closed = decisionsModule.closeDecision(hippoRoot, tenantId, id);
+        console.log(`Decision #${closed.id} closed.`);
+        return;
+    }
+    // Default subcommand: create. args[0] is the decision text.
+    const decisionText = subcommand;
+    if (!decisionText) {
+        console.error('Usage: hippo decide "<decision>" [--context "<why>"] [--supersedes <memory-id>]');
+        console.error('       hippo decide list [--status active|superseded|closed|all] [--limit N]');
+        console.error('       hippo decide get <id>');
+        console.error('       hippo decide close <id>');
+        process.exit(1);
+    }
+    const contextRaw = flags['context'];
+    const context = typeof contextRaw === 'string' && contextRaw ? contextRaw : undefined;
+    // A value-less `--supersedes` (parseArgs stores boolean true) is a malformed
+    // request: the user asked to supersede but gave no memory id. Reject it rather
+    // than silently creating a non-superseding decision (codex review 2026-05-28).
+    if (flags['supersedes'] === true) {
+        console.error('--supersedes requires a memory id, e.g. hippo decide "<text>" --supersedes mem_abc123.');
+        process.exit(1);
+    }
+    const supersedesMemId = typeof flags['supersedes'] === 'string' ? flags['supersedes'] : null;
+    // Backward-compat: --supersedes takes a MEMORY id. Validate it exists and
+    // resolve it to the active decision row (if any). Grill fix: commit the
+    // canonical table create+supersede FIRST (inside saveDecision's SAVEPOINT),
+    // weaken the old memory LAST (best-effort) so a memory-write failure cannot
+    // leave the memory stale without the table reflecting the supersession.
+    let supersedesDecisionId;
+    let oldEntry = null;
+    if (supersedesMemId) {
+        oldEntry = readEntry(hippoRoot, supersedesMemId, tenantId) ?? null;
+        if (!oldEntry) {
+            console.error(`Memory ${supersedesMemId} not found.`);
+            process.exit(1);
+        }
+        supersedesDecisionId =
+            decisionsModule.resolveActiveDecisionIdByMemory(hippoRoot, tenantId, supersedesMemId) ?? undefined;
+    }
+    const decisionPathTags = extractPathTags(process.cwd());
+    const created = decisionsModule.saveDecision(hippoRoot, tenantId, {
+        decisionText,
+        context,
+        supersedesDecisionId,
+        extraTags: decisionPathTags,
+    });
+    // Legacy memory-weaken (best-effort, LAST): half-life halved, marked stale +
+    // 'superseded' tag. Preserves the exact pre-promotion behavior for the memory
+    // mirror; the canonical table supersession already committed above.
+    if (oldEntry) {
+        // Best-effort: saveDecision already committed the canonical mutation (new
+        // decision created + old row superseded). If this legacy memory-weaken
+        // throws, do NOT fail the command — a retry would find no active decision
+        // for the old memory and create a duplicate active successor. Warn instead
+        // (codex review 2026-05-28).
+        try {
+            oldEntry.half_life_days = Math.max(1, Math.floor(oldEntry.half_life_days / 2));
+            oldEntry.confidence = 'stale';
+            if (!oldEntry.tags.includes('superseded'))
+                oldEntry.tags.push('superseded');
+            writeEntry(hippoRoot, oldEntry);
+        }
+        catch (e) {
+            console.error(`  warning: decision recorded and superseded, but failed to weaken the prior memory ${supersedesMemId}: ${e.message}`);
+        }
+    }
+    console.log(`Decision recorded: #${created.id}`);
+    if (created.memoryId)
+        console.log(`  memory: ${created.memoryId}`);
+    if (supersedesMemId) {
+        const tail = supersedesDecisionId !== undefined
+            ? ` (decision #${supersedesDecisionId} superseded)`
+            : ' (no active decision row; memory weakened only)';
+        console.log(`  supersedes memory: ${supersedesMemId}${tail}`);
+    }
+}
 function cmdCurrent(hippoRoot, args, flags) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
@@ -3830,166 +4029,166 @@ const HOOKS = {
     'claude-code': {
         file: 'CLAUDE.md',
         description: 'Claude Code',
-        content: `
-## Project Memory (Hippo)
-
-Before starting work, load relevant context:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-
-When you learn something important:
-\`\`\`bash
-hippo remember "<lesson>"
-\`\`\`
-
-When you hit an error or discover a gotcha:
-\`\`\`bash
-hippo remember "<what went wrong and why>" --error
-\`\`\`
-
-After completing work successfully:
-\`\`\`bash
-hippo outcome --good
-\`\`\`
-
-When the user ends the session, capture a brief summary:
-\`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
-\`\`\`
+        content: `
+## Project Memory (Hippo)
+
+Before starting work, load relevant context:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+
+When you learn something important:
+\`\`\`bash
+hippo remember "<lesson>"
+\`\`\`
+
+When you hit an error or discover a gotcha:
+\`\`\`bash
+hippo remember "<what went wrong and why>" --error
+\`\`\`
+
+After completing work successfully:
+\`\`\`bash
+hippo outcome --good
+\`\`\`
+
+When the user ends the session, capture a brief summary:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
+\`\`\`
 `.trim(),
     },
     'codex': {
         file: 'AGENTS.md',
         description: 'OpenAI Codex',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every task, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-On errors or unexpected behaviour:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-On task completion:
-\`\`\`bash
-hippo outcome --good
-\`\`\`
-
-When Hippo's Codex wrapper is installed, session-end capture runs automatically.
-If the wrapper is not installed, capture a brief summary manually:
-\`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
-\`\`\`
+        content: `
+## Project Memory (Hippo)
+
+At the start of every task, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+On task completion:
+\`\`\`bash
+hippo outcome --good
+\`\`\`
+
+When Hippo's Codex wrapper is installed, session-end capture runs automatically.
+If the wrapper is not installed, capture a brief summary manually:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
+\`\`\`
 `.trim(),
     },
     'cursor': {
         file: '.cursorrules',
         description: 'Cursor',
-        content: `
-# Project Memory (Hippo)
-# Before each task, load context:
-#   hippo context --auto --budget 1500
-# After errors:
-#   hippo remember "<error description>" --error
-# After completing:
-#   hippo outcome --good
+        content: `
+# Project Memory (Hippo)
+# Before each task, load context:
+#   hippo context --auto --budget 1500
+# After errors:
+#   hippo remember "<error description>" --error
+# After completing:
+#   hippo outcome --good
 `.trim(),
     },
     'openclaw': {
         file: 'AGENTS.md',
         description: 'OpenClaw',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every session, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-On errors or unexpected behaviour:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-On task completion:
-\`\`\`bash
-hippo outcome --good
-\`\`\`
-
-When ending a session, capture a brief summary:
-\`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
-\`\`\`
+        content: `
+## Project Memory (Hippo)
+
+At the start of every session, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+On task completion:
+\`\`\`bash
+hippo outcome --good
+\`\`\`
+
+When ending a session, capture a brief summary:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
+\`\`\`
 `.trim(),
     },
     'opencode': {
         file: 'AGENTS.md',
         description: 'OpenCode',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every task, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-When you learn something important or hit an error:
-\`\`\`bash
-hippo remember "<lesson>" --error
-\`\`\`
-
-When stuck or repeating yourself, check if this happened before:
-\`\`\`bash
-hippo recall "<what's going wrong>" --budget 2000
-\`\`\`
-
-On task completion:
-\`\`\`bash
-hippo outcome --good
-\`\`\`
-
-When ending a session, capture a brief summary:
-\`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
-\`\`\`
+        content: `
+## Project Memory (Hippo)
+
+At the start of every task, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+When you learn something important or hit an error:
+\`\`\`bash
+hippo remember "<lesson>" --error
+\`\`\`
+
+When stuck or repeating yourself, check if this happened before:
+\`\`\`bash
+hippo recall "<what's going wrong>" --budget 2000
+\`\`\`
+
+On task completion:
+\`\`\`bash
+hippo outcome --good
+\`\`\`
+
+When ending a session, capture a brief summary:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
+\`\`\`
 `.trim(),
     },
     'pi': {
         file: 'AGENTS.md',
         description: 'Pi',
-        content: `
-## Project Memory (Hippo)
-
-At the start of every session, run:
-\`\`\`bash
-hippo context --auto --budget 1500
-\`\`\`
-Read the output before writing any code.
-
-On errors or unexpected behaviour:
-\`\`\`bash
-hippo remember "<description of what went wrong>" --error
-\`\`\`
-
-On task completion:
-\`\`\`bash
-hippo outcome --good
-\`\`\`
-
-When ending a session, capture a brief summary:
-\`\`\`bash
-hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
-\`\`\`
-
-For full integration, copy the hippo-memory Pi extension to \`~/.pi/agent/extensions/hippo-memory/\`.
+        content: `
+## Project Memory (Hippo)
+
+At the start of every session, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+On task completion:
+\`\`\`bash
+hippo outcome --good
+\`\`\`
+
+When ending a session, capture a brief summary:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons — 2-5 bullets>'
+\`\`\`
+
+For full integration, copy the hippo-memory Pi extension to \`~/.pi/agent/extensions/hippo-memory/\`.
 `.trim(),
     },
 };
@@ -4677,6 +4876,10 @@ const VALID_AUDIT_OPS = new Set([
     'recall_anchor_detected_query_repeat', // v0.33 / J1 — emitted by detector on R1 fire
     'recall_anchor_detected_memory_dominance', // v0.33 / J1 — emitted by detector on R2 fire
     'recall_anchor_skipped_no_session', // v0.33 / J1 — telemetry: no sessionId, ring skipped
+    'recall_availability_detected', // v1.13.x / J2 - emitted when availability/recency-bias hint fires
+    'decision_create', // E2 decision first-class object — emitted by saveDecision
+    'decision_supersede', // E2 — emitted by saveDecision when --supersedes resolves to an active decision row
+    'decision_close', // E2 — emitted by closeDecision
 ]);
 function formatAuditRow(ev) {
     const target = ev.targetId ?? '-';
@@ -4882,12 +5085,12 @@ function cmdGoalPush(hippoRoot, args, flags) {
 function listAllGoals(hippoRoot, sessionId, tenantId) {
     const db = openHippoDb(hippoRoot);
     try {
-        const rows = db.prepare(`
-      SELECT id, session_id, tenant_id, goal_name, level, parent_goal_id, status,
-             success_condition, retrieval_policy_id, created_at, completed_at, outcome_score
-      FROM goal_stack
-      WHERE tenant_id = ? AND session_id = ?
-      ORDER BY created_at ASC
+        const rows = db.prepare(`
+      SELECT id, session_id, tenant_id, goal_name, level, parent_goal_id, status,
+             success_condition, retrieval_policy_id, created_at, completed_at, outcome_score
+      FROM goal_stack
+      WHERE tenant_id = ? AND session_id = ?
+      ORDER BY created_at ASC
     `).all(tenantId, sessionId);
         return rows.map(rowToGoal);
     }
@@ -5210,349 +5413,353 @@ function cmdSlack(hippoRoot, args, flags) {
     process.exit(1);
 }
 function printUsage() {
-    console.log(`
-Hippo - biologically-inspired memory system for AI agents
-
-Usage: hippo <command> [options]
-
-Commands:
-  init                     Create .hippo/ structure in current directory
-    --scan [dir]           Find all git repos under dir (default: ~) and init each
-    --days <n>             Days of git history to seed (default: 365 for --scan, 30 for single)
-    --global               Init the global store ($HIPPO_HOME or ~/.hippo/)
-    --no-hooks             Skip auto-detecting and installing agent hooks
-    --no-schedule          Skip auto-creating the machine-level daily runner
-    --no-learn             Skip seeding memories from git history
-  remember <text>          Store a memory
-    --tag <tag>            Add a tag (repeatable)
-    --error                Tag as error (boosts retention)
-    --pin                  Pin memory (never decays)
-    --verified             Set confidence: verified (default)
-    --observed             Set confidence: observed
-    --inferred             Set confidence: inferred
-    --global               Store in global store ($HIPPO_HOME or ~/.hippo/)
-  recall <query>           Search and retrieve memories (local + global)
-    --budget <n>           Token budget (default: 4000)
-    --min-results <n>      Minimum results regardless of budget (default: 1)
-    --json                 Output as JSON
-    --why                  Show match reasons and source annotations
-    --no-mmr               Disable MMR diversity re-ranking
-    --mmr-lambda <f>       MMR balance 0..1 (default: 0.7, 1.0 = pure relevance)
-    --evc-adaptive         ACC-style: when top-K shows high inter-item overlap
-                           (= conflict cluster), expand pool and re-rank by
-                           recency. Default off. RESEARCH.md §PFC.ACC.
-    --filter-conflicts     vlPFC interference filter: drop superseded entries
-                           and 0.3x-downweight entries flagged in an open
-                           conflict with a peer in the same result set.
-                           Uses recorded supersession + conflicts only — never
-                           lexical inference. Default off. RESEARCH.md §PFC.vlPFC.
-    --value-aware          vmPFC value attribution: boost memories with positive
-                           cumulative outcomes and demote those with negative
-                           outcomes during ranking. Multiplier
-                           clip(1 + 0.3*tanh(pos - neg), 0.7, 1.3). Reuses
-                           outcome_positive / outcome_negative; no schema
-                           change. Default off. RESEARCH.md §PFC.vmPFC.
-    --rerank-utility       OFC option-value re-ranker: combine relevance,
-                           strength, and integration cost into a single utility
-                           = score * (0.5 + 0.5 * strength) * (1 - cost_factor)
-                           where cost_factor = min(0.3, tokens / 10000). Re-sorts
-                           results by utility. Default off. RESEARCH.md §PFC.OFC.
-    --reranker <name>      Apply a reranker pass after retrieval
-                           (cross-encoder|llm). Looks up the named
-                           reranker from src/rerankers/index.ts and re-orders
-                           the top-K candidates. Default unset (no reranker).
-                           See docs/plans/2026-05-10-f6-reranker-hardening.md.
-    --reranker-top-k <n>   Cap candidates passed to the reranker (default 50).
-    --goal <tag>           dlPFC goal-conditioned recall: memories tagged with
-                           the goal tag get a 1.5x score boost and results are
-                           re-sorted. Default off. RESEARCH.md §PFC.dlPFC.
-    --session-id <id>      Session identifier for dlPFC goal-stack boost.
-                           Defaults to \$HIPPO_SESSION_ID. When set and the
-                           (tenant, session) has active goals (see
-                           'hippo goal push'), recall auto-boosts memories
-                           whose tags match an active goal name. Boost stacks
-                           on top of base BM25 score, capped at 3.0x.
-    --salience-threshold <n>
-                           Pineal salience: down-weight memories whose
-                           retrieval_count is below n. score *= max(0.5,
-                           retrieval_count / n) for entries with count < n;
-                           entries at or above n are unchanged. Salience emerges
-                           from USE, not from lexical overlap. Default off.
-                           RESEARCH.md §"AI Pineal Gland". (v1's creation-time
-                           lexical gate destroyed LoCoMo 0.28 -> 0.02; this v2
-                           is retrieval-side, opt-in only — see MEMORY.md
-                           "Hippo salience gate destroys benchmark recall".)
-    --continuity           Include continuity block (active task snapshot,
-                           latest matching session handoff, last 5 session
-                           events) above the memory list. Useful at agent
-                           boot when you want both relevant memories AND
-                           where you left off in one call. Anchored on the
-                           active snapshot's session_id; no anchor = no
-                           handoff/events (use 'hippo session resume' for
-                           the explicit handoff-without-snapshot path).
-  explain <query>          Show full score breakdown for each retrieved memory
-    --budget <n>           Token budget (default: 4000)
-    --limit <n>            Cap the number of results displayed
-    --json                 Output as JSON
-    --physics | --classic  Force search mode (default: from config)
-    --no-mmr               Disable MMR diversity re-ranking
-    --mmr-lambda <f>       MMR balance 0..1 (default: 0.7, 1.0 = pure relevance)
-  trace <id>               Memory dossier: content, decay trajectory, retrievals,
-                           outcomes, consolidation parents, open conflicts
-    --json                 Output as JSON
-  refine                   Rewrite consolidated semantic memories with Claude
-    --limit <n>            Cap the number of memories processed this run
-    --all                  Ignore \`llm-refined\` tag and re-refine everything
-    --dry-run              Call the API but don't write results back
-    --model <id>           Override the default model (claude-sonnet-4-6)
-    --json                 Output summary as JSON
-    (requires ANTHROPIC_API_KEY in env)
-  eval [<corpus.json>]     Measure recall quality against a test corpus
-    --bootstrap            Generate a synthetic corpus from current memories
-    --out <path>           With --bootstrap, write to file instead of stdout
-    --max-cases <n>        With --bootstrap, cap case count (default: 50)
-    --show-cases           Print per-case details (query, R@10, missed, top 3)
-    --compare <path>       JSON from a prior \`eval --json\` run; print deltas
-    --no-mmr               Disable MMR for this eval run
-    --mmr-lambda <f>       Override MMR lambda for this run
-    --embedding-weight <f> Override cosine weight (default: 0.6)
-    --local-bump <f>       Local-over-global priority multiplier (default: 1.2)
-    --equal-sources        Shortcut for --local-bump 1.0
-    --min-mrr <f>          Exit non-zero if mean MRR falls below this
-    --json                 Output full summary as JSON
-  context                  Smart context injection for AI agents
-    --auto                 Auto-detect task from git state
-    --budget <n>           Token budget (default: 1500)
-    --pinned-only          Only inject pinned memories (used by UserPromptSubmit hook)
-    --include-recent <n>   With --pinned-only, also inject the last N writes regardless of pinning
-    --format <fmt>         Output format: markdown (default), json, or additional-context (Claude Code hook JSON)
-    --framing <mode>       Framing: observe (default), suggest, assert
-  sleep                    Run consolidation pass (auto-learns + dedup + auto-shares)
-    --dry-run              Preview without writing
-    --no-learn             Skip auto git-learn before consolidation
-    --no-share             Skip auto-sharing to global store
-  daily-runner             Sweep registered workspaces and run daily learn+sleep
-  dedup                    Remove duplicate memories (keeps stronger copy)
-    --dry-run              Preview without removing
-    --threshold <n>        Overlap threshold 0-1 (default: 0.7)
-  status                   Show memory health stats
-  audit [--fix]            Check memory quality (--fix removes junk)
-  github                   GitHub connector subcommands (backfill, dlq)
-    backfill --repo <owner/name> [--since ISO] [--max <N>]
-                           Paginated backfill of issues + comments
-    dlq list               List DLQ entries for the active tenant
-    dlq replay <id> [--force]
-                           Re-ingest a DLQ entry (--force skips sig check)
-  provenance               Provenance coverage gate for kind='raw' rows
-    --json                 Output as JSON
-    --strict               Exit non-zero when coverage < 100%
-  drill <summary-id>       Walk down a DAG level-2 summary to its children
-    --limit N              Cap children list (default 50)
-    --budget N             Cap total child token cost (≈ chars/4)
-    --json                 Output as JSON
-  assemble --session <id>  Build a session's chronological context window
-    --budget N             Token budget (default 4000)
-    --fresh-tail N         Recent rows always kept verbatim (default 10)
-    --no-summarize-older   Disable older-row summary substitution
-    --scope <s>            Restrict to exact scope (default: deny *:private:*)
-    --json                 Output as JSON
-  correction-latency       Wall-clock lag from receipt to supersession (p50/p95/max)
-    --json                 Output as JSON
-  outcome                  Apply feedback to last recall
-    --good                 Memories were helpful
-    --bad                  Memories were irrelevant
-    --id <id>              Target a specific memory
-  conflicts                List detected open memory conflicts
-    --status <status>      Filter by status (default: open)
-    --json                 Output as JSON
-  resolve <conflict_id>    Resolve a memory conflict
-    --keep <memory_id>     Memory to keep (required)
-    --forget               Delete the losing memory (default: halve half-life)
-  snapshot <sub>           Persist or inspect the current active task
-    snapshot save          Save active task state
-      --task <task>
-      --summary <summary>
-      --next-step <step>
-      --source <source>    Optional source label
-      --session <id>       Link snapshot to a session trail
-    snapshot show          Show the active task snapshot
-      --json               Output as JSON
-    snapshot clear         Clear the active task snapshot
-      --status <status>    Mark final status (default: cleared)
-  session <sub>            Append or inspect short-term session history
-    session log            Append a structured session event
-      --id <session-id>
-      --content <text>
-      --type <type>        Event type (default: note)
-      --task <task>        Optional task label
-      --source <source>    Optional source label
-    session show           Show recent events for a session or task
-      --id <session-id>
-      --task <task>
-      --limit <n>          Event limit (default: 8)
-      --json               Output as JSON
-    session latest         Show latest task snapshot + events
-      --id <session-id>   Filter by session
-      --json               Output as JSON
-    session resume         Re-inject latest handoff as context output
-      --id <session-id>   Filter by session
-  handoff <sub>            Manage session handoffs for continuity
-    handoff create         Create a new session handoff
-      --summary <text>     Handoff summary (required)
-      --next <text>        Next action for successor
-      --session <id>       Session ID (auto-generated if omitted)
-      --task <id>          Associated task ID
-      --artifact <path>    Related file path (repeatable)
-    handoff latest         Show the most recent handoff
-      --session <id>       Filter by session
-      --json               Output as JSON
-    handoff show <id>      Show a specific handoff by ID
-  current <sub>            Show compact current state for agent injection
-    current show           Active task + recent session events (default)
-      --json               Output as JSON
-  forget <id>              Force remove a memory
-    --archive              Archive a raw (append-only) memory instead of deleting
-    --reason "<why>"       Reason recorded on the archive (required with --archive)
-  inspect <id>             Show full memory detail
-  embed                    Embed all memories for semantic search
-    --status               Show embedding coverage
-  watch "<command>"        Run command, auto-learn from failures
-  learn                    Learn lessons from repository history
-    --git                  Scan recent git commits for lessons
-    --days <n>             Scan this many days back (default: 7)
-    --repos <paths>        Comma-separated repo paths to scan
-  promote <id>             Copy a local memory to the global store
-  share <id>               Share a memory with attribution + transfer scoring
-    --force                Share even if transfer score is low
-    --auto                 Auto-share all high-transfer-score memories
-    --dry-run              Preview what would be shared
-    --min-score <n>        Minimum transfer score (default: 0.6)
-  peers                    List projects contributing to global store
-  sync                     Pull global memories into local project
-  import                   Import memories from other AI tools
-    --chatgpt <path>       Import from ChatGPT memory export (JSON or txt)
-    --claude <path>        Import from CLAUDE.md or Claude memory.json
-    --cursor <path>        Import from .cursorrules or .cursor/rules
-    --file <path>          Import from any markdown or text file
-    --markdown <path>      Import from structured MEMORY.md / AGENTS.md
-    --dry-run              Preview without writing
-    --global               Write to global store ($HIPPO_HOME or ~/.hippo/)
-    --tag <tag>            Add extra tag (repeatable)
-  export [file]            Export all memories (default: stdout)
-    --format <fmt>         Output format: json (default) or markdown
-  capture                  Extract memories from conversation text
-    --stdin                Read from piped input
-    --file <path>          Read from a file
-    --last-session         Read from the most recent agent session transcript
-    --transcript <path>    Explicit transcript path (implies --last-session)
-    --log-file <path>      Tee output to a log file (paired with 'hippo last-sleep')
-    --dry-run              Preview without writing
-    --global               Write to global store ($HIPPO_HOME or ~/.hippo/)
-  setup                    One-shot: detect installed AI tools and install all
-                           available SessionEnd+SessionStart hooks
-    --all                  Install for every JSON-hook tool, even if not detected
-    --dry-run              Show what would be installed without writing
-    --no-schedule          Skip installing or repairing the daily runner
-  last-sleep               Print the last 'hippo sleep --log-file' output and clear it
-    --path <p>             Log path (default: ~/.hippo/logs/last-sleep.log)
-    --keep                 Print without clearing
-  codex-run [-- ...args]   Launch real Codex behind Hippo's session-end wrapper
-  hook <sub> [target]      Manage framework integrations
-    hook list              Show available hooks
-    hook install <target>  Install hook (claude-code|codex|cursor|openclaw|opencode|pi)
-                           claude-code/opencode install SessionEnd+SessionStart;
-                           codex wraps the detected launcher in place
-    hook uninstall <target> Remove hook
-  decide "<decision>"      Record an architectural decision (90-day half-life)
-    --context "<why>"      Why this decision was made
-    --supersedes <id>      Supersede a previous decision (weakens it)
-  invalidate "<pattern>"   Actively weaken memories matching an old pattern
-    --reason "<why>"       Optional: what replaced it
-  wm <sub>                 Working memory — bounded buffer for current state
-    wm push                Push a working memory entry
-      --scope <scope>      Scope name (default: default)
-      --content <text>     Content to store (required)
-      --importance <n>     Priority 0-1 (default: 0.5)
-      --session <id>       Session ID
-      --task <id>          Task ID
-    wm read                Read working memory entries
-      --scope <scope>      Filter by scope
-      --session <id>       Filter by session
-      --limit <n>          Max entries (default: 20)
-      --json               Output as JSON
-    wm clear               Clear working memory entries
-      --scope <scope>      Filter by scope
-      --session <id>       Filter by session
-    wm flush               Flush working memory (session end)
-      --scope <scope>      Filter by scope
-      --session <id>       Filter by session
-  dashboard                Open web dashboard for memory health
-    --port <n>             Port to serve on (default: 3333)
-  mcp                      Start MCP server (stdio transport)
-  goal <sub>               dlPFC goal stack (B3) — scoped per session
-    goal push <name>       Push a new active goal; prints the new goal id
-      --policy <type>      schema-fit-biased | error-prioritized |
-                           recency-first | hybrid
-      --success "<cond>"   Optional success condition text
-      --level <n>          Goal level (default: 0)
-      --parent <goalId>    Parent goal id (for sub-goals)
-      --session-id <s>     Override session (defaults to HIPPO_SESSION_ID)
-      --tenant-id <t>      Override tenant (defaults to HIPPO_TENANT)
-    goal list              Show active goals as a table
-      --all                Include suspended/completed goals
-    goal complete <id>     Mark a goal completed
-      --outcome <0..1>     Outcome score; >=0.7 boosts, <0.3 decays recalled mems
-      --no-propagate       Close the goal without applying strength side-effects
-    goal suspend <id>      Move an active goal to suspended
-    goal resume <id>       Move a suspended goal back to active (depth-capped)
-  auth <sub>               Manage API keys (A5 stub auth)
-    auth create            Mint a new API key (plaintext shown ONCE)
-      --label <s>          Optional human label
-      --role <r>           admin | member (default: admin; member blocked from /v1/sleep)
-      --tenant <id>        Override tenant (defaults to HIPPO_TENANT)
-      --json               Output as JSON
-      --global             Operate on the global store
-    auth list              List API keys (active by default)
-      --all                Include revoked keys
-      --json               Output as JSON
-      --global             Operate on the global store
-    auth revoke <key_id>   Revoke an API key (subsequent validate fails)
-      --json               Output as JSON
-      --global             Operate on the global store
-  audit <sub>              Query the append-only audit log (A5 stub auth)
-    audit list             List audit events for the active tenant
-      --op <op>            Filter by op (remember | recall | promote |
-                           supersede | forget | archive_raw | auth_revoke)
-      --since <iso>        Lower bound on ts (ISO timestamp)
-      --limit <n>          Max events (default: 100, max: 10000)
-      --json               Output as JSON
-      --global             Operate on the global store
-
-Examples:
-  hippo init
-  hippo remember "FRED cache can silently drop series" --tag error
-  hippo recall "data pipeline issues" --budget 2000
-  hippo context --auto --budget 1500
-  hippo conflicts
-  hippo session log --id sess_123 --task "Ship feature" --type progress --content "Build is green, next step is docs"
-  hippo session latest --json
-  hippo session resume
-  hippo snapshot save --task "Ship feature" --summary "Tests are green" --next-step "Open the PR" --session sess_123
-  hippo handoff create --summary "PR is open, tests green" --next "Merge after review" --session sess_123 --artifact src/foo.ts
-  hippo embed --status
-  hippo watch "npm run build"
-  hippo learn --git --days 30
-  hippo promote mem_abc123
-  hippo sync
-  hippo setup
-  hippo hook install claude-code
-  hippo decide "Use PostgreSQL for new services" --context "JSONB support"
-  hippo invalidate "REST API" --reason "migrated to GraphQL"
-  hippo export memories.json
-  hippo export --format markdown memories.md
-  hippo sleep --dry-run
-  hippo outcome --good
-  hippo status
+    console.log(`
+Hippo - biologically-inspired memory system for AI agents
+
+Usage: hippo <command> [options]
+
+Commands:
+  init                     Create .hippo/ structure in current directory
+    --scan [dir]           Find all git repos under dir (default: ~) and init each
+    --days <n>             Days of git history to seed (default: 365 for --scan, 30 for single)
+    --global               Init the global store ($HIPPO_HOME or ~/.hippo/)
+    --no-hooks             Skip auto-detecting and installing agent hooks
+    --no-schedule          Skip auto-creating the machine-level daily runner
+    --no-learn             Skip seeding memories from git history
+  remember <text>          Store a memory
+    --tag <tag>            Add a tag (repeatable)
+    --error                Tag as error (boosts retention)
+    --pin                  Pin memory (never decays)
+    --verified             Set confidence: verified (default)
+    --observed             Set confidence: observed
+    --inferred             Set confidence: inferred
+    --global               Store in global store ($HIPPO_HOME or ~/.hippo/)
+  recall <query>           Search and retrieve memories (local + global)
+    --budget <n>           Token budget (default: 4000)
+    --min-results <n>      Minimum results regardless of budget (default: 1)
+    --json                 Output as JSON
+    --why                  Show match reasons and source annotations
+    --no-mmr               Disable MMR diversity re-ranking
+    --mmr-lambda <f>       MMR balance 0..1 (default: 0.7, 1.0 = pure relevance)
+    --evc-adaptive         ACC-style: when top-K shows high inter-item overlap
+                           (= conflict cluster), expand pool and re-rank by
+                           recency. Default off. RESEARCH.md §PFC.ACC.
+    --filter-conflicts     vlPFC interference filter: drop superseded entries
+                           and 0.3x-downweight entries flagged in an open
+                           conflict with a peer in the same result set.
+                           Uses recorded supersession + conflicts only — never
+                           lexical inference. Default off. RESEARCH.md §PFC.vlPFC.
+    --value-aware          vmPFC value attribution: boost memories with positive
+                           cumulative outcomes and demote those with negative
+                           outcomes during ranking. Multiplier
+                           clip(1 + 0.3*tanh(pos - neg), 0.7, 1.3). Reuses
+                           outcome_positive / outcome_negative; no schema
+                           change. Default off. RESEARCH.md §PFC.vmPFC.
+    --rerank-utility       OFC option-value re-ranker: combine relevance,
+                           strength, and integration cost into a single utility
+                           = score * (0.5 + 0.5 * strength) * (1 - cost_factor)
+                           where cost_factor = min(0.3, tokens / 10000). Re-sorts
+                           results by utility. Default off. RESEARCH.md §PFC.OFC.
+    --reranker <name>      Apply a reranker pass after retrieval
+                           (cross-encoder|llm). Looks up the named
+                           reranker from src/rerankers/index.ts and re-orders
+                           the top-K candidates. Default unset (no reranker).
+                           See docs/plans/2026-05-10-f6-reranker-hardening.md.
+    --reranker-top-k <n>   Cap candidates passed to the reranker (default 50).
+    --goal <tag>           dlPFC goal-conditioned recall: memories tagged with
+                           the goal tag get a 1.5x score boost and results are
+                           re-sorted. Default off. RESEARCH.md §PFC.dlPFC.
+    --session-id <id>      Session identifier for dlPFC goal-stack boost.
+                           Defaults to \$HIPPO_SESSION_ID. When set and the
+                           (tenant, session) has active goals (see
+                           'hippo goal push'), recall auto-boosts memories
+                           whose tags match an active goal name. Boost stacks
+                           on top of base BM25 score, capped at 3.0x.
+    --salience-threshold <n>
+                           Pineal salience: down-weight memories whose
+                           retrieval_count is below n. score *= max(0.5,
+                           retrieval_count / n) for entries with count < n;
+                           entries at or above n are unchanged. Salience emerges
+                           from USE, not from lexical overlap. Default off.
+                           RESEARCH.md §"AI Pineal Gland". (v1's creation-time
+                           lexical gate destroyed LoCoMo 0.28 -> 0.02; this v2
+                           is retrieval-side, opt-in only — see MEMORY.md
+                           "Hippo salience gate destroys benchmark recall".)
+    --continuity           Include continuity block (active task snapshot,
+                           latest matching session handoff, last 5 session
+                           events) above the memory list. Useful at agent
+                           boot when you want both relevant memories AND
+                           where you left off in one call. Anchored on the
+                           active snapshot's session_id; no anchor = no
+                           handoff/events (use 'hippo session resume' for
+                           the explicit handoff-without-snapshot path).
+  explain <query>          Show full score breakdown for each retrieved memory
+    --budget <n>           Token budget (default: 4000)
+    --limit <n>            Cap the number of results displayed
+    --json                 Output as JSON
+    --physics | --classic  Force search mode (default: from config)
+    --no-mmr               Disable MMR diversity re-ranking
+    --mmr-lambda <f>       MMR balance 0..1 (default: 0.7, 1.0 = pure relevance)
+  trace <id>               Memory dossier: content, decay trajectory, retrievals,
+                           outcomes, consolidation parents, open conflicts
+    --json                 Output as JSON
+  refine                   Rewrite consolidated semantic memories with Claude
+    --limit <n>            Cap the number of memories processed this run
+    --all                  Ignore \`llm-refined\` tag and re-refine everything
+    --dry-run              Call the API but don't write results back
+    --model <id>           Override the default model (claude-sonnet-4-6)
+    --json                 Output summary as JSON
+    (requires ANTHROPIC_API_KEY in env)
+  eval [<corpus.json>]     Measure recall quality against a test corpus
+    --bootstrap            Generate a synthetic corpus from current memories
+    --out <path>           With --bootstrap, write to file instead of stdout
+    --max-cases <n>        With --bootstrap, cap case count (default: 50)
+    --show-cases           Print per-case details (query, R@10, missed, top 3)
+    --compare <path>       JSON from a prior \`eval --json\` run; print deltas
+    --no-mmr               Disable MMR for this eval run
+    --mmr-lambda <f>       Override MMR lambda for this run
+    --embedding-weight <f> Override cosine weight (default: 0.6)
+    --local-bump <f>       Local-over-global priority multiplier (default: 1.2)
+    --equal-sources        Shortcut for --local-bump 1.0
+    --min-mrr <f>          Exit non-zero if mean MRR falls below this
+    --json                 Output full summary as JSON
+  context                  Smart context injection for AI agents
+    --auto                 Auto-detect task from git state
+    --budget <n>           Token budget (default: 1500)
+    --pinned-only          Only inject pinned memories (used by UserPromptSubmit hook)
+    --include-recent <n>   With --pinned-only, also inject the last N writes regardless of pinning
+    --format <fmt>         Output format: markdown (default), json, or additional-context (Claude Code hook JSON)
+    --framing <mode>       Framing: observe (default), suggest, assert
+  sleep                    Run consolidation pass (auto-learns + dedup + auto-shares)
+    --dry-run              Preview without writing
+    --no-learn             Skip auto git-learn before consolidation
+    --no-share             Skip auto-sharing to global store
+  daily-runner             Sweep registered workspaces and run daily learn+sleep
+  dedup                    Remove duplicate memories (keeps stronger copy)
+    --dry-run              Preview without removing
+    --threshold <n>        Overlap threshold 0-1 (default: 0.7)
+  status                   Show memory health stats
+  audit [--fix]            Check memory quality (--fix removes junk)
+  github                   GitHub connector subcommands (backfill, dlq)
+    backfill --repo <owner/name> [--since ISO] [--max <N>]
+                           Paginated backfill of issues + comments
+    dlq list               List DLQ entries for the active tenant
+    dlq replay <id> [--force]
+                           Re-ingest a DLQ entry (--force skips sig check)
+  provenance               Provenance coverage gate for kind='raw' rows
+    --json                 Output as JSON
+    --strict               Exit non-zero when coverage < 100%
+  drill <summary-id>       Walk down a DAG level-2 summary to its children
+    --limit N              Cap children list (default 50)
+    --budget N             Cap total child token cost (≈ chars/4)
+    --json                 Output as JSON
+  assemble --session <id>  Build a session's chronological context window
+    --budget N             Token budget (default 4000)
+    --fresh-tail N         Recent rows always kept verbatim (default 10)
+    --no-summarize-older   Disable older-row summary substitution
+    --scope <s>            Restrict to exact scope (default: deny *:private:*)
+    --json                 Output as JSON
+  correction-latency       Wall-clock lag from receipt to supersession (p50/p95/max)
+    --json                 Output as JSON
+  outcome                  Apply feedback to last recall
+    --good                 Memories were helpful
+    --bad                  Memories were irrelevant
+    --id <id>              Target a specific memory
+  conflicts                List detected open memory conflicts
+    --status <status>      Filter by status (default: open)
+    --json                 Output as JSON
+  resolve <conflict_id>    Resolve a memory conflict
+    --keep <memory_id>     Memory to keep (required)
+    --forget               Delete the losing memory (default: halve half-life)
+  snapshot <sub>           Persist or inspect the current active task
+    snapshot save          Save active task state
+      --task <task>
+      --summary <summary>
+      --next-step <step>
+      --source <source>    Optional source label
+      --session <id>       Link snapshot to a session trail
+    snapshot show          Show the active task snapshot
+      --json               Output as JSON
+    snapshot clear         Clear the active task snapshot
+      --status <status>    Mark final status (default: cleared)
+  session <sub>            Append or inspect short-term session history
+    session log            Append a structured session event
+      --id <session-id>
+      --content <text>
+      --type <type>        Event type (default: note)
+      --task <task>        Optional task label
+      --source <source>    Optional source label
+    session show           Show recent events for a session or task
+      --id <session-id>
+      --task <task>
+      --limit <n>          Event limit (default: 8)
+      --json               Output as JSON
+    session latest         Show latest task snapshot + events
+      --id <session-id>   Filter by session
+      --json               Output as JSON
+    session resume         Re-inject latest handoff as context output
+      --id <session-id>   Filter by session
+  handoff <sub>            Manage session handoffs for continuity
+    handoff create         Create a new session handoff
+      --summary <text>     Handoff summary (required)
+      --next <text>        Next action for successor
+      --session <id>       Session ID (auto-generated if omitted)
+      --task <id>          Associated task ID
+      --artifact <path>    Related file path (repeatable)
+    handoff latest         Show the most recent handoff
+      --session <id>       Filter by session
+      --json               Output as JSON
+    handoff show <id>      Show a specific handoff by ID
+  current <sub>            Show compact current state for agent injection
+    current show           Active task + recent session events (default)
+      --json               Output as JSON
+  forget <id>              Force remove a memory
+    --archive              Archive a raw (append-only) memory instead of deleting
+    --reason "<why>"       Reason recorded on the archive (required with --archive)
+  inspect <id>             Show full memory detail
+  embed                    Embed all memories for semantic search
+    --status               Show embedding coverage
+  watch "<command>"        Run command, auto-learn from failures
+  learn                    Learn lessons from repository history
+    --git                  Scan recent git commits for lessons
+    --days <n>             Scan this many days back (default: 7)
+    --repos <paths>        Comma-separated repo paths to scan
+  promote <id>             Copy a local memory to the global store
+  share <id>               Share a memory with attribution + transfer scoring
+    --force                Share even if transfer score is low
+    --auto                 Auto-share all high-transfer-score memories
+    --dry-run              Preview what would be shared
+    --min-score <n>        Minimum transfer score (default: 0.6)
+  peers                    List projects contributing to global store
+  sync                     Pull global memories into local project
+  import                   Import memories from other AI tools
+    --chatgpt <path>       Import from ChatGPT memory export (JSON or txt)
+    --claude <path>        Import from CLAUDE.md or Claude memory.json
+    --cursor <path>        Import from .cursorrules or .cursor/rules
+    --file <path>          Import from any markdown or text file
+    --markdown <path>      Import from structured MEMORY.md / AGENTS.md
+    --dry-run              Preview without writing
+    --global               Write to global store ($HIPPO_HOME or ~/.hippo/)
+    --tag <tag>            Add extra tag (repeatable)
+  export [file]            Export all memories (default: stdout)
+    --format <fmt>         Output format: json (default) or markdown
+  capture                  Extract memories from conversation text
+    --stdin                Read from piped input
+    --file <path>          Read from a file
+    --last-session         Read from the most recent agent session transcript
+    --transcript <path>    Explicit transcript path (implies --last-session)
+    --log-file <path>      Tee output to a log file (paired with 'hippo last-sleep')
+    --dry-run              Preview without writing
+    --global               Write to global store ($HIPPO_HOME or ~/.hippo/)
+  setup                    One-shot: detect installed AI tools and install all
+                           available SessionEnd+SessionStart hooks
+    --all                  Install for every JSON-hook tool, even if not detected
+    --dry-run              Show what would be installed without writing
+    --no-schedule          Skip installing or repairing the daily runner
+  last-sleep               Print the last 'hippo sleep --log-file' output and clear it
+    --path <p>             Log path (default: ~/.hippo/logs/last-sleep.log)
+    --keep                 Print without clearing
+  codex-run [-- ...args]   Launch real Codex behind Hippo's session-end wrapper
+  hook <sub> [target]      Manage framework integrations
+    hook list              Show available hooks
+    hook install <target>  Install hook (claude-code|codex|cursor|openclaw|opencode|pi)
+                           claude-code/opencode install SessionEnd+SessionStart;
+                           codex wraps the detected launcher in place
+    hook uninstall <target> Remove hook
+  decide "<decision>"      Record a decision (first-class object + memory mirror)
+    --context "<why>"      Why this decision was made
+    --supersedes <mem-id>  Supersede the decision backed by this memory id
+  decide list [--status active|superseded|closed|all] [--limit N]
+                           List decisions (table is authoritative, survives decay)
+  decide get <id>          Show a decision by its table id
+  decide close <id>        Retire (close) an active decision by its table id
+  invalidate "<pattern>"   Actively weaken memories matching an old pattern
+    --reason "<why>"       Optional: what replaced it
+  wm <sub>                 Working memory — bounded buffer for current state
+    wm push                Push a working memory entry
+      --scope <scope>      Scope name (default: default)
+      --content <text>     Content to store (required)
+      --importance <n>     Priority 0-1 (default: 0.5)
+      --session <id>       Session ID
+      --task <id>          Task ID
+    wm read                Read working memory entries
+      --scope <scope>      Filter by scope
+      --session <id>       Filter by session
+      --limit <n>          Max entries (default: 20)
+      --json               Output as JSON
+    wm clear               Clear working memory entries
+      --scope <scope>      Filter by scope
+      --session <id>       Filter by session
+    wm flush               Flush working memory (session end)
+      --scope <scope>      Filter by scope
+      --session <id>       Filter by session
+  dashboard                Open web dashboard for memory health
+    --port <n>             Port to serve on (default: 3333)
+  mcp                      Start MCP server (stdio transport)
+  goal <sub>               dlPFC goal stack (B3) — scoped per session
+    goal push <name>       Push a new active goal; prints the new goal id
+      --policy <type>      schema-fit-biased | error-prioritized |
+                           recency-first | hybrid
+      --success "<cond>"   Optional success condition text
+      --level <n>          Goal level (default: 0)
+      --parent <goalId>    Parent goal id (for sub-goals)
+      --session-id <s>     Override session (defaults to HIPPO_SESSION_ID)
+      --tenant-id <t>      Override tenant (defaults to HIPPO_TENANT)
+    goal list              Show active goals as a table
+      --all                Include suspended/completed goals
+    goal complete <id>     Mark a goal completed
+      --outcome <0..1>     Outcome score; >=0.7 boosts, <0.3 decays recalled mems
+      --no-propagate       Close the goal without applying strength side-effects
+    goal suspend <id>      Move an active goal to suspended
+    goal resume <id>       Move a suspended goal back to active (depth-capped)
+  auth <sub>               Manage API keys (A5 stub auth)
+    auth create            Mint a new API key (plaintext shown ONCE)
+      --label <s>          Optional human label
+      --role <r>           admin | member (default: admin; member blocked from /v1/sleep)
+      --tenant <id>        Override tenant (defaults to HIPPO_TENANT)
+      --json               Output as JSON
+      --global             Operate on the global store
+    auth list              List API keys (active by default)
+      --all                Include revoked keys
+      --json               Output as JSON
+      --global             Operate on the global store
+    auth revoke <key_id>   Revoke an API key (subsequent validate fails)
+      --json               Output as JSON
+      --global             Operate on the global store
+  audit <sub>              Query the append-only audit log (A5 stub auth)
+    audit list             List audit events for the active tenant
+      --op <op>            Filter by op (remember | recall | promote |
+                           supersede | forget | archive_raw | auth_revoke)
+      --since <iso>        Lower bound on ts (ISO timestamp)
+      --limit <n>          Max events (default: 100, max: 10000)
+      --json               Output as JSON
+      --global             Operate on the global store
+
+Examples:
+  hippo init
+  hippo remember "FRED cache can silently drop series" --tag error
+  hippo recall "data pipeline issues" --budget 2000
+  hippo context --auto --budget 1500
+  hippo conflicts
+  hippo session log --id sess_123 --task "Ship feature" --type progress --content "Build is green, next step is docs"
+  hippo session latest --json
+  hippo session resume
+  hippo snapshot save --task "Ship feature" --summary "Tests are green" --next-step "Open the PR" --session sess_123
+  hippo handoff create --summary "PR is open, tests green" --next "Merge after review" --session sess_123 --artifact src/foo.ts
+  hippo embed --status
+  hippo watch "npm run build"
+  hippo learn --git --days 30
+  hippo promote mem_abc123
+  hippo sync
+  hippo setup
+  hippo hook install claude-code
+  hippo decide "Use PostgreSQL for new services" --context "JSONB support"
+  hippo invalidate "REST API" --reason "migrated to GraphQL"
+  hippo export memories.json
+  hippo export --format markdown memories.md
+  hippo sleep --dry-run
+  hippo outcome --good
+  hippo status
 `);
 }
 // ---------------------------------------------------------------------------
@@ -6150,52 +6357,9 @@ async function main() {
             }
             break;
         }
-        case 'decide': {
-            requireInit(hippoRoot);
-            const text = args[0];
-            if (!text) {
-                console.error('Usage: hippo decide "<decision>" [--context "<why>"] [--supersedes <id>]');
-                process.exit(1);
-            }
-            const context = flags['context'] || '';
-            const supersedesId = flags['supersedes'] || null;
-            // Build content with context
-            const decisionContent = context ? `${text}\n\nContext: ${context}` : text;
-            // Handle supersession
-            if (supersedesId) {
-                const oldEntry = readEntry(hippoRoot, supersedesId, resolveTenantId({}));
-                if (!oldEntry) {
-                    console.error(`Memory ${supersedesId} not found.`);
-                    process.exit(1);
-                }
-                oldEntry.half_life_days = Math.max(1, Math.floor(oldEntry.half_life_days / 2));
-                oldEntry.confidence = 'stale';
-                if (!oldEntry.tags.includes('superseded'))
-                    oldEntry.tags.push('superseded');
-                writeEntry(hippoRoot, oldEntry);
-                console.log(`Superseded ${supersedesId} (half-life halved, marked stale)`);
-            }
-            // Create decision memory
-            const mem = createMemory(decisionContent, {
-                tags: ['decision'],
-                layer: Layer.Semantic,
-                confidence: 'verified',
-                source: 'decision',
-            });
-            mem.half_life_days = DECISION_HALF_LIFE_DAYS;
-            // Auto-tag with path context
-            const decisionPathTags = extractPathTags(process.cwd());
-            for (const pt of decisionPathTags) {
-                if (!mem.tags.includes(pt))
-                    mem.tags.push(pt);
-            }
-            writeEntry(hippoRoot, mem);
-            console.log(`Decision recorded: ${mem.id}`);
-            if (supersedesId) {
-                console.log(`   Supersedes: ${supersedesId}`);
-            }
+        case 'decide':
+            cmdDecide(hippoRoot, args, flags);
             break;
-        }
         case 'help':
         case '--help':
         case '-h':