hippo-memory 1.69.0 → 1.70.0

package/dist/{recall-history.js → api/recall-history.js}

@@ -17,7 +17,7 @@
  * AnchoringHint + PlanningFallacyHint are independent
  * signals; both can fire on the same recall.
  */
-import { envAnchoringOff, envAvailabilityOff } from './env.js';
+import { envAnchoringOff, envAvailabilityOff } from '../util/env.js';
 const DEFAULT_MIN_DOMINANCE = 3;
 const DEFAULT_RECENT_REPEAT_WINDOW = 5;
 const DEFAULT_COOLDOWN = 3;
@@ -47,7 +47,7 @@ export function hashQueryText(query) {
         .split(/\s+/)
         .filter((t) => t.length > 0);
     // Drop tokens under 3 chars (filler words) so `a login bug` and `login bug` hash
-    // alike; matches the >=3 filter in src/forward-claim-detector.ts.
+    // alike; matches the >=3 filter in src/learn/forward-claim-detector.ts.
     const filtered = normalized.filter((t) => t.length >= 3);
     // Fall back to all tokens when the filter empties the query (CJK 2-char words,
     // acronyms like `AI`) so distinct short queries do not all hash to fnv1a32('').
@@ -101,17 +101,8 @@ export function detectAnchoring(history, currentQueryHash, currentTopMemoryId, o
             return null;
         }
     }
