hippo-memory 1.69.0 → 1.71.0

package/dist/cli/recall.js

@@ -1,46 +1,23 @@
 // The `hippo recall` verb; main() loads it lazily from the command table.
-import { envHippoSessionId } from '../env.js';
-import { confidenceFacets, Layer } from '../memory.js';
-import { isInitialized } from '../store/open.js';
-import { strengthenRetrieved } from '../store/entry-writes.js';
-import { isRecallBoostAblated } from '../ablation.js';
-import { loadIndex, saveIndex, updateStats } from '../store/index-and-stats.js';
-import { loadActiveTaskSnapshot, listSessionEvents } from '../store/sessions.js';
-import { loadLatestHandoff } from '../store/handoffs.js';
-import { passesScopeFilterForRecall } from '../recall-scope.js';
-import { fitBudget } from '../search/finalize.js';
-import { explainMatch } from '../search/explain.js';
-import { DEFAULT_RECALL_BUDGET } from '../search/types.js';
-import { writeRecallTraceAtRoot } from '../recall-trace.js';
-import { loadConfig } from '../config.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { estimateTokens, recordTokenUse } from '../token-ledger.js';
-import { writeGoalRecallLog } from '../goals.js';
-import { dropHeldCopies } from '../same-text.js';
-import { isGlobalStoreRoot } from '../project-identity.js';
-import { detectScope } from '../scope.js';
-import { getGlobalRoot } from '../shared.js';
-import * as api from '../api.js';
-import { computePlanningFallacyOutput } from '../predictions/planning-fallacy.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled, snapshotRing } from '../recall-history.js';
-import { appendRecallAudit, recallAuditMetadata, recordShownRecall, resetSessionRings, sessionRing } from '../api/recall-record.js';
-import { detectAvailabilityBias } from '../availability.js';
-import { resolveTenantId } from '../tenant.js';
-import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from '../graph-recall.js';
-import { getReranker } from '../rerankers/index.js';
-import { rankRecall, } from '../recall-pipeline.js';
-import { JEV_DEFAULT_TOP_K } from '../rerankers/jev.js';
-import { isClefModel } from '../rerankers/clef.js';
-import { handoffText, printedTokens, sessionTrailText, settleTokens, snapshotText } from '../context-render.js';
-import { withLedgerDb } from '../ledger-db.js';
+import { envHippoSessionId } from '../util/env.js';
+import { Layer } from '../core/memory.js';
+import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
+import { loadConfig } from '../core/config.js';
+import { estimateTokens } from '../util/token-text.js';
+import { dropHeldCopies } from '../util/same-text.js';
+import * as api from '../api/index.js';
+import { detectAnchoring, hashQueryText, biasHintEnabled, snapshotRing } from '../api/recall-history.js';
+import { sessionRing, shownRecallRows } from '../api/recall-record.js';
+import { detectAvailabilityBias } from '../api/availability.js';
+import { cliRecallOrigin, cliRecallReranker, cliRecallSetting, DEFAULT_MAX_NEIGHBORS, fitRecallRows, loadCliRecallContinuity, MAX_HOPS, recallJsonRow, } from '../api/recall-cli.js';
+import { cliApiContext } from './api-context.js';
+import { handoffText, printedTokens, sessionTrailText, settleTokens, snapshotText } from '../api/context-render.js';
 import { printError } from './output.js';
