hippo-memory 1.70.0 → 1.72.0

package/dist/cli/eval.js

@@ -1,17 +1,19 @@
 // The `hippo eval` verb; main() loads it lazily from the command table.
 import * as path from 'path';
 import * as fs from 'fs';
-import { loadAllEntries } from '../store/entry-reads.js';
+import { listMemories } from '../api/memories.js';
+import { cliApiContext } from './api-context.js';
 import { loadConfig } from '../core/config.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import { runEval, bootstrapCorpus, compareSummaries } from '../eval/eval.js';
 import { runFeatureEval, formatResult, resultToBaseline, detectRegressions } from '../eval/eval-suite.js';
 import { PACKAGE_VERSION } from '../util/version.js';
 import { printError } from './output.js';
 import { requireInit } from './shared.js';
 import { fmt } from './print.js';
-import { boolFlag } from './flag-values.js';
+import { boolFlag, numberFlag } from './flag-values.js';
 import { errorMessage } from '../util/log.js';
+import { CliExit } from './exit.js';
 const HIT_TOP_K = 10;
 const MAX_FAILING_SHOWN = 10;
 const TOP_IDS_SHOWN = 3;
@@ -19,14 +21,14 @@ const MAX_MISSED_SHOWN = 4;
 const QUERY_PREVIEW_CHARS = 60;
 const MAX_DELTAS_SHOWN = 5;
 /** Runs `hippo eval`: --bootstrap writes a corpus, --suite runs the built-in feature eval, else it scores a corpus file. */