-    // memory_dominance check FIRST (wins on tie). Count distinct queryHashes in history
-    // where topMemoryId === currentTopMemoryId (excluding null tops).
-    const matchingQueryHashes = new Set();
-    for (const entry of history) {
-        if (entry.topMemoryId === currentTopMemoryId) {
-            matchingQueryHashes.add(entry.queryHash);
-        }
-    }
-    // Include current query in the count.
-    matchingQueryHashes.add(currentQueryHash);
-    const queryCount = matchingQueryHashes.size;
+    // memory_dominance check FIRST (wins on tie).
+    const queryCount = countDistinctQueries(history, currentQueryHash, currentTopMemoryId);
     if (queryCount >= minDominance) {
         return {
             reason: 'memory_dominance',
@@ -121,21 +112,35 @@ export function detectAnchoring(history, currentQueryHash, currentTopMemoryId, o
             source: 'j1-recurrence',
         };
     }
-    // query_repeat check: is currentQueryHash present in the last `recentRepeatWindow`
-    // entries AND was that entry's topMemoryId === currentTopMemoryId?
-    const r1Slice = history.slice(-recentRepeatWindow);
-    for (const entry of r1Slice) {
-        if (entry.queryHash === currentQueryHash && entry.topMemoryId === currentTopMemoryId) {
-            return {
-                reason: 'query_repeat',
-                memoryId: currentTopMemoryId,
-                summary: `Same query phrasing as a recent recall returned the same top result (${currentTopMemoryId}); you may be re-asking the same question.`,
-                source: 'j1-recurrence',
-            };
-        }
+    if (isRecentRepeat(history, recentRepeatWindow, currentQueryHash, currentTopMemoryId)) {
+        return {
+            reason: 'query_repeat',
+            memoryId: currentTopMemoryId,
+            summary: `Same query phrasing as a recent recall returned the same top result (${currentTopMemoryId}); you may be re-asking the same question.`,
+            source: 'j1-recurrence',
+        };
     }
     return null;
 }
+// Count distinct queryHashes in history where topMemoryId === the current top
+// (excluding null tops), plus the current query itself.
+function countDistinctQueries(history, currentQueryHash, currentTopMemoryId) {
+    const matchingQueryHashes = new Set();
+    for (const entry of history) {
+        if (entry.topMemoryId === currentTopMemoryId) {
+            matchingQueryHashes.add(entry.queryHash);
+        }
+    }
+    matchingQueryHashes.add(currentQueryHash);
+    return matchingQueryHashes.size;
+}
+// query_repeat check: is currentQueryHash present in the last `recentRepeatWindow`
+// entries AND was that entry's topMemoryId === currentTopMemoryId?
+function isRecentRepeat(history, recentRepeatWindow, currentQueryHash, currentTopMemoryId) {
+    return history
+        .slice(-recentRepeatWindow)
+        .some((entry) => entry.queryHash === currentQueryHash && entry.topMemoryId === currentTopMemoryId);
+}
 // ---------------------------------------------------------------------------
 // RingBuffer + caller-side state helpers
 // ---------------------------------------------------------------------------

package/dist/{recall-pipeline.d.ts → api/recall-pipeline.d.ts}

@@ -1,8 +1,8 @@
-import { type GoalRecallLogRow } from './goals.js';
-import { type MemoryEntry } from './memory.js';
-import type { PhysicsConfig } from './physics-config.js';
-import type { RerankerFn } from './rerankers/types.js';
-import type { ResultCost, SearchResult } from './search/types.js';
+import { type GoalRecallLogRow } from '../store/goals.js';
+import { type MemoryEntry } from '../core/memory.js';
+import type { PhysicsConfig } from '../core/physics-config.js';
+import type { RerankerFn } from '../rerankers/types.js';
+import type { ResultCost, SearchResult } from '../core/search-types.js';
 /** Stores rankRecall reads and where it sends operator notes. */
 export interface RankRecallCtx {
     hippoRoot: string;

package/dist/{recall-pipeline.js → api/recall-pipeline.js}

@@ -1,22 +1,22 @@
 // Ranking core shared by `hippo recall` and `hippo explain`: load, search, expand, re-rank and filter, with no
 // writes and no direct output. Callers own flag parsing, printing, budget fitting and persistence.
-import { evalNow } from './ablation.js';
-import { oneCopyPerMemory } from './api.js';
-import { compareEntryIdentity } from './compare.js';
-import { closeHippoDb, openHippoDb } from './db.js';
-import { isEmbeddingAvailable } from './local-embedding.js';
-import { computeGoalStackBoost } from './goals.js';
-import { graphExpandRecall } from './graph-recall.js';
-import { DEFAULT_GRAPH_STREAM_WEIGHT } from './graph-stream.js';
-import { Layer } from './memory.js';
-import { multihopSearch } from './multihop.js';
-import { passesCliRecallScopeFilter } from './recall-scope.js';
-import { currentEntries } from './search/as-of.js';
-import { hybridSearch } from './search/hybrid.js';
-import { physicsSearch } from './search/physics-search.js';
-import { searchBothHybrid } from './shared.js';
-import { loadRecallSearchEntries, recallScopeFilter } from './store/search-rows.js';
-import { textOverlap, tokenize as tokenizeQuery } from './tokenize.js';
+import { evalNow } from '../core/ablation.js';
+import { oneCopyPerMemory } from './context-select.js';
+import { compareEntryIdentity, compareScoresDesc } from '../core/compare.js';
+import { isEmbeddingAvailable } from '../store/embeddings/local.js';
+import { activeGoalsWithPolicies, boostByGoals } from '../store/goals.js';
+import { graphExpandRecall } from '../graph/recall.js';
+import { DEFAULT_GRAPH_STREAM_WEIGHT } from '../graph/stream.js';
+import { Layer } from '../core/memory.js';
+import { multihopSearch } from '../search/multihop.js';
+import { passesCliRecallScopeFilter } from '../store/recall-scope.js';
+import { currentEntries } from '../search/as-of.js';
+import { STRENGTH_RANK_FLOOR, STRENGTH_RANK_SPAN } from '../search/boosts.js';
+import { hybridSearch } from '../search/hybrid.js';
+import { physicsSearch } from '../search/physics-search.js';
+import { searchBothHybrid } from '../sharing/shared.js';
+import { loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
+import { textOverlap, tokenize as tokenizeQuery } from '../util/tokenize.js';
 /** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and
  *  physics state; writes nothing and prints nothing (notes go to `ctx.note`). The caller supplies the cost
  *  function and reranker in `opts`, and persists the returned goal-log rows. */
@@ -155,7 +155,7 @@ function traced(opts, prev, next, step) {
 }
 /** Re-sort after a score change. Plain and stable on purpose: ties keep the prior rank, not a content order. */
 function byScore(results) {
-    return results.sort((a, b) => b.score - a.score);
+    return results.sort((a, b) => compareScoresDesc(a.score, b.score));
 }
 function applyPfcRerankers(opts, state) {
     if (opts.evcAdaptive && state.results.length >= 2)
@@ -168,8 +168,8 @@ function applyPfcRerankers(opts, state) {
             const hasPeerInResults = (r.entry.conflicts_with || []).some((peerId) => presentIds.has(peerId));
             if (!hasPeerInResults)
                 return r;
-            const next = { ...r, score: r.score * 0.3 };
-            return traced(opts, r, next, { stage: 'interference', multiplier: 0.3, scoreBefore: r.score, scoreAfter: next.score });
+            const next = { ...r, score: r.score * CONFLICT_PEER_MULTIPLIER };
+            return traced(opts, r, next, { stage: 'interference', multiplier: CONFLICT_PEER_MULTIPLIER, scoreBefore: r.score, scoreAfter: next.score });
         }));
     }
     if (opts.valueAware && state.results.length >= 1) {
@@ -179,7 +179,7 @@ function applyPfcRerankers(opts, state) {
             const neg = r.entry.outcome_negative ?? 0;
             if (pos === 0 && neg === 0)
                 return r;
-            const valueMult = Math.max(0.7, Math.min(1.3, 1 + 0.3 * Math.tanh(pos - neg)));
+            const valueMult = Math.max(VALUE_MULT_MIN, Math.min(VALUE_MULT_MAX, 1 + VALUE_MULT_SLOPE * Math.tanh(pos - neg)));
             const next = { ...r, score: r.score * valueMult };
             return traced(opts, r, next, { stage: 'value', multiplier: valueMult, scoreBefore: r.score, scoreAfter: next.score });
         }));
