hippo-memory 1.70.0 → 1.72.0

package/dist/cli/predictions.js

@@ -0,0 +1,175 @@
+// First-class object verbs for predictions: record a claim, close it against the actual, and read the class base rate.
+import * as predictionsApi from '../api/predictions.js';
+import { VALID_CLOSURE_STATES } from '../core/prediction.js';
+import { cliApiContext } from './api-context.js';
+import { printError } from './output.js';
+import { parseListLimit, stringFlag } from './flag-values.js';
+import { requireInit } from './shared.js';
+import { foundOrExit, idArgOrExit, requireStatus } from './object-verbs.js';
+import { parseObjectId } from './lenient-id.js';
+import { CliExit } from './exit.js';
+const BASERATE_DECIMALS = 3;
+const PREDICTION_NOUN = 'Prediction';
+async function predictClose(ctx, args, flags) {
+    const id = idArgOrExit(args, 'Usage: hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]', 'prediction', parseObjectId);
+    const stateRaw = (stringFlag(flags, 'state') ?? '').trim();
+    // SAFETY: Set.has only compares by value, so a string outside the closure states is a plain miss.
+    if (!VALID_CLOSURE_STATES.has(stateRaw) || stateRaw === 'open') {
+        printError(`Invalid --state: "${stateRaw}". Must be one of: closed | closed-unknown.`);
+        throw new CliExit(1);
+    }
+    const actualRaw = flags['actual'];
+    const actualValue = actualRaw !== undefined ? Number(actualRaw) : undefined;
+    if (actualRaw !== undefined && !Number.isFinite(actualValue)) {
+        printError(`Invalid --actual: "${actualRaw}". Must be a number.`);
+        throw new CliExit(1);
+    }
+    const closureNote = stringFlag(flags, 'note');
+    const closed = await predictionsApi.closePrediction(ctx, id, {
+        // SAFETY: the check above exits unless stateRaw is in VALID_CLOSURE_STATES and not open.
+        closureState: stateRaw,
+        actualValue,
+        closureNote,
+    });
+    console.log(`Prediction ${closed.id} closed: state=${closed.closureState}${closed.actualValue !== null ? ` actual=${closed.actualValue}` : ''}`);
+}
+async function loadPredictionList(ctx, status, classTag, limit) {
+    if (status === 'open') {
+        return predictionsApi.listPredictions(ctx, {
+            classTag: classTag || undefined,
+            closureState: 'open',
+            limit,
+        });
+    }
+    if (status === 'all') {
+        return predictionsApi.listPredictions(ctx, classTag ? { classTag, limit } : { limit });
+    }
+    const closureState = requireStatus(status, VALID_CLOSURE_STATES);
+    if (!classTag) {
+        // status filter without class: scan all classes is more complex; v1 requires --class for non-default status
+        printError('--status filter (non-open) requires --class to be set.');
+        throw new CliExit(1);
+    }
+    return predictionsApi.listPredictions(ctx, {
+        classTag,
+        closureState,
+        limit,
+    });
+}
+async function predictList(ctx, flags) {
+    const classTag = stringFlag(flags, 'class')?.trim() ?? '';
+    const status = stringFlag(flags, 'status')?.trim() ?? 'all';
+    const limit = parseListLimit(flags);
+    const results = await loadPredictionList(ctx, status, classTag, limit);
+    if (results.length === 0) {
+        console.log(classTag ? `No predictions in class "${classTag}".` : 'No predictions.');
+        return;
+    }
+    console.log(`Found ${results.length} predictions:\n`);
+    for (const p of results) {
+        const estPart = p.estimateValue !== null ? ` estimate=${p.estimateValue}${p.estimateUnit ? ` ${p.estimateUnit}` : ''}` : '';
+        const actPart = p.actualValue !== null ? ` actual=${p.actualValue}` : '';
+        const tgtPart = p.targetDate ? ` target=${p.targetDate}` : '';
+        console.log(`#${p.id} [${p.closureState}] class=${p.classTag}${estPart}${actPart}${tgtPart}`);
+        console.log(`    ${p.claimText}`);
+        if (p.closureNote)
+            console.log(`    note: ${p.closureNote}`);
+    }
+}
+async function predictShow(ctx, args) {
+    const id = idArgOrExit(args, 'Usage: hippo predict show <id>', 'prediction', parseObjectId);
+    const pred = foundOrExit(await predictionsApi.predictionById(ctx, id), PREDICTION_NOUN, id);
+    console.log(`Prediction #${pred.id}`);
+    console.log(`  class: ${pred.classTag}`);
+    console.log(`  claim: ${pred.claimText}`);
+    console.log(`  state: ${pred.closureState}`);
+    if (pred.estimateValue !== null)
+        console.log(`  estimate: ${pred.estimateValue}${pred.estimateUnit ? ' ' + pred.estimateUnit : ''}`);
+    if (pred.targetDate)
+        console.log(`  target: ${pred.targetDate}`);
+    if (pred.actualValue !== null)
+        console.log(`  actual: ${pred.actualValue}`);
+    if (pred.closedAt)
+        console.log(`  closed: ${pred.closedAt}`);
+    if (pred.closureNote)
+        console.log(`  note: ${pred.closureNote}`);
+    if (pred.memoryId)
+        console.log(`  memory: ${pred.memoryId}`);
+    console.log(`  created: ${pred.createdAt}`);
+}
+async function predictBaserate(ctx, flags) {
+    // Reference-class / planning-fallacy detector
+    const classTag = stringFlag(flags, 'class')?.trim();
+    if (!classTag) {
+        printError('Usage: hippo predict baserate --class <c>');
+        throw new CliExit(1);
+    }
+    const baserate = await predictionsApi.predictionBaserate(ctx, classTag);
+    if (baserate.nClosed === 0) {
+        console.log(`No closed predictions in class "${baserate.classTag}" yet.`);
+        console.log(`  Create one with: hippo predict "<claim>" --class ${baserate.classTag} --estimate N`);
+        console.log(`  Close it later:  hippo predict close <id> --state closed --actual N`);
+        return;
+    }
+    console.log(baserate.summary);
+    console.log(`  n_closed:         ${baserate.nClosed}`);
+    console.log(`  n_ratio_eligible: ${baserate.nRatioEligible}`);
+    if (baserate.meanEstimate !== null)
+        console.log(`  mean_estimate:    ${baserate.meanEstimate.toFixed(BASERATE_DECIMALS)}`);
+    if (baserate.meanActual !== null)
+        console.log(`  mean_actual:      ${baserate.meanActual.toFixed(BASERATE_DECIMALS)}`);
+    if (baserate.meanRatio !== null)
+        console.log(`  mean_ratio:       ${baserate.meanRatio.toFixed(BASERATE_DECIMALS)}x`);
+    if (baserate.p50Ratio !== null)
+        console.log(`  p50_ratio:        ${baserate.p50Ratio.toFixed(BASERATE_DECIMALS)}x`);
+    if (baserate.mae !== null)
+        console.log(`  mae:              ${baserate.mae.toFixed(BASERATE_DECIMALS)}`);
+}
+export async function handlePredict({ hippoRoot, tenantId, args, flags }) {
+    requireInit(hippoRoot);
+    const ctx = cliApiContext(hippoRoot, tenantId);
+    const subcommand = args[0] ?? '';
+    if (subcommand === 'close')
+        return predictClose(ctx, args, flags);
+    if (subcommand === 'list')
+        return predictList(ctx, flags);
+    if (subcommand === 'show')
+        return predictShow(ctx, args);
+    if (subcommand === 'baserate')
+        return predictBaserate(ctx, flags);
+    // Default subcommand: create. args[0] is the claim text.
+    return predictCreate(ctx, subcommand, flags);
+}
+async function predictCreate(ctx, claimText, flags) {
+    if (!claimText) {
+        printError('Usage: hippo predict "<claim>" --class <c> [--estimate <v>] [--unit <u>] [--target <YYYY-MM-DD>]');
+        printError('       hippo predict close <id> --state <closed|closed-unknown> [--actual <v>] [--note "..."]');
+        printError('       hippo predict list [--class X] [--status open|closed|closed-unknown|all] [--limit N]');
+        printError('       hippo predict show <id>');
+        throw new CliExit(1);
+    }
+    const classTag = stringFlag(flags, 'class')?.trim();
+    if (!classTag) {
+        printError('--class is required for prediction creation.');
+        throw new CliExit(1);
+    }
+    const estimateRaw = flags['estimate'];
+    const estimateValue = estimateRaw !== undefined ? Number(estimateRaw) : undefined;
+    if (estimateRaw !== undefined && !Number.isFinite(estimateValue)) {
+        printError(`Invalid --estimate: "${estimateRaw}". Must be a number.`);
+        throw new CliExit(1);
+    }
+    const estimateUnit = stringFlag(flags, 'unit');
+    const targetDate = stringFlag(flags, 'target');
+    const created = await predictionsApi.recordPrediction(ctx, {
+        classTag,
+        claimText,
+        estimateValue,
+        estimateUnit,
+        targetDate,
+    });
+    console.log(`Prediction recorded: #${created.id} class=${created.classTag}`);
+    if (created.memoryId)
+        console.log(`  memory: ${created.memoryId}`);
+}
+//# sourceMappingURL=predictions.js.map

