hippo-memory 1.69.0 → 1.71.0

package/dist/{prompt-hook.js → api/prompt-hook.js}

@@ -1,27 +1,29 @@
 // The per-prompt hook's block and ledger rows, rendered here for `hippo context` and for promptHookContext (a remote hook route's call).
-// promptHookContext keeps the server-side copy of the CLI's getContext flags (cli/context.ts); the CLI parity case in tests/prompt-hook-context.test.ts is all that ties the two.
-import { getContext } from './api.js';
-import { BadRequestError } from './api-errors.js';
-import { isSharedStore, loadConfig } from './config.js';
+// promptHookContext keeps the server-side copy of the CLI's getContext flags (cli/context.ts);
+// the CLI parity case in tests/prompt-hook-context.test.ts is all that ties the two.
+import { getContext } from './index.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { isSharedStore, loadConfig } from '../core/config.js';
 import { contextBlockLines, contextCost, crossProjectLines, handoffText, sessionTrailText, settleTokens, snapshotText } from './context-render.js';
-import { isSqliteBusy, noteStoreBusy } from './db.js';
-import { MAX_ID_LEN } from './http-util.js';
-import { isJsonString } from './json.js';
-import { withLedgerDb } from './ledger-db.js';
+import { MAX_ID_LEN } from '../util/http-util.js';
+import { isJsonString } from '../util/json.js';
+import { bookLedgerTurn, ledgerLastSent, noteLedgerRowSkipped } from './ledger-db.js';
 import { sessionPilotArm } from './pilot-arm.js';