@@ -188,12 +188,26 @@ function applyPfcRerankers(opts, state) {
         // utility = score * (0.5 + 0.5 * strength) * (1 - min(0.3, tokens / 10000)); long evidence-rich rows pay for length.
         state.results = byScore(state.results.map((r) => {
             const strength = typeof r.entry.strength === 'number' ? r.entry.strength : 1.0;
-            const utilityMult = (0.5 + 0.5 * strength) * (1 - Math.min(0.3, (r.tokens || 0) / 10000));
+            const utilityMult = (STRENGTH_RANK_FLOOR + STRENGTH_RANK_SPAN * strength) * (1 - Math.min(UTILITY_LENGTH_PENALTY_CAP, (r.tokens || 0) / UTILITY_LENGTH_TOKENS));
             const utility = r.score * utilityMult;
             return traced(opts, r, { ...r, score: utility }, { stage: 'utility', multiplier: utilityMult, scoreBefore: r.score, scoreAfter: utility });
         }));
     }
 }
+// A recorded conflict peer in the same result list is cut to this share of its score.
+const CONFLICT_PEER_MULTIPLIER = 0.3;
+// The value-aware clamp is wider than the always-on outcome nudge, so outcome history can decide the order.
+const VALUE_MULT_SLOPE = 0.3;
+const VALUE_MULT_MIN = 0.7;
+const VALUE_MULT_MAX = 1.3;
+const UTILITY_LENGTH_PENALTY_CAP = 0.3;
+const UTILITY_LENGTH_TOKENS = 10000;
+// evcAdaptive acts when the top hits overlap this much; it keeps rows near the best score or covering the query.
+const NEAR_DUPLICATE_OVERLAP_MIN = 0.4;
+const SCORE_FLOOR_FRACTION = 0.5;
+const QUERY_COVERAGE_MIN = 0.6;
+const GOAL_TAG_BOOST = 1.5;
+const SALIENCE_MIN_MULTIPLIER = 0.5;
 /** When the top hits are near-duplicates (same topic, different facts), surface the newest on-topic row first. */
 function evcAdaptive(query, results) {
     const slice = results.slice(0, Math.min(3, results.length));
@@ -205,11 +219,11 @@ function evcAdaptive(query, results) {
             pairs++;
         }
     }
-    if ((pairs > 0 ? overlapSum / pairs : 0) < 0.4)
+    if ((pairs > 0 ? overlapSum / pairs : 0) < NEAR_DUPLICATE_OVERLAP_MIN)
         return results;
     const poolSize = Math.min(results.length, Math.max(slice.length * 3, 9));
     const pool = results.slice(0, poolSize);
