hippo-memory 1.12.12 → 1.13.1

package/dist/cli.js

@@ -56,6 +56,8 @@ import { listApiKeys, revokeApiKey } from './auth.js';
 import { buildProvenanceCoverage } from './provenance-coverage.js';
 import { buildCorrectionLatency } from './correction-latency.js';
 import * as api from './api.js';
+import * as predictionsModule from './predictions.js';
+import { computePlanningFallacyHint } from './predictions.js';
 import * as client from './client.js';
 import { detectServer, removePidfileIfOwned } from './server-detect.js';
 import { resolveTenantId } from './tenant.js';
@@ -682,6 +684,13 @@ async function cmdRecall(hippoRoot, query, flags) {
     const tenantId = resolveTenantId({});
     let localEntries = loadSearchEntries(hippoRoot, query, undefined, tenantId);
     let globalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query, undefined, tenantId) : [];
+    // v1.12.13 / C5 — WYSIATI counters. Track filter activity per the plan v3
+    // Task 3 mapping table. dropped_pre_rank is the SUM of all non-budget
+    // filter drops (pre-rank AND post-rank). Search-engine internal drops
+    // (scored-to-zero rows that hybridSearch/physicsSearch returns fewer of)
+    // are NOT counted in v1 — they are part of the rank step, not a filter.
+    const totalCandidatesCountCmd = localEntries.length + globalEntries.length;
+    let droppedPreRankCountCmd = 0;
     // Bi-temporal filtering for physics path (hybridSearch handles it internally)
     if (asOf) {
         const filterAsOf = (entries) => {
@@ -703,12 +712,16 @@ async function cmdRecall(hippoRoot, query, flags) {
                 return succVf ? new Date(succVf) > asOfDate : true;
             });
         };
+        const beforeAsOf = localEntries.length + globalEntries.length;
         localEntries = filterAsOf(localEntries);
         globalEntries = filterAsOf(globalEntries);
+        droppedPreRankCountCmd += beforeAsOf - (localEntries.length + globalEntries.length);
     }
     else if (!includeSuperseded) {
+        const beforeSupersededDrop = localEntries.length + globalEntries.length;
         localEntries = localEntries.filter(e => !e.superseded_by);
         globalEntries = globalEntries.filter(e => !e.superseded_by);
+        droppedPreRankCountCmd += beforeSupersededDrop - (localEntries.length + globalEntries.length);
     }
     const hasGlobal = globalEntries.length > 0;
     // Determine search mode: --physics forces physics, --classic forces BM25+cosine,
