hippo-memory 1.70.0 → 1.72.0

package/dist/cli/recall.js

@@ -1,41 +1,31 @@
 // The `hippo recall` verb; main() loads it lazily from the command table.
 import { envHippoSessionId } from '../util/env.js';
-import { confidenceFacets, Layer } from '../core/memory.js';
-import { isInitialized } from '../store/open.js';
-import { loadIndex } from '../store/index-and-stats.js';
-import { loadActiveTaskSnapshot, listSessionEvents } from '../store/sessions.js';
-import { loadLatestHandoff } from '../store/handoffs.js';
-import { passesScopeFilterForRecall } from '../store/recall-scope.js';
-import { fitBudget } from '../search/finalize.js';
-import { explainMatch } from '../search/explain.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 { isGlobalStoreRoot } from '../core/project-identity.js';
-import { detectScope } from '../sharing/scope.js';
-import { getGlobalRoot } from '../sharing/shared.js';
 import * as api from '../api/index.js';
 import { detectAnchoring, hashQueryText, biasHintEnabled, snapshotRing } from '../api/recall-history.js';
-import { noteRecall, sessionRing, shownRecallRows } from '../api/recall-record.js';
+import { sessionRing, shownRecallRows } from '../api/recall-record.js';
 import { detectAvailabilityBias } from '../api/availability.js';
-import { resolveTenantId } from '../store/tenant.js';
-import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from '../graph/recall.js';
-import { getReranker } from '../rerankers/index.js';
-import { JEV_DEFAULT_TOP_K } from '../rerankers/jev.js';
-import { isClefModel } from '../rerankers/clef.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, parseAsOfFlag, engineFlags, boolFlag, flagIsTrue } from './flag-values.js';
+import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag, flagIsTrue, isBooleanFlag, numberFlag, } 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)
         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)}]`;
+    if (p.watching) {
+        return `Planning fallacy: watching this query (reason: ${p.watching.reason}). ${p.watching.suggestion} ` +
+            `[detected: ${JSON.stringify(p.watching.detectedPhrase)}]`;
+    }
     return null;
 }
 function cutoffLine(shown, s) {
@@ -56,14 +46,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) {
@@ -73,7 +63,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)
@@ -86,7 +76,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) {
@@ -95,7 +85,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) {
@@ -105,18 +95,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.`) };
@@ -168,23 +159,25 @@ function parseRecallLateFlags(flags) {
     };
 }
 /** Runs `hippo recall`: the flags name the ranking core and this verb's presenter, `retrieve` ranks and records, then the block prints. */
