hippo-memory 1.14.0 → 1.16.0

package/dist/src/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,6 +58,14 @@ 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 * as incidentsModule from './incidents.js';
+import * as processesModule from './processes.js';
+import * as policiesModule from './policies.js';
+import * as skillsModule from './skills.js';
+import * as briefsModule from './project-briefs.js';
+import * as customerNotesModule from './customer-notes.js';
+import { extractGraph } from './graph-extract.js';
 import { createHash } from 'node:crypto';
 import { detectAnchoring, hashQueryText, buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, } from './recall-history.js';
 import { detectAvailabilityBias } from './availability.js';
@@ -91,6 +99,7 @@ import { runFeatureEval, formatResult, resultToBaseline, detectRegressions } fro
 import { refineStore } from './refine-llm.js';
 import { wmPush, wmRead, wmClear, wmFlush } from './working-memory.js';
 import { multihopSearch } from './multihop.js';
+import { graphExpandRecall, MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph-recall.js';
 import { getReranker } from './rerankers/index.js';
 import { computeSalience } from './salience.js';
 import { computeAmbientState, renderAmbientSummary } from './ambient.js';
@@ -218,8 +227,8 @@ function parseArgs(argv) {
                 i++;
             }
             else {
-                // Check if it's a repeatable flag (tag, artifact)
-                if (key === 'tag' || key === 'artifact') {
+                // Check if it's a repeatable flag (tag, artifact, link, step)
+                if (key === 'tag' || key === 'artifact' || key === 'link' || key === 'step') {
                     if (Array.isArray(flags[key])) {
                         flags[key].push(next);
                     }
@@ -805,6 +814,51 @@ async function cmdRecall(hippoRoot, query, flags) {
             includeSuperseded, asOf,
         });
     }
+    // E3.2 multi-hop graph recall. After the base branch produces `results`, optionally
+    // augment with memories reached by walking the entities/relations graph `--hops N` out
+    // from the lexical seeds. Runs BEFORE the opt-in re-rankers below so graph-reached
+    // results are first-class candidates in any downstream re-ranking / --why. Default OFF
+    // (absent or 0 = no-op). Reached memories are loaded directly by id (NOT via the
+    // lexical candidate set, which would exclude the orthogonal neighbours graph recall
+    // exists to surface); the engine re-applies the same superseded/asOf hard filters.
+    if (flags['hops'] !== undefined) {
+        // Reject a value-less `--hops` (parseArgs stores boolean true): Number(true) === 1
+        // would otherwise silently run a 1-hop expansion when the user fat-fingered the value.
+        if (typeof flags['hops'] === 'boolean') {
+            console.error(`--hops requires an integer value 0..${MAX_HOPS} (e.g. --hops 1).`);
+            process.exit(1);
+        }
+        const hops = Number(flags['hops']);
+        if (!Number.isInteger(hops) || hops < 0 || hops > MAX_HOPS) {
+            console.error(`Invalid --hops: "${String(flags['hops'])}". Must be an integer 0..${MAX_HOPS}.`);
+            process.exit(1);
+        }
+        let maxNeighbors = DEFAULT_MAX_NEIGHBORS;
+        if (flags['max-neighbors'] !== undefined) {
+            if (typeof flags['max-neighbors'] === 'boolean') {
+                console.error(`--max-neighbors requires an integer value 1..200.`);
+                process.exit(1);
+            }
+            maxNeighbors = Number(flags['max-neighbors']);
+            if (!Number.isInteger(maxNeighbors) || maxNeighbors < 1 || maxNeighbors > 200) {
+                console.error(`Invalid --max-neighbors: "${String(flags['max-neighbors'])}". Must be an integer 1..200.`);
+                process.exit(1);
+            }
+        }
+        if (hops > 0) {
+            results = graphExpandRecall(results, {
+                hops,
+                maxNeighbors,
+                hippoRoot,
+                globalRoot: isInitialized(globalRoot) && globalRoot !== hippoRoot ? globalRoot : undefined,
+                tenantId,
+                includeSuperseded,
+                asOf,
+                budget,
+                minResults: minResults ?? 1,
+            });
+        }
+    }
     // ACC EVC-adaptive recall (RESEARCH.md §PFC.ACC). When the initial top-K is
     // dominated by lexically similar but distinct memories (high pairwise token
     // overlap = same topic, different facts = conflict), allocate extra retrieval
@@ -1322,6 +1376,9 @@ async function cmdRecall(hippoRoot, query, flags) {
                 base.superseded = true;
                 base.superseded_by = r.entry.superseded_by;
             }
+            if (r.graphVia) {
+                base.graphVia = r.graphVia;
+            }
             if (showWhy) {
                 const explanation = explainMatch(query, r);
                 base.confidence = resolveConfidence(r.entry);
@@ -1435,8 +1492,9 @@ async function cmdRecall(hippoRoot, query, flags) {
         const isGlobal = isInitialized(globalRoot) && !localIndex.entries[e.id];
         const globalMark = isGlobal ? ' [global]' : '';
         const supersededMark = e.superseded_by ? ' [superseded]' : '';
+        const graphMark = r.graphVia ? ` [graph: ${r.graphVia.hops}hop ${r.graphVia.relType}]` : '';
         const sourceMark = isGlobal ? ' [global]' : ' [local]';
-        console.log(`--- ${e.id} [${e.layer}] ${confLabel}${globalMark}${supersededMark} score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`);
+        console.log(`--- ${e.id} [${e.layer}] ${confLabel}${globalMark}${supersededMark}${graphMark} score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`);
         console.log(`    [${strengthBar}] tags: ${e.tags.join(', ') || 'none'} | retrieved: ${e.retrieval_count}x`);
         if (showWhy) {
             const explanation = explainMatch(query, r);
@@ -3061,246 +3119,1461 @@ function cmdHandoff(hippoRoot, args, flags) {
             }
             return;
         }
-        if (flags['json']) {
-            console.log(JSON.stringify({ handoff }, null, 2));
+        if (flags['json']) {
+            console.log(JSON.stringify({ handoff }, null, 2));
+            return;
+        }
+        printHandoff(handoff);
+        return;
+    }
+    if (subcommand === 'show') {
+        const idArg = args[1];
+        if (!idArg) {
+            console.error('Usage: hippo handoff show <id> [--json]');
+            process.exit(1);
+        }
+        const handoffId = parseInt(idArg, 10);
+        if (!Number.isFinite(handoffId) || handoffId <= 0) {
+            console.error(`Invalid handoff ID: ${idArg}`);
+            process.exit(1);
+        }
+        const handoff = loadHandoffById(hippoRoot, resolveTenantId({}), handoffId);
+        if (!handoff) {
+            if (flags['json']) {
+                console.log(JSON.stringify({ handoff: null }));
+            }
+            else {
+                console.log(`No handoff found with ID ${handoffId}.`);
+            }
+            return;
+        }
+        if (flags['json']) {
+            console.log(JSON.stringify({ handoff }, null, 2));
+            return;
+        }
+        printHandoff(handoff);
+        return;
+    }
+    console.error('Usage: hippo handoff <create|latest|show>');
+    process.exit(1);
+}
+// ---------------------------------------------------------------------------
+// E2 prediction first-class object (v0.31)
+// docs/plans/2026-05-26-e2-prediction-object.md
+// ---------------------------------------------------------------------------
+function cmdPredict(hippoRoot, args, flags) {
+    requireInit(hippoRoot);
+    const tenantId = resolveTenantId({});
+    const subcommand = args[0] ?? '';
+    if (subcommand === 'close') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]');
+            process.exit(1);
+        }
+        const id = parseInt(String(idRaw), 10);
+        if (!Number.isFinite(id) || id <= 0) {
+            console.error(`Invalid prediction id: "${idRaw}"`);
+            process.exit(1);
+        }
+        const stateRaw = typeof flags['state'] === 'string' ? flags['state'].trim() : '';
+        if (!predictionsModule.VALID_CLOSURE_STATES.has(stateRaw) || stateRaw === 'open') {
+            console.error(`Invalid --state: "${stateRaw}". Must be one of: closed | closed-unknown.`);
+            process.exit(1);
+        }
+        const actualRaw = flags['actual'];
+        const actualValue = actualRaw !== undefined ? Number(actualRaw) : undefined;
+        if (actualRaw !== undefined && !Number.isFinite(actualValue)) {
+            console.error(`Invalid --actual: "${actualRaw}". Must be a number.`);
+            process.exit(1);
+        }
+        const noteRaw = flags['note'];
+        const closureNote = typeof noteRaw === 'string' ? noteRaw : undefined;
+        const closed = predictionsModule.closePrediction(hippoRoot, tenantId, id, {
+            closureState: stateRaw,
+            actualValue,
+            closureNote,
+        });
+        console.log(`Prediction ${closed.id} closed: state=${closed.closureState}${closed.actualValue !== null ? ` actual=${closed.actualValue}` : ''}`);
+        return;
+    }
+    if (subcommand === 'list') {
+        const classTagRaw = flags['class'];
+        const classTag = typeof classTagRaw === 'string' ? classTagRaw.trim() : '';
+        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 === 'open') {
+            results = predictionsModule.loadOpenPredictions(hippoRoot, tenantId, {
+                classTag: classTag || undefined,
+                limit,
+            });
+        }
+        else if (status === 'all') {
+            // No closure-state filter; pull both via loadPredictionsByClass if class given
+            if (classTag) {
+                results = predictionsModule.loadPredictionsByClass(hippoRoot, tenantId, classTag, { limit });
+            }
+            else {
+                // No class filter + status=all = pull open + closed across all classes
+                // (kept simple: report open via loadOpenPredictions; closed via two
+                // class scans isn't symmetrical. v1 callers typically pass --class.)
+                results = predictionsModule.loadOpenPredictions(hippoRoot, tenantId, { limit });
+            }
+        }
+        else {
+            if (!predictionsModule.VALID_CLOSURE_STATES.has(status)) {
+                console.error(`Invalid --status: "${status}". Must be one of: open | closed | closed-unknown | all.`);
+                process.exit(1);
+            }
+            if (classTag) {
+                results = predictionsModule.loadPredictionsByClass(hippoRoot, tenantId, classTag, {
+                    closureState: status,
+                    limit,
+                });
+            }
+            else {
+                // status filter without class — scan all classes is more complex; v1 requires --class for non-default status
+                console.error('--status filter (non-open) requires --class to be set.');
+                process.exit(1);
+            }
+        }
+        if (results.length === 0) {
+            console.log(classTag ? `No predictions in class "${classTag}".` : 'No predictions.');
+            return;
+        }
+        console.log(`Found ${results.length} predictions:\n`);
+        for (const p of results) {
+            const estPart = p.estimateValue !== null ? ` estimate=${p.estimateValue}${p.estimateUnit ? ` ${p.estimateUnit}` : ''}` : '';
+            const actPart = p.actualValue !== null ? ` actual=${p.actualValue}` : '';
+            const tgtPart = p.targetDate ? ` target=${p.targetDate}` : '';
+            console.log(`#${p.id} [${p.closureState}] class=${p.classTag}${estPart}${actPart}${tgtPart}`);
+            console.log(`    ${p.claimText}`);
+            if (p.closureNote)
+                console.log(`    note: ${p.closureNote}`);
+        }
+        return;
+    }
+    if (subcommand === 'show') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo predict show <id>');
+            process.exit(1);
+        }
+        const id = parseInt(String(idRaw), 10);
+        if (!Number.isFinite(id) || id <= 0) {
+            console.error(`Invalid prediction id: "${idRaw}"`);
+            process.exit(1);
+        }
+        const pred = predictionsModule.loadPredictionById(hippoRoot, tenantId, id);
+        if (!pred) {
+            console.error(`Prediction ${id} not found.`);
+            process.exit(1);
+        }
+        console.log(`Prediction #${pred.id}`);
+        console.log(`  class: ${pred.classTag}`);
+        console.log(`  claim: ${pred.claimText}`);
+        console.log(`  state: ${pred.closureState}`);
+        if (pred.estimateValue !== null)
+            console.log(`  estimate: ${pred.estimateValue}${pred.estimateUnit ? ' ' + pred.estimateUnit : ''}`);
+        if (pred.targetDate)
+            console.log(`  target: ${pred.targetDate}`);
+        if (pred.actualValue !== null)
+            console.log(`  actual: ${pred.actualValue}`);
+        if (pred.closedAt)
+            console.log(`  closed: ${pred.closedAt}`);
+        if (pred.closureNote)
+            console.log(`  note: ${pred.closureNote}`);
+        if (pred.memoryId)
+            console.log(`  memory: ${pred.memoryId}`);
+        console.log(`  created: ${pred.createdAt}`);
+        return;
+    }
+    if (subcommand === 'baserate') {
+        // J3 reference-class / planning-fallacy detector
+        const classTagRaw = flags['class'];
+        if (typeof classTagRaw !== 'string' || !classTagRaw.trim()) {
+            console.error('Usage: hippo predict baserate --class <c>');
+            process.exit(1);
+        }
+        const baserate = predictionsModule.computePredictionBaserate(hippoRoot, tenantId, classTagRaw.trim());
+        if (baserate.nClosed === 0) {
+            console.log(`No closed predictions in class "${baserate.classTag}" yet.`);
+            console.log(`  Create one with: hippo predict "<claim>" --class ${baserate.classTag} --estimate N`);
+            console.log(`  Close it later:  hippo predict close <id> --state closed --actual N`);
+            return;
+        }
+        console.log(baserate.summary);
+        console.log(`  n_closed:         ${baserate.nClosed}`);
+        console.log(`  n_ratio_eligible: ${baserate.nRatioEligible}`);
+        if (baserate.meanEstimate !== null)
+            console.log(`  mean_estimate:    ${baserate.meanEstimate.toFixed(3)}`);
+        if (baserate.meanActual !== null)
+            console.log(`  mean_actual:      ${baserate.meanActual.toFixed(3)}`);
+        if (baserate.meanRatio !== null)
+            console.log(`  mean_ratio:       ${baserate.meanRatio.toFixed(3)}x`);
+        if (baserate.p50Ratio !== null)
+            console.log(`  p50_ratio:        ${baserate.p50Ratio.toFixed(3)}x`);
+        if (baserate.mae !== null)
+            console.log(`  mae:              ${baserate.mae.toFixed(3)}`);
+        return;
+    }
+    // Default subcommand: create. args[0] is the claim text.
+    const claimText = subcommand;
+    if (!claimText) {
+        console.error('Usage: hippo predict "<claim>" --class <c> [--estimate <v>] [--unit <u>] [--target <YYYY-MM-DD>]');
+        console.error('       hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]');
+        console.error('       hippo predict list [--class X] [--status open|closed|closed-unknown|all] [--limit N]');
+        console.error('       hippo predict show <id>');
+        process.exit(1);
+    }
+    const classTagRaw = flags['class'];
+    if (typeof classTagRaw !== 'string' || !classTagRaw.trim()) {
+        console.error('--class is required for prediction creation.');
+        process.exit(1);
+    }
+    const classTag = classTagRaw.trim();
+    const estimateRaw = flags['estimate'];
+    const estimateValue = estimateRaw !== undefined ? Number(estimateRaw) : undefined;
+    if (estimateRaw !== undefined && !Number.isFinite(estimateValue)) {
+        console.error(`Invalid --estimate: "${estimateRaw}". Must be a number.`);
+        process.exit(1);
+    }
+    const unitRaw = flags['unit'];
+    const estimateUnit = typeof unitRaw === 'string' ? unitRaw : undefined;
+    const targetRaw = flags['target'];
+    const targetDate = typeof targetRaw === 'string' ? targetRaw : undefined;
+    const created = predictionsModule.savePrediction(hippoRoot, tenantId, {
+        classTag,
+        claimText,
+        estimateValue,
+        estimateUnit,
+        targetDate,
+    });
+    console.log(`Prediction recorded: #${created.id} class=${created.classTag}`);
+    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}`);
+    }
+}
+// Strict positive-integer parse for incident id args. parseInt() alone accepts
+// trailing junk ("1abc" -> 1), which would let a mutating subcommand (close/
+// resolve) silently hit the wrong row; require the whole arg to be digits.
+// (codex P2, 2026-05-29.)
+function parsePositiveIncidentId(idRaw) {
+    const s = String(idRaw ?? '').trim();
+    const id = parseInt(s, 10);
+    if (!/^\d+$/.test(s) || id <= 0) {
+        console.error(`Invalid incident id: "${idRaw}" (expected a positive integer).`);
+        process.exit(1);
+    }
+    return id;
+}
+function cmdIncident(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 = incidentsModule.loadIncidents(hippoRoot, tenantId, { limit });
+        }
+        else {
+            if (!incidentsModule.VALID_INCIDENT_STATES.has(status)) {
+                console.error(`Invalid --status: "${status}". Must be one of: open | resolved | closed | all.`);
+                process.exit(1);
+            }
+            results = incidentsModule.loadIncidents(hippoRoot, tenantId, {
+                status: status,
+                limit,
+            });
+        }
+        if (results.length === 0) {
+            console.log('No incidents.');
+            return;
+        }
+        console.log(`Found ${results.length} incidents:\n`);
+        for (const inc of results) {
+            const linkPart = inc.linkedMemoryIds.length > 0 ? ` links=${inc.linkedMemoryIds.length}` : '';
+            console.log(`#${inc.id} [${inc.status}]${linkPart} memory=${inc.memoryId ?? '-'}`);
+            console.log(`    ${inc.incidentText}`);
+            if (inc.context)
+                console.log(`    context: ${inc.context}`);
+        }
+        return;
+    }
+    if (subcommand === 'get') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo incident get <id>');
+            process.exit(1);
+        }
+        const id = parsePositiveIncidentId(idRaw);
+        const incident = incidentsModule.loadIncidentById(hippoRoot, tenantId, id);
+        if (!incident) {
+            console.error(`Incident ${id} not found.`);
+            process.exit(1);
+        }
+        console.log(`Incident #${incident.id}`);
+        console.log(`  status: ${incident.status}`);
+        console.log(`  text: ${incident.incidentText}`);
+        if (incident.context)
+            console.log(`  context: ${incident.context}`);
+        if (incident.resolutionText)
+            console.log(`  resolution: ${incident.resolutionText}`);
+        if (incident.resolvedAt)
+            console.log(`  resolved_at: ${incident.resolvedAt}`);
+        if (incident.closedAt)
+            console.log(`  closed_at: ${incident.closedAt}`);
+        if (incident.linkedMemoryIds.length > 0) {
+            console.log(`  linked memories: ${incident.linkedMemoryIds.join(', ')}`);
+        }
+        if (incident.memoryId)
+            console.log(`  memory: ${incident.memoryId}`);
+        console.log(`  created: ${incident.createdAt}`);
+        return;
+    }
+    if (subcommand === 'resolve') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo incident resolve <id> --resolution "<text>"');
+            process.exit(1);
+        }
+        const id = parsePositiveIncidentId(idRaw);
+        const resolutionRaw = flags['resolution'];
+        if (typeof resolutionRaw !== 'string' || !resolutionRaw.trim()) {
+            console.error('--resolution requires a non-empty value, e.g. hippo incident resolve <id> --resolution "root cause fixed".');
+            process.exit(1);
+        }
+        const resolved = incidentsModule.resolveIncident(hippoRoot, tenantId, id, resolutionRaw);
+        console.log(`Incident #${resolved.id} resolved.`);
+        return;
+    }
+    if (subcommand === 'close') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo incident close <id>');
+            process.exit(1);
+        }
+        const id = parsePositiveIncidentId(idRaw);
+        const closed = incidentsModule.closeIncident(hippoRoot, tenantId, id);
+        console.log(`Incident #${closed.id} closed.`);
+        return;
+    }
+    // Default subcommand: open (create). Accept both the documented
+    // `incident open "<text>"` form and the bare `incident "<text>"` form: for the
+    // `open` keyword the text is args[1], otherwise args[0] IS the text.
+    const incidentText = subcommand === 'open' ? (args[1] ?? '') : subcommand;
+    if (!incidentText) {
+        console.error('Usage: hippo incident "<incident>" [--context "<details>"] [--link <memory-id>]...');
+        console.error('       hippo incident list [--status open|resolved|closed|all] [--limit N]');
+        console.error('       hippo incident get <id>');
+        console.error('       hippo incident resolve <id> --resolution "<text>"');
+        console.error('       hippo incident close <id>');
+        process.exit(1);
+    }
+    const contextRaw = flags['context'];
+    const context = typeof contextRaw === 'string' && contextRaw ? contextRaw : undefined;
+    // --link is a repeatable flag (collected into an array by parseArgs). A
+    // single --link <id> yields a string; normalize both to string[].
+    const linkRaw = flags['link'];
+    let linkedMemoryIds;
+    if (Array.isArray(linkRaw)) {
+        linkedMemoryIds = linkRaw;
+    }
+    else if (typeof linkRaw === 'string') {
+        linkedMemoryIds = [linkRaw];
+    }
+    else if (linkRaw === true) {
+        console.error('--link requires a memory id, e.g. hippo incident "<text>" --link mem_abc123.');
+        process.exit(1);
+    }
+    const incidentPathTags = extractPathTags(process.cwd());
+    const created = incidentsModule.saveIncident(hippoRoot, tenantId, {
+        incidentText,
+        context,
+        linkedMemoryIds,
+        extraTags: incidentPathTags,
+    });
+    console.log(`Incident recorded: #${created.id}`);
+    if (created.memoryId)
+        console.log(`  memory: ${created.memoryId}`);
+    if (created.linkedMemoryIds.length > 0) {
+        console.log(`  linked memories: ${created.linkedMemoryIds.join(', ')}`);
+    }
+}
+// Strict positive-integer id parse for the mutating process subcommands.
+// parseInt alone accepts trailing junk ('1abc' -> 1), which would let
+// `process close 1abc` / `supersede 1abc` silently hit the wrong row; require
+// the whole arg to be digits. (Mirrors parsePositiveIncidentId; codex P2,
+// 2026-05-29.)
+function parsePositiveProcessId(idRaw) {
+    const s = String(idRaw ?? '').trim();
+    const id = parseInt(s, 10);
+    if (!/^\d+$/.test(s) || id <= 0) {
+        console.error(`Invalid process id: "${idRaw}" (expected a positive integer).`);
+        process.exit(1);
+    }
+    return id;
+}
+// --step is a repeatable flag (collected into an array by parseArgs). A single
+// --step yields a string; normalize both to string[]. A value-less --step errors.
+function collectProcessSteps(stepRaw) {
+    if (Array.isArray(stepRaw))
+        return stepRaw;
+    if (typeof stepRaw === 'string')
+        return [stepRaw];
+    if (stepRaw === true) {
+        console.error('--step requires a value, e.g. hippo process new "<name>" --step "do X".');
+        process.exit(1);
+    }
+    return [];
+}
+function cmdProcess(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 = processesModule.loadProcesses(hippoRoot, tenantId, { limit });
+        }
+        else {
+            if (!processesModule.VALID_PROCESS_STATES.has(status)) {
+                console.error(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
+                process.exit(1);
+            }
+            results = processesModule.loadProcesses(hippoRoot, tenantId, {
+                status: status,
+                limit,
+            });
+        }
+        if (results.length === 0) {
+            console.log('No processes.');
+            return;
+        }
+        console.log(`Found ${results.length} processes:\n`);
+        for (const proc of results) {
+            console.log(`#${proc.id} [${proc.status}] v${proc.version} steps=${proc.steps.length} memory=${proc.memoryId ?? '-'}`);
+            console.log(`    ${proc.processName}`);
+            if (proc.changeSummary)
+                console.log(`    change: ${proc.changeSummary}`);
+        }
+        return;
+    }
+    if (subcommand === 'get') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo process get <id>');
+            process.exit(1);
+        }
+        const id = parsePositiveProcessId(idRaw);
+        const proc = processesModule.loadProcessById(hippoRoot, tenantId, id);
+        if (!proc) {
+            console.error(`Process ${id} not found.`);
+            process.exit(1);
+        }
+        console.log(`Process #${proc.id}`);
+        console.log(`  name: ${proc.processName}`);
+        console.log(`  status: ${proc.status}`);
+        console.log(`  version: ${proc.version}`);
+        if (proc.description)
+            console.log(`  description: ${proc.description}`);
+        if (proc.steps.length > 0) {
+            console.log(`  steps:`);
+            proc.steps.forEach((s, i) => console.log(`    ${i + 1}. ${s}`));
+        }
+        if (proc.changeSummary)
+            console.log(`  change_summary: ${proc.changeSummary}`);
+        if (proc.supersededBy !== null)
+            console.log(`  superseded_by: #${proc.supersededBy}`);
+        if (proc.supersededAt)
+            console.log(`  superseded_at: ${proc.supersededAt}`);
+        if (proc.closedAt)
+            console.log(`  closed_at: ${proc.closedAt}`);
+        if (proc.memoryId)
+            console.log(`  memory: ${proc.memoryId}`);
+        console.log(`  created: ${proc.createdAt}`);
+        return;
+    }
+    if (subcommand === 'supersede') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo process supersede <id> --step "<text>" [--step ...] [--change "<summary>"] [--description "<text>"]');
+            process.exit(1);
+        }
+        const id = parsePositiveProcessId(idRaw);
+        const steps = collectProcessSteps(flags['step']);
+        if (steps.length === 0) {
+            console.error('hippo process supersede requires at least one --step "<text>" for the new version.');
+            process.exit(1);
+        }
+        // A supersession is a new version of the SAME process, so the new row reuses
+        // the predecessor's name (stable identity across versions). loadProcessById
+        // gives an early not-found before the write; saveProcess's in-SAVEPOINT
+        // preflight is the authoritative active-state check.
+        const existing = processesModule.loadProcessById(hippoRoot, tenantId, id);
+        if (!existing) {
+            console.error(`Process ${id} not found.`);
+            process.exit(1);
+        }
+        const changeRaw = flags['change'];
+        const changeSummary = typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined;
+        const descRaw = flags['description'];
+        const description = typeof descRaw === 'string' && descRaw ? descRaw : undefined;
+        const procPathTags = extractPathTags(process.cwd());
+        const created = processesModule.saveProcess(hippoRoot, tenantId, {
+            processName: existing.processName,
+            steps,
+            description,
+            changeSummary,
+            supersedesProcessId: id,
+            extraTags: procPathTags,
+        });
+        console.log(`Process #${created.id} recorded (v${created.version}), superseding #${id}.`);
+        if (created.memoryId)
+            console.log(`  memory: ${created.memoryId}`);
+        return;
+    }
+    if (subcommand === 'close') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo process close <id>');
+            process.exit(1);
+        }
+        const id = parsePositiveProcessId(idRaw);
+        const closed = processesModule.closeProcess(hippoRoot, tenantId, id);
+        console.log(`Process #${closed.id} closed.`);
+        return;
+    }
+    // Default subcommand: new (create). Accept both the documented
+    // `process new "<name>"` form and the bare `process "<name>"` form: for the
+    // `new` keyword the name is args[1], otherwise args[0] IS the name.
+    const processName = subcommand === 'new' ? (args[1] ?? '') : subcommand;
+    if (!processName) {
+        console.error('Usage: hippo process new "<name>" --step "<text>" [--step ...] [--description "<text>"]');
+        console.error('       hippo process list [--status active|superseded|closed|all] [--limit N]');
+        console.error('       hippo process get <id>');
+        console.error('       hippo process supersede <id> --step "<text>" [--change "<summary>"]');
+        console.error('       hippo process close <id>');
+        process.exit(1);
+    }
+    const steps = collectProcessSteps(flags['step']);
+    const descRaw = flags['description'];
+    const description = typeof descRaw === 'string' && descRaw ? descRaw : undefined;
+    const procPathTags = extractPathTags(process.cwd());
+    const created = processesModule.saveProcess(hippoRoot, tenantId, {
+        processName,
+        steps,
+        description,
+        extraTags: procPathTags,
+    });
+    console.log(`Process recorded: #${created.id} (v${created.version}, ${created.steps.length} steps)`);
+    if (created.memoryId)
+        console.log(`  memory: ${created.memoryId}`);
+}
+// Strict positive-integer id parse for the mutating policy subcommands (mirrors
+// parsePositiveProcessId; codex P2 class - parseInt alone accepts '1abc' -> 1).
+function parsePositivePolicyId(idRaw) {
+    const s = String(idRaw ?? '').trim();
+    const id = parseInt(s, 10);
+    if (!/^\d+$/.test(s) || id <= 0) {
+        console.error(`Invalid policy id: "${idRaw}" (expected a positive integer).`);
+        process.exit(1);
+    }
+    return id;
+}
+function printPolicyRow(p) {
+    const range = p.validTo ? `${p.validFrom}..${p.validTo}` : `${p.validFrom}..(open)`;
+    console.log(`#${p.id} [${p.status}] v${p.version} ${range} memory=${p.memoryId ?? '-'}`);
+    console.log(`    ${p.policyName}: ${p.policyText}`);
+    if (p.changeSummary)
+        console.log(`    change: ${p.changeSummary}`);
+}
+function cmdPolicy(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 = policiesModule.loadPolicies(hippoRoot, tenantId, { limit });
+        }
+        else {
+            if (!policiesModule.VALID_POLICY_STATES.has(status)) {
+                console.error(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
+                process.exit(1);
+            }
+            results = policiesModule.loadPolicies(hippoRoot, tenantId, {
+                status: status,
+                limit,
+            });
+        }
+        if (results.length === 0) {
+            console.log('No policies.');
+            return;
+        }
+        console.log(`Found ${results.length} policies:\n`);
+        for (const p of results)
+            printPolicyRow(p);
+        return;
+    }
+    if (subcommand === 'asof') {
+        const dateRaw = args[1];
+        if (!dateRaw) {
+            console.error('Usage: hippo policy asof <iso-date> [--name "<policy>"]');
+            process.exit(1);
+        }
+        const nameRaw = flags['name'];
+        const name = typeof nameRaw === 'string' && nameRaw ? nameRaw : undefined;
+        let results;
+        try {
+            results = policiesModule.loadPoliciesAsOf(hippoRoot, tenantId, dateRaw, { name });
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(1);
+        }
+        if (results.length === 0) {
+            console.log(`No active policies in force at ${dateRaw}${name ? ` for "${name}"` : ''}.`);
+            return;
+        }
+        console.log(`Policies in force at ${dateRaw}:\n`);
+        for (const p of results)
+            printPolicyRow(p);
+        return;
+    }
+    if (subcommand === 'get') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo policy get <id>');
+            process.exit(1);
+        }
+        const id = parsePositivePolicyId(idRaw);
+        const p = policiesModule.loadPolicyById(hippoRoot, tenantId, id);
+        if (!p) {
+            console.error(`Policy ${id} not found.`);
+            process.exit(1);
+        }
+        console.log(`Policy #${p.id}`);
+        console.log(`  name: ${p.policyName}`);
+        console.log(`  text: ${p.policyText}`);
+        console.log(`  status: ${p.status}`);
+        console.log(`  version: ${p.version}`);
+        console.log(`  valid_from: ${p.validFrom}`);
+        console.log(`  valid_to: ${p.validTo ?? '(open-ended)'}`);
+        if (p.changeSummary)
+            console.log(`  change_summary: ${p.changeSummary}`);
+        if (p.supersededBy !== null)
+            console.log(`  superseded_by: #${p.supersededBy}`);
+        if (p.supersededAt)
+            console.log(`  superseded_at: ${p.supersededAt}`);
+        if (p.closedAt)
+            console.log(`  closed_at: ${p.closedAt}`);
+        if (p.memoryId)
+            console.log(`  memory: ${p.memoryId}`);
+        console.log(`  created: ${p.createdAt}`);
+        return;
+    }
+    if (subcommand === 'supersede') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo policy supersede <id> --text "<rule>" [--from <iso>] [--to <iso>] [--change "<summary>"]');
+            process.exit(1);
+        }
+        const id = parsePositivePolicyId(idRaw);
+        const textRaw = flags['text'];
+        if (typeof textRaw !== 'string' || !textRaw.trim()) {
+            console.error('hippo policy supersede requires --text "<rule>" for the new version.');
+            process.exit(1);
+        }
+        const existing = policiesModule.loadPolicyById(hippoRoot, tenantId, id);
+        if (!existing) {
+            console.error(`Policy ${id} not found.`);
+            process.exit(1);
+        }
+        const fromRaw = flags['from'];
+        const toRaw = flags['to'];
+        const changeRaw = flags['change'];
+        try {
+            const created = policiesModule.savePolicy(hippoRoot, tenantId, {
+                policyName: existing.policyName,
+                policyText: textRaw,
+                validFrom: typeof fromRaw === 'string' && fromRaw ? fromRaw : undefined,
+                validTo: typeof toRaw === 'string' && toRaw ? toRaw : undefined,
+                changeSummary: typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined,
+                supersedesPolicyId: id,
+                extraTags: extractPathTags(process.cwd()),
+            });
+            console.log(`Policy #${created.id} recorded (v${created.version}), superseding #${id}.`);
+            if (created.memoryId)
+                console.log(`  memory: ${created.memoryId}`);
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(1);
+        }
+        return;
+    }
+    if (subcommand === 'close') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo policy close <id>');
+            process.exit(1);
+        }
+        const id = parsePositivePolicyId(idRaw);
+        const closed = policiesModule.closePolicy(hippoRoot, tenantId, id);
+        console.log(`Policy #${closed.id} closed.`);
+        return;
+    }
+    // Default subcommand: new (create). Accept both `policy new "<name>"` and the
+    // bare `policy "<name>"` form: for the `new` keyword the name is args[1].
+    const policyName = subcommand === 'new' ? (args[1] ?? '') : subcommand;
+    const textRaw = flags['text'];
+    if (!policyName || typeof textRaw !== 'string' || !textRaw.trim()) {
+        console.error('Usage: hippo policy new "<name>" --text "<rule>" [--from <iso>] [--to <iso>]');
+        console.error('       hippo policy list [--status active|superseded|closed|all] [--limit N]');
+        console.error('       hippo policy get <id>');
+        console.error('       hippo policy asof <iso-date> [--name "<policy>"]');
+        console.error('       hippo policy supersede <id> --text "<rule>" [--from] [--to] [--change "<summary>"]');
+        console.error('       hippo policy close <id>');
+        process.exit(1);
+    }
+    const fromRaw = flags['from'];
+    const toRaw = flags['to'];
+    try {
+        const created = policiesModule.savePolicy(hippoRoot, tenantId, {
+            policyName,
+            policyText: textRaw,
+            validFrom: typeof fromRaw === 'string' && fromRaw ? fromRaw : undefined,
+            validTo: typeof toRaw === 'string' && toRaw ? toRaw : undefined,
+            extraTags: extractPathTags(process.cwd()),
+        });
+        const range = created.validTo ? `${created.validFrom}..${created.validTo}` : `${created.validFrom}..(open)`;
+        console.log(`Policy recorded: #${created.id} (v${created.version}, effective ${range})`);
+        if (created.memoryId)
+            console.log(`  memory: ${created.memoryId}`);
+    }
+    catch (e) {
+        console.error(e.message);
+        process.exit(1);
+    }
+}
+// Strict positive-integer id parse for the mutating skill subcommands (mirrors
+// parsePositivePolicyId; codex P2 class - parseInt accepts '1abc' -> 1).
+function parsePositiveSkillId(idRaw) {
+    const s = String(idRaw ?? '').trim();
+    const id = parseInt(s, 10);
+    if (!/^\d+$/.test(s) || id <= 0) {
+        console.error(`Invalid skill id: "${idRaw}" (expected a positive integer).`);
+        process.exit(1);
+    }
+    return id;
+}
+function printSkillRow(s) {
+    const trig = s.trigger ? ` when="${s.trigger}"` : '';
+    console.log(`#${s.id} [${s.status}] v${s.version}${trig} memory=${s.memoryId ?? '-'}`);
+    console.log(`    ${s.skillName}`);
+    if (s.changeSummary)
+        console.log(`    change: ${s.changeSummary}`);
+}
+function cmdSkill(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 = skillsModule.loadSkills(hippoRoot, tenantId, { limit });
+        }
+        else {
+            if (!skillsModule.VALID_SKILL_STATES.has(status)) {
+                console.error(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
+                process.exit(1);
+            }
+            results = skillsModule.loadSkills(hippoRoot, tenantId, {
+                status: status,
+                limit,
+            });
+        }
+        if (results.length === 0) {
+            console.log('No skills.');
+            return;
+        }
+        console.log(`Found ${results.length} skills:\n`);
+        for (const s of results)
+            printSkillRow(s);
+        return;
+    }
+    if (subcommand === 'export') {
+        const md = skillsModule.exportSkills(hippoRoot, tenantId);
+        if (!md) {
+            console.log('No active skills.');
+            return;
+        }
+        console.log(md);
+        return;
+    }
+    if (subcommand === 'get') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo skill get <id>');
+            process.exit(1);
+        }
+        const id = parsePositiveSkillId(idRaw);
+        const s = skillsModule.loadSkillById(hippoRoot, tenantId, id);
+        if (!s) {
+            console.error(`Skill ${id} not found.`);
+            process.exit(1);
+        }
+        console.log(`Skill #${s.id}`);
+        console.log(`  name: ${s.skillName}`);
+        console.log(`  status: ${s.status}`);
+        console.log(`  version: ${s.version}`);
+        if (s.trigger)
+            console.log(`  when: ${s.trigger}`);
+        console.log(`  instructions: ${s.instructions}`);
+        if (s.changeSummary)
+            console.log(`  change_summary: ${s.changeSummary}`);
+        if (s.supersededBy !== null)
+            console.log(`  superseded_by: #${s.supersededBy}`);
+        if (s.supersededAt)
+            console.log(`  superseded_at: ${s.supersededAt}`);
+        if (s.closedAt)
+            console.log(`  closed_at: ${s.closedAt}`);
+        if (s.memoryId)
+            console.log(`  memory: ${s.memoryId}`);
+        console.log(`  created: ${s.createdAt}`);
+        return;
+    }
+    if (subcommand === 'supersede') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo skill supersede <id> --instructions "<text>" [--trigger "<when>"] [--change "<summary>"]');
+            process.exit(1);
+        }
+        const id = parsePositiveSkillId(idRaw);
+        const instrRaw = flags['instructions'];
+        if (typeof instrRaw !== 'string' || !instrRaw.trim()) {
+            console.error('hippo skill supersede requires --instructions "<text>" for the new version.');
+            process.exit(1);
+        }
+        const existing = skillsModule.loadSkillById(hippoRoot, tenantId, id);
+        if (!existing) {
+            console.error(`Skill ${id} not found.`);
+            process.exit(1);
+        }
+        const trigRaw = flags['trigger'];
+        const changeRaw = flags['change'];
+        try {
+            const created = skillsModule.saveSkill(hippoRoot, tenantId, {
+                skillName: existing.skillName,
+                instructions: instrRaw,
+                trigger: typeof trigRaw === 'string' && trigRaw ? trigRaw : undefined,
+                changeSummary: typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined,
+                supersedesSkillId: id,
+                extraTags: extractPathTags(process.cwd()),
+            });
+            console.log(`Skill #${created.id} recorded (v${created.version}), superseding #${id}.`);
+            if (created.memoryId)
+                console.log(`  memory: ${created.memoryId}`);
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(1);
+        }
+        return;
+    }
+    if (subcommand === 'close') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo skill close <id>');
+            process.exit(1);
+        }
+        const id = parsePositiveSkillId(idRaw);
+        const closed = skillsModule.closeSkill(hippoRoot, tenantId, id);
+        console.log(`Skill #${closed.id} closed.`);
+        return;
+    }
+    // Default subcommand: new (create). Accept both `skill new "<name>"` and the
+    // bare `skill "<name>"` form: for the `new` keyword the name is args[1].
+    const skillName = subcommand === 'new' ? (args[1] ?? '') : subcommand;
+    const instrRaw = flags['instructions'];
+    if (!skillName || typeof instrRaw !== 'string' || !instrRaw.trim()) {
+        console.error('Usage: hippo skill new "<name>" --instructions "<text>" [--trigger "<when>"]');
+        console.error('       hippo skill list [--status active|superseded|closed|all] [--limit N]');
+        console.error('       hippo skill get <id>');
+        console.error('       hippo skill export   (render active skills as an AGENTS.md/CLAUDE.md block)');
+        console.error('       hippo skill supersede <id> --instructions "<text>" [--trigger] [--change "<summary>"]');
+        console.error('       hippo skill close <id>');
+        process.exit(1);
+    }
+    const trigRaw = flags['trigger'];
+    try {
+        const created = skillsModule.saveSkill(hippoRoot, tenantId, {
+            skillName,
+            instructions: instrRaw,
+            trigger: typeof trigRaw === 'string' && trigRaw ? trigRaw : undefined,
+            extraTags: extractPathTags(process.cwd()),
+        });
+        console.log(`Skill recorded: #${created.id} (v${created.version})`);
+        if (created.memoryId)
+            console.log(`  memory: ${created.memoryId}`);
+    }
+    catch (e) {
+        console.error(e.message);
+        process.exit(1);
+    }
+}
+function parsePositiveBriefId(idRaw) {
+    const s = String(idRaw ?? '').trim();
+    const id = parseInt(s, 10);
+    if (!/^\d+$/.test(s) || id <= 0) {
+        console.error(`Invalid brief id: "${idRaw}" (expected a positive integer).`);
+        process.exit(1);
+    }
+    return id;
+}
+function printBriefRow(b) {
+    console.log(`#${b.id} [${b.status}] v${b.version} repo="${b.repo}" memory=${b.memoryId ?? '-'}`);
+    if (b.changeSummary)
+        console.log(`    change: ${b.changeSummary}`);
+}
+function briefUsage() {
+    console.error('Usage: hippo brief new "<repo>" --summary "<text>"');
+    console.error('       hippo brief list [--status active|superseded|closed|all] [--repo "<repo>"] [--limit N]');
+    console.error('       hippo brief get <id>');
+    console.error('       hippo brief supersede <id> --summary "<text>" [--change "<summary>"]');
+    console.error('       hippo brief close <id>');
+    console.error('       hippo brief refresh "<repo>" [--dry-run]   (auto-assemble the brief from the repo\'s receipts)');
+}
+function cmdProjectBrief(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 repoRaw = flags['repo'];
+        const repo = typeof repoRaw === 'string' && repoRaw.trim() ? repoRaw.trim() : undefined;
+        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);
+        }
+        const opts = { limit, repo };
+        if (status !== 'all') {
+            if (!briefsModule.VALID_BRIEF_STATES.has(status)) {
+                console.error(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
+                process.exit(1);
+            }
+            opts.status = status;
+        }
+        const results = briefsModule.loadProjectBriefs(hippoRoot, tenantId, opts);
+        if (results.length === 0) {
+            console.log('No project briefs.');
             return;
         }
-        printHandoff(handoff);
+        console.log(`Found ${results.length} project briefs:\n`);
+        for (const b of results)
+            printBriefRow(b);
         return;
     }