-    const scoreFloor = pool.reduce((m, r) => Math.max(m, r.score), 0) * 0.5;
+    const scoreFloor = pool.reduce((m, r) => Math.max(m, r.score), 0) * SCORE_FLOOR_FRACTION;
     // Query coverage catches the differently phrased update a score floor alone would miss.
     const queryTokens = new Set(tokenizeQuery(query));
     const onTopic = [];
@@ -223,7 +237,7 @@ function evcAdaptive(query, results) {
                     hits++;
         }
         const queryCoverage = queryTokens.size > 0 ? hits / queryTokens.size : 0;
-        (r.score >= scoreFloor || queryCoverage >= 0.6 ? onTopic : offTopic).push(r);
+        (r.score >= scoreFloor || queryCoverage >= QUERY_COVERAGE_MIN ? onTopic : offTopic).push(r);
     }
     // Recency is the primary key; identity only breaks exact-timestamp ties.
     onTopic.sort((a, b) => {
@@ -248,29 +262,20 @@ function applyGoalBoosts(ctx, opts, state) {
         state.results = byScore(state.results.map((r) => {
             if (!r.entry.tags?.includes(goalTag))
                 return r;
-            const boosted = { ...r, score: r.score * 1.5 };
-            return traced(opts, r, boosted, { stage: 'goal', multiplier: 1.5, scoreBefore: r.score, scoreAfter: r.score * 1.5, note: `--goal ${goalTag}` });
+            const boosted = { ...r, score: r.score * GOAL_TAG_BOOST };
+            return traced(opts, r, boosted, { stage: 'goal', multiplier: GOAL_TAG_BOOST, scoreBefore: r.score, scoreAfter: r.score * GOAL_TAG_BOOST, note: `--goal ${goalTag}` });
         }));
         return;
     }
     if (!opts.sessionId)
         return;
-    const db = openHippoDb(ctx.hippoRoot);
     // The helper re-spreads rows, so its steps come back in a map keyed by entry id.
     const goalBoostTrace = opts.why ? new Map() : undefined;
-    try {
-        const boost = computeGoalStackBoost(db, state.results, {
-            sessionId: opts.sessionId,
-            tenantId: ctx.tenantId,
-            limit: opts.limit,
-            trace: goalBoostTrace,
-        });
-        state.results = boost.results;
-        state.goalRecallLog = boost.log;
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    const session = { sessionId: opts.sessionId, tenantId: ctx.tenantId };
+    // The log may name global rows; the store drops those when it writes, as it does for api.recall.
+    const boost = boostByGoals(state.results, activeGoalsWithPolicies(ctx.hippoRoot, session), { ...session, limit: opts.limit, trace: goalBoostTrace });
+    state.results = boost.results;
+    state.goalRecallLog = boost.log;
     if (goalBoostTrace && goalBoostTrace.size > 0) {
         state.results = state.results.map((r) => {
             const step = goalBoostTrace.get(r.entry.id);
@@ -284,7 +289,7 @@ function applySalience(opts, threshold, results) {
         const count = r.entry.retrieval_count ?? 0;
         if (count >= threshold)
             return r;
-        const mult = Math.max(0.5, count / threshold);
+        const mult = Math.max(SALIENCE_MIN_MULTIPLIER, count / threshold);
         const next = { ...r, score: r.score * mult };
         return traced(opts, r, next, { stage: 'retrieval-count-downweight', multiplier: mult, scoreBefore: r.score, scoreAfter: next.score });
     }));

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

@@ -1,6 +1,8 @@
-import { type AppendAuditOpts, type AuditOp } from '../audit.js';
-import type { AvailabilityHint } from '../availability.js';
-import { RingBuffer, type AnchoringHint, type RecallHistorySnapshot } from '../recall-history.js';
+import { type AppendAuditOpts, type AuditOp } from '../store/audit.js';
+import type { AvailabilityHint } from './availability.js';
+import { RingBuffer, type AnchoringHint, type RecallHistorySnapshot } from './recall-history.js';
+import type { RecallWrites } from '../store/index.js';
+import type { Context } from './types.js';
 export type RecallSurface = 'cli' | 'mcp' | 'http';
 /** The session's ring, created on first use; null when anchoring is off or the call has no session. */
 export declare function sessionRing(surface: RecallSurface, tenantId: string, sessionId: string | undefined): RingBuffer | null;
@@ -9,19 +11,16 @@ export declare function peekSessionRing(surface: RecallSurface, tenantId: string
 /** Records this recall's top row and hint, which the next recall's cooldown reads. */
 export declare function noteRecall(ring: RingBuffer, query: string, topId: string | null, anchoredOn: string | undefined): void;
 export declare function resetSessionRings(surface: RecallSurface): void;
-export interface RecallAuditor {
-    readonly hippoRoot: string;
+/** Whom a recall audit row names. */
+export interface RecallAuditCaller {
     readonly tenantId: string;
     readonly actor: string;
-    /** Log and count a failed write instead of throwing, for a CLI command that has already done its work. */
-    readonly bestEffort?: boolean;
 }
-/** Whom a recall audit row names; a surface that writes through the store port needs no root. */
-export type RecallAuditCaller = Pick<RecallAuditor, 'tenantId' | 'actor'>;
+export declare function callerOf(ctx: Context): RecallAuditCaller;
+/** The strengthen every ranker of `retrieve` hands to the recall's write: the shown ids, in the caller's tenant. */
+export declare function strengthenOf(ctx: Context, ids: readonly string[]): NonNullable<RecallWrites['strengthen']>;
 type RecallAuditMetadata = Readonly<Record<string, string | number | null>>;
 export declare function recallAuditRow(who: RecallAuditCaller, op: AuditOp, targetId?: string, metadata?: RecallAuditMetadata): AppendAuditOpts;
-/** One audit row on its own short-lived handle. */
-export declare function appendRecallAudit(who: RecallAuditor, op: AuditOp, targetId?: string, metadata?: RecallAuditMetadata): void;
 export declare function recallAuditMetadata(query: string, results: number): {
     results: number;
     query_hash: string;
@@ -40,7 +39,5 @@ export interface ShownRecall {
 }
 /** The hint rows for a list a surface showed, so a surface on the store port can hand them to the recall's one write. */
 export declare function shownRecallRows(who: RecallAuditCaller, shown: ShownRecall): AppendAuditOpts[];
-/** For a surface that computes its hints over the list it shows: feeds the ring after the final detect, then audits the hints. */
-export declare function recordShownRecall(who: RecallAuditor, shown: ShownRecall): void;
 export {};
 //# sourceMappingURL=recall-record.d.ts.map

package/dist/api/recall-record.js

@@ -1,7 +1,7 @@
 // The recall session rings and the recall audit rows, in one place for the CLI, MCP and HTTP surfaces.
-import { appendAuditEvent, auditQueryFields, reportAuditWriteFailure } from '../audit.js';
-import { closeHippoDb, openHippoDb } from '../db.js';
-import { appendRecall, biasHintEnabled, buildSessionKey, getOrCreateRing, hashQueryText, snapshotRing, } from '../recall-history.js';
+import { isRecallBoostAblated } from '../core/ablation.js';
+import { auditQueryFields } from '../store/audit.js';
+import { appendRecall, biasHintEnabled, buildSessionKey, getOrCreateRing, hashQueryText, snapshotRing, } from './recall-history.js';
 // One map per surface, each with its own LRU cap, so a repeat on one surface is a first recall on another.
 const rings = {
     cli: new Map(),
@@ -26,28 +26,15 @@ export function noteRecall(ring, query, topId, anchoredOn) {
 export function resetSessionRings(surface) {
     rings[surface].clear();
 }
-export function recallAuditRow(who, op, targetId, metadata) {
-    return { tenantId: who.tenantId, actor: who.actor, op, targetId, metadata };
+export function callerOf(ctx) {
+    return { tenantId: ctx.tenantId, actor: ctx.actor.subject };
 }
-function writeRecallAudit(who, row) {
-    try {
-        const db = openHippoDb(who.hippoRoot);
-        try {
-            appendAuditEvent(db, row);
-        }
-        finally {
-            closeHippoDb(db);
-        }
-    }
-    catch (err) {
-        if (!who.bestEffort)
-            throw err;
-        reportAuditWriteFailure(row.op, String(err), row.targetId);
-    }
+/** The strengthen every ranker of `retrieve` hands to the recall's write: the shown ids, in the caller's tenant. */
+export function strengthenOf(ctx, ids) {
+    return { ids, opts: { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() } };
 }
-/** One audit row on its own short-lived handle. */
-export function appendRecallAudit(who, op, targetId, metadata) {
-    writeRecallAudit(who, recallAuditRow(who, op, targetId, metadata));
+export function recallAuditRow(who, op, targetId, metadata) {
+    return { tenantId: who.tenantId, actor: who.actor, op, targetId, metadata };
 }
 // The row stores a hash of the query, never its text, so an archived memory's words cannot persist there.
 export function recallAuditMetadata(query, results) {
@@ -88,11 +75,4 @@ export function shownRecallRows(who, shown) {
         ...availabilityRows(who, shown.availability),
     ];
 }
-/** For a surface that computes its hints over the list it shows: feeds the ring after the final detect, then audits the hints. */
-export function recordShownRecall(who, shown) {
-    if (shown.ring)
-        noteRecall(shown.ring, shown.query, shown.topId, shown.anchoring?.memoryId);
-    for (const row of shownRecallRows(who, shown))
-        writeRecallAudit(who, row);
-}
 //# sourceMappingURL=recall-record.js.map

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

@@ -1,5 +1,5 @@
-import { BadRequestError } from '../api-errors.js';
-import { type JsonValue } from '../json.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { type JsonValue } from '../util/json.js';
 import type { ContextOpts } from './context-types.js';
 import type { RecallOpts } from './recall-types.js';
 /** A recall or context input the caller must fix; MCP answers it with an isError result, HTTP with a 400. */

package/dist/api/recall-request.js

@@ -1,7 +1,7 @@
 // The recall and context input rules in one copy, so MCP and HTTP reject the same inputs with the same messages.
-import { BadRequestError } from '../api-errors.js';
-import { MAX_ID_LEN } from '../http-util.js';
-import { isJsonString } from '../json.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { MAX_ID_LEN } from '../util/http-util.js';
+import { isJsonString } from '../util/json.js';
 const MAX_RECALL_LIMIT = 1000;
 // recall() owns the shape rule for scorer_window (invalid_scorer_window); this cap bounds remote cost.
 const MAX_SCORER_WINDOW = 1000;

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

@@ -1,12 +1,12 @@
-import type { TaskSnapshot, SessionEvent } from '../store/rows.js';
-import type { SessionHandoff } from '../handoff.js';
-import type { MemoryEntry } from '../memory.js';
-import type { RerankStep, SearchResult } from '../search/types.js';
-import type { PlanningFallacyHint, PlanningFallacyWatching } from '../predictions/planning-fallacy.js';
-import type { AnchoringHint, RecallHistorySnapshot } from '../recall-history.js';
-import type { AvailabilityHint } from '../availability.js';
-import type { AppendAuditOpts } from '../audit.js';
-import type { CallerProject } from '../prompt-hook.js';
+import type { ContinuityBlock } from '../store/port.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { RerankStep, SearchResult } from '../core/search-types.js';
+import type { PlanningFallacyHint, PlanningFallacyOutput, PlanningFallacyWatching } from '../predictions/planning-fallacy.js';
+import type { AnchoringHint, RecallHistorySnapshot } from './recall-history.js';
+import type { AvailabilityHint } from './availability.js';
+import type { AppendAuditOpts } from '../store/audit.js';
+import type { CallerProject } from './prompt-hook.js';
+import type { RankRecallOpts, RankRecallResult } from './recall-pipeline.js';
 export interface RecallOpts {
     query: string;
     limit?: number;
@@ -155,6 +155,35 @@ export interface RecallOpts {
     leadingAudit?: readonly AppendAuditOpts[];
     /** MCP recall only: `retrieve` ranks the whole scoped store and strengthens and traces (pipeline 'mcp') just the ids this returns; `results` stays the window band. */
     showRanked?: (ranking: StoreRanking, result: RecallResult) => ShownRanking;
+    /** Named ranker: `retrieve` ranks with the CLI ranking core. Unset, it ranks the SQL BM25 band, or the wide hybrid list under `showRanked`. */
+    cliCore?: CliCoreRanker;
+}
+interface CliCoreRanking {
+    rank: Omit<RankRecallOpts, 'query' | 'sessionId' | 'goalTag'>;
+    /** A second store searched beside `ctx.hippoRoot`. */
+    sources?: {
+        globalRoot?: string;
+    };
+    /** Receives each operator note when ranking reaches it. */
+    note?: (line: string) => void;
+}
+/** A recall the caller prints. `show` runs once ranking ends, unless it halted; `retrieve` then records the list it returns. */
+export interface CliCoreRecall extends CliCoreRanking {
+    /** The host agent's session: it stamps the token ledger row, and the trace when the recall names no session. */
+    hostSessionId?: string;
+    show: (ranking: RankRecallResult, planning: PlanningFallacyOutput) => ShownCliCore;
+}
+/** A read-only look at the ranking (`hippo explain`): no hint is evaluated and nothing is written. */
+export interface CliCoreInspection extends CliCoreRanking {
+    inspect: (ranking: RankRecallResult) => void;
+}
+/** The CLI ranking core (`rankRecall`) as a ranker of `retrieve`: host admin only, on hippo.db. Of the other RecallOpts it reads `query`, `sessionId` and `goalTag`. */
+export type CliCoreRanker = CliCoreRecall | CliCoreInspection;
+/** `results`: the rows the caller shows, best first; `audit`: its hint rows, written ahead of the 'recall' row; `tokens`: the text it prints, for the ledger. */
+export interface ShownCliCore {
+    results: readonly SearchResult[];
+    audit: readonly AppendAuditOpts[];
+    tokens: number;
 }
 /** `ids`: what the caller showed; `audit`: its own rows, written after the recall's and in the same transaction, so all land or none. */
 export interface ShownRanking {
@@ -167,11 +196,7 @@ export interface StoreRanking {
     pool: MemoryEntry[];
     droppedByScope: number;
 }
-export interface ContinuityBlock {
-    activeSnapshot: TaskSnapshot | null;
-    sessionHandoff: SessionHandoff | null;
-    recentSessionEvents: SessionEvent[];
-}
+export type { ContinuityBlock } from '../store/port.js';
 export interface RecallResultItem {
     id: string;
     content: string;
@@ -263,7 +288,7 @@ export interface RecallResult {
      * the calling agent sees its track record at the moment of forecasting
      * (Lovallo-Kahneman 2003 inside-vs-outside view).
      *
-     * Populated by `api.recall` itself via `computePlanningFallacyOutput`.
+     * Populated by `api.recall` itself via `decidePlanningFallacy`.
      * Pipeline-invariant: the value depends only on (queryText, tenantId,
      * predictions table state) — all three are identical regardless of
      * which downstream search pipeline produces the memory list, so MCP
@@ -372,7 +397,7 @@ export interface RecallSuppressionSummary {
     /** Counter of memories suppressed by detected interference patterns.
      *  Incremented by 1 PER PIPELINE when that
      *  pipeline's own memory_dominance verdict fires (via the
-     *  anchoring detector, see `detectAnchoring()` in src/recall-history.ts).
+     *  anchoring detector, see `detectAnchoring()` in src/api/recall-history.ts).
      *  Each pipeline (api.recall, cmdRecall, MCP physics/hybrid) bumps its
      *  OWN suppressionSummary independently because each runs its own
      *  detector against its own top-1 + its own per-(tenant, session) ring

package/dist/api/recall.d.ts

@@ -32,6 +32,6 @@ export declare function buildSuppressionSummary(counts: {
  * `tests/api-recall-no-side-effects.test.ts`.
  */
 export declare function recall(ctx: Context, opts: RecallOpts): RecallResult;
-/** Mode-aware recall through the served store that strengthens each returned row; never writes last_retrieval_ids (contract lock). */
+/** The one recall entry: ranks with the ranker `opts` names, then writes the recall. Only the CLI core ranker writes last_retrieval_ids (contract lock). */
 export declare function retrieve(ctx: Context, opts: RecallOpts): Promise<RecallResult>;
 //# sourceMappingURL=recall.d.ts.map