hippo-memory 1.71.0 → 2.0.0

package/dist/cli/eval.js

@@ -1,7 +1,8 @@
 // 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/global-store.js';
 import { runEval, bootstrapCorpus, compareSummaries } from '../eval/eval.js';
@@ -10,7 +11,7 @@ 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;
@@ -20,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;
@@ -55,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) {
@@ -220,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/explain.d.ts

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

package/dist/cli/explain.js

@@ -1,15 +1,12 @@
 // 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 { 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';
@@ -19,18 +16,13 @@ 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).`);
     }
 }
-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']);
@@ -38,25 +30,26 @@ 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(cliApiContext(hippoRoot, tenantId), {
+    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 },
@@ -119,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();
 }
@@ -152,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) {
@@ -164,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.');
         throw new CliExit(1);
     }
-    await cmdExplain(hippoRoot, query, flags);
+    await cmdExplain(hippoRoot, tenantId, query, flags);
 }
 //# sourceMappingURL=explain.js.map

package/dist/cli/flag-values.js

@@ -1,4 +1,5 @@
 // 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) {
@@ -35,7 +36,8 @@ export function parseBudgetFlag(value, fallback) {
     }
     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);
@@ -47,8 +49,8 @@ export function parsePositiveId(idRaw, label) {
 }
 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.`);
         throw new CliExit(1);
     }
@@ -73,9 +75,17 @@ export function stringListFlag(flags, name) {
 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 isStringFlag(v) ? 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) {
@@ -99,10 +109,10 @@ 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

package/dist/cli/flags.d.ts

@@ -6,295 +6,6 @@ export interface VerbFlags {
     readonly numbers?: readonly string[];
     readonly lists?: readonly string[];
 }
-export declare const VERB_FLAGS: {
-    init: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    remember: {
-        switches: string[];
-        values: string[];
-        lists: string[];
-    };
-    recall: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    drill: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    assemble: {
-        switches: string[];
-        values: string[];
-    };
-    supersede: {
-        switches: string[];
-        values: string[];
-        lists: string[];
-    };
-    explain: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    eval: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    trace: {
-        switches: string[];
-        values: string[];
-        lists: string[];
-    };
-    refine: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    sleep: {
-        switches: string[];
-        values: string[];
-    };
-    'last-sleep': {
-        switches: string[];
-        values: string[];
-    };
-    'session-end': {
-        switches: string[];
-        values: string[];
-    };
-    '__session-end-worker': {
-        switches: string[];
-        values: string[];
-    };
-    'pre-compact': {
-        values: string[];
-    };
-    'post-compact': {
-        values: string[];
-    };
-    'capture-error': {
-        values: string[];
-    };
-    'compact-resume': {};
-    'codex-run': {};
-    '__codex-session-end-worker': {
-        values: string[];
-    };
-    dedup: {
-        switches: string[];
-        numbers: string[];
-    };
-    dag: {
-        switches: string[];
-    };
-    auth: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    goal: {
-        switches: string[];
-        values: string[];
-    };
-    slack: {
-        switches: string[];
-        values: string[];
-    };
-    github: {
-        switches: string[];
-        values: string[];
-    };
-    audit: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    'correction-latency': {
-        switches: string[];
-    };
-    provenance: {
-        switches: string[];
-    };
-    status: {};
-    outcome: {
-        switches: string[];
-        values: string[];
-    };
-    conflicts: {
-        switches: string[];
-        values: string[];
-    };
-    resolve: {
-        switches: string[];
-        values: string[];
-    };
-    reject: {
-        switches: string[];
-        values: string[];
-    };
-    rejections: {
-        switches: string[];
-    };
-    unreject: {
-        switches: string[];
-    };
-    dormant: {
-        switches: string[];
-        numbers: string[];
-    };
-    projects: {
-        switches: string[];
-    };
-    quarantine: {
-        switches: string[];
-    };
-    tokens: {
-        switches: string[];
-        numbers: string[];
-    };
-    failures: {
-        switches: string[];
-        numbers: string[];
-    };
-    doctor: {
-        switches: string[];
-    };
-    'support-bundle': {
-        switches: string[];
-        values: string[];
-    };
-    snapshot: {
-        switches: string[];
-        values: string[];
-    };
-    session: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    handoff: {
-        switches: string[];
-        values: string[];
-        lists: string[];
-    };
-    card: {
-        switches: string[];
-        values: string[];
-        lists: string[];
-    };
-    predict: {
-        values: string[];
-        numbers: string[];
-    };
-    current: {
-        switches: string[];
-    };
-    forget: {
-        switches: string[];
-        values: string[];
-    };
-    inspect: {};
-    context: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    hook: {};
-    setup: {
-        switches: string[];
-    };
-    'daily-runner': {};
-    embed: {
-        switches: string[];
-    };
-    watch: {};
-    learn: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    promote: {};
-    sync: {
-        switches: string[];
-    };
-    share: {
-        switches: string[];
-        numbers: string[];
-    };
-    peers: {
-        switches: string[];
-    };
-    import: {
-        switches: string[];
-        values: string[];
-        lists: string[];
-    };
-    export: {
-        values: string[];
-    };
-    capture: {
-        switches: string[];
-        values: string[];
-    };
-    dashboard: {
-        numbers: string[];
-    };
-    wm: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    mcp: {};
-    serve: {
-        values: string[];
-        numbers: string[];
-    };
-    invalidate: {
-        switches: string[];
-        values: string[];
-    };
-    decide: {
-        values: string[];
-        numbers: string[];
-    };
-    incident: {
-        values: string[];
-        numbers: string[];
-        lists: string[];
-    };
-    process: {
-        values: string[];
-        numbers: string[];
-        lists: string[];
-    };
-    policy: {
-        values: string[];
-        numbers: string[];
-    };
-    skill: {
-        values: string[];
-        numbers: string[];
-    };
-    brief: {
-        switches: string[];
-        values: string[];
-        numbers: string[];
-    };
-    note: {
-        values: string[];
-        numbers: string[];
-    };
-    graph: {
-        switches: string[];
-        values: string[];
-    };
-};
 /** How parseArgs reads `--name` on the verb with these flags; `undefined` is a command the table lacks. */
 export declare function flagKind(verb: VerbFlags | undefined, name: string): FlagKind;
 /** Whether any verb, or the entry point, reads `--name`. */