hippo-memory 2.0.0 → 2.1.0

package/dist/cli/quality-repair-once.js

@@ -1,8 +1,8 @@
 // Sleep and the daily runner clean a store's old automatic memories once, so an upgrade needs no command.
 import * as path from 'path';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
-import { repairMemoryQualityOnce } from '../api/audit.js';
+import { repairMemoryQualityOnce } from '../api/auth/audit.js';
 import { cliApiContext } from './api-context.js';
 /** Fault-isolated like the project tag repair: a failure warns, leaves the store unmarked and runs again next time. */
 export async function repairQualityOnceAt(root, tenantId) {
@@ -25,13 +25,14 @@ export async function repairQualityOnceAt(root, tenantId) {
         const review = result.issues.filter((issue) => issue.disposition === 'review').length;
         if (review > 0) {
             const lead = moved > 0 ? `  ${review} more` : `Checked old automatic memories once after the upgrade: ${review}`;
-            console.log(`${lead} ${review === 1 ? 'looks' : 'look'} doubtful and ${review === 1 ? 'was' : 'were'} kept; hippo audit repair${scope} lists them.`);
+            console.log(`${lead} ${review === 1 ? 'looks' : 'look'} doubtful and ${review === 1 ? 'was' : 'were'} kept; hippo audit ` +
+                `repair${scope} lists them.`);
         }
         for (const warning of result.warnings)
             log.warn(warning);
     }
     catch (err) {
-        log.warn(`memory quality repair skipped, tried again next time: ${errorMessage(err)}`);
+        log.warn(`memory quality repair skipped, tried again next time: ${errorMessage(err)}`, errorFields(err));
     }
 }
 //# sourceMappingURL=quality-repair-once.js.map

package/dist/cli/recall.js

@@ -6,22 +6,20 @@ 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 { availabilityPool, cutoffClauses, detectRecallHints, handoffText, hashQueryText, printedTokens, sessionRing, sessionTrailText, settleTokens, shownRecallRows, shrinkToFit, snapshotText, suppressionSummary, tokenPurse, } from '../api/cli-surface.js';
+import { cliRecallOrigin, cliRecallReranker, cliRecallSetting, DEFAULT_MAX_NEIGHBORS, fitRecallRows, loadCliRecallContinuity, MAX_HOPS, recallJsonRow, } from '../api/recall/rows.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, parseAsOfFlag, engineFlags, boolFlag, flagIsTrue, isBooleanFlag, numberFlag, } from './flag-values.js';
+import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag, flagIsTrue, isBooleanFlag, isStringFlag, numberFlag, stringFlag, stringFlagOrExit, } from './flag-values.js';
 import { requireInit } from './shared.js';
-import { recallEntryText, recallHeading, printActiveTaskSnapshot, printSessionEvents, printHandoff, captureConsole } from './print.js';
+import { recallEntryText, recallHeading, printActiveTaskSnapshot, printSessionEvents, printHandoff, captureConsole, } from './print.js';
 import { hostSessionId, hookStoreRoot } from './hook-runtime.js';
-import { CliExit } from './exit.js';
+import { fail } from './exit.js';
 // JSON.stringify keeps quotes or parens in the matched phrase from blurring the line.
 function planningLine(p) {
-    if (p.hint)
+    if (p.hint) {
         return `Planning fallacy hint (class: ${p.hint.classTag}): ${p.hint.baserateSummary} [detected: ${JSON.stringify(p.hint.detectedPhrase)}]`;
+    }
     if (p.watching) {
         return `Planning fallacy: watching this query (reason: ${p.watching.reason}). ${p.watching.suggestion} ` +
             `[detected: ${JSON.stringify(p.watching.detectedPhrase)}]`;
@@ -29,45 +27,38 @@ function planningLine(p) {
     return null;
 }
 function cutoffLine(shown, s) {
-    const clauses = [];
-    // The residual covers rank, budget and limit drops alike, and fires with no --limit at all.
-    if (s.droppedByBudget > 0)
-        clauses.push(`${s.droppedByBudget} not shown (rank, budget or limit)`);
-    if (s.droppedPreRank > 0)
-        clauses.push(`${s.droppedPreRank} filtered pre-rank`);
-    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`);
-    return clauses.length > 0 ? `Cutoff: showing ${shown} of ${s.totalCandidates} candidates; ${clauses.join('; ')}.` : null;
+    const clauses = cutoffClauses(s);
+    return clauses.length > 0
+        ? `Cutoff: showing ${shown} of ${s.totalCandidates} candidates; ${clauses.join('; ')}.`
+        : null;
 }
 function failWith(message) {
     return () => {
-        printError(message);
-        throw new CliExit(1);
+        fail(message);
     };
 }
 /** `--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 (isBooleanFlag(flags['graph-hops']))
+        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) {
-            failWith(`Invalid --graph-hops: "${String(flags['graph-hops'])}". Must be an integer 1..${MAX_HOPS}.`)();
+            failWith(`Invalid --graph-hops: "${stringFlag(flags, 'graph-hops')}". Must be an integer 1..${MAX_HOPS}.`)();
         }
         hops = h;
     }
     let seeds;
     if (flags['graph-seeds'] !== undefined) {
-        if (isBooleanFlag(flags['graph-seeds']))
+        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)
-            failWith(`Invalid --graph-seeds: "${String(flags['graph-seeds'])}". Must be a positive integer.`)();
+        if (!Number.isInteger(s) || s < 1) {
+            failWith(`Invalid --graph-seeds: "${stringFlag(flags, 'graph-seeds')}". Must be a positive integer.`)();
+        }
         seeds = s;
     }
     return { hops, seeds };
