hippo-memory 1.68.0 → 1.70.0

package/dist/cli/explain.js

@@ -1,19 +1,21 @@
 // The `hippo explain` verb; main() loads it lazily from the command table.
-import { confidenceFacets } from '../memory.js';
+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 '../search/types.js';
-import { loadConfig } from '../config.js';
-import { dropHeldCopies } from '../same-text.js';
-import { detectScope } from '../scope.js';
-import { getGlobalRoot } from '../shared.js';
-import * as api from '../api.js';
-import { resolveTenantId } from '../tenant.js';
-import { rankRecall } from '../recall-pipeline.js';
-import { printedTokens } from '../context-render.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 * as api from '../api/index.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { printedTokens } from '../api/context-render.js';
 import { printError } from './output.js';
-import { parseLimitFlag, parseBudgetFlag, requireInit, fmt, recallEntryText, recallHeading, parseAsOfFlag, engineFlags, } from './shared.js';
+import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag } from './flag-values.js';
+import { requireInit } from './shared.js';
+import { fmt, recallEntryText, recallHeading } from './print.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 = [
@@ -30,8 +32,8 @@ export async function cmdExplain(hippoRoot, query, flags) {
     requireInit(hippoRoot);
     const budget = parseBudgetFlag(flags['budget'], DEFAULT_RECALL_BUDGET);
     const limit = parseLimitFlag(flags['limit']);
-    const asJson = Boolean(flags['json']);
-    const includeSuperseded = Boolean(flags['include-superseded']);
+    const asJson = boolFlag(flags, 'json');
+    const includeSuperseded = boolFlag(flags, 'include-superseded');
     const asOf = parseAsOfFlag(flags);
     const globalRoot = getGlobalRoot();
     const tenantId = resolveTenantId({});
@@ -46,13 +48,27 @@ export async function cmdExplain(hippoRoot, query, flags) {
     const explainIndex = loadIndex(hippoRoot);
     const cost = (r) => printedTokens(recallEntryText(r, query, false, explainGlobalOn && !explainIndex.entries[r.entry.id]));
     const entryBudget = Math.max(0, budget - printedTokens(recallHeading(budget, budget, query)));
-    const rank = await rankRecall({ hippoRoot, globalRoot: explainGlobalOn ? globalRoot : undefined, tenantId }, {
-        query, budget: entryBudget, cost, limit, includeSuperseded, asOf,
-        explicitScope, activeScope: explicitScope || detectScope(),
-        search: { ...engine, multihop: false, explain: true },
+    const slot = {};
+    await api.retrieve({ hippoRoot, tenantId, actor: api.adminActor('cli') }, {
+        query,
+        cliCore: {
+            rank: {
+                budget: entryBudget, cost, limit, includeSuperseded, asOf,
+                explicitScope, activeScope: explicitScope || detectScope(),
+                search: { ...engine, multihop: false, explain: true },
+            },
+            sources: { globalRoot: explainGlobalOn ? globalRoot : undefined },
+            inspect: (ranking) => { slot.rank = ranking; },
+        },
     });
+    const rank = slot.rank;
+    if (!rank)
+        throw new Error('explain ranked but inspected nothing');
+    printExplainResults(rank, engine.usePhysics, query, asJson);
+}
+function printExplainResults(rank, usePhysics, query, asJson) {
     const hasGlobal = rank.globalEntries.length > 0;
-    const modeUsed = engine.usePhysics && !hasGlobal
+    const modeUsed = usePhysics && !hasGlobal
         ? 'physics'
         : hasGlobal ? 'searchBothHybrid' : 'hybrid';
     const results = dropHeldCopies(rank.results, (r) => r.entry);
@@ -99,7 +115,7 @@ function printExplainTable(results, query, modeUsed, candidates) {
     for (let i = 0; i < results.length; i++) {
         const r = results[i];
         const b = r.breakdown;
-        const preview = r.entry.content.replace(/\s+/g, ' ').slice(0, 48);
+        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}`);
     }

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

@@ -0,0 +1,25 @@
+import type { RecallSearchOpts } from '../api/recall-pipeline.js';
+import type { HippoConfig } from '../core/config.js';
+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 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 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 args: string[];
+    readonly flags: CliFlags;
+}
+export type EngineFlags = Pick<RecallSearchOpts, 'usePhysics' | 'physicsConfig' | 'mmr' | 'mmrLambda' | 'localBump'>;
+export declare function parseAsOfFlag(flags: CliFlags): string | undefined;
+/** --physics forces physics, --classic forces BM25+cosine, else physics unless the config turns it off. */
+export declare function engineFlags(flags: CliFlags, config: HippoConfig): EngineFlags;
+export declare function stringFlagOrExit(flags: CliFlags, key: string): string | undefined;
+//# sourceMappingURL=flag-values.d.ts.map

package/dist/cli/flag-values.js

@@ -0,0 +1,103 @@
+// Readers that turn parsed CLI flags into typed values, and the flag types they share.
+import { printError } from './output.js';
+export function parseLimitFlag(value) {
+    if (!value)
+        return Infinity;
+    const parsed = parseInt(String(value), 10);
+    return Number.isFinite(parsed) && parsed >= 1 ? parsed : Infinity;
+}
+export function parseCountFlag(value) {
+    if (!value || value === true || Array.isArray(value))
+        return 0;
+    const parsed = parseInt(String(value), 10);
+    return Number.isFinite(parsed) && parsed >= 1 ? parsed : 0;
+}
+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') {
+        printError('--budget requires an integer value (e.g. --budget 1500).');
+        process.exit(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);
+    }
+    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.
+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);
+    }
+    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) {
+        printError(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
+        process.exit(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;
+}
+// An empty value reads as absent, so `--change ""` keeps the default.
+export function nonEmptyStringFlag(flags, name) {
+    return stringFlag(flags, name) || undefined;
+}
+export function numberFlag(flags, name) {
+    const v = flags[name];
+    return typeof v === 'string' ? Number(v) : undefined;
+}
+// Any truthy value counts, so a string value is true too.
+export function boolFlag(flags, name) {
+    return Boolean(flags[name]);
+}
+// Only a bare switch counts; `--x value` is false.
+export function flagIsTrue(flags, name) {
+    return flags[name] === true;
+}
+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);
+    }
+    return asOf;
+}
+/** --physics forces physics, --classic forces BM25+cosine, else physics unless the config turns it off. */
+export function engineFlags(flags, config) {
+    return {
+        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,
+        localBump: flags['equal-sources']
+            ? 1.0
+            : flags['local-bump'] !== undefined ? parseFloat(String(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.
+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);
+    }
+    return v.trim();
+}
+//# sourceMappingURL=flag-values.js.map

package/dist/cli/flags.d.ts

@@ -0,0 +1,303 @@
+export type FlagKind = 'switch' | 'value' | 'number' | 'list';
+/** One verb's flags by kind: a number is refused unless numeric, and a list collects repeats. */
+export interface VerbFlags {
+    readonly switches?: readonly string[];
+    readonly values?: readonly string[];
+    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[];
+    };
+    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`. */
+export declare function isKnownFlag(name: string): boolean;
+/** The typed flags this verb does not read, in the order typed. */
+export declare function undeclaredFlags(verb: VerbFlags, typed: readonly string[]): string[];
+//# sourceMappingURL=flags.d.ts.map