package/dist/cli/print.d.ts

@@ -1,4 +1,4 @@
-import { TaskSnapshot, SessionEvent } from '../store/rows.js';
+import type { TaskSnapshot, SessionEvent } from '../store/rows.js';
 import type { SessionHandoff } from '../core/handoff.js';
 import type { SearchResult } from '../core/search-types.js';
 import { type ImportReport } from '../agent-memories/report.js';
@@ -10,9 +10,6 @@ export declare function printAgentImport(report: ImportReport, indent?: string):
 export declare function printActiveTaskSnapshot(snapshot: TaskSnapshot): void;
 export declare function printSessionEvents(events: SessionEvent[]): void;
 export declare function printHandoff(handoff: SessionHandoff): void;
-/**
- * Run `fn` with console.log captured; returns the captured lines joined by
- * newlines (what the same calls would have printed, minus the final newline).
- */
+/** Run `fn` with console.log captured; returns the captured lines joined by newlines (no final newline). */
 export declare function captureConsole(fn: () => void): string;
 //# sourceMappingURL=print.d.ts.map

package/dist/cli/print.js

@@ -15,7 +15,8 @@ export function recallEntryText(r, query, showWhy, isGlobal) {
     const bars = Math.round(e.strength * 10);
     const graphMark = r.graphVia ? ` [graph: ${r.graphVia.hops}hop ${r.graphVia.relType}]` : '';
     const lines = [
-        `--- ${e.id} [${e.layer}] ${confLabel}${isGlobal ? ' [global]' : ''}${e.superseded_by ? ' [superseded]' : ''}${graphMark} score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`,
+        `--- ${e.id} [${e.layer}] ${confLabel}${isGlobal ? ' [global]' : ''}${e.superseded_by ? ' [superseded]' : ''}${graphMark} ` +
+            `score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`,
         `    [${'█'.repeat(bars)}${'░'.repeat(10 - bars)}] tags: ${e.tags.join(', ') || 'none'} | retrieved: ${e.retrieval_count}x`,
     ];
     if (showWhy) {
@@ -66,10 +67,7 @@ export function printSessionEvents(events) {
 export function printHandoff(handoff) {
     console.log(handoffText(handoff));
 }
-/**
- * Run `fn` with console.log captured; returns the captured lines joined by
- * newlines (what the same calls would have printed, minus the final newline).
- */
+/** Run `fn` with console.log captured; returns the captured lines joined by newlines (no final newline). */
 export function captureConsole(fn) {
     const lines = [];
     const realLog = console.log;

package/dist/cli/projects.d.ts

@@ -1,3 +1,3 @@
-import { type CliFlags } from './flag-values.js';
-export declare function cmdProjects(hippoRoot: string, args: string[], flags: CliFlags): void;
+import { type CommandContext } from './flag-values.js';
+export declare function handleProjects({ hippoRoot, tenantId, args, flags }: CommandContext): void;
 //# sourceMappingURL=projects.d.ts.map

package/dist/cli/projects.js

@@ -1,9 +1,8 @@
 // The `hippo projects` verb: list a store's project names, fold an old worktree name into its repo, repair old tags in one pass.
 import * as path from 'path';
 import { execFileSync } from 'child_process';
-import { closeHippoDb, openHippoDb } from '../db/index.js';
-import { listProjects, mergeProjects, repairProjects } from '../sharing/project-merge.js';
-import { resolveTenantId } from '../store/tenant.js';
+import * as api from '../api/index.js';
+import { cliApiContext } from './api-context.js';
 import { flagIsTrue } from './flag-values.js';
 import { resolveAuthRoot } from './shared.js';
 import { printError } from './output.js';
@@ -12,7 +11,12 @@ import { DATE_PREFIX_CHARS } from '../util/token-text.js';
 /** Old per-worktree project names of the repo at cwd, mapped to the repo's main checkout name; empty outside git. */
 function worktreeNames() {
     try {
-        const out = execFileSync('git', ['worktree', 'list', '--porcelain'], { encoding: 'utf8', timeout: 10_000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true });
+        const out = execFileSync('git', ['worktree', 'list', '--porcelain'], {
+            encoding: 'utf8',
+            timeout: 10_000,
+            stdio: ['ignore', 'pipe', 'ignore'],
+            windowsHide: true,
+        });
         const paths = out.split(/\r?\n/).filter((l) => l.startsWith('worktree ')).map((l) => path.basename(l.slice('worktree '.length)));
         return new Map(paths.slice(1).map((name) => [name, paths[0]]));
     }
@@ -33,8 +37,9 @@ function hint(p, worktrees) {
 function count(n, one, many = `${one}s`) {
     return `${n} ${n === 1 ? one : many}`;
 }
-function projectsList(db, tenantId, root, flags) {
-    const projects = listProjects(db, tenantId);
+function projectsList(ctx, flags) {
+    const root = ctx.hippoRoot;
+    const projects = api.listProjectNames(ctx);
     if (flags['json']) {
         console.log(JSON.stringify({ store: root, projects }, null, 2));
         return;
@@ -42,52 +47,56 @@ function projectsList(db, tenantId, root, flags) {
     const worktrees = worktreeNames();
     console.log(`${count(projects.length, 'project name')} in ${root} (newest write first):\n`);
     for (const p of projects) {
-        console.log(`${label(p.origin)}  ${count(p.live, 'memory', 'memories')}, ${p.imported} imported from agent notes, newest ${p.newest.slice(0, DATE_PREFIX_CHARS)}${hint(p, worktrees)}`);
+        console.log(`${label(p.origin)}  ${count(p.live, 'memory', 'memories')}, ${p.imported} imported from agent notes, ` +
+            `newest ${p.newest.slice(0, DATE_PREFIX_CHARS)}${hint(p, worktrees)}`);
     }
 }
-function projectsMerge(db, tenantId, root, args, flags) {
+function projectsMerge(ctx, args, flags) {
     const apply = flagIsTrue(flags, 'apply');
     const [from, into] = [args[1] ?? '', args[2] ?? ''];
-    const r = mergeProjects(db, root, { tenantId, from, into, dryRun: !apply });
+    const r = api.mergeProjectNames(ctx, { from, into, dryRun: !apply });
     if (flags['json']) {
         console.log(JSON.stringify(r, null, 2));
         return;
     }
     console.log(`${apply ? 'Merged' : 'Dry run: would merge'} ${from} into ${into}:`);
-    console.log(`  ${count(r.setAside.length, 'imported note copy', 'imported note copies')} set aside (${into} already holds the same note; the rest move under ${into} on the next sync)`);
-    console.log(`  ${count(r.restamped.length, 'memory', 'memories')} re-tagged, plus ${r.dormantRestamped.length} dormant and ${count(r.compactions, 'compaction record')}`);
+    console.log(`  ${count(r.setAside.length, 'imported note ' +
+        'copy', 'imported note copies')} set aside (${into} already holds the same note; the rest move under ${into} on the next sync)`);
+    console.log(`  ${count(r.restamped.length, 'memory', 'memories')} re-tagged, plus ${r.dormantRestamped.length} dormant ` +
+        `and ${count(r.compactions, 'compaction record')}`);
     console.log(apply ? `Backup: ${r.backup}\nEvery id is in the audit log: hippo audit list --op project_merge` : 'Nothing written. Add --apply to run it.');
 }
-function projectsRepair(db, tenantId, root, flags) {
+function projectsRepair(ctx, flags) {
+    const root = ctx.hippoRoot;
     const apply = flagIsTrue(flags, 'apply');
-    const r = repairProjects(db, root, { tenantId, dryRun: !apply });
+    const r = api.repairProjectNames(ctx, { dryRun: !apply });
     if (flags['json']) {
         console.log(JSON.stringify(r, null, 2));
         return;
     }
     console.log(`${apply ? 'Repaired' : 'Dry run: would repair'} ${root}:`);
-    console.log(`  ${count(r.copies.length, 'imported note copy', 'imported note copies')} under the wrong project set aside (the note stays under its own, or user-global)`);
+    console.log(`  ${count(r.copies.length, 'imported note ' +
+        'copy', 'imported note copies')} under the wrong project set aside (the note stays under its own, or user-global)`);
     for (const f of r.folds)
         console.log(`  ${f.from} folded into ${f.into} (its sessions' folders resolve there now)`);
-    for (const c of r.collisions)
+    for (const c of r.collisions) {
         console.log(`  ${c.name} left as it is: its folders now resolve to ${c.ids.join(', ')}; fold it by hand with hippo projects merge`);
+    }
     console.log(`  sleep's user-global merged rows: ${r.toProject.length} re-tagged to their parents' project`);
     console.log(`  ${r.setAside.length} set aside (parents in two projects; sleep re-merges them per project)`);
     console.log(`  ${r.untraced.length} left as they are (no parent left to show which project; check them with hippo inspect <id>)`);
     console.log(apply ? `Backup: ${r.backup}\nEvery id is in the audit log: hippo audit list --op project_repair` : 'Nothing written. Add --apply to run it.');
 }
-export function cmdProjects(hippoRoot, args, flags) {
-    const root = resolveAuthRoot(hippoRoot, flags);
-    const tenantId = resolveTenantId({});
+export function handleProjects({ hippoRoot, tenantId, args, flags }) {
+    const ctx = cliApiContext(resolveAuthRoot(hippoRoot, flags), tenantId);
     const sub = args[0] ?? 'list';
-    const db = openHippoDb(root);
     try {
         if (sub === 'list')
-            return projectsList(db, tenantId, root, flags);
+            return projectsList(ctx, flags);
         if (sub === 'merge')
-            return projectsMerge(db, tenantId, root, args, flags);
+            return projectsMerge(ctx, args, flags);
         if (sub === 'repair')
-            return projectsRepair(db, tenantId, root, flags);
+            return projectsRepair(ctx, flags);
         printError('Usage: hippo projects [list] [--json] | merge <from> <into> [--apply] | repair [--apply]  [--global]');
         process.exitCode = 1;
     }
@@ -95,8 +104,5 @@ export function cmdProjects(hippoRoot, args, flags) {
         printError(errorMessage(err));
         process.exitCode = 1;
     }
-    finally {
-        closeHippoDb(db);
-    }
 }
 //# sourceMappingURL=projects.js.map

package/dist/cli/quality-repair-once.d.ts

@@ -1,3 +1,3 @@
 /** Fault-isolated like the project tag repair: a failure warns, leaves the store unmarked and runs again next time. */
-export declare function repairQualityOnceAt(root: string): void;
+export declare function repairQualityOnceAt(root: string, tenantId: string): void;
 //# sourceMappingURL=quality-repair-once.d.ts.map

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

@@ -1,13 +1,13 @@
 // Sleep and the daily runner clean a store's old automatic memories once, so an upgrade needs no command.
 import * as path from 'path';
 import { errorMessage, log } from '../util/log.js';
-import { repairQualityOnce } from './quality-repair.js';
-import { getGlobalRoot } from '../sharing/shared.js';
-import { resolveTenantId } from '../store/tenant.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { repairMemoryQualityOnce } from '../api/audit.js';
+import { cliApiContext } from './api-context.js';
 /** Fault-isolated like the project tag repair: a failure warns, leaves the store unmarked and runs again next time. */
-export function repairQualityOnceAt(root) {
+export function repairQualityOnceAt(root, tenantId) {
     try {
-        const result = repairQualityOnce(root, resolveTenantId({}));
+        const result = repairMemoryQualityOnce(cliApiContext(root, tenantId));
         if (result === null)
             return;
         if (!result.supported) {
@@ -18,7 +18,8 @@ export function repairQualityOnceAt(root) {
         const scope = path.resolve(root) === path.resolve(getGlobalRoot()) ? ' --global' : '';
         const moved = result.appliedIds.length;
         if (moved > 0) {
-            console.log(`Set aside ${moved} automatic ${moved === 1 ? 'memory' : 'memories'} with a certain defect, once after the upgrade (backup: ${result.backup}).`);
+            console.log(`Set aside ${moved} automatic ${moved === 1 ? 'memory' : 'memories'} with a certain defect, ` +
+                `once after the upgrade (backup: ${result.backup}).`);
             console.log(`  List them: hippo dormant${scope}   Bring one back: hippo dormant restore <id>${scope}`);
         }
         const review = result.issues.filter((issue) => issue.disposition === 'review').length;

package/dist/cli/recall.d.ts

@@ -1,5 +1,3 @@
-import { type CliFlags, type CommandContext } from './flag-values.js';
-/** Runs `hippo recall`: the flags name the ranking core and this verb's presenter, `retrieve` ranks and records, then the block prints. */
-export declare function cmdRecall(hippoRoot: string, query: string, flags: CliFlags): Promise<void>;
-export declare function handleRecall({ hippoRoot, args, flags }: CommandContext): Promise<void>;
+import { type CommandContext } from './flag-values.js';
+export declare function handleRecall({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=recall.d.ts.map