hippo-memory 1.69.0 → 1.70.0

package/dist/cli/projects.js

@@ -1,11 +1,14 @@
 // 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.js';
-import { listProjects, mergeProjects, repairProjects } from '../project-merge.js';
-import { resolveTenantId } from '../tenant.js';
+import { closeHippoDb, openHippoDb } from '../db/index.js';
+import { listProjects, mergeProjects, repairProjects } from '../sharing/project-merge.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { flagIsTrue } from './flag-values.js';
 import { resolveAuthRoot } from './shared.js';
 import { printError } from './output.js';
+import { errorMessage } from '../util/log.js';
+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 {
@@ -30,62 +33,66 @@ 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);
+    if (flags['json']) {
+        console.log(JSON.stringify({ store: root, projects }, null, 2));
+        return;
+    }
+    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)}`);
+    }
+}
+function projectsMerge(db, tenantId, root, args, flags) {
+    const apply = flagIsTrue(flags, 'apply');
+    const [from, into] = [args[1] ?? '', args[2] ?? ''];
+    const r = mergeProjects(db, root, { tenantId, 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(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) {
+    const apply = flagIsTrue(flags, 'apply');
+    const r = repairProjects(db, root, { tenantId, 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)`);
+    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)
+        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({});
-    const apply = flags['apply'] === true;
     const sub = args[0] ?? 'list';
     const db = openHippoDb(root);
     try {
-        if (sub === 'list') {
-            const projects = listProjects(db, tenantId);
-            if (flags['json']) {
-                console.log(JSON.stringify({ store: root, projects }, null, 2));
-                return;
-            }
-            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, 10)}${hint(p, worktrees)}`);
-            }
-            return;
-        }
-        if (sub === 'merge') {
-            const [from, into] = [args[1] ?? '', args[2] ?? ''];
-            const r = mergeProjects(db, root, { tenantId, 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(apply ? `Backup: ${r.backup}\nEvery id is in the audit log: hippo audit list --op project_merge` : 'Nothing written. Add --apply to run it.');
-            return;
-        }
-        if (sub === 'repair') {
-            const r = repairProjects(db, root, { tenantId, 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)`);
-            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)
-                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.');
-            return;
-        }
+        if (sub === 'list')
+            return projectsList(db, tenantId, root, flags);
+        if (sub === 'merge')
+            return projectsMerge(db, tenantId, root, args, flags);
+        if (sub === 'repair')
+            return projectsRepair(db, tenantId, root, flags);
         printError('Usage: hippo projects [list] [--json] | merge <from> <into> [--apply] | repair [--apply]  [--global]');
         process.exitCode = 1;
     }
     catch (err) {
-        printError(err instanceof Error ? err.message : String(err));
+        printError(errorMessage(err));
         process.exitCode = 1;
     }
     finally {

package/dist/{provenance-coverage.d.ts → cli/provenance-coverage.d.ts}

@@ -1,4 +1,4 @@
-import { MemoryEntry } from './memory.js';
+import { MemoryEntry } from '../core/memory.js';
 export interface ProvenanceCoverage {
     rawTotal: number;
     rawWithEnvelope: number;

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

@@ -1,9 +1,9 @@
 // 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 '../log.js';
-import { repairQualityOnce } from '../quality-repair.js';
-import { getGlobalRoot } from '../shared.js';
-import { resolveTenantId } from '../tenant.js';
+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';
 /** Fault-isolated like the project tag repair: a failure warns, leaves the store unmarked and runs again next time. */
 export function repairQualityOnceAt(root) {
     try {

package/dist/{quality-repair.js → cli/quality-repair.js}

@@ -1,20 +1,22 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { appendAuditEvent } from './audit.js';
-import { withBackup } from './db/backup.js';
-import { assertSqliteAllowed } from './db/open.js';
-import { DatabaseSync } from './db/sqlite.js';
-import { getMeta, setMeta } from './db/meta.js';
-import { tableColumns } from './db/tables.js';
-import { assertBinaryCompatible } from './db/migrate.js';
-import { insertDormantRow, listDormantSnapshots } from './dormant.js';
-import { calculateStrength, canAutoDelete } from './memory.js';
-import { assessAutomaticMemory, BUNDLE_HEADER, isAutomaticEntry, isCertainReason } from './memory-quality.js';
-import { heldTexts } from './same-text.js';
-import { deleteEntryCore, MEMORY_BACKED_TABLES, memoriesBackingObjectsOn } from './store/delete-and-batch.js';
-import { selectAllEntries } from './store/entry-reads.js';
-import { MEMORY_SELECT_COLUMNS, parseJsonArray } from './store/rows.js';
-import { purgeMirrorBestEffort } from './store/mirrors.js';
+import { appendAuditEvent } from '../store/audit.js';
+import { withBackup } from '../db/backup.js';
+import { withTrialScope, withWriteScope } from '../db/busy.js';
+import { assertSqliteAllowed } from '../db/open.js';
+import { DatabaseSync } from '../db/sqlite.js';
+import { getMeta, pragmaUserVersion, setMeta } from '../db/meta.js';
+import { tableColumns } from '../db/tables.js';
+import { assertBinaryCompatible } from '../db/migrate.js';
+import { insertDormantRow, listDormantSnapshots } from '../store/dormant.js';
+import { calculateStrength, canAutoDelete } from '../core/memory.js';
+import { assessAutomaticMemory, BUNDLE_HEADER, isAutomaticEntry, isCertainReason } from '../core/memory-quality.js';
+import { heldTexts } from '../util/same-text.js';
+import { deleteEntryCore, MEMORY_BACKED_TABLES, memoriesBackingObjectsOn } from '../store/delete-and-batch.js';
+import { selectAllEntries, selectPreviewRows } from '../store/entry-reads.js';
+import { ftsRowExists } from '../store/entry-row.js';
+import { MEMORY_SELECT_COLUMNS, parseJsonArray } from '../store/rows.js';
+import { purgeMirrorBestEffort } from '../store/mirrors.js';
 const REQUIRED_COLUMNS = {
     memories: MEMORY_SELECT_COLUMNS.split(',').map((s) => s.trim()),
     meta: ['key', 'value'],
@@ -104,11 +106,7 @@ function unsupportedPreview(db, tenantId) {
     const columns = tableColumns(db, 'memories');
     if (!columns.has('id') || !columns.has('content'))
         return { total: 0, issues: [] };
-    const tenant = columns.has('tenant_id') ? ' WHERE tenant_id = ?' : '';
-    const column = (name, fallback) => (columns.has(name) ? name : `${fallback} AS ${name}`);
-    const statement = db.prepare(`SELECT id, content, ${column('source', "''")}, ${column('confidence', 'NULL')}, ${column('extracted_from', 'NULL')}, ${column('dag_level', '0')}, ${column('tags_json', "'[]'")} FROM memories${tenant}`);
-    // SAFETY: the SELECT names every Row field, each a literal fallback when its column is missing.
-    const rows = (tenant ? statement.all(tenantId) : statement.all());
+    const rows = selectPreviewRows(db, columns, tenantId);
     const issues = rows.flatMap((row) => {
         const provenance = { ...row, source: row.source ?? '', confidence: row.confidence ?? 'observed', dag_level: row.dag_level ?? 0, tags: parseJsonArray(row.tags_json) };
         if (!isAutomaticEntry(provenance))
@@ -120,8 +118,7 @@ function unsupportedPreview(db, tenantId) {
 }
 function initialResult(db, root, tenantId) {
     const blockers = capabilityBlockers(db);
-    // SAFETY: PRAGMA user_version returns one row with one integer column.
-    const schema = db.prepare('PRAGMA user_version').get().user_version;
+    const schema = pragmaUserVersion(db);
     const plan = blockers.length > 0 ? unsupportedPreview(db, tenantId) : planRows(db, tenantId);
     return {
         root, schema, supported: blockers.length === 0, blockers,
@@ -135,15 +132,14 @@ function setAsideIssue(db, entry, reason, now, backup) {
     if (deleteEntryCore(db, entry.id, { actor, automatic: true, suppressForgetAudit: true }) === null)
         return false;
     insertDormantRow(db, { entry, strength: calculateStrength(entry, now), reason: 'quality-repair', dormantAt: now.toISOString() });
-    if (getMeta(db, 'fts5_available', '0') === '1' && db.prepare('SELECT id FROM memories_fts WHERE id = ?').get(entry.id)) {
+    if (getMeta(db, 'fts5_available', '0') === '1' && ftsRowExists(db, entry.id)) {
         throw new Error(`Quality repair could not remove the full-text row for ${entry.id}`);
     }
     appendAuditEvent(db, { tenantId: entry.tenantId, actor, op: 'quality_repair', targetId: entry.id, metadata: { reason, backup } });
     return true;
 }
 function applyPlan(db, root, tenantId, backup, doneKey) {
-    db.exec('BEGIN IMMEDIATE');
-    try {
+    return withWriteScope(db, 'quality_repair_apply', () => {
         const result = initialResult(db, root, tenantId);
         if (!result.supported)
             throw new Error(`Quality repair capability changed: ${result.blockers.join('; ')}`);
@@ -161,21 +157,11 @@ function applyPlan(db, root, tenantId, backup, doneKey) {
         }
         if (doneKey)
             setMeta(db, doneKey, '1');
-        db.exec('COMMIT');
         return { ...result, appliedIds, backup, warnings };
-    }
-    catch (error) {
-        try {
-            db.exec('ROLLBACK');
-        }
-        catch { /* preserve the mutation error */ }
-        throw error;
-    }
+    });
 }
 function repairOn(db, root, opts) {
-    db.exec('BEGIN');
-    const initial = initialResult(db, root, opts.tenantId);
-    db.exec('ROLLBACK');
+    const initial = withTrialScope(db, 'quality_repair_plan', () => initialResult(db, root, opts.tenantId));
     if (!opts.apply || !initial.supported || !initial.issues.some((issue) => issue.disposition === 'set-aside'))
         return initial;
     db.exec('PRAGMA foreign_keys = ON');

package/dist/cli/recall.d.ts

@@ -1,7 +1,5 @@
-import { type CliFlags, type CommandContext } from './shared.js';
-/** Test-only: reset the CLI recall rings. Call from beforeEach. */
-export declare function __resetSessionRecallHistoryCli(): void;
-/** Runs `hippo recall`: parse, rank, load continuity, fit the printed block to the budget, audit, then write and print. */
+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>;
 //# sourceMappingURL=recall.d.ts.map

package/dist/cli/recall.js

@@ -1,46 +1,35 @@
 // The `hippo recall` verb; main() loads it lazily from the command table.
-import { envHippoSessionId } from '../env.js';
-import { confidenceFacets, Layer } from '../memory.js';
+import { envHippoSessionId } from '../util/env.js';
+import { confidenceFacets, Layer } from '../core/memory.js';
 import { isInitialized } from '../store/open.js';
-import { strengthenRetrieved } from '../store/entry-writes.js';
-import { isRecallBoostAblated } from '../ablation.js';
-import { loadIndex, saveIndex, updateStats } from '../store/index-and-stats.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 '../recall-scope.js';
+import { passesScopeFilterForRecall } from '../store/recall-scope.js';
 import { fitBudget } from '../search/finalize.js';
 import { explainMatch } from '../search/explain.js';
-import { DEFAULT_RECALL_BUDGET } from '../search/types.js';
-import { writeRecallTraceAtRoot } from '../recall-trace.js';
-import { loadConfig } from '../config.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { estimateTokens, recordTokenUse } from '../token-ledger.js';
-import { writeGoalRecallLog } from '../goals.js';
-import { dropHeldCopies } from '../same-text.js';
-import { isGlobalStoreRoot } from '../project-identity.js';
-import { detectScope } from '../scope.js';
-import { getGlobalRoot } from '../shared.js';
-import * as api from '../api.js';
-import { computePlanningFallacyOutput } from '../predictions/planning-fallacy.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled, snapshotRing } from '../recall-history.js';
-import { appendRecallAudit, recallAuditMetadata, recordShownRecall, resetSessionRings, sessionRing } from '../api/recall-record.js';
-import { detectAvailabilityBias } from '../availability.js';
-import { resolveTenantId } from '../tenant.js';
-import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from '../graph-recall.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 { 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 { rankRecall, } from '../recall-pipeline.js';
 import { JEV_DEFAULT_TOP_K } from '../rerankers/jev.js';
 import { isClefModel } from '../rerankers/clef.js';
-import { handoffText, printedTokens, sessionTrailText, settleTokens, snapshotText } from '../context-render.js';
-import { withLedgerDb } from '../ledger-db.js';
+import { handoffText, printedTokens, sessionTrailText, settleTokens, snapshotText } from '../api/context-render.js';
 import { printError } from './output.js';
-import { parseLimitFlag, parseBudgetFlag, requireInit, recallEntryText, recallHeading, parseAsOfFlag, engineFlags, printActiveTaskSnapshot, printSessionEvents, printHandoff, hostSessionId, captureConsole, hookStoreRoot, } from './shared.js';
-// Per-process rings: a single-shot `hippo recall` starts empty, so anchoring only accumulates in long-lived
-// hosts (in-process loops, `hippo serve`, the MCP server).
-/** Test-only: reset the CLI recall rings. Call from beforeEach. */
-export function __resetSessionRecallHistoryCli() {
-    resetSessionRings('cli');
-}
+import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag, flagIsTrue } 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';
 // JSON.stringify keeps quotes or parens in the matched phrase from blurring the line.
 function planningLine(p) {
     if (p.hint)
@@ -178,22 +167,46 @@ function parseRecallLateFlags(flags) {
         error,
     };
 }
-/** Runs `hippo recall`: parse, rank, load continuity, fit the printed block to the budget, audit, then write and print. */
+/** 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) {
     requireInit(hippoRoot);
     const o = parseRecallOptions(hippoRoot, flags);
-    const ranked = await rankForRecall(hippoRoot, query, flags, o);
-    const fit = fitRecallBlock(hippoRoot, query, o, ranked, loadRecallContinuity(hippoRoot, o));
-    auditRecall(hippoRoot, o, query, fit);
-    writeRecallResult(hippoRoot, query, o, fit, ranked.localIndex);
+    const priced = priceRecallEntries(hippoRoot, query, o);
+    const slot = {};
+    await api.retrieve({ hippoRoot, tenantId: o.tenantId, actor: api.adminActor('cli') }, {
+        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 },
+            note: (line) => printError(line),
+            hostSessionId: hostSessionId(),
+            show: (rank, planning) => {
+                slot.presented = presentRecall(hippoRoot, query, o, { rank, ...priced }, planning);
+                return slot.presented.shown;
+            },
+        },
+    });
+    // A late flag is rejected where the ranking halted, after the notes its earlier stages printed.
+    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);
 }
 /** Every flag recall reads, parsed in the order the single-body command checked them. */
 function parseRecallOptions(hippoRoot, flags) {
     const budget = parseBudgetFlag(flags['budget'], DEFAULT_RECALL_BUDGET);
     const limit = parseLimitFlag(flags['limit']);
-    const asJson = Boolean(flags['json']);
-    const showWhy = Boolean(flags['why']);
-    const includeSuperseded = Boolean(flags['include-superseded']);
+    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);
@@ -206,7 +219,7 @@ function parseRecallOptions(hippoRoot, flags) {
         ? parseInt(String(flags['min-results']), 10)
         : undefined;
     const activeScope = explicitScope || detectScope();
-    const graphStream = flags['graph-stream'] === true ? parseGraphStreamFlags(flags) : undefined;
+    const graphStream = flagIsTrue(flags, 'graph-stream') ? parseGraphStreamFlags(flags) : undefined;
     const late = parseRecallLateFlags(flags);
     const goalTag = flags['goal'] !== undefined ? String(flags['goal']).trim() : '';
     const sessionId = (flags['session-id'] !== undefined
@@ -215,45 +228,37 @@ function parseRecallOptions(hippoRoot, flags) {
     return {
         budget, limit, asJson, showWhy, includeSuperseded, asOf, globalRoot, primaryIsGlobal, tenantId,
         explicitScope, config, minResults, activeScope, graphStream, late, goalTag, sessionId,
-        includeContinuity: Boolean(flags['continuity']),
+        includeContinuity: boolFlag(flags, 'continuity'),
     };
 }
-/** Ranks against each entry's printed cost, then rejects a late flag at the stage where the pipeline halted. */
-async function rankForRecall(hippoRoot, query, flags, o) {
-    // Engines spend the budget on the text each result prints as, less the header, so selection and print agree.
+/** 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 entryText = (r) => recallEntryText(r, query, o.showWhy, o.primaryIsGlobal || (globalOn && !localIndex.entries[r.entry.id]));
+    const isGlobal = (r) => o.primaryIsGlobal || (globalOn && !localIndex.entries[r.entry.id]);
+    const entryText = (r) => recallEntryText(r, query, o.showWhy, isGlobal(r));
     const printCost = (r) => printedTokens(entryText(r));
+    return { 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) {
+    // Engines spend the budget on the text each result prints as, less the header, so selection and print agree.
     const entryBudget = Math.max(0, o.budget - printedTokens(recallHeading(o.budget, o.budget, query)));
-    const rank = await rankRecall({ hippoRoot, globalRoot: o.globalRoot !== hippoRoot && globalOn ? o.globalRoot : undefined, tenantId: o.tenantId, note: (line) => printError(line) }, {
-        query, budget: entryBudget, cost: printCost, limit: o.limit, why: o.showWhy, includeSuperseded: o.includeSuperseded, asOf: o.asOf,
+    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: flags['multihop'] === true || o.config.multihop.enabled, graphStream: o.graphStream, minResults: o.minResults, explain: false },
+        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: Boolean(flags['evc-adaptive']),
-        filterConflicts: Boolean(flags['filter-conflicts']),
-        valueAware: Boolean(flags['value-aware']),
-        rerankUtility: Boolean(flags['rerank-utility']),
+        evcAdaptive: boolFlag(flags, 'evc-adaptive'),
+        filterConflicts: boolFlag(flags, 'filter-conflicts'),
+        valueAware: boolFlag(flags, 'value-aware'),
+        rerankUtility: boolFlag(flags, 'rerank-utility'),
         reranker: o.late.reranker,
-        goalTag: o.goalTag,
-        sessionId: o.sessionId,
         salienceThreshold: o.late.salienceThreshold,
         outcome: o.late.outcome,
         layer: o.late.layer,
         haltBefore: o.late.error?.stage,
-    });
-    if (rank.goalRecallLog.length > 0) {
-        const dbForGoals = openHippoDb(hippoRoot);
-        try {
-            writeGoalRecallLog(dbForGoals, rank.goalRecallLog);
-        }
-        finally {
-            closeHippoDb(dbForGoals);
-        }
-    }
-    o.late.error?.fail();
-    return { rank, localIndex, entryText, printCost };
+    };
 }
 /** Loaded before the zero-result branch, so a no-match query with live continuity still returns a resume packet. */
 function loadRecallContinuity(hippoRoot, o) {
@@ -355,7 +360,7 @@ function renderRecallBlock(list, h, v) {
     }));
 }
 /** Pays the continuity sections and the plan hint first, then fits the memories into what is left. */
-function fitRecallBlock(hippoRoot, query, o, ranked, loaded) {
+function fitRecallBlock(query, o, ranked, loaded, planning) {
     const { budget } = o;
     let { activeSnapshot, sessionHandoff, recentSessionEvents } = loaded;
     // Sections print ahead of the memories, so they are paid first, after the header; one that does not fit is dropped.
@@ -372,12 +377,11 @@ function fitRecallBlock(hippoRoot, query, o, ranked, loaded) {
     const continuityTokens = sectionBudget - left;
     const continuity = { activeSnapshot, sessionHandoff, recentSessionEvents };
     const hasContinuity = activeSnapshot !== null || sessionHandoff !== null || recentSessionEvents.length > 0;
-    // The baserate hint depends on the query alone; its audit is pipeline-local (actor 'cli').
-    const cmdPlanningFallacyOutput = computePlanningFallacyOutput(hippoRoot, o.tenantId, query, { actor: 'cli' });
-    const planText = planningLine(cmdPlanningFallacyOutput);
+    // The baserate hint depends on the query alone, so `retrieve` evaluates it and this only prices the line.
+    const planText = planningLine(planning);
     const showPlan = planText !== null && pays(printedTokens(`${planText}\n`));
-    const cmdPlanningFallacyHint = showPlan ? cmdPlanningFallacyOutput.hint ?? null : null;
-    const cmdPlanningFallacyWatching = showPlan ? cmdPlanningFallacyOutput.watching ?? null : null;
+    const cmdPlanningFallacyHint = showPlan ? planning.hint ?? null : null;
+    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);
@@ -398,60 +402,35 @@ function fitRecallBlock(hippoRoot, query, o, ranked, loaded) {
     }
     return { results, hints, recallText, continuity, continuityTokens, cmdPlanningFallacyHint, cmdPlanningFallacyWatching, anchorRing };
 }
-function auditRecall(hippoRoot, o, query, fit) {
+/** 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);
     const { results, hints } = fit;
-    const who = { hippoRoot, tenantId: o.tenantId, actor: 'cli', bestEffort: true };
-    recordShownRecall(who, { query, ring: fit.anchorRing, topId: results[0]?.entry.id ?? null, anchoring: hints.anchoring, availability: hints.availability });
-    // One 'recall' event per query, before the early-empty return, in every participating store.
-    const metadata = recallAuditMetadata(query, results.length);
-    appendRecallAudit(who, 'recall', undefined, metadata);
-    if (isInitialized(o.globalRoot) && o.globalRoot !== hippoRoot) {
-        appendRecallAudit({ ...who, hippoRoot: o.globalRoot }, 'recall', undefined, metadata);
-    }
+    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) } };
 }
-/** Traces the recall, books retrieval for a non-empty list, then prints JSON or the fitted block. */
-function writeRecallResult(hippoRoot, query, o, fit, localIndex) {
-    const { tenantId, sessionId, showWhy, asJson, includeContinuity } = o;
+/** What this recall prints: the JSON object, or the fitted block. */
+function recallOutput(query, o, fit, isGlobal) {
+    const { asJson, includeContinuity } = o;
     const { results, recallText } = fit;
-    // The token ledger books the block this recall prints, on whichever exit it takes.
-    const emit = (text) => {
-        withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
-            tenantId,
-            sessionId: hostSessionId() ?? null,
-            surface: 'recall',
-            event: 'inject',
-            items: results.length,
-            tokens: estimateTokens(text),
-        }));
-        console.log(text);
-    };
     if (results.length === 0) {
-        // Traced too, so a coverage gap still lands in the training corpus; this path never touches localIndex.
-        writeRecallTraceAtRoot(hippoRoot, {
-            tenantId,
-            sessionId: sessionId || hostSessionId() || null,
-            pipeline: 'cli',
-            query,
-            explainMode: showWhy,
-            results: [],
-        });
         // HTTP and MCP surface the hint whatever matched, so the zero-result JSON keeps it for parity.
-        emit(asJson ? JSON.stringify({ query, results: [], total: 0, ...recallJsonTail(fit, includeContinuity) }) : recallText);
-        return;
-    }
-    recordRetrieval(hippoRoot, query, o, results, localIndex);
-    if (asJson) {
-        const output = results.map((r) => recallJsonRow(r, query, showWhy, o.primaryIsGlobal || (isInitialized(o.globalRoot) && !localIndex.entries[r.entry.id])));
-        emit(JSON.stringify({
-            query,
-            budget: o.budget,
-            results: output,
-            total: output.length,
-            ...recallJsonTail(fit, includeContinuity),
-        }));
-        return;
+        return asJson ? JSON.stringify({ query, results: [], total: 0, ...recallJsonTail(fit, includeContinuity) }) : recallText;
     }
-    emit(recallText);
+    if (!asJson)
+        return recallText;
+    const output = results.map((r) => recallJsonRow(r, query, o.showWhy, isGlobal(r)));
+    return JSON.stringify({
+        query,
+        budget: o.budget,
+        results: output,
+        total: output.length,
+        ...recallJsonTail(fit, includeContinuity),
+    });
 }
 /** The JSON keys after the result list: suppression summary, any bias hints, then continuity when asked for. */
 function recallJsonTail(fit, includeContinuity) {
@@ -475,34 +454,6 @@ function recallJsonTail(fit, includeContinuity) {
     }
     return tail;
 }
-/** Strengthens the returned rows and persists last_retrieval_ids and last_trace_id in one saveIndex call. */
-function recordRetrieval(hippoRoot, query, o, results, localIndex) {
-    const { globalRoot, tenantId, sessionId, showWhy } = o;
-    const retrievedIds = results.map((r) => r.entry.id);
-    const gate = { recallBoostAblated: isRecallBoostAblated() };
-    const strengthenedHere = strengthenRetrieved(hippoRoot, retrievedIds, gate);
-    if (isInitialized(globalRoot))
-        strengthenRetrieved(globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)), gate);
-    // Track last retrieval IDs for outcome command
-    localIndex.last_retrieval_ids = retrievedIds;
-    // One trace at hippoRoot, where outcome attribution lives, written first so the same saveIndex keeps
-    // last_retrieval_ids and last_trace_id in lockstep (see writeRecallTraceAtRoot). Fail-soft; never throws.
-    const traceId = writeRecallTraceAtRoot(hippoRoot, {
-        tenantId,
-        sessionId: sessionId || hostSessionId() || null,
-        pipeline: 'cli',
-        query,
-        explainMode: showWhy,
-        results: results.map((r) => ({
-            memoryId: r.entry.id,
-            score: r.score,
-            rerankSteps: r.rerankTrace,
-        })),
-    });
-    localIndex.last_trace_id = traceId !== null ? String(traceId) : null;
-    saveIndex(hippoRoot, localIndex);
-    updateStats(hippoRoot, { recalled: results.length });
-}
 function recallJsonRow(r, query, showWhy, isGlobal) {
     const base = {
         id: r.entry.id,

package/dist/{refine-llm.d.ts → cli/refine-llm.d.ts}

@@ -12,7 +12,7 @@
  * - Uses fetch directly so no SDK dependency.
  * - On failure (API error, bad response), the original memory is untouched.
  */
-import { MemoryEntry } from './memory.js';
+import { MemoryEntry } from '../core/memory.js';
 export interface RefineOptions {
     apiKey: string;
     model?: string;