-import { parseLimitFlag, parseBudgetFlag, requireInit, recallEntryText, recallHeading, parseAsOfFlag, engineFlags, printActiveTaskSnapshot, printSessionEvents, printHandoff, hostSessionId, captureConsole, hookStoreRoot, } from './shared.js';
-// Per-process rings: a single-shot `hippo recall` starts empty, so anchoring only accumulates in long-lived
-// hosts (in-process loops, `hippo serve`, the MCP server).
-/** Test-only: reset the CLI recall rings. Call from beforeEach. */
-export function __resetSessionRecallHistoryCli() {
-    resetSessionRings('cli');
-}
+import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag, flagIsTrue, isBooleanFlag, } from './flag-values.js';
+import { requireInit } from './shared.js';
+import { recallEntryText, recallHeading, printActiveTaskSnapshot, printSessionEvents, printHandoff, captureConsole } from './print.js';
+import { hostSessionId, hookStoreRoot } from './hook-runtime.js';
+import { CliExit } from './exit.js';
 // JSON.stringify keeps quotes or parens in the matched phrase from blurring the line.
 function planningLine(p) {
     if (p.hint)
@@ -67,14 +44,14 @@ function cutoffLine(shown, s) {
 function failWith(message) {
     return () => {
         printError(message);
-        process.exit(1);
+        throw new CliExit(1);
     };
 }
 /** `--graph-stream` implies rrf fusion as well as the graph stream; the CLI fuses the local store only. */
 function parseGraphStreamFlags(flags) {
     let hops;
     if (flags['graph-hops'] !== undefined) {
-        if (typeof flags['graph-hops'] === 'boolean')
+        if (isBooleanFlag(flags['graph-hops']))
             failWith(`--graph-hops requires an integer value 1..${MAX_HOPS} (e.g. --graph-hops 2).`)();
         const h = Number(flags['graph-hops']);
         if (!Number.isInteger(h) || h < 1 || h > MAX_HOPS) {
@@ -84,7 +61,7 @@ function parseGraphStreamFlags(flags) {
     }
     let seeds;
     if (flags['graph-seeds'] !== undefined) {
-        if (typeof flags['graph-seeds'] === 'boolean')
+        if (isBooleanFlag(flags['graph-seeds']))
             failWith('--graph-seeds requires a positive integer value (e.g. --graph-seeds 10).')();
         const s = Number(flags['graph-seeds']);
         if (!Number.isInteger(s) || s < 1)
@@ -97,7 +74,7 @@ function parseHopsFlags(flags) {
     if (flags['hops'] === undefined)
         return {};
     // A value-less `--hops` parses as true, and Number(true) === 1 would silently run a 1-hop expansion.
-    if (typeof flags['hops'] === 'boolean')
+    if (isBooleanFlag(flags['hops']))
         return { fail: failWith(`--hops requires an integer value 0..${MAX_HOPS} (e.g. --hops 1).`) };
     const hops = Number(flags['hops']);
     if (!Number.isInteger(hops) || hops < 0 || hops > MAX_HOPS) {
@@ -106,7 +83,7 @@ function parseHopsFlags(flags) {
     const raw = flags['max-neighbors'];
     if (raw === undefined)
         return { value: { hops, maxNeighbors: DEFAULT_MAX_NEIGHBORS } };
-    if (typeof raw === 'boolean')
+    if (isBooleanFlag(raw))
         return { fail: failWith(`--max-neighbors requires an integer value 1..200.`) };
     const maxNeighbors = Number(raw);
     if (!Number.isInteger(maxNeighbors) || maxNeighbors < 1 || maxNeighbors > 200) {
@@ -116,18 +93,19 @@ function parseHopsFlags(flags) {
 }
 function parseRerankerFlag(flags) {
     const name = flags['reranker'] !== undefined ? String(flags['reranker']).trim() : '';
-    let fn;
+    let picked;
     try {
-        fn = getReranker(name);
+        picked = cliRecallReranker(name);
     }
     catch (err) {
         // An unknown name throws to the top-level handler, as it did when the lookup sat mid-pipeline.
         return { fail: () => { throw err; } };
     }
-    if (!fn)
+    if (!picked)
         return {};
+    const { fn } = picked;
     const raw = flags['reranker-top-k'];
-    const topK = raw !== undefined ? Number(raw) : name === 'jev' || isClefModel(name) ? JEV_DEFAULT_TOP_K : 50;
+    const topK = raw !== undefined ? Number(raw) : picked.defaultTopK;
     // slice(0, -1) would quietly drop the last candidate rather than fail.
     if (!Number.isInteger(topK) || topK < 1) {
         return { fail: failWith(`Invalid --reranker-top-k: "${String(raw)}". Must be a positive integer.`) };
@@ -178,102 +156,89 @@ function parseRecallLateFlags(flags) {
         error,
     };
 }
-/** Runs `hippo recall`: parse, rank, load continuity, fit the printed block to the budget, audit, then write and print. */
-export async function cmdRecall(hippoRoot, query, flags) {
+/** Runs `hippo recall`: the flags name the ranking core and this verb's presenter, `retrieve` ranks and records, then the block prints. */
+async function cmdRecall(hippoRoot, tenantId, query, flags) {
     requireInit(hippoRoot);
-    const o = parseRecallOptions(hippoRoot, flags);
-    const ranked = await rankForRecall(hippoRoot, query, flags, o);
-    const fit = fitRecallBlock(hippoRoot, query, o, ranked, loadRecallContinuity(hippoRoot, o));
-    auditRecall(hippoRoot, o, query, fit);
-    writeRecallResult(hippoRoot, query, o, fit, ranked.localIndex);
+    const ctx = cliApiContext(hippoRoot, tenantId);
+    const o = parseRecallOptions(ctx, flags);
+    const priced = priceRecallEntries(ctx, query, o);
+    const { globalRoot } = o.setting;
+    const slot = {};
+    await api.retrieve(ctx, {
+        query,
+        goalTag: o.goalTag,
+        sessionId: o.sessionId,
+        cliCore: {
+            rank: rankOptions(query, flags, o, priced),
+            // The global store is a second source for this surface alone, and never when it is the store being searched.
+            sources: { globalRoot: globalRoot !== hippoRoot && priced.globalOn ? globalRoot : undefined },
+            note: (line) => printError(line),
+            hostSessionId: hostSessionId(),
+            show: (rank, planning) => {
+                slot.presented = presentRecall(ctx, query, o, { rank, ...priced }, planning);
+                return slot.presented.shown;
+            },
+        },
+    });
+    // A late flag is rejected where the ranking halted, after the notes its earlier stages printed.
+    o.late.error?.fail();
+    if (!slot.presented)
+        throw new Error('recall ranked but presented nothing');
+    console.log(slot.presented.text);
 }
 /** Every flag recall reads, parsed in the order the single-body command checked them. */
-function parseRecallOptions(hippoRoot, flags) {
+function parseRecallOptions(ctx, flags) {
     const budget = parseBudgetFlag(flags['budget'], DEFAULT_RECALL_BUDGET);
     const limit = parseLimitFlag(flags['limit']);
-    const asJson = Boolean(flags['json']);
-    const showWhy = Boolean(flags['why']);
-    const includeSuperseded = Boolean(flags['include-superseded']);
+    const asJson = boolFlag(flags, 'json');
+    const showWhy = boolFlag(flags, 'why');
+    const includeSuperseded = boolFlag(flags, 'include-superseded');
     const asOf = parseAsOfFlag(flags);
-    const globalRoot = getGlobalRoot();
-    const primaryIsGlobal = isGlobalStoreRoot(hippoRoot);
-    // Cross-tenant rows must never surface, so the tenant is resolved once and threaded through every load.
-    const tenantId = resolveTenantId({});
     // The explicit --scope is the filter input; the detected scope only boosts, so auto-detection never filters.
     const explicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
-    const config = loadConfig(hippoRoot);
+    const setting = cliRecallSetting(ctx, explicitScope);
+    const config = loadConfig(ctx.hippoRoot);
     const minResults = flags['min-results'] !== undefined
         ? parseInt(String(flags['min-results']), 10)
         : undefined;
-    const activeScope = explicitScope || detectScope();
-    const graphStream = flags['graph-stream'] === true ? parseGraphStreamFlags(flags) : undefined;
+    const graphStream = flagIsTrue(flags, 'graph-stream') ? parseGraphStreamFlags(flags) : undefined;
     const late = parseRecallLateFlags(flags);
     const goalTag = flags['goal'] !== undefined ? String(flags['goal']).trim() : '';
     const sessionId = (flags['session-id'] !== undefined
         ? String(flags['session-id'])
         : envHippoSessionId() ?? '').trim();
     return {
-        budget, limit, asJson, showWhy, includeSuperseded, asOf, globalRoot, primaryIsGlobal, tenantId,
-        explicitScope, config, minResults, activeScope, graphStream, late, goalTag, sessionId,
-        includeContinuity: Boolean(flags['continuity']),
+        budget, limit, asJson, showWhy, includeSuperseded, asOf, setting, tenantId: ctx.tenantId,
+        explicitScope, config, minResults, graphStream, late, goalTag, sessionId,
+        includeContinuity: boolFlag(flags, 'continuity'),
     };
 }
-/** Ranks against each entry's printed cost, then rejects a late flag at the stage where the pipeline halted. */
-async function rankForRecall(hippoRoot, query, flags, o) {
-    // Engines spend the budget on the text each result prints as, less the header, so selection and print agree.
-    const localIndex = loadIndex(hippoRoot);
-    const globalOn = isInitialized(o.globalRoot);
-    const entryText = (r) => recallEntryText(r, query, o.showWhy, o.primaryIsGlobal || (globalOn && !localIndex.entries[r.entry.id]));
+/** Each entry priced as the line it prints, with the source marker `--why` shows. */
+function priceRecallEntries(ctx, query, o) {
+    const origin = cliRecallOrigin(ctx, o.setting);
+    const isGlobal = (r) => origin.isGlobal(r.entry.id);
+    const entryText = (r) => recallEntryText(r, query, o.showWhy, isGlobal(r));
     const printCost = (r) => printedTokens(entryText(r));
+    return { globalOn: origin.globalOn, isGlobal, entryText, printCost };
+}
+/** The ranking core's options; a late flag error halts it before the stage that reads the flag. */
+function rankOptions(query, flags, o, priced) {
+    // Engines spend the budget on the text each result prints as, less the header, so selection and print agree.
     const entryBudget = Math.max(0, o.budget - printedTokens(recallHeading(o.budget, o.budget, query)));
-    const rank = await rankRecall({ hippoRoot, globalRoot: o.globalRoot !== hippoRoot && globalOn ? o.globalRoot : undefined, tenantId: o.tenantId, note: (line) => printError(line) }, {
-        query, budget: entryBudget, cost: printCost, limit: o.limit, why: o.showWhy, includeSuperseded: o.includeSuperseded, asOf: o.asOf,
-        explicitScope: o.explicitScope, activeScope: o.activeScope,
-        search: { ...engineFlags(flags, o.config), multihop: flags['multihop'] === true || o.config.multihop.enabled, graphStream: o.graphStream, minResults: o.minResults, explain: false },
+    return {
+        budget: entryBudget, cost: priced.printCost, limit: o.limit, why: o.showWhy, includeSuperseded: o.includeSuperseded, asOf: o.asOf,
+        explicitScope: o.explicitScope, activeScope: o.setting.activeScope,
+        search: { ...engineFlags(flags, o.config), multihop: flagIsTrue(flags, 'multihop') || o.config.multihop.enabled, graphStream: o.graphStream, minResults: o.minResults, explain: false },
         graphHops: o.late.graphHops,
-        evcAdaptive: Boolean(flags['evc-adaptive']),
-        filterConflicts: Boolean(flags['filter-conflicts']),
-        valueAware: Boolean(flags['value-aware']),
-        rerankUtility: Boolean(flags['rerank-utility']),
+        evcAdaptive: boolFlag(flags, 'evc-adaptive'),
+        filterConflicts: boolFlag(flags, 'filter-conflicts'),
+        valueAware: boolFlag(flags, 'value-aware'),
+        rerankUtility: boolFlag(flags, 'rerank-utility'),
         reranker: o.late.reranker,
-        goalTag: o.goalTag,
-        sessionId: o.sessionId,
         salienceThreshold: o.late.salienceThreshold,
         outcome: o.late.outcome,
         layer: o.late.layer,
         haltBefore: o.late.error?.stage,
-    });
-    if (rank.goalRecallLog.length > 0) {
-        const dbForGoals = openHippoDb(hippoRoot);
-        try {
-            writeGoalRecallLog(dbForGoals, rank.goalRecallLog);
-        }
-        finally {
-            closeHippoDb(dbForGoals);
-        }
-    }
-    o.late.error?.fail();
-    return { rank, localIndex, entryText, printCost };
-}
-/** Loaded before the zero-result branch, so a no-match query with live continuity still returns a resume packet. */
-function loadRecallContinuity(hippoRoot, o) {
-    if (!o.includeContinuity || o.primaryIsGlobal)
-        return { activeSnapshot: null, sessionHandoff: null, recentSessionEvents: [] };
-    const rawSnapshot = loadActiveTaskSnapshot(hippoRoot, o.tenantId);
-    const sessionId = rawSnapshot?.session_id ?? undefined;
-    const rawHandoff = sessionId
-        ? loadLatestHandoff(hippoRoot, o.tenantId, sessionId)
-        : null;
-    const rawEvents = sessionId
-        ? listSessionEvents(hippoRoot, o.tenantId, { session_id: sessionId, limit: 5 })
-        : [];
-    // The same shared scope rule as api.recall; the active scope merges --scope and detectScope().
-    const effectiveScope = o.activeScope || undefined;
-    const rowScope = (r) => r?.scope ?? null;
-    return {
-        activeSnapshot: rawSnapshot && passesScopeFilterForRecall(rowScope(rawSnapshot), effectiveScope) ? rawSnapshot : null,
-        sessionHandoff: rawHandoff && passesScopeFilterForRecall(rowScope(rawHandoff), effectiveScope) ? rawHandoff : null,
-        recentSessionEvents: rawEvents.filter((e) => passesScopeFilterForRecall(rowScope(e), effectiveScope)),
     };
 }
 /** Each pipeline computes its hints over the list it returns, so they follow the list as it shrinks. */
@@ -290,7 +255,7 @@ function recallHinter(query, o, rank) {
         const availability = availabilityPool
             ? detectAvailabilityBias({ topK: list.map((r) => ({ id: r.entry.id, created: r.entry.created })), pool: availabilityPool })
             : null;
-        const summary = api.buildSuppressionSummary({
+        const summary = {
             // The published total includes graph-surfaced rows, so total == preRank + byBudget + returned holds for callers.
             totalCandidates: rank.totalCandidates + rank.graphAdded,
             droppedPreRank: rank.droppedPreRank + held,
@@ -298,7 +263,7 @@ function recallHinter(query, o, rank) {
             summarySubstitutionsAdded: 0,
             freshTailAdded: 0,
             suppressedByInterference: anchoring?.reason === 'memory_dominance' ? 1 : 0, // a query_repeat is a re-ask, not competition
-        });
+        };
         return { anchoring, availability, summary };
     };
     return { anchorRing, hintsFor };
@@ -355,7 +320,7 @@ function renderRecallBlock(list, h, v) {
     }));
 }
 /** Pays the continuity sections and the plan hint first, then fits the memories into what is left. */
-function fitRecallBlock(hippoRoot, query, o, ranked, loaded) {
+function fitRecallBlock(query, o, ranked, loaded, planning) {
     const { budget } = o;
     let { activeSnapshot, sessionHandoff, recentSessionEvents } = loaded;
     // Sections print ahead of the memories, so they are paid first, after the header; one that does not fit is dropped.
@@ -372,15 +337,14 @@ function fitRecallBlock(hippoRoot, query, o, ranked, loaded) {
     const continuityTokens = sectionBudget - left;
     const continuity = { activeSnapshot, sessionHandoff, recentSessionEvents };
     const hasContinuity = activeSnapshot !== null || sessionHandoff !== null || recentSessionEvents.length > 0;
-    // The baserate hint depends on the query alone; its audit is pipeline-local (actor 'cli').
-    const cmdPlanningFallacyOutput = computePlanningFallacyOutput(hippoRoot, o.tenantId, query, { actor: 'cli' });
-    const planText = planningLine(cmdPlanningFallacyOutput);
+    // The baserate hint depends on the query alone, so `retrieve` evaluates it and this only prices the line.
+    const planText = planningLine(planning);
     const showPlan = planText !== null && pays(printedTokens(`${planText}\n`));
-    const cmdPlanningFallacyHint = showPlan ? cmdPlanningFallacyOutput.hint ?? null : null;
-    const cmdPlanningFallacyWatching = showPlan ? cmdPlanningFallacyOutput.watching ?? null : null;
+    const cmdPlanningFallacyHint = showPlan ? planning.hint ?? null : null;
+    const cmdPlanningFallacyWatching = showPlan ? planning.watching ?? null : null;
     // The first --min-results are kept whatever they cost (the documented exception); the rest skip and continue.
     const floor = o.minResults ?? 1;
-    const fitted = fitBudget(ranked.rank.results, left, floor, ranked.printCost);
+    const fitted = fitRecallRows(ranked.rank.results, left, floor, ranked.printCost);
     // Copies go after every cut, so a merged row the budget drops never hides its sources.
     const shown = (n) => dropHeldCopies(fitted.slice(0, n), (r) => r.entry);
     let kept = fitted.length;
@@ -398,73 +362,51 @@ function fitRecallBlock(hippoRoot, query, o, ranked, loaded) {
     }
     return { results, hints, recallText, continuity, continuityTokens, cmdPlanningFallacyHint, cmdPlanningFallacyWatching, anchorRing };
 }
-function auditRecall(hippoRoot, o, query, fit) {
+/** The presenter `retrieve` calls once ranking ends: fits and renders the block, and names the rows and hint rows to record. */
+function presentRecall(ctx, query, o, ranked, planning) {
+    // Loaded before the zero-result branch, so a no-match query with live continuity still returns a resume packet.
+    const fit = fitRecallBlock(query, o, ranked, loadCliRecallContinuity(ctx, o.setting, o.includeContinuity), planning);
     const { results, hints } = fit;
-    const who = { hippoRoot, tenantId: o.tenantId, actor: 'cli', bestEffort: true };
-    recordShownRecall(who, { query, ring: fit.anchorRing, topId: results[0]?.entry.id ?? null, anchoring: hints.anchoring, availability: hints.availability });
-    // One 'recall' event per query, before the early-empty return, in every participating store.
-    const metadata = recallAuditMetadata(query, results.length);
-    appendRecallAudit(who, 'recall', undefined, metadata);
-    if (isInitialized(o.globalRoot) && o.globalRoot !== hippoRoot) {
-        appendRecallAudit({ ...who, hippoRoot: o.globalRoot }, 'recall', undefined, metadata);
-    }
+    const text = recallOutput(query, o, fit, ranked.isGlobal);
+    const audit = shownRecallRows({ tenantId: o.tenantId, actor: 'cli' }, {
+        query, ring: fit.anchorRing, topId: results[0]?.entry.id ?? null, anchoring: hints.anchoring, availability: hints.availability,
+    });
+    // The token ledger books the text this recall prints, on whichever exit it takes; the ring keeps the hint the final detect made.
+    return { text, shown: { results, audit, tokens: estimateTokens(text), anchoredOn: hints.anchoring?.memoryId } };
 }
-/** Traces the recall, books retrieval for a non-empty list, then prints JSON or the fitted block. */
-function writeRecallResult(hippoRoot, query, o, fit, localIndex) {
-    const { tenantId, sessionId, showWhy, asJson, includeContinuity } = o;
+/** What this recall prints: the JSON object, or the fitted block. */
+function recallOutput(query, o, fit, isGlobal) {
+    const { asJson, includeContinuity } = o;
     const { results, recallText } = fit;
-    // The token ledger books the block this recall prints, on whichever exit it takes.
-    const emit = (text) => {
-        withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
-            tenantId,
-            sessionId: hostSessionId() ?? null,
-            surface: 'recall',
-            event: 'inject',
-            items: results.length,
-            tokens: estimateTokens(text),
-        }));
-        console.log(text);
-    };
     if (results.length === 0) {
-        // Traced too, so a coverage gap still lands in the training corpus; this path never touches localIndex.
-        writeRecallTraceAtRoot(hippoRoot, {
-            tenantId,
-            sessionId: sessionId || hostSessionId() || null,
-            pipeline: 'cli',
-            query,
-            explainMode: showWhy,
-            results: [],
-        });
         // HTTP and MCP surface the hint whatever matched, so the zero-result JSON keeps it for parity.
-        emit(asJson ? JSON.stringify({ query, results: [], total: 0, ...recallJsonTail(fit, includeContinuity) }) : recallText);
-        return;
-    }
-    recordRetrieval(hippoRoot, query, o, results, localIndex);
-    if (asJson) {
-        const output = results.map((r) => recallJsonRow(r, query, showWhy, o.primaryIsGlobal || (isInitialized(o.globalRoot) && !localIndex.entries[r.entry.id])));
-        emit(JSON.stringify({
-            query,
-            budget: o.budget,
-            results: output,
-            total: output.length,
-            ...recallJsonTail(fit, includeContinuity),
-        }));
-        return;
+        return asJson ? JSON.stringify({ query, results: [], total: 0, ...recallJsonTail(fit, includeContinuity) }) : recallText;
     }
-    emit(recallText);
+    if (!asJson)
+        return recallText;
+    const output = results.map((r) => recallJsonRow(r, query, o.showWhy, isGlobal(r)));
+    return JSON.stringify({
+        query,
+        budget: o.budget,
+        results: output,
+        total: output.length,
+        ...recallJsonTail(fit, includeContinuity),
+    });
 }
 /** The JSON keys after the result list: suppression summary, any bias hints, then continuity when asked for. */
 function recallJsonTail(fit, includeContinuity) {
     const { cmdPlanningFallacyHint, cmdPlanningFallacyWatching, continuityTokens } = fit;
     const { activeSnapshot, sessionHandoff, recentSessionEvents } = fit.continuity;
     const { anchoring: cmdAnchoringHint, availability: cmdAvailabilityHint, summary: cmdSuppressionSummary } = fit.hints;
-    const tail = {
-        suppressionSummary: cmdSuppressionSummary,
-        ...(cmdPlanningFallacyHint ? { planningFallacyHint: cmdPlanningFallacyHint } : {}),
-        ...(cmdPlanningFallacyWatching ? { planningFallacyWatching: cmdPlanningFallacyWatching } : {}),
-        ...(cmdAnchoringHint ? { anchoringHint: cmdAnchoringHint } : {}),
-        ...(cmdAvailabilityHint ? { availabilityHint: cmdAvailabilityHint } : {}),
-    };
+    const tail = { suppressionSummary: cmdSuppressionSummary };
+    if (cmdPlanningFallacyHint)
+        tail.planningFallacyHint = cmdPlanningFallacyHint;
+    if (cmdPlanningFallacyWatching)
+        tail.planningFallacyWatching = cmdPlanningFallacyWatching;
+    if (cmdAnchoringHint)
+        tail.anchoringHint = cmdAnchoringHint;
+    if (cmdAvailabilityHint)
+        tail.availabilityHint = cmdAvailabilityHint;
     if (includeContinuity) {
         tail.continuity = {
             activeSnapshot,
@@ -475,79 +417,12 @@ function recallJsonTail(fit, includeContinuity) {
     }
     return tail;
 }
-/** Strengthens the returned rows and persists last_retrieval_ids and last_trace_id in one saveIndex call. */
-function recordRetrieval(hippoRoot, query, o, results, localIndex) {
-    const { globalRoot, tenantId, sessionId, showWhy } = o;
-    const retrievedIds = results.map((r) => r.entry.id);
-    const gate = { recallBoostAblated: isRecallBoostAblated() };
-    const strengthenedHere = strengthenRetrieved(hippoRoot, retrievedIds, gate);
-    if (isInitialized(globalRoot))
-        strengthenRetrieved(globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)), gate);
-    // Track last retrieval IDs for outcome command
-    localIndex.last_retrieval_ids = retrievedIds;
-    // One trace at hippoRoot, where outcome attribution lives, written first so the same saveIndex keeps
-    // last_retrieval_ids and last_trace_id in lockstep (see writeRecallTraceAtRoot). Fail-soft; never throws.
-    const traceId = writeRecallTraceAtRoot(hippoRoot, {
-        tenantId,
-        sessionId: sessionId || hostSessionId() || null,
-        pipeline: 'cli',
-        query,
-        explainMode: showWhy,
-        results: results.map((r) => ({
-            memoryId: r.entry.id,
-            score: r.score,
-            rerankSteps: r.rerankTrace,
-        })),
-    });
-    localIndex.last_trace_id = traceId !== null ? String(traceId) : null;
-    saveIndex(hippoRoot, localIndex);
-    updateStats(hippoRoot, { recalled: results.length });
-}
-function recallJsonRow(r, query, showWhy, isGlobal) {
-    const base = {
-        id: r.entry.id,
-        score: r.score,
-        strength: r.entry.strength,
-        tokens: r.tokens,
-        tags: r.entry.tags,
-        content: r.entry.content,
-        layer: r.entry.layer,
-    };
-    if (r.entry.layer === Layer.Trace) {
-        base.trace_outcome = r.entry.trace_outcome;
-    }
-    if (r.entry.superseded_by) {
-        base.superseded = true;
-        base.superseded_by = r.entry.superseded_by;
-    }
-    if (r.graphVia) {
-        base.graphVia = r.graphVia;
-    }
-    if (showWhy) {
-        const explanation = explainMatch(query, r);
-        const facets = confidenceFacets(r.entry);
-        base.confidence = facets.tier;
-        base.aged_out = facets.agedOut;
-        base.source = isGlobal ? 'global' : 'local';
-        base.reason = explanation.reason;
-        base.bm25 = r.bm25;
-        base.cosine = r.cosine;
-        if (explanation.envelope) {
-            base.envelope = explanation.envelope;
-        }
-        // The ordered lifecycle re-ranking steps, so a caller can see why a row moved.
-        if (r.rerankTrace && r.rerankTrace.length > 0) {
-            base.rerankTrace = r.rerankTrace;
-        }
-    }
-    return base;
-}
-export async function handleRecall({ hippoRoot, args, flags }) {
+export async function handleRecall({ hippoRoot, tenantId, args, flags }) {
     const query = args.join(' ').trim();
     if (!query) {
         printError('Please provide a search query.');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    await cmdRecall(hookStoreRoot(hippoRoot), query, flags);
+    await cmdRecall(hookStoreRoot(hippoRoot), tenantId, query, flags);
 }
 //# sourceMappingURL=recall.js.map

package/dist/cli/refine-llm.d.ts

@@ -0,0 +1,35 @@
+/** LLM refinement of consolidated semantic memories (`hippo refine`): a separate command so API-key users opt in; idempotent via the `llm-refined` tag.
+ * Uses fetch directly (no SDK dependency); on any failure the original memory is untouched. */
+import { MemoryEntry } from '../core/memory.js';
+export interface RefineOptions {
+    apiKey: string;
+    model?: string;
+    limit?: number;
+    dryRun?: boolean;
+    /** Ignore the llm-refined tag and re-refine everything eligible. */
+    all?: boolean;
+    /** Injected for testing — defaults to the real fetch. */
+    fetcher?: typeof fetch;
+    /** Tenant scope: only that tenant's consolidated entries are scanned; cross-tenant parents return null and are skipped. */
+    tenantId?: string;
+}
+export interface RefineResult {
+    scanned: number;
+    refined: number;
+    skipped: number;
+    failed: number;
+    details: Array<{
+        id: string;
+        status: 'refined' | 'skipped' | 'failed';
+        reason?: string;
+    }>;
+}
+/** Ask Claude to synthesize a clean semantic memory from the merged content and its sources; returns null when the API call failed. */
+export declare function refineSemanticMemory(merged: string, sources: MemoryEntry[], opts: {
+    apiKey: string;
+    model?: string;
+    fetcher?: typeof fetch;
+}): Promise<string | null>;
+/** Refine each consolidated semantic memory with the LLM and write it back, tagging `llm-refined` so reruns skip it (unless `all`). */
+export declare function refineStore(hippoRoot: string, opts: RefineOptions): Promise<RefineResult>;
+//# sourceMappingURL=refine-llm.d.ts.map