@@ -76,11 +67,12 @@ 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 (isBooleanFlag(flags['hops']))
+    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) {
-        return { fail: failWith(`Invalid --hops: "${String(flags['hops'])}". Must be an integer 0..${MAX_HOPS}.`) };
+        return { fail: failWith(`Invalid --hops: "${stringFlag(flags, 'hops')}". Must be an integer 0..${MAX_HOPS}.`) };
     }
     const raw = flags['max-neighbors'];
     if (raw === undefined)
@@ -94,7 +86,10 @@ function parseHopsFlags(flags) {
     return { value: { hops, maxNeighbors } };
 }
 function parseRerankerFlag(flags) {
-    const name = flags['reranker'] !== undefined ? String(flags['reranker']).trim() : '';
+    const nameRaw = flags['reranker'];
+    if (nameRaw !== undefined && !isStringFlag(nameRaw))
+        return { fail: failWith('--reranker requires a value.') };
+    const name = nameRaw?.trim() ?? '';
     let picked;
     try {
         picked = cliRecallReranker(name);
@@ -125,11 +120,16 @@ function parseSalienceFlag(flags) {
     return { value: threshold };
 }
 function parseChoiceFlag(flags, name, valid) {
-    const value = flags[name] !== undefined ? String(flags[name]).trim() : '';
+    const raw = flags[name];
+    if (raw !== undefined && !isStringFlag(raw)) {
+        return { fail: failWith(`--${name} requires a value. Must be one of: ${valid.join(', ')}.`) };
+    }
+    const value = raw?.trim() ?? '';
     if (!value)
         return {};
-    if (!valid.includes(value))
+    if (!valid.includes(value)) {
         return { fail: failWith(`Invalid --${name}: "${value}". Must be one of: ${valid.join(', ')}.`) };
+    }
     return { value };
 }
 /** Parses every flag a ranking stage reads; the first invalid one in pipeline order becomes `error`. */
@@ -140,7 +140,11 @@ function parseRecallLateFlags(flags) {
     const outcome = parseChoiceFlag(flags, 'outcome', ['success', 'failure', 'partial']);
     const layer = parseChoiceFlag(flags, 'layer', Object.values(Layer));
     const staged = [
-        ['expand', graphHops.fail], ['rerank', reranker.fail], ['salience', salience.fail], ['outcome', outcome.fail], ['layer', layer.fail],
+        ['expand', graphHops.fail],
+        ['rerank', reranker.fail],
+        ['salience', salience.fail],
+        ['outcome', outcome.fail],
+        ['layer', layer.fail],
     ];
     let error;
     for (const [stage, fail] of staged) {
@@ -158,7 +162,8 @@ function parseRecallLateFlags(flags) {
         error,
     };
 }
-/** Runs `hippo recall`: the flags name the ranking core and this verb's presenter, `retrieve` ranks and records, then the block prints. */
+/** 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 ctx = cliApiContext(hippoRoot, tenantId);
@@ -173,11 +178,13 @@ async function cmdRecall(hippoRoot, tenantId, query, flags) {
         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 },
+            sources: globalRoot !== hippoRoot && priced.globalOn
+                ? { globalRoot, globalStore: cliApiContext(globalRoot, tenantId).store }
+                : undefined,
             note: (line) => printError(line),
             hostSessionId: hostSessionId(),
-            show: (rank, planning) => {
-                slot.presented = presentRecall(ctx, query, o, { rank, ...priced }, planning);
+            show: async (rank, planning) => {
+                slot.presented = await presentRecall(ctx, query, o, { rank, ...priced }, planning);
                 return slot.presented.shown;
             },
         },
@@ -197,16 +204,14 @@ function parseRecallOptions(ctx, flags) {
     const includeSuperseded = boolFlag(flags, 'include-superseded');
     const asOf = parseAsOfFlag(flags);
     // 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 explicitScope = stringFlagOrExit(flags, 'scope') ?? null;
     const setting = cliRecallSetting(ctx, explicitScope);
     const config = loadConfig(ctx.hippoRoot);
     const minResults = numberFlag(flags, 'min-results');
     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();
+    const goalTag = stringFlagOrExit(flags, 'goal') ?? '';
+    const sessionId = (stringFlagOrExit(flags, 'session-id') ?? envHippoSessionId() ?? '').trim();
     return {
         budget, limit, asJson, showWhy, includeSuperseded, asOf, setting, tenantId: ctx.tenantId,
         explicitScope, config, minResults, graphStream, late, goalTag, sessionId,
@@ -226,8 +231,14 @@ 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)));
     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,
+        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,
@@ -253,23 +264,17 @@ function recallHinter(query, o, rank) {
     // HIPPO_ANCHORING=off and HIPPO_AVAILABILITY=off skip the work entirely.
     const anchorRing = sessionRing('cli', tenantId, sessionId);
     const queryHash = hashQueryText(query);
-    const availabilityPool = biasHintEnabled('availability')
-        ? [...rank.localEntries, ...rank.globalEntries].map((e) => ({ id: e.id, created: e.created }))
-        : null;
+    const pool = availabilityPool(() => [...rank.localEntries, ...rank.globalEntries]);
     const hintsFor = (list, held) => {
-        const anchoring = anchorRing ? detectAnchoring(snapshotRing(anchorRing), queryHash, list[0]?.entry.id ?? null) : null;
-        const availability = availabilityPool
-            ? detectAvailabilityBias({ topK: list.map((r) => ({ id: r.entry.id, created: r.entry.created })), pool: availabilityPool })
-            : null;
-        const summary = {
-            // The published total includes graph-surfaced rows, so total == preRank + byBudget + returned holds for callers.
+        const { anchoring, availability } = detectRecallHints({ list, pool, anchorRing, queryHash });
+        const summary = suppressionSummary({
+            // The total includes graph-surfaced rows, so total == preRank + byBudget + returned holds for callers.
             totalCandidates: rank.totalCandidates + rank.graphAdded,
             droppedPreRank: rank.droppedPreRank + held,
             droppedByBudget: Math.max(0, rank.totalCandidates + rank.graphAdded - rank.droppedPreRank - held - list.length),
             summarySubstitutionsAdded: 0,
             freshTailAdded: 0,
-            suppressedByInterference: anchoring?.reason === 'memory_dominance' ? 1 : 0, // a query_repeat is a re-ask, not competition
-        };
+        }, anchoring);
         return { anchoring, availability, summary };
     };
     return { anchorRing, hintsFor };
@@ -325,59 +330,89 @@ function renderRecallBlock(list, h, v) {
             console.log(entryText(r));
     }));
 }
-/** Pays the continuity sections and the plan hint first, then fits the memories into what is left. */
-function fitRecallBlock(query, o, ranked, loaded, planning) {
-    const { budget } = o;
+/** Pays the continuity sections in print order after the header; one that does not fit is dropped. */
+function payContinuity(loaded, sectionBudget) {
     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.
-    const sectionBudget = budget - printedTokens(recallHeading(budget, budget, query));
-    let left = sectionBudget;
-    const pays = (tokens) => { if (tokens > left)
-        return false; left -= tokens; return true; };
+    const { pays, left } = tokenPurse(sectionBudget);
     if (activeSnapshot && !pays(printedTokens(snapshotText(activeSnapshot))))
         activeSnapshot = null;
     if (sessionHandoff && !pays(printedTokens(handoffText(sessionHandoff))))
         sessionHandoff = null;
-    if (recentSessionEvents.length > 0 && !pays(printedTokens(sessionTrailText(recentSessionEvents))))
+    if (recentSessionEvents.length > 0 && !pays(printedTokens(sessionTrailText(recentSessionEvents)))) {
         recentSessionEvents = [];
-    const continuityTokens = sectionBudget - left;
+    }
     const continuity = { activeSnapshot, sessionHandoff, recentSessionEvents };
+    return { continuity, continuityTokens: sectionBudget - left() };
+}
+/** Drops the lowest-ranked entry until the whole block, hints and header included, fits the budget. */
+function renderWithinBudget(fitted, hintsFor, view, floor, budget) {
+    // Copies go after every cut, so a merged row the budget drops never hides its sources.
+    const render = (kept) => {
+        const results = dropHeldCopies(fitted.slice(0, kept), (r) => r.entry);
+        const hints = hintsFor(results, kept - results.length);
+        return { results, hints, recallText: renderRecallBlock(results, hints, view) };
+    };
+    return shrinkToFit(fitted.length, floor, budget, render, (r) => r.recallText);
+}
+/** Pays the continuity sections and the plan hint first, then fits the memories into what is left. */
+function fitRecallBlock(query, o, ranked, loaded, planning) {
+    const { budget } = o;
+    // Sections print ahead of the memories, so they are paid first, after the header; one that does not fit is dropped.
+    const sectionBudget = budget - printedTokens(recallHeading(budget, budget, query));
+    const { continuity, continuityTokens } = payContinuity(loaded, sectionBudget);
+    let left = sectionBudget - continuityTokens;
+    const { activeSnapshot, sessionHandoff, recentSessionEvents } = continuity;
     const hasContinuity = activeSnapshot !== null || sessionHandoff !== null || recentSessionEvents.length > 0;
     // 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 ? planning.hint ?? null : null;
-    const cmdPlanningFallacyWatching = showPlan ? planning.watching ?? null : null;
+    const planTokens = planText === null ? 0 : printedTokens(`${planText}\n`);
+    const showPlan = planText !== null && planTokens <= left;
+    if (showPlan)
+        left -= planTokens;
+    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 = 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;
-    let results = shown(kept);
     const { anchorRing, hintsFor } = recallHinter(query, o, ranked.rank);
-    const view = { query, showWhy: o.showWhy, showPlan, planText, hasContinuity, continuity, entryText: ranked.entryText };
-    let hints = hintsFor(results, kept - results.length);
-    let recallText = renderRecallBlock(results, hints, view);
-    // The hints, Cutoff line and header vary with the list, so the lowest-ranked entry goes until the whole block fits.
-    while (kept > floor && estimateTokens(recallText) > budget) {
-        kept--;
-        results = shown(kept);
-        hints = hintsFor(results, kept - results.length);
-        recallText = renderRecallBlock(results, hints, view);
-    }
-    return { results, hints, recallText, continuity, continuityTokens, cmdPlanningFallacyHint, cmdPlanningFallacyWatching, anchorRing };
+    const view = {
+        query,
+        showWhy: o.showWhy,
+        showPlan,
+        planText,
+        hasContinuity,
+        continuity,
+        entryText: ranked.entryText,
+    };
+    const { results, hints, recallText } = renderWithinBudget(fitted, hintsFor, view, floor, budget);
+    return {
+        results,
+        hints,
+        recallText,
+        continuity,
+        continuityTokens,
+        cmdPlanningFallacyHint,
+        cmdPlanningFallacyWatching,
+        anchorRing,
+    };
 }
-/** 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) {
+/** The presenter `retrieve` calls once ranking ends: fits and
+ * renders the block, and names the rows and hint rows to record. */
+async 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 loaded = await loadCliRecallContinuity(ctx, o.setting, o.includeContinuity);
+    const fit = fitRecallBlock(query, o, ranked, loaded, planning);
     const { results, hints } = fit;
     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,
+        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.
+    // 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 } };
 }
 /** What this recall prints: the JSON object, or the fitted block. */
@@ -386,7 +421,9 @@ function recallOutput(query, o, fit, isGlobal) {
     const { results, recallText } = fit;
     if (results.length === 0) {
         // HTTP and MCP surface the hint whatever matched, so the zero-result JSON keeps it for parity.
-        return asJson ? JSON.stringify({ query, results: [], total: 0, ...recallJsonTail(fit, includeContinuity) }) : recallText;
+        return asJson
+            ? JSON.stringify({ query, results: [], total: 0, ...recallJsonTail(fit, includeContinuity) })
+            : recallText;
     }
     if (!asJson)
         return recallText;
@@ -426,8 +463,7 @@ function recallJsonTail(fit, includeContinuity) {
 export async function handleRecall({ hippoRoot, tenantId, args, flags }) {
     const query = args.join(' ').trim();
     if (!query) {
-        printError('Please provide a search query.');
-        throw new CliExit(1);
+        fail('Please provide a search query.');
     }
     await cmdRecall(hookStoreRoot(hippoRoot), tenantId, query, flags);
 }

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

@@ -1,4 +1,6 @@
-/** LLM refinement of consolidated semantic memories (`hippo refine`): a separate command so API-key users opt in; idempotent via the `llm-refined` tag.
+/**
+ * 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 {
@@ -10,7 +12,10 @@ export interface RefineOptions {
     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. */
+    /**
+     * Tenant scope: only that tenant's consolidated entries are scanned; cross-tenant parents return null and are
+     * skipped.
+     */
     tenantId?: string;
 }
 export interface RefineResult {
@@ -24,12 +29,18 @@ export interface RefineResult {
         reason?: string;
     }>;
 }
-/** Ask Claude to synthesize a clean semantic memory from the merged content and its sources; returns null when the API call failed. */
+/**
+ * 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`). */
+/**
+ * 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

package/dist/cli/refine-llm.js

@@ -1,8 +1,10 @@
-/** LLM refinement of consolidated semantic memories (`hippo refine`): a separate command so API-key users opt in; idempotent via the `llm-refined` tag.
+/**
+ * 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 { Layer } from '../core/memory.js';
 import { REFINED_TAG, storeRefinement } from '../api/index.js';
-import { listMemories, listMemoriesByIds } from '../api/memories.js';
+import { listMemories, listMemoriesByIds } from '../api/memories/memories.js';
 import { cliApiContext } from './api-context.js';
 import { chunked } from '../util/chunked.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
@@ -17,7 +19,10 @@ const CONSOLIDATED_MARKERS = [
     '[Consolidated from',
     '[Consolidated pattern from',
 ];
-/** Ask Claude to synthesize a clean semantic memory from the merged content and its sources; returns null when the API call failed. */
+/**
+ * Ask Claude to synthesize a clean semantic memory from the merged content and its sources; returns null when the API
+ * call failed.
+ */
 export async function refineSemanticMemory(merged, sources, opts) {
     const sourceBlock = sources
         .slice(0, MAX_REFINE_SOURCES)
@@ -69,7 +74,10 @@ function isConsolidated(entry) {
         return false;
     return CONSOLIDATED_MARKERS.some((m) => entry.content.startsWith(m));
 }
-/** Refine each consolidated semantic memory with the LLM and write it back, tagging `llm-refined` so reruns skip it (unless `all`). */
+/**
+ * Refine each consolidated semantic memory with the LLM and write it back, tagging `llm-refined` so reruns skip it
+ * (unless `all`).
+ */
 export async function refineStore(hippoRoot, opts) {
     const result = {
         scanned: 0,
@@ -81,7 +89,7 @@ export async function refineStore(hippoRoot, opts) {
     // No tenant means every tenant, so the ctx's own tenant is never read.
     const ctx = cliApiContext(hippoRoot, opts.tenantId ?? '');
     const reach = { everyTenant: opts.tenantId === undefined };
-    const entries = listMemories(ctx, reach);
+    const entries = await listMemories(ctx, reach);
     let processed = 0;
     for (const entry of entries) {
         if (!isConsolidated(entry))
@@ -105,7 +113,8 @@ async function refineOneEntry(ctx, reach, entry, opts, result) {
     const parentIds = Array.isArray(entry.parents) ? entry.parents : [];
     // Parent lookup is tenant-scoped; cross-tenant parents are absent and skipped,
     // so refine still works from the merged content alone.
-    const found = new Map(chunked(parentIds).flatMap((chunk) => listMemoriesByIds(ctx, chunk, reach)).map((p) => [p.id, p]));
+    const chunks = await Promise.all(chunked(parentIds).map((chunk) => listMemoriesByIds(ctx, chunk, reach)));
+    const found = new Map(chunks.flat().map((p) => [p.id, p]));
     const sources = parentIds.flatMap((pid) => found.get(pid) ?? []);
     const refined = await refineSemanticMemory(entry.content, sources, {
         apiKey: opts.apiKey,
@@ -122,7 +131,7 @@ async function refineOneEntry(ctx, reach, entry, opts, result) {
         result.details.push({ id: entry.id, status: 'refined', reason: 'dry-run (no write)' });
         return;
     }
-    storeRefinement(cliApiContext(ctx.hippoRoot, entry.tenant_id), entry, refined);
+    await storeRefinement(cliApiContext(ctx.hippoRoot, entry.tenant_id), entry, refined);
     result.refined++;
     result.details.push({ id: entry.id, status: 'refined' });
 }