-export async function cmdRecall(hippoRoot, query, flags) {
+async function cmdRecall(hippoRoot, tenantId, query, flags) {
     requireInit(hippoRoot);
-    const o = parseRecallOptions(hippoRoot, flags);
-    const priced = priceRecallEntries(hippoRoot, query, o);
+    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({ hippoRoot, tenantId: o.tenantId, actor: api.adminActor('cli') }, {
+    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: o.globalRoot !== hippoRoot && priced.globalOn ? o.globalRoot : undefined },
+            sources: { globalRoot: globalRoot !== hippoRoot && priced.globalOn ? globalRoot : undefined },
             note: (line) => printError(line),
             hostSessionId: hostSessionId(),
             show: (rank, planning) => {
-                slot.presented = presentRecall(hippoRoot, query, o, { rank, ...priced }, planning);
+                slot.presented = presentRecall(ctx, query, o, { rank, ...priced }, planning);
                 return slot.presented.shown;
             },
         },
@@ -193,32 +186,21 @@ export async function cmdRecall(hippoRoot, query, flags) {
     o.late.error?.fail();
     if (!slot.presented)
         throw new Error('recall ranked but presented nothing');
-    const { fit, text } = slot.presented;
-    const { results, hints } = fit;
-    // Fed after the final detect, so the next recall's cooldown reads the top row and hint this one showed.
-    if (fit.anchorRing)
-        noteRecall(fit.anchorRing, query, results[0]?.entry.id ?? null, hints.anchoring?.memoryId);
-    console.log(text);
+    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 = 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 minResults = flags['min-results'] !== undefined
-        ? parseInt(String(flags['min-results']), 10)
-        : undefined;
-    const activeScope = explicitScope || detectScope();
+    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() : '';
@@ -226,19 +208,18 @@ function parseRecallOptions(hippoRoot, flags) {
         ? String(flags['session-id'])
         : envHippoSessionId() ?? '').trim();
     return {
-        budget, limit, asJson, showWhy, includeSuperseded, asOf, globalRoot, primaryIsGlobal, tenantId,
-        explicitScope, config, minResults, activeScope, graphStream, late, goalTag, sessionId,
+        budget, limit, asJson, showWhy, includeSuperseded, asOf, setting, tenantId: ctx.tenantId,
+        explicitScope, config, minResults, graphStream, late, goalTag, sessionId,
         includeContinuity: boolFlag(flags, 'continuity'),
     };
 }
 /** Each entry priced as the line it prints, with the source marker `--why` shows. */
-function priceRecallEntries(hippoRoot, query, o) {
-    const localIndex = loadIndex(hippoRoot);
-    const globalOn = isInitialized(o.globalRoot);
-    const isGlobal = (r) => o.primaryIsGlobal || (globalOn && !localIndex.entries[r.entry.id]);
+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, isGlobal, entryText, printCost };
+    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) {
@@ -246,8 +227,14 @@ function rankOptions(query, flags, o, priced) {
     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.activeScope,
-        search: { ...engineFlags(flags, o.config), multihop: flagIsTrue(flags, 'multihop') || o.config.multihop.enabled, graphStream: o.graphStream, minResults: o.minResults, explain: false },
+        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: boolFlag(flags, 'evc-adaptive'),
         filterConflicts: boolFlag(flags, 'filter-conflicts'),
@@ -260,27 +247,6 @@ function rankOptions(query, flags, o, priced) {
         haltBefore: o.late.error?.stage,
     };
 }
-/** 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. */
 function recallHinter(query, o, rank) {
     const { tenantId, sessionId } = o;
@@ -295,7 +261,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,
@@ -303,7 +269,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 };
@@ -384,7 +350,7 @@ function fitRecallBlock(query, o, ranked, loaded, planning) {
     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;
@@ -403,15 +369,16 @@ function fitRecallBlock(query, o, ranked, loaded, planning) {
     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(hippoRoot, query, o, ranked, planning) {
-    const fit = fitRecallBlock(query, o, ranked, loadRecallContinuity(hippoRoot, o), planning);
+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 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.
-    return { fit, text, shown: { results, audit, tokens: estimateTokens(text) } };
+    // 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. */
 function recallOutput(query, o, fit, isGlobal) {
@@ -437,13 +404,15 @@ 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,
@@ -454,51 +423,12 @@ function recallJsonTail(fit, includeContinuity) {
     }
     return tail;
 }
-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

@@ -1,17 +1,5 @@
-/**
- * LLM-powered refinement of consolidated semantic memories.
- *
- * The rule-based `mergeContents` in consolidate.ts produces functional but
- * ugly semantic memories — typically "[Consolidated from N related memories]"
- * prepended to the longest source, or a bulleted list. `hippo refine` takes
- * those and asks Claude to synthesize a clean, generalized principle.
- *
- * Design choices:
- * - Separate command (not baked into `hippo sleep`) so API-key users opt in.
- * - Idempotent via the `llm-refined` tag — re-running skips already-refined.
- * - Uses fetch directly so no SDK dependency.
- * - On failure (API error, bad response), the original memory is untouched.
- */
+/** 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;
@@ -22,13 +10,7 @@ export interface RefineOptions {
     all?: boolean;
     /** Injected for testing — defaults to the real fetch. */
     fetcher?: typeof fetch;
-    /**
-     * Tenant scope. When provided, refineStore only scans consolidated
-     * entries belonging to this tenant, and parent lookups are scoped to the
-     * same tenant. Cross-tenant parents return null from readEntry and are
-     * silently skipped (refine still produces output from merged content).
-     * Undefined preserves pre-1.12.1 host-wide scan behaviour.
-     */
+    /** Tenant scope: only that tenant's consolidated entries are scanned; cross-tenant parents return null and are skipped. */
     tenantId?: string;
 }
 export interface RefineResult {
@@ -42,20 +24,12 @@ export interface RefineResult {
         reason?: string;
     }>;
 }
-/**
- * Ask Claude to synthesize a clean semantic memory from the merged content
- * plus the original source memories. Returns the refined content string or
- * `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>;
-/**
- * Scan the store for consolidated semantic memories, refine each with the
- * LLM, and write the refined content back. Tags with `llm-refined` so
- * repeated runs are idempotent (unless `all` is set).
- */
+/** 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,26 +1,15 @@
-/**
- * LLM-powered refinement of consolidated semantic memories.
- *
- * The rule-based `mergeContents` in consolidate.ts produces functional but
- * ugly semantic memories — typically "[Consolidated from N related memories]"
- * prepended to the longest source, or a bulleted list. `hippo refine` takes
- * those and asks Claude to synthesize a clean, generalized principle.
- *
- * Design choices:
- * - Separate command (not baked into `hippo sleep`) so API-key users opt in.
- * - Idempotent via the `llm-refined` tag — re-running skips already-refined.
- * - Uses fetch directly so no SDK dependency.
- * - On failure (API error, bad response), the original memory is untouched.
- */
+/** 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 { writeEntry } from '../store/entry-writes.js';
-import { loadAllEntries, readEntry } from '../store/entry-reads.js';
+import { REFINED_TAG, storeRefinement } from '../api/index.js';
+import { listMemories, listMemoriesByIds } from '../api/memories.js';
+import { cliApiContext } from './api-context.js';
+import { chunked } from '../util/chunked.js';
 import { redactSecretsStrict } from '../util/secret-detect.js';
 import { sendAnthropicMessage } from '../util/anthropic-messages.js';
 import { log } from '../util/log.js';
 const MAX_REFINE_SOURCES = 8;
 const REFINE_SOURCE_CHARS = 400;
-const REFINED_TAG = 'llm-refined';
 // Output budget for one refined memory, and the shortest reply kept as a refinement.
 const REFINE_MAX_TOKENS = 800;
 const REFINE_MIN_CHARS = 10;
@@ -28,17 +17,15 @@ const CONSOLIDATED_MARKERS = [
     '[Consolidated from',
     '[Consolidated pattern from',
 ];
-/**
- * Ask Claude to synthesize a clean semantic memory from the merged content
- * plus the original source memories. Returns the refined content string or
- * `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)
         .map((s, i) => `[source ${i + 1}] ${redactSecretsStrict(s.content).slice(0, REFINE_SOURCE_CHARS)}`)
         .join('\n\n');
-    const prompt = `You are refining a semantic memory in an agent's memory store. The rule-based consolidator merged several related episodic memories into one, but the output is clumsy. Produce a single coherent semantic memory that captures the underlying principle.
+    const prompt = `You are refining a semantic memory in an agent's memory store. ` +
+        `The rule-based consolidator merged several related episodic memories into one, but the output is clumsy. ` +
+        `Produce a single coherent semantic memory that captures the underlying principle.
 
 Rules:
 - Output ONLY the refined content — no preamble, no quote marks, no "Here is...".
@@ -72,7 +59,7 @@ ${sourceBlock}`;
 function describeRefineFailure(failure) {
     switch (failure.kind) {
         case 'request': return `refine: request failed: ${failure.message}`;
-        case 'http': return `refine: API answered HTTP ${failure.status}`;
+        case 'http': return `refine: API answered HTTP ${failure.status}${failure.detail ? `: ${failure.detail}` : ''}`;
         case 'unreadable': return `refine: unreadable response: ${failure.message}`;
     }
 }
@@ -81,11 +68,7 @@ function isConsolidated(entry) {
         return false;
     return CONSOLIDATED_MARKERS.some((m) => entry.content.startsWith(m));
 }
-/**
- * Scan the store for consolidated semantic memories, refine each with the
- * LLM, and write the refined content back. Tags with `llm-refined` so
- * repeated runs are idempotent (unless `all` is set).
- */
+/** 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,
@@ -94,9 +77,10 @@ export async function refineStore(hippoRoot, opts) {
         failed: 0,
         details: [],
     };
-    // When opts.tenantId is provided, scope the top-level scan to this
-    // tenant's consolidated entries.
-    const entries = loadAllEntries(hippoRoot, opts.tenantId);
+    // 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);
     let processed = 0;
     for (const entry of entries) {
         if (!isConsolidated(entry))
@@ -110,24 +94,18 @@ export async function refineStore(hippoRoot, opts) {
         if (opts.limit !== undefined && processed >= opts.limit)
             break;
         processed++;
-        await refineOneEntry(hippoRoot, entry, opts, result);
+        await refineOneEntry(ctx, reach, entry, opts, result);
     }
     return result;
 }
-async function refineOneEntry(hippoRoot, entry, opts, result) {
+async function refineOneEntry(ctx, reach, entry, opts, result) {
     // Best-effort: walk parents_json (schema v9) to fetch originals. When
     // parents aren't recorded we still refine using just the merged content.
-    const sources = [];
     const parentIds = Array.isArray(entry.parents) ? entry.parents : [];
-    for (const pid of parentIds) {
-        // Parent lookup scoped by opts.tenantId when provided.
-        // Cross-tenant parents return null and are silently skipped — refine
-        // still produces output from the merged content alone (graceful
-        // degradation rather than refuse-to-refine).
-        const p = readEntry(hippoRoot, pid, opts.tenantId);
-        if (p)
-            sources.push(p);
-    }
+    // 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 sources = parentIds.flatMap((pid) => found.get(pid) ?? []);
     const refined = await refineSemanticMemory(entry.content, sources, {
         apiKey: opts.apiKey,
         model: opts.model,
@@ -143,12 +121,7 @@ async function refineOneEntry(hippoRoot, entry, opts, result) {
         result.details.push({ id: entry.id, status: 'refined', reason: 'dry-run (no write)' });
         return;
     }
-    const updated = {
-        ...entry,
-        content: refined,
-        tags: entry.tags.includes(REFINED_TAG) ? entry.tags : [...entry.tags, REFINED_TAG],
-    };
-    writeEntry(hippoRoot, updated);
+    storeRefinement(cliApiContext(ctx.hippoRoot, entry.tenantId), entry, refined);
     result.refined++;
     result.details.push({ id: entry.id, status: 'refined' });
 }

package/dist/cli/remember.d.ts

@@ -1,5 +1,5 @@
 import { type CommandContext } from './flag-values.js';
-export declare function handleRemember({ hippoRoot, args, flags }: CommandContext): Promise<void>;
-export declare function handleSupersede({ hippoRoot, args, flags }: CommandContext): void;
-export declare function handleTrace({ hippoRoot, args, flags }: CommandContext): void;
+export declare function handleRemember({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleSupersede({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleTrace({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=remember.d.ts.map