-import { assertCallerProject, MAX_PROJECT_ALIASES } from './project-identity.js';
-import { writeDeliveryEventAtRoot, writeDeliveryEventOnHandle } from './recall-trace.js';
-import { blockHash, estimateTokens, hookPayloadString, isSubagentPayload, lastSentState, recordTokenUse, shouldSkipUnchanged, } from './token-ledger.js';
-/** With `db`, writes on the token ledger's handle (same store); without it, opens its own. A second flush is a no-op. */
-export function flushDeliveryRecorder(rec, db) {
+import { assertCallerProject, MAX_PROJECT_ALIASES } from '../core/project-identity.js';
+import { writeDeliveryEventAtRoot } from '../store/recall-trace.js';
+import { hookPayloadString, isSubagentPayload, shouldSkipUnchanged, } from '../store/token-ledger.js';
+import { blockHash, estimateTokens } from '../util/token-text.js';
+import { errorMessage, log } from '../util/log.js';
+import { DEFAULT_CONTEXT_BUDGET } from './context.js';
+/** With `write`, stores on the token ledger's connection (same store); without it, opens its own. A second flush is a no-op. */
+export function flushDeliveryRecorder(rec, write) {
     if (rec === null)
         return;
     try {
-        rec.flush((input) => (db ? writeDeliveryEventOnHandle(db, input) : writeDeliveryEventAtRoot(rec.root, input)));
+        rec.flush(write ?? ((input) => writeDeliveryEventAtRoot(rec.root, input)));
     }
     catch (error) {
-        // The hook's one-line stderr contract pins this exact text, so it bypasses the leveled logger.
-        console.error(`[hippo] delivery ledger write failed:${error instanceof Error ? error.message : String(error)}`);
+        log.error(`delivery ledger write failed: ${errorMessage(error)}`);
     }
 }
 /** A Copilot sessionStart reply's wrapper, picked by the sender's casing: stdin.ts keeps a camelCase `sessionId`, which only the Copilot harness sends. */
@@ -113,56 +115,36 @@ function skipUnchangedStatic(view, surface, staticBlock, recallBlock, staticCoun
     // Before the ledger read, so a caller that did not print this block books no skip row.
     if (view.printedHash !== undefined && view.printedHash !== staticHash)
         return false;
-    const last = withLedgerDb(hippoRoot, (db) => lastSentState(db, view.tenantId, payloadSessionId, surface), ledgerOpts);
+    const last = ledgerLastSent(hippoRoot, view.tenantId, payloadSessionId, surface, ledgerOpts);
     if (!shouldSkipUnchanged(last ?? null, staticHash, refreshTurns))
         return false;
-    withLedgerDb(hippoRoot, (db) => {
-        recordTokenUse(db, {
-            tenantId: view.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
-            items: staticCount, tokens: estimateTokens(staticBlock), hash: staticHash,
-        });
-        if (recallBlock.trim())
-            return;
-        rec?.delivered({ state: 'reused', staticHash, staticReused: true });
-        flushDeliveryRecorder(rec, db);
+    bookLedgerTurn(hippoRoot, {
+        uses: [{
+                tenantId: view.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
+                items: staticCount, tokens: estimateTokens(staticBlock), hash: staticHash,
+            }],
+        delivery: recallBlock.trim() ? undefined : (write) => {
+            rec?.delivered({ state: 'reused', staticHash, staticReused: true });
+            flushDeliveryRecorder(rec, write);
+        },
     }, ledgerOpts);
     return true;
 }
-/** One connection for both rows; each insert in its own try so one failing doesn't skip the other. */
+/** One connection for both rows; a failed row is logged and the other still lands, because a ledger failure must not break the hook. */
 function recordAdditionalContextRows(view, surface, staticPart, recallPart) {
-    withLedgerDb(view.hippoRoot, (db) => {
-        if (staticPart.text) {
-            try {
-                recordTokenUse(db, {
-                    tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface, event: 'inject',
-                    items: staticPart.items, tokens: estimateTokens(staticPart.text), hash: blockHash(staticPart.text),
-                });
-                // Best-effort row: only a busy store is actionable, and a ledger failure must not break the hook.
-            }
-            catch (error) {
-                if (isSqliteBusy(error))
-                    noteStoreBusy('token ledger row skipped');
-            }
-        }
-        if (recallPart.text) {
-            try {
-                recordTokenUse(db, {
-                    tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface: 'hook_recall', event: 'inject',
-                    items: recallPart.items, tokens: estimateTokens(recallPart.text), hash: blockHash(recallPart.text),
-                });
-                // Same best-effort rule as the inject row above.
-            }
-            catch (error) {
-                if (isSqliteBusy(error))
-                    noteStoreBusy('token ledger row skipped');
-            }
-        }
-        flushDeliveryRecorder(view.rec, db);
+    const row = (part, on) => ({
+        tenantId: view.tenantId, sessionId: view.ledgerSessionId, surface: on, event: 'inject',
+        items: part.items, tokens: estimateTokens(part.text), hash: blockHash(part.text),
+    });
+    bookLedgerTurn(view.hippoRoot, {
+        uses: [...(staticPart.text ? [row(staticPart, surface)] : []), ...(recallPart.text ? [row(recallPart, 'hook_recall')] : [])],
+        onRowError: noteLedgerRowSkipped,
+        delivery: (write) => flushDeliveryRecorder(view.rec, write),
     }, { sharedStore: view.sharedStore });
 }
 // The flags HIPPO_PINNED_INJECT_COMMAND gives the local hook; the CLI parity test fails if the two drift.
 const HOOK_INCLUDE_RECENT = 5;
-const HOOK_BUDGET = 1500;
+const HOOK_BUDGET = DEFAULT_CONTEXT_BUDGET;
 const HOOK_FRAMING = 'observe';
 // blockHash's shape (token-ledger.ts).
 const BLOCK_HASH_RE = /^[0-9a-f]{16}$/;
@@ -181,10 +163,10 @@ function assertPromptHookRequest(req) {
         throw new BadRequestError('printed hash: 16 lowercase hex characters');
     }
 }
-/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for the caller's project, leaving out an unchanged static block only when `printedHash` matches it.
- *  `arm` is the raw ledger arm (`hippo` or `holdout`), null at rate 0; a holdout session gets an empty stdout. `staticHash` is the hash to echo back: null with no static block, for a sub-agent or a holdout.
- *  Scope detection (HIPPO_SCOPE and skill env vars) and delivery-ledger events are CLI-only.
- *  Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
+/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for its project.
+ * Omits an unchanged static block only when `printedHash` matches; `arm` is the ledger arm (`hippo` or `holdout`, null at rate 0); a holdout gets empty stdout.
+ * `staticHash` is the hash to echo back (null with no static block, a sub-agent or a holdout). Scope detection and delivery-ledger events are CLI-only.
+ * Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
 export async function promptHookContext(ctx, req, opts = {}) {
     assertPromptHookRequest(req);
     const { sessionId, payload } = req;

package/dist/api/quarantine.d.ts

@@ -1,5 +1,5 @@
-import { type QuarantineStatus } from '../quarantine.js';
-import type { KeysetPosition } from '../keyset.js';
+import type { QuarantineStatus } from '../store/quarantine.js';
+import type { KeysetPosition } from '../util/keyset.js';
 import type { Context } from './types.js';
 export interface QuarantineListItem {
     id: string;
@@ -16,9 +16,9 @@ export declare function quarantineList(ctx: Context, opts?: {
     status?: QuarantineStatus | 'all';
     limit?: number;
     after?: KeysetPosition;
-}): QuarantineListItem[];
+}): Promise<QuarantineListItem[]>;
 /** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
-export declare function quarantineApprove(ctx: Context, id: string): void;
+export declare function quarantineApprove(ctx: Context, id: string): Promise<void>;
 /** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
-export declare function quarantineReject(ctx: Context, id: string): void;
+export declare function quarantineReject(ctx: Context, id: string): Promise<void>;
 //# sourceMappingURL=quarantine.d.ts.map

package/dist/api/quarantine.js

@@ -1,122 +1,46 @@
 // Quarantine review: list, approve and reject held memories.
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { ConflictError, ForbiddenError, NotFoundError } from '../api-errors.js';
-import { writeEntryMirrors } from '../store/entry-writes.js';
-import { readEntry, selectEntriesByIds } from '../store/entry-reads.js';
-import { quarantineScopeFor, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from '../quarantine.js';
-import { log } from '../log.js';
-import { appendAuditEvent } from '../audit.js';
+import { ConflictError, ForbiddenError, NotFoundError } from '../core/api-errors.js';
+import { requireGroup, storeFor } from '../store/index.js';
 const QUARANTINE_PREVIEW_CHARS = 200;
 /** A tenant's quarantined memories, newest first. Default `status` is 'pending' (the review queue). */
-export function quarantineList(ctx, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const rows = listQuarantineRows(db, ctx.tenantId, opts.status ?? 'pending', opts.limit, opts.after);
-        const entries = selectEntriesByIds(db, rows.map((row) => row.memoryId), ctx.tenantId);
-        return rows.map((row) => {
-            const entry = entries.get(row.memoryId);
-            return {
-                id: row.memoryId,
-                originalScope: row.originalScope,
-                reason: row.reason,
-                status: row.status,
-                quarantinedAt: row.quarantinedAt,
-                decidedAt: row.decidedAt,
-                decidedBy: row.decidedBy,
-                contentPreview: entry ? entry.content.slice(0, QUARANTINE_PREVIEW_CHARS) : '',
-            };
-        });
-    }
-    finally {
-        closeHippoDb(db);
-    }
+export async function quarantineList(ctx, opts = {}) {
+    const rows = await requireGroup(storeFor(ctx), 'quarantine')
+        .listQuarantined(ctx.tenantId, { status: opts.status ?? 'pending', limit: opts.limit, after: opts.after });
+    return rows.map((row) => ({
+        id: row.memoryId,
+        originalScope: row.originalScope,
+        reason: row.reason,
+        status: row.status,
+        quarantinedAt: row.quarantinedAt,
+        decidedAt: row.decidedAt,
+        decidedBy: row.decidedBy,
+        contentPreview: (row.content ?? '').slice(0, QUARANTINE_PREVIEW_CHARS),
+    }));
 }
-function loadPendingQuarantineRow(db, tenantId, id) {
-    const row = getQuarantineRow(db, tenantId, id);
-    if (!row)
-        throw new NotFoundError(`not quarantined: ${id}`);
-    if (row.status !== 'pending')
-        throw new ConflictError(`${id} is already ${row.status}`);
-    return row;
+function refusalError(id, refusal) {
+    if (refusal.outcome === 'not_quarantined')
+        return new NotFoundError(`not quarantined: ${id}`);
+    return new ConflictError(`${id} is already ${refusal.status}`);
 }
 /** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
-export function quarantineApprove(ctx, id) {
+export async function quarantineApprove(ctx, id) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can approve a quarantined memory');
     }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const row = loadPendingQuarantineRow(db, ctx.tenantId, id);
-            const quarantineScope = quarantineScopeFor(row.originalScope);
-            const updated = db
-                .prepare(`UPDATE memories SET scope = ? WHERE id = ? AND tenant_id = ? AND scope = ?`)
-                .run(row.originalScope, id, ctx.tenantId, quarantineScope);
-            if (Number(updated.changes ?? 0) !== 1) {
-                throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
-            }
-            approveQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'quarantine_approve',
-                targetId: id,
-                metadata: { originalScope: row.originalScope },
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            throw err;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    // Post-commit, best-effort: a failed rewrite leaves the mirror showing the quarantine scope (fail-closed).
-    try {
-        const restored = readEntry(ctx.hippoRoot, id, ctx.tenantId);
-        if (restored)
-            writeEntryMirrors(ctx.hippoRoot, restored);
-    }
-    catch (err) {
-        log.error(`quarantine: mirror rewrite failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const result = await requireGroup(storeFor(ctx), 'quarantine').approveQuarantined(ctx.tenantId, id, ctx.actor.subject);
+    if (result.outcome === 'approved')
+        return;
+    if (result.outcome === 'scope_moved')
+        throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
+    throw refusalError(id, result);
 }
 /** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
-export function quarantineReject(ctx, id) {
+export async function quarantineReject(ctx, id) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can reject a quarantined memory');
     }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            loadPendingQuarantineRow(db, ctx.tenantId, id);
-            rejectQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'quarantine_reject',
-                targetId: id,
-                metadata: {},
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            throw err;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    const result = await requireGroup(storeFor(ctx), 'quarantine').rejectQuarantined(ctx.tenantId, id, ctx.actor.subject);
+    if (result.outcome !== 'rejected')
+        throw refusalError(id, result);
 }
 //# sourceMappingURL=quarantine.js.map

package/dist/api/recall-cli.d.ts

@@ -0,0 +1,55 @@
+import { confidenceFacets } from '../core/memory.js';
+import type { ResultCost, SearchResult } from '../core/search-types.js';
+import type { RerankerFn } from '../rerankers/types.js';
+import { explainMatch } from '../search/explain.js';
+import type { ContinuityBlock } from '../store/port.js';
+import type { Context } from './types.js';
+export { DEFAULT_MAX_NEIGHBORS, MAX_HOPS } from '../graph/recall.js';
+/** The global store beside this one, whether this one is it, and the scope that boosts rows. */
+export interface CliRecallSetting {
+    readonly globalRoot: string;
+    readonly primaryIsGlobal: boolean;
+    readonly activeScope: string | null;
+}
+/** The active scope merges `--scope` with the detected one, which only boosts. */
+export declare function cliRecallSetting(ctx: Context, explicitScope: string | null): CliRecallSetting;
+export interface CliRecallOrigin {
+    readonly globalOn: boolean;
+    /** True when a ranked row came from the global store: this store is it, or the global store is on and this one lacks the id. */
+    readonly isGlobal: (id: string) => boolean;
+}
+export declare function cliRecallOrigin(ctx: Context, setting: CliRecallSetting): CliRecallOrigin;
+/** The active snapshot, its session's latest handoff and last five events, each kept only when its scope passes. */
+export declare function loadCliRecallContinuity(ctx: Context, setting: CliRecallSetting, wanted: boolean): ContinuityBlock;
+export interface CliRecallRerankerPick {
+    readonly fn: RerankerFn;
+    readonly defaultTopK: number;
+}
+/** The reranker a `--reranker` name picks and the top-k it takes by default; an unknown name throws, a blank one picks none. */
+export declare function cliRecallReranker(name: string): CliRecallRerankerPick | null;
+/** The ranked rows a print budget holds, best first; the first `floor` stay whatever they cost. */
+export declare function fitRecallRows(ranked: SearchResult[], budget: number, floor: number, cost: ResultCost): SearchResult[];
+/** One result row; the optional keys are set in the order the JSON prints them. */
+export interface RecallJsonRow {
+    id: string;
+    score: number;
+    strength: SearchResult['entry']['strength'];
+    tokens: number;
+    tags: SearchResult['entry']['tags'];
+    content: string;
+    layer: SearchResult['entry']['layer'];
+    trace_outcome?: SearchResult['entry']['trace_outcome'];
+    superseded?: boolean;
+    superseded_by?: SearchResult['entry']['superseded_by'];
+    graphVia?: SearchResult['graphVia'];
+    confidence?: ReturnType<typeof confidenceFacets>['tier'];
+    aged_out?: ReturnType<typeof confidenceFacets>['agedOut'];
+    source?: 'global' | 'local';
+    reason?: ReturnType<typeof explainMatch>['reason'];
+    bm25?: SearchResult['bm25'];
+    cosine?: SearchResult['cosine'];
+    envelope?: ReturnType<typeof explainMatch>['envelope'];
+    rerankTrace?: SearchResult['rerankTrace'];
+}
+export declare function recallJsonRow(r: SearchResult, query: string, showWhy: boolean, isGlobal: boolean): RecallJsonRow;
+//# sourceMappingURL=recall-cli.d.ts.map

package/dist/api/recall-cli.js

@@ -0,0 +1,94 @@
+// What the `hippo recall` verb reads beside its ranking core: the stores it searches, the resume packet and the JSON rows.
+import { confidenceFacets, Layer } from '../core/memory.js';
+import { isGlobalStoreRoot } from '../core/project-identity.js';
+import { getReranker } from '../rerankers/index.js';
+import { isClefModel } from '../rerankers/clef.js';
+import { JEV_DEFAULT_TOP_K } from '../rerankers/jev.js';
+import { explainMatch } from '../search/explain.js';
+import { fitBudget } from '../search/finalize.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { detectScope } from '../sharing/scope.js';
+import { loadLatestHandoff } from '../store/handoffs.js';
+import { loadIndex } from '../store/index-and-stats.js';
+import { isInitialized } from '../store/open.js';
+import { passesScopeFilterForRecall } from '../store/recall-scope.js';
+import { listSessionEvents, loadActiveTaskSnapshot } from '../store/sessions.js';
+export { DEFAULT_MAX_NEIGHBORS, MAX_HOPS } from '../graph/recall.js';
+/** The active scope merges `--scope` with the detected one, which only boosts. */
+export function cliRecallSetting(ctx, explicitScope) {
+    return { globalRoot: getGlobalRoot(), primaryIsGlobal: isGlobalStoreRoot(ctx.hippoRoot), activeScope: explicitScope || detectScope() };
+}
+export function cliRecallOrigin(ctx, setting) {
+    const localIndex = loadIndex(ctx.hippoRoot);
+    const globalOn = isInitialized(setting.globalRoot);
+    return { globalOn, isGlobal: (id) => setting.primaryIsGlobal || (globalOn && !localIndex.entries[id]) };
+}
+/** The active snapshot, its session's latest handoff and last five events, each kept only when its scope passes. */
+export function loadCliRecallContinuity(ctx, setting, wanted) {
+    if (!wanted || setting.primaryIsGlobal)
+        return { activeSnapshot: null, sessionHandoff: null, recentSessionEvents: [] };
+    const { hippoRoot, tenantId } = ctx;
+    const rawSnapshot = loadActiveTaskSnapshot(hippoRoot, tenantId);
+    const sessionId = rawSnapshot?.session_id ?? undefined;
+    const rawHandoff = sessionId ? loadLatestHandoff(hippoRoot, tenantId, sessionId) : null;
+    const rawEvents = sessionId ? listSessionEvents(hippoRoot, tenantId, { session_id: sessionId, limit: 5 }) : [];
+    // The same shared scope rule as api.recall; the active scope merges --scope and detectScope().
+    const effectiveScope = setting.activeScope || undefined;
+    const passes = (r) => passesScopeFilterForRecall(r.scope ?? null, effectiveScope);
+    return {
+        activeSnapshot: rawSnapshot && passes(rawSnapshot) ? rawSnapshot : null,
+        sessionHandoff: rawHandoff && passes(rawHandoff) ? rawHandoff : null,
+        recentSessionEvents: rawEvents.filter(passes),
+    };
+}
+/** The reranker a `--reranker` name picks and the top-k it takes by default; an unknown name throws, a blank one picks none. */
+export function cliRecallReranker(name) {
+    const fn = getReranker(name);
+    if (!fn)
+        return null;
+    return { fn, defaultTopK: name === 'jev' || isClefModel(name) ? JEV_DEFAULT_TOP_K : 50 };
+}
+/** The ranked rows a print budget holds, best first; the first `floor` stay whatever they cost. */
+export function fitRecallRows(ranked, budget, floor, cost) {
+    return fitBudget(ranked, budget, floor, cost);
+}
+export function recallJsonRow(r, query, showWhy, isGlobal) {
+    const base = {
+        id: r.entry.id,
+        score: r.score,
+        strength: r.entry.strength,
+        tokens: r.tokens,
+        tags: r.entry.tags,
+        content: r.entry.content,
+        layer: r.entry.layer,
+    };
+    if (r.entry.layer === Layer.Trace) {
+        base.trace_outcome = r.entry.trace_outcome;
+    }
+    if (r.entry.superseded_by) {
+        base.superseded = true;
+        base.superseded_by = r.entry.superseded_by;
+    }
+    if (r.graphVia) {
+        base.graphVia = r.graphVia;
+    }
+    if (showWhy) {
+        const explanation = explainMatch(query, r);
+        const facets = confidenceFacets(r.entry);
+        base.confidence = facets.tier;
+        base.aged_out = facets.agedOut;
+        base.source = isGlobal ? 'global' : 'local';
+        base.reason = explanation.reason;
+        base.bm25 = r.bm25;
+        base.cosine = r.cosine;
+        if (explanation.envelope) {
+            base.envelope = explanation.envelope;
+        }
+        // The ordered lifecycle re-ranking steps, so a caller can see why a row moved.
+        if (r.rerankTrace && r.rerankTrace.length > 0) {
+            base.rerankTrace = r.rerankTrace;
+        }
+    }
+    return base;
+}
+//# sourceMappingURL=recall-cli.js.map

package/dist/api/recall-core.d.ts

@@ -0,0 +1,4 @@
+import type { CliCoreRanker, RecallOpts, RecallResult } from './recall-types.js';
+import type { Context } from './types.js';
+export declare function retrieveWithCliCore(ctx: Context, opts: RecallOpts, core: CliCoreRanker): Promise<RecallResult>;
+//# sourceMappingURL=recall-core.d.ts.map

package/dist/api/recall-core.js

@@ -0,0 +1,120 @@
+// The CLI ranking core as a ranker of retrieve(): rank, let the caller pick the list it shows, then record that list once.
+import { ForbiddenError } from '../core/api-errors.js';
+import { reportAuditWriteFailure } from '../store/audit.js';
+import { decidePlanningFallacy, detectPlanningClaim } from '../predictions/planning-fallacy.js';
+import { rankRecall } from './recall-pipeline.js';
+import { writeRecallTraceAtRoot } from '../store/recall-trace.js';
+import { saveIndex } from '../store/index-and-stats.js';
+import { sqliteStore } from '../store/index.js';
+import { estimateTokens } from '../util/token-text.js';
+import { callerOf, recallAuditMetadata, recallAuditRow, strengthenOf } from './recall-record.js';
+import { RECALL_RECORDING, recordShownRecall } from './recall-finish.js';
+// entriesByIds reads at most this many ids a call.
+const ID_READ_CHUNK = 500;
+export async function retrieveWithCliCore(ctx, opts, core) {
+    // This ranker applies the operator's scope rule and may search a second store, so no bearer client may reach it.
+    if (!ctx.actor.hostAdmin)
+        throw new ForbiddenError('The CLI ranking core serves the host admin only');
+    const globalRoot = core.sources?.globalRoot;
+    // The ranking core reads hippo.db itself, so its writes go to the same file whatever store the context names.
+    const store = sqliteStore(ctx.hippoRoot);
+    const ranking = await rankRecall({ hippoRoot: ctx.hippoRoot, globalRoot, tenantId: ctx.tenantId, note: core.note }, { ...core.rank, query: opts.query, sessionId: opts.sessionId, goalTag: opts.goalTag });
+    if (ranking.halted) {
+        // The stages that ran earned these rows, so the caller's flag error does not drop them.
+        if (ranking.goalRecallLog.length > 0)
+            await store.finishRecall({ goalLog: ranking.goalRecallLog, audit: [] });
+        return resultOf(ranking, []);
+    }
+    if ('inspect' in core) {
+        core.inspect(ranking);
+        return resultOf(ranking, ranking.results);
+    }
+    const planning = await planningFor(ctx, store, opts.query);
+    const shown = core.show(ranking, planning?.output ?? {});
+    await recordShown(ctx, store, opts, core, { ranking, shown, planningAudit: planning?.audit });
+    const result = resultOf(ranking, shown.results);
+    if (planning?.output.hint)
+        result.planningFallacyHint = planning.output.hint;
+    if (planning?.output.watching)
+        result.planningFallacyWatching = planning.output.watching;
+    return result;
+}
+async function planningFor(ctx, store, query) {
+    const claim = detectPlanningClaim(query);
+    if (!claim)
+        return null;
+    return decidePlanningFallacy(claim, await store.planningFallacyEvidence(ctx.tenantId, claim.classQueryTokens), ctx.tenantId, ctx.actor.subject);
+}
+function resultOf(ranking, shown) {
+    const results = shown.map((r) => ({ id: r.entry.id, content: r.entry.content, score: r.score, layer: r.entry.layer, strength: r.entry.strength }));
+    return {
+        results,
+        total: ranking.totalCandidates + ranking.graphAdded,
+        tokens: results.reduce((sum, r) => sum + estimateTokens(r.content), 0),
+    };
+}
+/** Audit rows first: a recall they cannot be written for leaves no strengthen, trace, marker or count, as under the other rankers. */
+async function recordShown(ctx, store, opts, core, done) {
+    const { ranking, shown, planningAudit } = done;
+    const ids = shown.results.map((r) => r.entry.id);
+    const recallRow = recallAuditRow(callerOf(ctx), 'recall', undefined, recallAuditMetadata(opts.query, ids.length));
+    const second = core.sources?.globalRoot !== undefined && core.sources.globalRoot !== ctx.hippoRoot ? core.sources.globalRoot : undefined;
+    const heldElsewhere = second !== undefined ? await idsNotHeld(store, ids, ctx.tenantId) : [];
+    const audited = await finishOrReport(store, {
+        goalLog: ranking.goalRecallLog,
+        audit: [...(planningAudit ? [planningAudit] : []), ...shown.audit, recallRow],
+        strengthen: strengthenOf(ctx, ids),
+    });
+    if (audited) {
+        // The second store logs that it was searched, and strengthens only the rows the first does not hold.
+        if (second !== undefined)
+            await finishOrReport(sqliteStore(second), { goalLog: [], audit: [recallRow], strengthen: strengthenOf(ctx, heldElsewhere) });
+        traceAndMark(ctx, opts, core, shown.results);
+    }
+    // The caller prints whether or not the record was written, so the ring and the ledger still take this list; `written` holds back the count.
+    await recordShownRecall(ctx, store, RECALL_RECORDING.cli, {
+        query: opts.query,
+        sessionId: opts.sessionId,
+        topId: ids[0] ?? null,
+        anchoredOn: shown.anchoredOn,
+        items: ids.length,
+        tokens: shown.tokens,
+        ledgerSessionId: core.hostSessionId ?? null,
+        written: audited,
+    });
+}
+// The caller has ranked and is about to print, so a failed audit write is logged and counted, never thrown.
+async function finishOrReport(store, writes) {
+    try {
+        await store.finishRecall(writes);
+        return true;
+    }
+    catch (err) {
+        reportAuditWriteFailure('recall', String(err));
+        return false;
+    }
+}
+async function idsNotHeld(store, ids, tenantId) {
+    const held = new Set();
+    for (let i = 0; i < ids.length; i += ID_READ_CHUNK) {
+        for (const entry of await store.entriesByIds(ids.slice(i, i + ID_READ_CHUNK), tenantId))
+            held.add(entry.id);
+    }
+    return ids.filter((id) => !held.has(id));
+}
+function traceAndMark(ctx, opts, core, shown) {
+    // An empty list is traced too, so a coverage gap still reaches the training corpus.
+    const traceId = writeRecallTraceAtRoot(ctx.hippoRoot, {
+        tenantId: ctx.tenantId,
+        sessionId: opts.sessionId || core.hostSessionId || null,
+        pipeline: 'cli',
+        query: opts.query,
+        explainMode: core.rank.why === true,
+        results: shown.map((r) => ({ memoryId: r.entry.id, score: r.score, rerankSteps: r.rerankTrace })),
+    });
+    if (shown.length === 0)
+        return;
+    // One write for both markers, so `hippo outcome` never pairs these ids with an older trace.
+    saveIndex(ctx.hippoRoot, { last_retrieval_ids: shown.map((r) => r.entry.id), last_trace_id: traceId !== null ? String(traceId) : null });
+}
+//# sourceMappingURL=recall-core.js.map

package/dist/api/recall-finish.d.ts

@@ -0,0 +1,53 @@
+import type { AppendAuditOpts } from '../store/audit.js';
+import type { HippoStore } from '../store/index.js';
+import type { TokenSurface } from '../store/token-ledger.js';
+import { type RecallHistorySnapshot } from './recall-history.js';
+import { type RecallSurface } from './recall-record.js';
+import type { Context } from './types.js';
+/** How one surface's recall is recorded. The surfaces differ in these three values and in the list they hand over, nowhere else. */
+export interface RecallRecording {
+    /** Whose session rings the recall reads and feeds. */
+    readonly ring: RecallSurface;
+    /** The label of its token ledger row. */
+    readonly ledger: TokenSurface;
+    /** 'every': an empty list still reaches the stats write, which then only rewrites stats.json; 'shown': an empty list skips it. */
+    readonly stats: 'every' | 'shown';
+}
+/** The surfaces `retrieve` records in full. MCP is pending: src/mcp still feeds its own ring and books its own ledger row, and counts no stats. */
+export declare const RECALL_RECORDING: {
+    readonly http: {
+        readonly ring: "http";
+        readonly ledger: "http_recall";
+        readonly stats: "every";
+    };
+    readonly cli: {
+        readonly ring: "cli";
+        readonly ledger: "recall";
+        readonly stats: "shown";
+    };
+};
+/** What a recorded recall takes into ranking. */
+export interface RecallLead {
+    readonly recallHistory: RecallHistorySnapshot | undefined;
+    readonly leadingAudit: readonly AppendAuditOpts[];
+}
+/** For a surface whose hint `retrieve` judges: the session's history, or the row saying the recall named no session. */
+export declare function recallLead(ctx: Context, how: RecallRecording, query: string, sessionId: string | undefined): RecallLead;
+/** The list a recall showed, as its ranker counted and priced it. */
+export interface ShownList {
+    readonly query: string;
+    /** The recall's session, which keys the ring. */
+    readonly sessionId: string | undefined;
+    readonly topId: string | null;
+    /** The memory this recall's anchoring hint named; the next recall's cooldown reads it. */
+    readonly anchoredOn: string | undefined;
+    readonly items: number;
+    readonly tokens: number;
+    /** The session the ledger row names: the recall's own on HTTP, the host agent's on the CLI. */
+    readonly ledgerSessionId: string | null;
+    /** False when the audit rows could not be written and the caller answers anyway. */
+    readonly written: boolean;
+}
+/** Runs after the recall's own write, in this order: the ring, then the counter, then the ledger. */
+export declare function recordShownRecall(ctx: Context, store: HippoStore, how: RecallRecording, shown: ShownList): Promise<void>;
+//# sourceMappingURL=recall-finish.d.ts.map