-    if (subcommand === 'show') {
-        const idArg = args[1];
-        if (!idArg) {
-            console.error('Usage: hippo handoff show <id> [--json]');
+    if (subcommand === 'refresh') {
+        const repoRaw = args[1];
+        if (!repoRaw) {
+            console.error('Usage: hippo brief refresh "<repo>" [--dry-run]');
             process.exit(1);
         }
-        const handoffId = parseInt(idArg, 10);
-        if (!Number.isFinite(handoffId) || handoffId <= 0) {
-            console.error(`Invalid handoff ID: ${idArg}`);
+        const dryRun = Boolean(flags['dry-run']);
+        try {
+            if (dryRun) {
+                const { markdown, receiptCount } = briefsModule.assembleBriefFromReceipts(hippoRoot, tenantId, repoRaw);
+                console.error(`(dry-run: assembled from ${receiptCount} receipt(s); brief NOT written)`);
+                console.log(markdown);
+                return;
+            }
+            const created = briefsModule.refreshBrief(hippoRoot, tenantId, repoRaw, 'cli');
+            console.log(`Project brief #${created.id} recorded (v${created.version}) for repo "${created.repo}".`);
+            if (created.changeSummary)
+                console.log(`  change: ${created.changeSummary}`);
+            if (created.memoryId)
+                console.log(`  memory: ${created.memoryId}`);
+        }
+        catch (e) {
+            console.error(e.message);
             process.exit(1);
         }
-        const handoff = loadHandoffById(hippoRoot, resolveTenantId({}), handoffId);
-        if (!handoff) {
-            if (flags['json']) {
-                console.log(JSON.stringify({ handoff: null }));
-            }
-            else {
-                console.log(`No handoff found with ID ${handoffId}.`);
-            }
-            return;
+        return;
+    }
+    if (subcommand === 'get') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo brief get <id>');
+            process.exit(1);
         }
-        if (flags['json']) {
-            console.log(JSON.stringify({ handoff }, null, 2));
-            return;
+        const id = parsePositiveBriefId(idRaw);
+        const b = briefsModule.loadProjectBriefById(hippoRoot, tenantId, id);
+        if (!b) {
+            console.error(`Project brief ${id} not found.`);
+            process.exit(1);
         }
-        printHandoff(handoff);
+        console.log(`Project brief #${b.id}`);
+        console.log(`  repo: ${b.repo}`);
+        console.log(`  status: ${b.status}`);
+        console.log(`  version: ${b.version}`);
+        console.log(`  summary: ${b.summary}`);
+        if (b.changeSummary)
+            console.log(`  change_summary: ${b.changeSummary}`);
+        if (b.supersededBy !== null)
+            console.log(`  superseded_by: #${b.supersededBy}`);
+        if (b.supersededAt)
+            console.log(`  superseded_at: ${b.supersededAt}`);
+        if (b.closedAt)
+            console.log(`  closed_at: ${b.closedAt}`);
+        if (b.memoryId)
+            console.log(`  memory: ${b.memoryId}`);
+        console.log(`  created: ${b.createdAt}`);
         return;
     }
-    console.error('Usage: hippo handoff <create|latest|show>');
-    process.exit(1);
-}
-// ---------------------------------------------------------------------------
-// E2 prediction first-class object (v0.31)
-// docs/plans/2026-05-26-e2-prediction-object.md
-// ---------------------------------------------------------------------------
-function cmdPredict(hippoRoot, args, flags) {
-    requireInit(hippoRoot);
-    const tenantId = resolveTenantId({});
-    const subcommand = args[0] ?? '';
-    if (subcommand === 'close') {
+    if (subcommand === 'supersede') {
         const idRaw = args[1];
         if (!idRaw) {
-            console.error('Usage: hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]');
+            console.error('Usage: hippo brief supersede <id> --summary "<text>" [--change "<summary>"]');
             process.exit(1);
         }
-        const id = parseInt(String(idRaw), 10);
-        if (!Number.isFinite(id) || id <= 0) {
-            console.error(`Invalid prediction id: "${idRaw}"`);
+        const id = parsePositiveBriefId(idRaw);
+        const summaryRaw = flags['summary'];
+        if (typeof summaryRaw !== 'string' || !summaryRaw.trim()) {
+            console.error('hippo brief supersede requires --summary "<text>" for the new version.');
             process.exit(1);
         }
-        const stateRaw = typeof flags['state'] === 'string' ? flags['state'].trim() : '';
-        if (!predictionsModule.VALID_CLOSURE_STATES.has(stateRaw) || stateRaw === 'open') {
-            console.error(`Invalid --state: "${stateRaw}". Must be one of: closed | closed-unknown.`);
+        const existing = briefsModule.loadProjectBriefById(hippoRoot, tenantId, id);
+        if (!existing) {
+            console.error(`Project brief ${id} not found.`);
             process.exit(1);
         }
-        const actualRaw = flags['actual'];
-        const actualValue = actualRaw !== undefined ? Number(actualRaw) : undefined;
-        if (actualRaw !== undefined && !Number.isFinite(actualValue)) {
-            console.error(`Invalid --actual: "${actualRaw}". Must be a number.`);
+        const changeRaw = flags['change'];
+        try {
+            const created = briefsModule.saveProjectBrief(hippoRoot, tenantId, {
+                repo: existing.repo,
+                summary: summaryRaw,
+                changeSummary: typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined,
+                supersedesBriefId: id,
+                extraTags: extractPathTags(process.cwd()),
+            });
+            console.log(`Project brief #${created.id} recorded (v${created.version}), superseding #${id}.`);
+            if (created.memoryId)
+                console.log(`  memory: ${created.memoryId}`);
+        }
+        catch (e) {
+            console.error(e.message);
             process.exit(1);
         }
-        const noteRaw = flags['note'];
-        const closureNote = typeof noteRaw === 'string' ? noteRaw : undefined;
-        const closed = predictionsModule.closePrediction(hippoRoot, tenantId, id, {
-            closureState: stateRaw,
-            actualValue,
-            closureNote,
+        return;
+    }
+    if (subcommand === 'close') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo brief close <id>');
+            process.exit(1);
+        }
+        const id = parsePositiveBriefId(idRaw);
+        const closed = briefsModule.closeProjectBrief(hippoRoot, tenantId, id);
+        console.log(`Project brief #${closed.id} closed.`);
+        return;
+    }
+    // Default subcommand: new (create). Accept both `brief new "<repo>"` and the
+    // bare `brief "<repo>"` form: for the `new` keyword the repo is args[1].
+    const repo = subcommand === 'new' ? (args[1] ?? '') : subcommand;
+    const summaryRaw = flags['summary'];
+    if (!repo || typeof summaryRaw !== 'string' || !summaryRaw.trim()) {
+        briefUsage();
+        process.exit(1);
+    }
+    try {
+        const created = briefsModule.saveProjectBrief(hippoRoot, tenantId, {
+            repo,
+            summary: summaryRaw,
+            extraTags: extractPathTags(process.cwd()),
         });
-        console.log(`Prediction ${closed.id} closed: state=${closed.closureState}${closed.actualValue !== null ? ` actual=${closed.actualValue}` : ''}`);
+        console.log(`Project brief recorded: #${created.id} (v${created.version}) for repo "${created.repo}"`);
+        if (created.memoryId)
+            console.log(`  memory: ${created.memoryId}`);
+    }
+    catch (e) {
+        console.error(e.message);
+        process.exit(1);
+    }
+}
+function parsePositiveNoteId(idRaw) {
+    const s = String(idRaw ?? '').trim();
+    const id = parseInt(s, 10);
+    if (!/^\d+$/.test(s) || id <= 0) {
+        console.error(`Invalid note id: "${idRaw}" (expected a positive integer).`);
+        process.exit(1);
+    }
+    return id;
+}
+function printNoteRow(n) {
+    console.log(`#${n.id} [${n.status}] v${n.version} customer="${n.customer}" memory=${n.memoryId ?? '-'}`);
+    if (n.changeSummary)
+        console.log(`    change: ${n.changeSummary}`);
+}
+function noteUsage() {
+    console.error('Usage: hippo note new "<customer>" --text "<note>"');
+    console.error('       hippo note list [--status active|superseded|closed|all] [--customer "<id>"] [--limit N]');
+    console.error('       hippo note get <id>');
+    console.error('       hippo note supersede <id> --text "<note>" [--change "<summary>"]');
+    console.error('       hippo note close <id>');
+}
+function cmdGraph(hippoRoot, args, _flags) {
+    requireInit(hippoRoot);
+    const tenantId = resolveTenantId({});
+    const subcommand = args[0] ?? '';
+    if (subcommand === 'extract') {
+        const result = extractGraph(hippoRoot, tenantId);
+        const byType = Object.entries(result.byType)
+            .map(([t, n]) => `${t} ${n}`)
+            .join(', ');
+        console.log(`Graph extracted: ${result.entities} entities (${byType}) + ${result.relations} supersedes relations.`);
+        if (result.truncated.length > 0) {
+            console.error(`WARNING: under-extracted (hit the per-type cap): ${result.truncated.join(', ')}. The graph is incomplete for those types.`);
+        }
         return;
     }
+    console.error('Usage: hippo graph extract   (rebuild the entity/relation graph from consolidated decisions/policies/customer-notes/project-briefs)');
+    process.exit(1);
+}
+function cmdCustomerNote(hippoRoot, args, flags) {
+    requireInit(hippoRoot);
+    const tenantId = resolveTenantId({});
+    const subcommand = args[0] ?? '';
     if (subcommand === 'list') {
-        const classTagRaw = flags['class'];
-        const classTag = typeof classTagRaw === 'string' ? classTagRaw.trim() : '';
         const statusRaw = flags['status'];
         const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
+        const customerRaw = flags['customer'];
+        const customer = typeof customerRaw === 'string' && customerRaw.trim() ? customerRaw.trim() : undefined;
         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 === 'open') {
-            results = predictionsModule.loadOpenPredictions(hippoRoot, tenantId, {
-                classTag: classTag || undefined,
-                limit,
-            });
-        }
-        else if (status === 'all') {
-            // No closure-state filter; pull both via loadPredictionsByClass if class given
-            if (classTag) {
-                results = predictionsModule.loadPredictionsByClass(hippoRoot, tenantId, classTag, { limit });
-            }
-            else {
-                // No class filter + status=all = pull open + closed across all classes
-                // (kept simple: report open via loadOpenPredictions; closed via two
-                // class scans isn't symmetrical. v1 callers typically pass --class.)
-                results = predictionsModule.loadOpenPredictions(hippoRoot, tenantId, { limit });
-            }
-        }
-        else {
-            if (!predictionsModule.VALID_CLOSURE_STATES.has(status)) {
-                console.error(`Invalid --status: "${status}". Must be one of: open | closed | closed-unknown | all.`);
-                process.exit(1);
-            }
-            if (classTag) {
-                results = predictionsModule.loadPredictionsByClass(hippoRoot, tenantId, classTag, {
-                    closureState: status,
-                    limit,
-                });
-            }
-            else {
-                // status filter without class — scan all classes is more complex; v1 requires --class for non-default status
-                console.error('--status filter (non-open) requires --class to be set.');
+        const opts = { limit, customer };
+        if (status !== 'all') {
+            if (!customerNotesModule.VALID_NOTE_STATES.has(status)) {
+                console.error(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
                 process.exit(1);
             }
+            opts.status = status;
         }
+        const results = customerNotesModule.loadCustomerNotes(hippoRoot, tenantId, opts);
         if (results.length === 0) {
-            console.log(classTag ? `No predictions in class "${classTag}".` : 'No predictions.');
+            console.log('No customer notes.');
             return;
         }
-        console.log(`Found ${results.length} predictions:\n`);
-        for (const p of results) {
-            const estPart = p.estimateValue !== null ? ` estimate=${p.estimateValue}${p.estimateUnit ? ` ${p.estimateUnit}` : ''}` : '';
-            const actPart = p.actualValue !== null ? ` actual=${p.actualValue}` : '';
-            const tgtPart = p.targetDate ? ` target=${p.targetDate}` : '';
-            console.log(`#${p.id} [${p.closureState}] class=${p.classTag}${estPart}${actPart}${tgtPart}`);
-            console.log(`    ${p.claimText}`);
-            if (p.closureNote)
-                console.log(`    note: ${p.closureNote}`);
+        console.log(`Found ${results.length} customer notes:\n`);
+        for (const n of results)
+            printNoteRow(n);
+        return;
+    }
+    if (subcommand === 'get') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo note get <id>');
+            process.exit(1);
+        }
+        const id = parsePositiveNoteId(idRaw);
+        const n = customerNotesModule.loadCustomerNoteById(hippoRoot, tenantId, id);
+        if (!n) {
+            console.error(`Customer note ${id} not found.`);
+            process.exit(1);
         }
+        console.log(`Customer note #${n.id}`);
+        console.log(`  customer: ${n.customer}`);
+        console.log(`  status: ${n.status}`);
+        console.log(`  version: ${n.version}`);
+        console.log(`  note: ${n.note}`);
+        if (n.changeSummary)
+            console.log(`  change_summary: ${n.changeSummary}`);
+        if (n.supersededBy !== null)
+            console.log(`  superseded_by: #${n.supersededBy}`);
+        if (n.supersededAt)
+            console.log(`  superseded_at: ${n.supersededAt}`);
+        if (n.closedAt)
+            console.log(`  closed_at: ${n.closedAt}`);
+        if (n.memoryId)
+            console.log(`  memory: ${n.memoryId}`);
+        console.log(`  created: ${n.createdAt}`);
         return;
     }
-    if (subcommand === 'show') {
+    if (subcommand === 'supersede') {
         const idRaw = args[1];
         if (!idRaw) {
-            console.error('Usage: hippo predict show <id>');
+            console.error('Usage: hippo note supersede <id> --text "<note>" [--change "<summary>"]');
             process.exit(1);
         }
-        const id = parseInt(String(idRaw), 10);
-        if (!Number.isFinite(id) || id <= 0) {
-            console.error(`Invalid prediction id: "${idRaw}"`);
+        const id = parsePositiveNoteId(idRaw);
+        const textRaw = flags['text'];
+        if (typeof textRaw !== 'string' || !textRaw.trim()) {
+            console.error('hippo note supersede requires --text "<note>" for the new version.');
             process.exit(1);
         }
-        const pred = predictionsModule.loadPredictionById(hippoRoot, tenantId, id);
-        if (!pred) {
-            console.error(`Prediction ${id} not found.`);
+        const existing = customerNotesModule.loadCustomerNoteById(hippoRoot, tenantId, id);
+        if (!existing) {
+            console.error(`Customer note ${id} not found.`);
+            process.exit(1);
+        }
+        const changeRaw = flags['change'];
+        try {
+            const created = customerNotesModule.saveCustomerNote(hippoRoot, tenantId, {
+                customer: existing.customer,
+                note: textRaw,
+                changeSummary: typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined,
+                supersedesNoteId: id,
+                extraTags: extractPathTags(process.cwd()),
+            });
+            console.log(`Customer note #${created.id} recorded (v${created.version}), superseding #${id}.`);
+            if (created.memoryId)
+                console.log(`  memory: ${created.memoryId}`);
+        }
+        catch (e) {
+            console.error(e.message);
             process.exit(1);
         }
-        console.log(`Prediction #${pred.id}`);
-        console.log(`  class: ${pred.classTag}`);
-        console.log(`  claim: ${pred.claimText}`);
-        console.log(`  state: ${pred.closureState}`);
-        if (pred.estimateValue !== null)
-            console.log(`  estimate: ${pred.estimateValue}${pred.estimateUnit ? ' ' + pred.estimateUnit : ''}`);
-        if (pred.targetDate)
-            console.log(`  target: ${pred.targetDate}`);
-        if (pred.actualValue !== null)
-            console.log(`  actual: ${pred.actualValue}`);
-        if (pred.closedAt)
-            console.log(`  closed: ${pred.closedAt}`);
-        if (pred.closureNote)
-            console.log(`  note: ${pred.closureNote}`);
-        if (pred.memoryId)
-            console.log(`  memory: ${pred.memoryId}`);
-        console.log(`  created: ${pred.createdAt}`);
         return;
     }
-    if (subcommand === 'baserate') {
-        // J3 reference-class / planning-fallacy detector
-        const classTagRaw = flags['class'];
-        if (typeof classTagRaw !== 'string' || !classTagRaw.trim()) {
-            console.error('Usage: hippo predict baserate --class <c>');
+    if (subcommand === 'close') {
+        const idRaw = args[1];
+        if (!idRaw) {
+            console.error('Usage: hippo note close <id>');
             process.exit(1);
         }
-        const baserate = predictionsModule.computePredictionBaserate(hippoRoot, tenantId, classTagRaw.trim());
-        if (baserate.nClosed === 0) {
-            console.log(`No closed predictions in class "${baserate.classTag}" yet.`);
-            console.log(`  Create one with: hippo predict "<claim>" --class ${baserate.classTag} --estimate N`);
-            console.log(`  Close it later:  hippo predict close <id> --state closed --actual N`);
-            return;
-        }
-        console.log(baserate.summary);
-        console.log(`  n_closed:         ${baserate.nClosed}`);
-        console.log(`  n_ratio_eligible: ${baserate.nRatioEligible}`);
-        if (baserate.meanEstimate !== null)
-            console.log(`  mean_estimate:    ${baserate.meanEstimate.toFixed(3)}`);
-        if (baserate.meanActual !== null)
-            console.log(`  mean_actual:      ${baserate.meanActual.toFixed(3)}`);
-        if (baserate.meanRatio !== null)
-            console.log(`  mean_ratio:       ${baserate.meanRatio.toFixed(3)}x`);
-        if (baserate.p50Ratio !== null)
-            console.log(`  p50_ratio:        ${baserate.p50Ratio.toFixed(3)}x`);
-        if (baserate.mae !== null)
-            console.log(`  mae:              ${baserate.mae.toFixed(3)}`);
+        const id = parsePositiveNoteId(idRaw);
+        const closed = customerNotesModule.closeCustomerNote(hippoRoot, tenantId, id);
+        console.log(`Customer note #${closed.id} closed.`);
         return;
     }
-    // Default subcommand: create. args[0] is the claim text.
-    const claimText = subcommand;
-    if (!claimText) {
-        console.error('Usage: hippo predict "<claim>" --class <c> [--estimate <v>] [--unit <u>] [--target <YYYY-MM-DD>]');
-        console.error('       hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]');
-        console.error('       hippo predict list [--class X] [--status open|closed|closed-unknown|all] [--limit N]');
-        console.error('       hippo predict show <id>');
+    // Default subcommand: new (create). Accept both `note new "<customer>"` and the
+    // bare `note "<customer>"` form: for the `new` keyword the customer is args[1].
+    const customer = subcommand === 'new' ? (args[1] ?? '') : subcommand;
+    const textRaw = flags['text'];
+    if (!customer || typeof textRaw !== 'string' || !textRaw.trim()) {
+        noteUsage();
         process.exit(1);
     }
-    const classTagRaw = flags['class'];
-    if (typeof classTagRaw !== 'string' || !classTagRaw.trim()) {
-        console.error('--class is required for prediction creation.');
-        process.exit(1);
+    try {
+        const created = customerNotesModule.saveCustomerNote(hippoRoot, tenantId, {
+            customer,
+            note: textRaw,
+            extraTags: extractPathTags(process.cwd()),
+        });
+        console.log(`Customer note recorded: #${created.id} (v${created.version}) for customer "${created.customer}"`);
+        if (created.memoryId)
+            console.log(`  memory: ${created.memoryId}`);
     }
-    const classTag = classTagRaw.trim();
-    const estimateRaw = flags['estimate'];
-    const estimateValue = estimateRaw !== undefined ? Number(estimateRaw) : undefined;
-    if (estimateRaw !== undefined && !Number.isFinite(estimateValue)) {
-        console.error(`Invalid --estimate: "${estimateRaw}". Must be a number.`);
+    catch (e) {
+        console.error(e.message);
         process.exit(1);
     }
-    const unitRaw = flags['unit'];
-    const estimateUnit = typeof unitRaw === 'string' ? unitRaw : undefined;
-    const targetRaw = flags['target'];
-    const targetDate = typeof targetRaw === 'string' ? targetRaw : undefined;
-    const created = predictionsModule.savePrediction(hippoRoot, tenantId, {
-        classTag,
-        claimText,
-        estimateValue,
-        estimateUnit,
-        targetDate,
-    });
-    console.log(`Prediction recorded: #${created.id} class=${created.classTag}`);
-    if (created.memoryId)
-        console.log(`  memory: ${created.memoryId}`);
 }
 function cmdCurrent(hippoRoot, args, flags) {
     requireInit(hippoRoot);
@@ -4716,6 +5989,27 @@ const VALID_AUDIT_OPS = new Set([
     '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
+    'incident_open', // E2 incident first-class object — emitted by saveIncident
+    'incident_resolve', // E2 — emitted by resolveIncident (open -> resolved)
+    'incident_close', // E2 — emitted by closeIncident (open|resolved -> closed)
+    'process_create', // E2 process first-class object — emitted by saveProcess
+    'process_supersede', // E2 — emitted by saveProcess on a supersession
+    'process_close', // E2 — emitted by closeProcess
+    'policy_create', // E2 policy first-class object — emitted by savePolicy
+    'policy_supersede', // E2 — emitted by savePolicy on a supersession
+    'policy_close', // E2 — emitted by closePolicy
+    'skill_create', // E2 skill first-class object — emitted by saveSkill
+    'skill_supersede', // E2 — emitted by saveSkill on a supersession
+    'skill_close', // E2 — emitted by closeSkill
+    'project_brief_create', // E2 project_brief first-class object — emitted by saveProjectBrief
+    'project_brief_supersede', // E2 — emitted by saveProjectBrief on a supersession (incl. refresh)
+    'project_brief_close', // E2 — emitted by closeProjectBrief
+    'customer_note_create', // E2 customer_note first-class object — emitted by saveCustomerNote
+    'customer_note_supersede', // E2 — emitted by saveCustomerNote on a supersession
+    'customer_note_close', // E2 — emitted by closeCustomerNote
 ]);
 function formatAuditRow(ev) {
     const target = ev.targetId ?? '-';
@@ -5275,6 +6569,13 @@ Commands:
     --min-results <n>      Minimum results regardless of budget (default: 1)
     --json                 Output as JSON
     --why                  Show match reasons and source annotations
+    --hops <n>             E3.2 multi-hop graph recall: also surface memories
+                           reached by walking the entities/relations graph <n>
+                           hops (0..3, default off) out from the lexical seeds.
+                           Graph hits are tagged [graph: Nhop <rel>]. Today the
+                           graph holds supersedes edges (E3.1); cross-object edges
+                           light up the same traversal once extracted.
+    --max-neighbors <n>    Per-hop fanout cap for --hops (1..200, default 25).
     --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
@@ -5502,9 +6803,82 @@ Commands:
                            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)
+  decide "<decision>"      Record a decision (first-class object + memory mirror)
     --context "<why>"      Why this decision was made
-    --supersedes <id>      Supersede a previous decision (weakens it)
+    --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
+  incident "<incident>"    Record an incident (first-class object + memory mirror)
+    --context "<details>"  What happened / surrounding detail
+    --link <mem-id>        Link a memory as evidence (repeatable)
+  incident list [--status open|resolved|closed|all] [--limit N]
+                           List incidents (table is authoritative, survives decay)
+  incident get <id>        Show an incident by its table id
+  incident resolve <id>    Resolve an open incident (open -> resolved)
+    --resolution "<text>"  How it was resolved (required)
+  incident close <id>      Retire (close) an open or resolved incident by its table id
+  process new "<name>"     Record a process map (first-class object + memory mirror)
+    --step "<text>"        An ordered step (repeatable)
+    --description "<text>" Optional summary of the process
+  process list [--status active|superseded|closed|all] [--limit N]
+                           List processes (table is authoritative, survives decay)
+  process get <id>         Show a process (with its steps) by its table id
+  process supersede <id>   Record a new version that supersedes an active process
+    --step "<text>"        A step of the new version (repeatable, required)
+    --change "<summary>"   What changed in this version (the delta note)
+    --description "<text>" Optional summary of the new version
+  process close <id>       Retire (close) an active process by its table id
+  policy new "<name>"      Record a policy (bi-temporal first-class object + mirror)
+    --text "<rule>"        The policy rule/statement (required)
+    --from "<iso>"         Effective-from date (default: now)
+    --to "<iso>"           Effective-to date (optional; open-ended if omitted)
+  policy list [--status active|superseded|closed|all] [--limit N]
+                           List policies (table is authoritative, survives decay)
+  policy get <id>          Show a policy by its table id
+  policy asof "<iso-date>" Show active policies in force at a valid-time
+    --name "<policy>"      Filter to one policy by name
+  policy supersede <id>    Record a new version that supersedes an active policy
+    --text "<rule>"        The new rule (required)
+    --from "<iso>"         New effective-from (default: now)
+    --to "<iso>"           New effective-to (optional)
+    --change "<summary>"   What changed in this version (the delta note)
+  policy close <id>        Retire (close) an active policy by its table id
+  skill new "<name>"       Record a skill (reusable agent-followable capability)
+    --instructions "<txt>" The skill body (required)
+    --trigger "<when>"     Optional: when to apply this skill
+  skill list [--status active|superseded|closed|all] [--limit N]
+                           List skills (table is authoritative, survives decay)
+  skill get <id>           Show a skill by its table id
+  skill export             Render active skills as an AGENTS.md/CLAUDE.md markdown block
+  skill supersede <id>     Record a new version that supersedes an active skill
+    --instructions "<txt>" The new skill body (required)
+    --trigger "<when>"     Optional new trigger
+    --change "<summary>"   What changed in this version (the delta note)
+  skill close <id>         Retire (close) an active skill by its table id
+  brief new "<repo>"       Record a repo-scoped project brief
+    --summary "<text>"     The brief body (required)
+  brief list [--status active|superseded|closed|all] [--repo "<repo>"] [--limit N]
+                           List project briefs (table is authoritative, survives decay)
+  brief get <id>           Show a project brief by its table id
+  brief supersede <id>     Record a new version that supersedes an active brief
+    --summary "<text>"     The new brief body (required)
+    --change "<summary>"   What changed in this version (the delta note)
+  brief close <id>         Retire (close) an active project brief by its table id
+  brief refresh "<repo>"   Auto-assemble the brief from the repo's receipts (path:<repo>)
+    --dry-run              Print the assembled brief without writing it
+  note new "<customer>"    Record a customer/account-scoped note
+    --text "<note>"        The note body (required)
+  note list [--status active|superseded|closed|all] [--customer "<id>"] [--limit N]
+                           List customer notes (table is authoritative, survives decay)
+  note get <id>            Show a customer note by its table id
+  note supersede <id>      Record a new version that supersedes an active note
+    --text "<note>"        The new note body (required)
+    --change "<summary>"   What changed in this version (the delta note)
+  note close <id>          Retire (close) an active customer note by its table id
+  graph extract            Rebuild the entity/relation graph from consolidated objects
+                           (decisions/policies/customer-notes/project-briefs); idempotent
   invalidate "<pattern>"   Actively weaken memories matching an old pattern
     --reason "<why>"       Optional: what replaced it
   wm <sub>                 Working memory — bounded buffer for current state
@@ -5586,6 +6960,17 @@ Examples:
   hippo setup
   hippo hook install claude-code
   hippo decide "Use PostgreSQL for new services" --context "JSONB support"
+  hippo incident "Prod outage: DB connection pool exhausted" --context "spike at 14:00"
+  hippo process new "Release" --step "run tests" --step "bump version" --step "publish"
+  hippo policy new "Data retention" --text "Delete logs after 90 days" --from 2026-01-01
+  hippo policy asof 2026-03-01 --name "Data retention"
+  hippo skill new "Run tests" --instructions "npm test before every commit" --trigger "before commit"
+  hippo skill export
+  hippo brief new "hippo" --summary "Agent-memory library; E2 first-class objects in progress"
+  hippo brief refresh "hippo"
+  hippo note new "Acme Corp" --text "Renewal call: wants SSO before Q3; champion is the VP Eng"
+  hippo note list --customer "Acme Corp" --status active
+  hippo graph extract
   hippo invalidate "REST API" --reason "migrated to GraphQL"
   hippo export memories.json
   hippo export --format markdown memories.md
@@ -6189,52 +7574,32 @@ 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 'incident':
+            cmdIncident(hippoRoot, args, flags);
+            break;
+        case 'process':
+            cmdProcess(hippoRoot, args, flags);
+            break;
+        case 'policy':
+            cmdPolicy(hippoRoot, args, flags);
+            break;
+        case 'skill':
+            cmdSkill(hippoRoot, args, flags);
+            break;
+        case 'brief':
+        case 'project-brief':
+            cmdProjectBrief(hippoRoot, args, flags);
+            break;
+        case 'note':
+        case 'customer-note':
+            cmdCustomerNote(hippoRoot, args, flags);
+            break;
+        case 'graph':
+            cmdGraph(hippoRoot, args, flags);
             break;
-        }
         case 'help':
         case '--help':
         case '-h':