-async function cmdEval(hippoRoot, corpusPath, flags) {
+async function cmdEval(hippoRoot, tenantId, corpusPath, flags) {
     const asJson = boolFlag(flags, 'json');
-    const minMrr = flags['min-mrr'] !== undefined ? parseFloat(String(flags['min-mrr'])) : null;
+    const minMrr = numberFlag(flags, 'min-mrr') ?? null;
     const comparePath = flags['compare'] ? String(flags['compare']) : null;
     // Suite mode doesn't need an initialized store
     if (!flags['suite'])
         requireInit(hippoRoot);
-    const entries = flags['suite'] ? [] : loadAllEntries(hippoRoot);
+    const entries = flags['suite'] ? [] : listMemories(cliApiContext(hippoRoot, tenantId), { everyTenant: true });
     if (flags['bootstrap']) {
         writeBootstrapCorpus(entries, flags);
         return;
@@ -44,7 +46,7 @@ async function cmdEval(hippoRoot, corpusPath, flags) {
     }
     if (minMrr !== null && summary.meanMrr < minMrr) {
         printError(`MRR ${fmt(summary.meanMrr, 4)} below threshold ${minMrr}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (comparePath)
         printEvalCompare(summary, comparePath, asJson);
@@ -54,22 +56,20 @@ async function runCorpusEval(hippoRoot, corpusPath, entries, flags) {
     const globalRoot = getGlobalRoot();
     const localBump = flags['equal-sources']
         ? 1.0
-        : flags['local-bump'] !== undefined
-            ? parseFloat(String(flags['local-bump']))
-            : loadConfig(hippoRoot).search.localBump;
+        : numberFlag(flags, 'local-bump') ?? loadConfig(hippoRoot).search.localBump;
     return runEval(cases, entries, {
         hippoRoot,
         globalRoot,
         mmr: !flags['no-mmr'],
-        mmrLambda: flags['mmr-lambda'] !== undefined ? parseFloat(String(flags['mmr-lambda'])) : undefined,
-        embeddingWeight: flags['embedding-weight'] !== undefined ? parseFloat(String(flags['embedding-weight'])) : undefined,
+        mmrLambda: numberFlag(flags, 'mmr-lambda'),
+        embeddingWeight: numberFlag(flags, 'embedding-weight'),
         localBump,
     });
 }
 /** Bootstrap mode: emit a synthetic corpus built from the store's own memories. */
 function writeBootstrapCorpus(entries, flags) {
     const outPath = flags['out'] ? String(flags['out']) : null;
-    const max = flags['max-cases'] !== undefined ? parseInt(String(flags['max-cases']), 10) : 50;
+    const max = numberFlag(flags, 'max-cases') ?? 50;
     const corpus = bootstrapCorpus(entries, max);
     const payload = JSON.stringify({ cases: corpus }, null, 2);
     if (outPath) {
@@ -85,11 +85,12 @@ function writeBootstrapCorpus(entries, flags) {
 async function runEvalSuite(hippoRoot, flags, asJson, minMrr) {
     const baselinePath = flags['baseline'] ? String(flags['baseline']) : path.join(hippoRoot, 'eval-baseline.json');
     let baseline;
-    if (fs.existsSync(baselinePath)) {
-        try {
-            baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
-        }
-        catch {
+    try {
+        baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
+    }
+    catch (err) {
+        // No baseline file is a first run and says nothing; a file that is there and cannot be used warns.
+        if (!(err instanceof Error && 'code' in err && err.code === 'ENOENT')) {
             printError(`Warning: eval baseline ${baselinePath} is unreadable; running without it.`);
         }
     }
@@ -109,7 +110,7 @@ async function runEvalSuite(hippoRoot, flags, asJson, minMrr) {
     if (baseline) {
         const report = detectRegressions(baseline, result);
         if (report.verdict === 'REGRESSION' && minMrr === null) {
-            process.exit(1);
+            throw new CliExit(1);
         }
     }
 }
@@ -117,11 +118,11 @@ async function runEvalSuite(hippoRoot, flags, asJson, minMrr) {
 function readCorpus(corpusPath) {
     if (!corpusPath) {
         printError('Usage: hippo eval <corpus.json>  OR  hippo eval --suite [--save-baseline]  OR  hippo eval --bootstrap');
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (!fs.existsSync(corpusPath)) {
         printError(`Corpus file not found: ${corpusPath}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     let cases;
     try {
@@ -132,7 +133,7 @@ function readCorpus(corpusPath) {
     }
     catch (err) {
         printError(`Failed to read corpus: ${errorMessage(err)}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return cases;
 }
@@ -176,7 +177,7 @@ function printEvalSummary(summary, showCases) {
 function printEvalCompare(summary, comparePath, asJson) {
     if (!fs.existsSync(comparePath)) {
         printError(`Baseline file not found: ${comparePath}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     let baseline;
     try {
@@ -184,7 +185,7 @@ function printEvalCompare(summary, comparePath, asJson) {
     }
     catch (err) {
         printError(`Failed to parse baseline: ${errorMessage(err)}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const cmp = compareSummaries(baseline, summary);
     if (asJson) {
@@ -218,8 +219,8 @@ function printEvalCompare(summary, comparePath, asJson) {
         }
     }
 }
-export async function handleEval({ hippoRoot, args, flags }) {
+export async function handleEval({ hippoRoot, tenantId, args, flags }) {
     const corpusPath = args[0] ? String(args[0]) : null;
-    await cmdEval(hippoRoot, corpusPath, flags);
+    await cmdEval(hippoRoot, tenantId, corpusPath, flags);
 }
 //# sourceMappingURL=eval.js.map

package/dist/cli/exit.d.ts

@@ -0,0 +1,6 @@
+/** Thrown after the verb has printed its own message, so it carries the exit code and nothing for the entry to print. */
+export declare class CliExit extends Error {
+    readonly code: number;
+    constructor(code: number);
+}
+//# sourceMappingURL=exit.d.ts.map

package/dist/cli/exit.js

@@ -0,0 +1,11 @@
+// The one error a CLI verb throws to stop its command; runCli is the one place that turns it into the process exit code.
+/** Thrown after the verb has printed its own message, so it carries the exit code and nothing for the entry to print. */
+export class CliExit extends Error {
+    code;
+    constructor(code) {
+        super(`hippo exits with code ${code}`);
+        this.name = 'CliExit';
+        this.code = code;
+    }
+}
+//# sourceMappingURL=exit.js.map

package/dist/cli/explain.d.ts

@@ -1,4 +1,3 @@
-import { type CliFlags, type CommandContext } from './flag-values.js';
-export declare function cmdExplain(hippoRoot: string, query: string, flags: CliFlags): Promise<void>;
-export declare function handleExplain({ hippoRoot, args, flags }: CommandContext): Promise<void>;
+import { type CommandContext } from './flag-values.js';
+export declare function handleExplain({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=explain.d.ts.map

package/dist/cli/explain.js

@@ -1,34 +1,28 @@
 // The `hippo explain` verb; main() loads it lazily from the command table.
 import { confidenceFacets } from '../core/memory.js';
-import { isInitialized } from '../store/open.js';
-import { loadSearchEntries } from '../store/search-rows.js';
-import { loadIndex } from '../store/index-and-stats.js';
 import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { loadConfig } from '../core/config.js';
 import { dropHeldCopies } from '../util/same-text.js';
-import { detectScope } from '../sharing/scope.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { detectScope } from '../core/active-scope.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import * as api from '../api/index.js';
-import { resolveTenantId } from '../store/tenant.js';
+import { cliRecallOrigin, scopeHiddenCount } from '../api/recall-cli.js';
+import { cliApiContext } from './api-context.js';
 import { printedTokens } from '../api/context-render.js';
 import { printError } from './output.js';
 import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { fmt, recallEntryText, recallHeading } from './print.js';
+import { CliExit } from './exit.js';
 const EXPLAIN_PREVIEW_CHARS = 48;
 /** The SQL predicate drops denied rows before the window, so an unscoped probe counts what the policy hides. */
-function noteScopeHidden(hippoRoot, globalRoot, query, tenantId, requested) {
-    const probe = [
-        ...loadSearchEntries(hippoRoot, query, undefined, tenantId),
-        ...(globalRoot ? loadSearchEntries(globalRoot, query, undefined, tenantId) : []),
-    ];
-    // Window-capped, so the count is a floor on large stores; fine for a "why is my row missing" hint.
-    const hidden = probe.filter((e) => !api.passesCliRecallScopeFilter(e.scope ?? null, requested)).length;
+function noteScopeHidden(ctx, globalRoot, query, requested) {
+    const hidden = scopeHiddenCount(ctx, query, globalRoot, requested);
     if (hidden > 0) {
         printError(`[note] ${hidden} candidate${hidden === 1 ? '' : 's'} hidden by recall scope policy (pass an explicit --scope to inspect).`);
     }
 }
-export async function cmdExplain(hippoRoot, query, flags) {
+async function cmdExplain(hippoRoot, tenantId, query, flags) {
     requireInit(hippoRoot);
     const budget = parseBudgetFlag(flags['budget'], DEFAULT_RECALL_BUDGET);
     const limit = parseLimitFlag(flags['limit']);
@@ -36,25 +30,26 @@ export async function cmdExplain(hippoRoot, query, flags) {
     const includeSuperseded = boolFlag(flags, 'include-superseded');
     const asOf = parseAsOfFlag(flags);
     const globalRoot = getGlobalRoot();
-    const tenantId = resolveTenantId({});
+    const ctx = cliApiContext(hippoRoot, tenantId);
     // Explain shows what recall would see, so it applies the same scope rule.
     const explicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const activeScope = explicitScope || detectScope();
     // Unlike recall, explain reads the global store whenever it exists, even when it is the local root.
-    const explainGlobalOn = isInitialized(globalRoot);
-    noteScopeHidden(hippoRoot, explainGlobalOn ? globalRoot : undefined, query, tenantId, explicitScope || undefined);
+    const origin = cliRecallOrigin(ctx, { globalRoot, primaryIsGlobal: false, activeScope });
+    const explainGlobalOn = origin.globalOn;
+    noteScopeHidden(ctx, explainGlobalOn ? globalRoot : undefined, query, explicitScope || undefined);
     const config = loadConfig(hippoRoot);
     const engine = engineFlags(flags, config);
     // Priced as recall prints each result, so explain returns what recall's engines would.
-    const explainIndex = loadIndex(hippoRoot);
-    const cost = (r) => printedTokens(recallEntryText(r, query, false, explainGlobalOn && !explainIndex.entries[r.entry.id]));
+    const cost = (r) => printedTokens(recallEntryText(r, query, false, origin.isGlobal(r.entry.id)));
     const entryBudget = Math.max(0, budget - printedTokens(recallHeading(budget, budget, query)));
     const slot = {};
-    await api.retrieve({ hippoRoot, tenantId, actor: api.adminActor('cli') }, {
+    await api.retrieve(ctx, {
         query,
         cliCore: {
             rank: {
                 budget: entryBudget, cost, limit, includeSuperseded, asOf,
-                explicitScope, activeScope: explicitScope || detectScope(),
+                explicitScope, activeScope,
                 search: { ...engine, multihop: false, explain: true },
             },
             sources: { globalRoot: explainGlobalOn ? globalRoot : undefined },
@@ -117,7 +112,8 @@ function printExplainTable(results, query, modeUsed, candidates) {
         const b = r.breakdown;
         const preview = r.entry.content.replace(/\s+/g, ' ').slice(0, EXPLAIN_PREVIEW_CHARS);
         const ageStr = b ? `${b.ageDays}d` : '?';
-        console.log(`${String(i + 1).padEnd(5)} ${fmt(r.score, 3).padEnd(7)} ${fmt(r.entry.strength).padEnd(9)} ${ageStr.padEnd(6)} ${r.entry.layer.padEnd(10)} ${r.entry.id.padEnd(17)} ${preview}`);
+        console.log(`${String(i + 1).padEnd(5)} ${fmt(r.score, 3).padEnd(7)} ${fmt(r.entry.strength).padEnd(9)} ${ageStr.padEnd(6)} ` +
+            `${r.entry.layer.padEnd(10)} ${r.entry.id.padEnd(17)} ${preview}`);
     }
     console.log();
 }
@@ -150,8 +146,10 @@ function printExplainBreakdown(r, i) {
             console.log(`    path:      x${fmt(b.pathBoost, 3)}  (cwd path tag overlap)`);
         if (b.sourceBump !== 1)
             console.log(`    source:    x${fmt(b.sourceBump, 2)}  (local priority bump over global)`);
-        if (b.outcomeBoost !== 1)
-            console.log(`    outcome:   x${fmt(b.outcomeBoost, 3)}  (user feedback: pos-neg = ${(r.entry.outcome_positive ?? 0) - (r.entry.outcome_negative ?? 0)})`);
+        if (b.outcomeBoost !== 1) {
+            console.log(`    outcome:   x${fmt(b.outcomeBoost, 3)}  ` +
+                `(user feedback: pos-neg = ${(r.entry.outcome_positive ?? 0) - (r.entry.outcome_negative ?? 0)})`);
+        }
         if (b.churnStaleMultiplier !== 1)
             console.log(`    churn:     x${fmt(b.churnStaleMultiplier, 2)}  (tagged 'churn-stale')`);
         if (b.preMmrRank !== undefined && b.postMmrRank !== undefined && b.preMmrRank !== b.postMmrRank) {
@@ -162,12 +160,12 @@ function printExplainBreakdown(r, i) {
     }
     console.log();
 }
-export async function handleExplain({ hippoRoot, args, flags }) {
+export async function handleExplain({ 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 cmdExplain(hippoRoot, query, flags);
+    await cmdExplain(hippoRoot, tenantId, query, flags);
 }
 //# sourceMappingURL=explain.js.map

package/dist/cli/flag-values.d.ts

@@ -1,19 +1,24 @@
 import type { RecallSearchOpts } from '../api/recall-pipeline.js';
 import type { HippoConfig } from '../core/config.js';
+export declare function isBooleanFlag(value: string | boolean | string[] | undefined): value is boolean;
+export declare function isStringFlag(value: string | boolean | string[] | undefined): value is string;
 export declare function parseLimitFlag(value: string | boolean | string[] | undefined): number;
 export declare function parseCountFlag(value: string | boolean | string[] | undefined): number;
 export declare function parseBudgetFlag(value: string | boolean | string[] | undefined, fallback: number): number;
 export type CliFlags = Record<string, string | boolean | string[]>;
-export declare function parsePositiveId(idRaw: unknown, label: string): number;
+export declare function parsePositiveId(idRaw: string | undefined, label: string): number;
 export declare function parseListLimit(flags: CliFlags): number;
 export declare function stringFlag(flags: CliFlags, name: string): string | undefined;
 export declare function nonEmptyStringFlag(flags: CliFlags, name: string): string | undefined;
+export declare function stringListFlag(flags: CliFlags, name: string): string[] | undefined;
+export declare function isOneOf<T extends string>(allowed: readonly T[], value: string): value is T;
 export declare function numberFlag(flags: CliFlags, name: string): number | undefined;
 export declare function boolFlag(flags: CliFlags, name: string): boolean;
 export declare function flagIsTrue(flags: CliFlags, name: string): boolean;
 /** What the command table hands each verb's run(). */
 export interface CommandContext {
     readonly hippoRoot: string;
+    readonly tenantId: string;
     readonly args: string[];
     readonly flags: CliFlags;
 }

package/dist/cli/flag-values.js

@@ -1,5 +1,13 @@
 // Readers that turn parsed CLI flags into typed values, and the flag types they share.
+import { resolveListLimit } from '../util/limits.js';
 import { printError } from './output.js';
+import { CliExit } from './exit.js';
+export function isBooleanFlag(value) {
+    return typeof value === 'boolean';
+}
+export function isStringFlag(value) {
+    return typeof value === 'string';
+}
 export function parseLimitFlag(value) {
     if (!value)
         return Infinity;
@@ -16,49 +24,68 @@ export function parseBudgetFlag(value, fallback) {
     if (value === undefined)
         return fallback;
     // A value-less flag and a junk value are different typos; the --hops guard already splits them.
-    if (typeof value !== 'string') {
+    if (!isStringFlag(value)) {
         printError('--budget requires an integer value (e.g. --budget 1500).');
-        process.exit(1);
+        throw new CliExit(1);
     }
     // Number(), like the --hops guard: parseInt('12abc') is 12, silently accepting what this message rejects.
     const parsed = Number(value);
     if (!Number.isInteger(parsed) || parsed < 0) {
         printError(`Invalid --budget: "${value}". Must be a non-negative integer.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return parsed;
 }
-// Whole-arg digits only: parseInt alone reads "1abc" as 1 and a mutating verb would hit the wrong row. Digits past 2^53 round to a neighbouring id, so they are refused too.
+// Whole-arg digits only: parseInt alone reads "1abc" as 1 and a mutating verb would hit the wrong row.
+// Digits past 2^53 round to a neighbouring id, so they are refused too.
 export function parsePositiveId(idRaw, label) {
     const s = String(idRaw ?? '').trim();
     const id = parseInt(s, 10);
     if (!/^\d+$/.test(s) || id <= 0 || !Number.isSafeInteger(id)) {
         printError(`Invalid ${label} id: "${idRaw}" (expected a positive integer).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return id;
 }
 export function parseListLimit(flags) {
     const limitRaw = flags['limit'];
-    const limit = limitRaw !== undefined ? parseInt(String(limitRaw), 10) : 100;
-    if (!Number.isFinite(limit) || limit <= 0) {
+    const limit = resolveListLimit(limitRaw !== undefined ? parseInt(String(limitRaw), 10) : undefined);
+    if (limit === undefined) {
         printError(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return limit;
 }
 // A value-less flag is `true` and a repeated one is a string[]; only a string counts here.
 export function stringFlag(flags, name) {
     const v = flags[name];
-    return typeof v === 'string' ? v : undefined;
+    return isStringFlag(v) ? v : undefined;
 }
 // An empty value reads as absent, so `--change ""` keeps the default.
 export function nonEmptyStringFlag(flags, name) {
     return stringFlag(flags, name) || undefined;
 }
+// A repeated flag is already a list; a single value is a comma-separated list.
+export function stringListFlag(flags, name) {
+    const v = flags[name];
+    if (Array.isArray(v))
+        return v;
+    return isStringFlag(v) ? v.split(',').map((t) => t.trim()).filter(Boolean) : undefined;
+}
+export function isOneOf(allowed, value) {
+    return allowed.some((a) => a === value);
+}
+// A junk value exits instead of becoming NaN, which would pass every `<` gate.
 export function numberFlag(flags, name) {
     const v = flags[name];
-    return typeof v === 'string' ? Number(v) : undefined;
+    if (!isStringFlag(v))
+        return undefined;
+    const parsed = Number(v);
+    if (v.trim() === '' || !Number.isFinite(parsed)) {
+        printError(`Invalid --${name}: "${v}". Must be a number.`);
+        throw new CliExit(1);
+    }
+    return parsed;
 }
 // Any truthy value counts, so a string value is true too.
 export function boolFlag(flags, name) {
@@ -72,7 +99,7 @@ export function parseAsOfFlag(flags) {
     const asOf = stringFlag(flags, 'as-of');
     if (asOf !== undefined && Number.isNaN(new Date(asOf).getTime())) {
         printError(`Error: --as-of value "${asOf}" is not a valid ISO date (e.g. 2026-04-22 or 2026-04-22T12:00:00Z).`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return asOf;
 }
@@ -82,21 +109,21 @@ export function engineFlags(flags, config) {
         usePhysics: boolFlag(flags, 'physics') || (!flags['classic'] && config.physics.enabled !== false),
         physicsConfig: config.physics,
         mmr: !flags['no-mmr'] && config.mmr.enabled,
-        mmrLambda: flags['mmr-lambda'] !== undefined ? parseFloat(String(flags['mmr-lambda'])) : config.mmr.lambda,
+        mmrLambda: numberFlag(flags, 'mmr-lambda') ?? config.mmr.lambda,
         localBump: flags['equal-sources']
             ? 1.0
-            : flags['local-bump'] !== undefined ? parseFloat(String(flags['local-bump'])) : config.search.localBump,
+            : numberFlag(flags, 'local-bump') ?? config.search.localBump,
     };
 }
 // parseArgs turns a value-less flag into `true`; refuse rather than silently
-// stringifying it (String(true) === 'true'), mirroring cmdHandoff's guard.
+// stringifying it (String(true) === 'true'), mirroring handleHandoff's guard.
 export function stringFlagOrExit(flags, key) {
     const v = flags[key];
     if (v === undefined)
         return undefined;
     if (v === true || v === false || Array.isArray(v)) {
         printError(`--${key} requires a value`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     return v.trim();
 }