@@ -817,7 +830,9 @@ async function cmdRecall(hippoRoot, query, flags) {
     // We never infer conflicts from lexical overlap. The v1 salience gate did
     // that and destroyed LoCoMo (0.28 → 0.02). Recorded structure only.
     if (flags['filter-conflicts']) {
+        const beforeFilterConflicts = results.length;
         results = results.filter((r) => !r.entry.superseded_by);
+        droppedPreRankCountCmd += beforeFilterConflicts - results.length;
         const presentIds = new Set(results.map((r) => r.entry.id));
         results = results.map((r) => {
             const peers = r.entry.conflicts_with || [];
@@ -981,11 +996,13 @@ async function cmdRecall(hippoRoot, query, flags) {
             console.error(`Invalid --outcome: "${outcomeFilter}". Must be one of: ${validOutcomes.join(', ')}.`);
             process.exit(1);
         }
+        const beforeOutcomeFilter = results.length;
         results = results.filter((r) => {
             if (r.entry.layer !== Layer.Trace)
                 return true;
             return r.entry.trace_outcome === outcomeFilter;
         });
+        droppedPreRankCountCmd += beforeOutcomeFilter - results.length;
     }
     // --layer filter: strict, drops entries whose layer does not match.
     const layerFilter = flags['layer'] !== undefined ? String(flags['layer']).trim() : '';
@@ -995,11 +1012,38 @@ async function cmdRecall(hippoRoot, query, flags) {
             console.error(`Invalid --layer: "${layerFilter}". Must be one of: ${validLayers.join(', ')}.`);
             process.exit(1);
         }
+        const beforeLayerFilter = results.length;
         results = results.filter((r) => r.entry.layer === layerFilter);
+        droppedPreRankCountCmd += beforeLayerFilter - results.length;
     }
+    // v1.12.13 / C5 — WYSIATI dropped_by_budget counter (final limit cut).
+    let droppedByBudgetCountCmd = 0;
     if (limit < results.length) {
+        droppedByBudgetCountCmd = results.length - limit;
         results = results.slice(0, limit);
     }
+    // v1.12.13 / C5 — Build suppressionSummary for cmdRecall pipeline. Surfaced
+    // in --why text output and in the --json JSON output. cmdRecall does not
+    // run the summarizeOverflow path (api.recall does) and does not currently
+    // expose fresh-tail in the CLI, so those two counters are 0 here.
+    const cmdSuppressionSummary = api.buildSuppressionSummary({
+        totalCandidates: totalCandidatesCountCmd,
+        droppedPreRank: droppedPreRankCountCmd,
+        droppedByBudget: droppedByBudgetCountCmd,
+        summarySubstitutionsAdded: 0,
+        freshTailAdded: 0,
+        suppressedByInterference: 0,
+    });
+    // v0.32 / J3.2 — auto-injection of reference-class baserate when the
+    // CLI query carries a forward-prediction phrase AND a class matches.
+    // cmdRecall runs its own pipeline (doesn't go through api.recall for
+    // the memory list), so it computes the hint here. The hint VALUE is
+    // pipeline-invariant — same (hippoRoot, tenantId, query) inputs would
+    // produce the same hint in api.recall — but the audit emission is
+    // pipeline-local (one audit row per actual call, actor='cli' here).
+    // computePlanningFallacyHint short-circuits BEFORE the regex gate
+    // when HIPPO_AUTODEBIAS=off so the no-match path is effectively free.
+    const cmdPlanningFallacyHint = computePlanningFallacyHint(hippoRoot, tenantId, query, { actor: 'cli' });
     // A5 audit: emit one 'recall' event per query, capturing the (truncated)
     // query text and the post-filter result count. Tenant resolved by emitCliAudit.
     // Emit before the early-empty return so zero-result recalls are still logged.
@@ -1079,7 +1123,19 @@ async function cmdRecall(hippoRoot, query, flags) {
         || recentSessionEvents.length > 0;
     if (results.length === 0) {
         if (asJson) {
-            const out = { query, results: [], total: 0 };
+            const out = {
+                query,
+                results: [],
+                total: 0,
+                suppressionSummary: cmdSuppressionSummary,
+                // v0.32 / J3.2 — preserve planningFallacyHint on zero-result
+                // recalls. Codex review round 1 catch: hint was previously only
+                // included in the populated-results JSON branch, breaking parity
+                // with HTTP/MCP which surface the hint regardless of memory
+                // matches. A forward-claim query that finds no memories STILL
+                // produces useful planning-fallacy debias when the class resolves.
+                ...(cmdPlanningFallacyHint ? { planningFallacyHint: cmdPlanningFallacyHint } : {}),
+            };
             if (includeContinuity) {
                 out.continuity = {
                     activeSnapshot,
@@ -1091,6 +1147,15 @@ async function cmdRecall(hippoRoot, query, flags) {
             console.log(JSON.stringify(out));
             return;
         }
+        // v0.32 / J3.2 — render hint BEFORE the no-memories message so the
+        // calling agent sees its track record even when the query missed
+        // every memory. Same single-line shape + JSON.stringify-safe phrase
+        // as the populated-results path below.
+        if (cmdPlanningFallacyHint) {
+            const safePhrase = JSON.stringify(cmdPlanningFallacyHint.detectedPhrase);
+            console.log(`Planning fallacy hint (class: ${cmdPlanningFallacyHint.classTag}): ${cmdPlanningFallacyHint.baserateSummary} [detected: ${safePhrase}]`);
+            console.log();
+        }
         if (hasContinuity) {
             // Print continuity even when no memories matched. The resume packet
             // is the whole point of `--continuity` and must not be dropped here.
@@ -1149,7 +1214,14 @@ async function cmdRecall(hippoRoot, query, flags) {
             }
             return base;
         });
-        const jsonOut = { query, budget, results: output, total: output.length };
+        const jsonOut = {
+            query,
+            budget,
+            results: output,
+            total: output.length,
+            suppressionSummary: cmdSuppressionSummary,
+            ...(cmdPlanningFallacyHint ? { planningFallacyHint: cmdPlanningFallacyHint } : {}),
+        };
         if (includeContinuity) {
             jsonOut.continuity = {
                 activeSnapshot,
@@ -1170,6 +1242,17 @@ async function cmdRecall(hippoRoot, query, flags) {
         if (recentSessionEvents.length > 0)
             printSessionEvents(recentSessionEvents);
     }
+    // v0.32 / J3.2 — render planning-fallacy hint ABOVE the result list so
+    // the agent sees its track record before scrolling. Hint absent (env
+    // disabled or no forward-claim match) is silent. detectedPhrase is
+    // sanitised against control chars and ASCII quotes via JSON.stringify
+    // to head off rendering ambiguity when a regex match contains quotes
+    // or parens (plan-eng-critic round 2 LOW).
+    if (cmdPlanningFallacyHint) {
+        const safePhrase = JSON.stringify(cmdPlanningFallacyHint.detectedPhrase);
+        console.log(`Planning fallacy hint (class: ${cmdPlanningFallacyHint.classTag}): ${cmdPlanningFallacyHint.baserateSummary} [detected: ${safePhrase}]`);
+        console.log();
+    }
     console.log(`Found ${results.length} memories (${totalTokens} tokens) for: "${query}"\n`);
     for (const r of results) {
         const e = r.entry;
@@ -1204,6 +1287,30 @@ async function cmdRecall(hippoRoot, query, flags) {
         console.log(e.content);
         console.log();
     }
+    // v1.12.13 / C5 — WYSIATI cutoff transparency in --why text output.
+    // Single-line summary after the result list, emitted only when --why is
+    // set AND at least one counter is non-zero. Skip zero-count clauses to
+    // keep the line tight. The calling agent uses this to spot when the
+    // shown set is a small slice of a much larger candidate pool (Kahneman
+    // "What You See Is All There Is" failure mode).
+    if (showWhy) {
+        const s = cmdSuppressionSummary;
+        const clauses = [];
+        if (s.droppedByBudget > 0)
+            clauses.push(`${s.droppedByBudget} dropped by limit`);
+        if (s.droppedPreRank > 0)
+            clauses.push(`${s.droppedPreRank} pre-rank filtered`);
+        if (s.summarySubstitutionsAdded > 0)
+            clauses.push(`${s.summarySubstitutionsAdded} summary substitutions added`);
+        if (s.freshTailAdded > 0)
+            clauses.push(`${s.freshTailAdded} fresh-tail added`);
+        if (s.suppressedByInterference > 0)
+            clauses.push(`${s.suppressedByInterference} suppressed by interference`);
+        if (clauses.length > 0) {
+            console.log(`WYSIATI: showing ${results.length}/${s.totalCandidates}; ${clauses.join('; ')}.`);
+            console.log();
+        }
+    }
 }
 async function cmdExplain(hippoRoot, query, flags) {
     requireInit(hippoRoot);
@@ -2840,6 +2947,209 @@ function cmdHandoff(hippoRoot, args, flags) {
     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 cmdCurrent(hippoRoot, args, flags) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
@@ -4244,6 +4554,12 @@ const VALID_AUDIT_OPS = new Set([
     'summary_marked_dirty', // v0.30 / E1 — lockstep with AuditOp union + server.ts VALID_AUDIT_OPS (v1.11.5 CRIT A institutional rule)
     'summary_marked_clean', // v0.30 / E3 — buildDag post-link clean op; lockstep
     'summary_rebuilt', // v0.30 / E3 — sleep-cycle rebuild op; lockstep
+    'predict_create', // v0.31 / E2 prediction first-class object — emitted by savePrediction
+    'predict_close', // v0.31 / E2 — emitted by closePrediction
+    'predict_baserate', // v0.31 / J3 — emitted by computePredictionBaserate
+    'recall_autodebias_hint', // v0.32 / J3.2 — emitted by computePlanningFallacyHint on success
+    'recall_autodebias_hint_no_class_match', // v0.32 / J3.2 — telemetry: forward-claim, no class scored
+    'recall_autodebias_hint_tiebreak', // v0.32 / J3.2 — telemetry: forward-claim, >=2 classes tied
 ]);
 function formatAuditRow(ev) {
     const target = ev.targetId ?? '-';
@@ -5426,6 +5742,9 @@ async function main() {
         case 'handoff':
             cmdHandoff(hippoRoot, args, flags);
             break;
+        case 'predict':
+            cmdPredict(hippoRoot, args, flags);
+            break;
         case 'current':
             cmdCurrent(hippoRoot, args, flags);
             break;