hippo-memory 1.68.0 → 1.70.0

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

package/dist/api/recall.js

@@ -1,26 +1,28 @@
 // Read path: recall (sync) and retrieve (async, adds the vector arm).
-import { envRequireSessionScopedFreshTail } from '../env.js';
+import { envRequireSessionScopedFreshTail } from '../util/env.js';
 import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
-import { isRecallBoostAblated } from '../ablation.js';
 import { loadEntriesByIds, loadFreshRawMemories } from '../store/entry-reads.js';
 import { loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
-import { estimateTokens } from '../token-ledger.js';
-import { formatHandoffEvidenceLine } from '../handoff.js';
-import { activeGoalsWithPolicies, boostByGoals } from '../goals.js';
-import { continuityAt, finishRecallAt, storeFor } from '../store-port.js';
+import { estimateTokens } from '../util/token-text.js';
+import { formatHandoffEvidenceLine } from '../core/handoff.js';
+import { activeGoalsWithPolicies, boostByGoals } from '../store/goals.js';
+import { continuityAt, finishRecallAt, storeFor } from '../store/index.js';
 import { hybridSearch } from '../search/hybrid.js';
 import { physicsSearch } from '../search/physics-search.js';
 import { churnStaleFactor } from '../search/boosts.js';
-import { compareEntryIdentity } from '../compare.js';
-import { dropHeldCopies, duplicateKey, storedTextKeys } from '../same-text.js';
-import { isSharedStore, loadConfig } from '../config.js';
-import { classifyOriginProject, projectNames } from '../project-identity.js';
-import { decidePlanningFallacy, detectPlanningClaim, planningFallacyEvidenceAt } from '../predictions/planning-fallacy.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled } from '../recall-history.js';
-import { detectAvailabilityBias } from '../availability.js';
-import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../recall-scope.js';
+import { compareEntryIdentity } from '../core/compare.js';
+import { dropHeldCopies, duplicateKey, storedTextKeys } from '../util/same-text.js';
+import { isSharedStore, loadConfig } from '../core/config.js';
+import { classifyOriginProject, projectNames } from '../core/project-identity.js';
+import { decidePlanningFallacy, detectPlanningClaim } from '../predictions/planning-fallacy.js';
+import { planningFallacyEvidenceAt } from '../store/planning-fallacy-evidence.js';
+import { detectAnchoring, hashQueryText, biasHintEnabled } from './recall-history.js';
+import { detectAvailabilityBias } from './availability.js';
+import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../store/recall-scope.js';
 import { ownerOrSubject, RecallContractError } from './types.js';
-import { anchoringRows, availabilityRows, recallAuditMetadata, recallAuditRow } from './recall-record.js';
+import { anchoringRows, availabilityRows, callerOf, recallAuditMetadata, recallAuditRow, strengthenOf } from './recall-record.js';
+import { retrieveWithCliCore } from './recall-core.js';
+const DEFAULT_RECALL_LIMIT = 10;
 /**
  * Shared construction helper for `RecallSuppressionSummary`. Used by
  * `api.recall`, `cmdRecall`, and the MCP `hippo_recall` handler so all three
@@ -61,7 +63,7 @@ export function recall(ctx, opts) {
     const own = personalScopeOf(ctx.actor) ?? undefined;
     const all = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own);
     const plan = planRecall(ctx, opts, all, own);
-    const { result, writes } = composeRecall(ctx, opts, windowSize, all, plan, readRecallSync(ctx, opts, plan));
+    const { result, writes } = composeRecall(ctx, opts, { windowSize, all, plan, reads: readRecallSync(ctx, opts, plan) });
     finishRecallAt(ctx.hippoRoot, { ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit] });
     return result;
 }
@@ -71,9 +73,11 @@ function recallOrigin(opts) {
 function inCallerProject(entry, opts) {
     return !opts.project || classifyOriginProject(entry.origin_project, opts.project) !== 'cross-project';
 }
-/** 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 async function retrieve(ctx, opts) {
     assertScopeRequestAllowed(ctx.actor, opts.scope);
+    if (opts.cliCore)
+        return retrieveWithCliCore(ctx, opts, opts.cliCore);
     const windowSize = recallWindowSize(opts);
     // From the authenticated actor, never from RecallOpts, which a caller fills in.
     const own = personalScopeOf(ctx.actor) ?? undefined;
@@ -90,7 +94,7 @@ export async function retrieve(ctx, opts) {
         candidates = [...ranked.map((r) => r.entry), ...candidates.filter((e) => !rankedIds.has(e.id))];
     }
     const plan = planRecall(ctx, opts, candidates, own);
-    const { result, writes } = composeRecall(ctx, opts, windowSize, candidates, plan, await readRecall(store, ctx, opts, plan));
+    const { result, writes } = composeRecall(ctx, opts, { windowSize, all: candidates, plan, reads: await readRecall(store, ctx, opts, plan) });
     await store.finishRecall({ ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit], strengthen: strengthenOf(ctx, result.results.map((r) => r.id)) });
     return result;
 }
@@ -106,9 +110,6 @@ function recallSearchArgs(ctx, opts, limit, own) {
         ownScope: own,
     };
 }
-function strengthenOf(ctx, ids) {
-    return { ids, opts: { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() } };
-}
 /** api.retrieve's vector arm: the recall load's exact-scope rule, current rows only. */
 function recallVectorSpec(ctx, opts, own) {
     return {
@@ -142,7 +143,7 @@ async function retrieveFromStore(ctx, opts, windowSize, show, own) {
     const window = ranked.slice(0, windowSize).map((r) => r.entry);
     const bandOpts = { ...opts, suppressRecallTrace: true };
     const plan = planRecall(ctx, bandOpts, window, own);
-    const { result, writes } = composeRecall(ctx, bandOpts, windowSize, window, plan, await readRecall(store, ctx, bandOpts, plan, goals), false);
+    const { result, writes } = composeRecall(ctx, bandOpts, { windowSize, all: window, plan, reads: await readRecall(store, ctx, bandOpts, plan, goals), auditBand: false });
     // Rows the vector arm added count as candidates too.
     const inPool = new Set(pool.map((e) => e.id));
     const candidates = [...pool, ...ranked.map((r) => r.entry).filter((e) => !inPool.has(e.id))];
@@ -187,7 +188,7 @@ function recallWindowSize(opts) {
 }
 const CONTINUITY_EVENT_LIMIT = 5;
 function planRecall(ctx, opts, all, own) {
-    const limit = opts.limit ?? 10;
+    const limit = opts.limit ?? DEFAULT_RECALL_LIMIT;
     const window = admitCandidates(opts, all, limit, own);
     return {
         limit,
@@ -228,9 +229,8 @@ function continuityKey(ctx, opts) {
         return null;
     return { owner: ownerOrSubject(ctx.actor), project: opts.project ? projectNames(opts.project) : [] };
 }
-/** The reply and the rows it writes, from the candidates and the plan's reads; touches no store.
- *  `auditBand` false: the caller shows a cut of the band and audits the rows it shows. */
-function composeRecall(ctx, opts, windowSize, all, plan, reads, auditBand = true) {
+function composeRecall(ctx, opts, options) {
+    const { windowSize, all, plan, reads, auditBand = true } = options;
     const { window } = plan;
     const bands = rankBands(opts, plan, reads);
     const rankedOut = bands.rankedOut;
@@ -319,7 +319,9 @@ function rankBands(opts, plan, reads) {
     const baseRanked = baseScored.map((r) => baseItem(r, opts, explainTrace));
     const summaryRanked = substituted.map((s) => summaryItem(s, opts));
     const freshRanked = (opts.freshTailCount ?? 0) > 0
-        ? freshTailBand(opts, reads.freshRaws, baseRanked, summaryRanked, opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)], own)
+        ? freshTailBand(opts, {
+            recent: reads.freshRaws, baseRanked, summaryRanked, shownEntries: opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)], own,
+        })
         : [];
     return {
         rankedOut: [...freshRanked, ...baseRanked, ...summaryRanked],
@@ -334,7 +336,7 @@ function rankBands(opts, plan, reads) {
 // `limit`. Each one is tenant-scoped and re-checked against the scope filter; drillDown recovers the children.
 function substituteOverflow(opts, overflowByParent, parents, limit, own) {
     const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by && passesScopeFilterForRecall(p.scope ?? null, opts.scope, own) && inCallerProject(p, opts));
-    const maxSub = Math.max(1, Math.ceil(limit * 0.3));
+    const maxSub = Math.max(1, Math.ceil(limit * SUMMARY_SUB_FRACTION));
     // Most overflowed children first; compareEntryIdentity only breaks a tie, which used to fall to scan order.
     eligibleParents.sort((a, b) => {
         const ac = overflowByParent.get(a.id)?.length ?? 0;
@@ -380,12 +382,16 @@ function baseItem(r, opts, explainTrace) {
     }
     return item;
 }
-// Score 0.5 keeps a summary below the strong top-N matches but above the weakest leaves.
+// A summary scores below the strong top-N matches but above the weakest leaves.
+const SUMMARY_ITEM_SCORE = 0.5;
+const FRESH_TAIL_ITEM_SCORE = 1.0;
+// Summaries may take this share of the limit.
+const SUMMARY_SUB_FRACTION = 0.3;
 function summaryItem(s, opts) {
     const item = {
         id: s.entry.id,
         content: s.entry.content,
-        score: 0.5,
+        score: SUMMARY_ITEM_SCORE,
         layer: s.entry.layer,
         strength: s.entry.strength,
         isSummary: true,
@@ -396,9 +402,8 @@ function summaryItem(s, opts) {
         item.rerankPipeline = 'api';
     return item;
 }
-// The last N raw rows, so "what did I just see" always covers the recent window. A recent row already in the BM25
-// band is only tagged isFreshTail; new ones are prepended, so every recent row appears exactly once.
-function freshTailBand(opts, recent, baseRanked, summaryRanked, shownEntries, own) {
+function freshTailBand(opts, options) {
+    const { recent, baseRanked, summaryRanked, shownEntries, own } = options;
     const recentScoped = recent.filter((m) => passesScopeFilterForRecall(m.scope ?? null, opts.scope, own) && inCallerProject(m, opts));
     const recentIdSet = new Set(recentScoped.map((m) => m.id));
     for (const r of baseRanked) {
@@ -415,7 +420,7 @@ function freshTailBand(opts, recent, baseRanked, summaryRanked, shownEntries, ow
         const item = {
             id: m.id,
             content: m.content,
-            score: 1.0,
+            score: FRESH_TAIL_ITEM_SCORE,
             layer: m.layer,
             strength: m.strength,
             isFreshTail: true,
@@ -471,9 +476,6 @@ function continuityTokensOf(c) {
         tokenize(filteredHandoff?.cardId) +
         c.recentSessionEvents.reduce((acc, e) => acc + tokenize(e.content), 0);
 }
-function callerOf(ctx) {
-    return { tenantId: ctx.tenantId, actor: ctx.actor.subject };
-}
 // A pure read of the caller's recallHistory snapshot against this top-1. HIPPO_ANCHORING=off skips even the detect
 // call; CLI paths pass no history (cmdRecall computes its own hint), so the hint stays absent there.
 function detectRecallAnchoring(opts, topMemoryId) {

package/dist/api/remember.d.ts

@@ -1,6 +1,6 @@
-import type { DatabaseSyncLike } from '../db.js';
-import { type MemoryKind } from '../memory.js';
-import type { Context } from './types.js';
+import type { ConnectorEvent } from '../store/port.js';
+import { type MemoryKind } from '../core/memory.js';
+import type { Context, StoreReply } from './types.js';
 export interface RememberOpts {
     content: string;
     kind?: MemoryKind;
@@ -8,15 +8,8 @@ export interface RememberOpts {
     owner?: string;
     artifactRef?: string;
     tags?: string[];
-    /**
-     * Optional hook invoked inside the same transaction as the underlying
-     * memories INSERT. Used by ingestion connectors to stamp
-     * idempotency / cursor rows atomically with the memory row, so a crash
-     * mid-write cannot produce a memory without its corresponding side-effect
-     * log row (or vice versa). If the callback throws, the INSERT is rolled
-     * back and the error is rethrown.
-     */
-    afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
+    /** The connector event this write answers. The store logs it in the memory's own transaction; an event logged before stores nothing and answers `duplicate`. */
+    event?: ConnectorEvent;
     /** Connector-ingested content an agent doesn't control; gates detectInstruction. CLI/HTTP/MCP never set this. */
     untrusted?: boolean;
     /** The caller's project: its name becomes the row's origin. Without it the store's fallback applies (NULL on a shared store). */
@@ -37,6 +30,12 @@ export interface RememberResult {
     };
     /** Set only when the content held secret material: untrusted text had it redacted, typed text was stored as sent. */
     warnings?: string[];
+    /** Set only when the write's event was logged before: nothing was stored, so `id` names no row; `memoryId` is the id the first write logged. */
+    duplicate?: {
+        memoryId: string | null;
+    };
 }
-export declare function remember(ctx: Context, opts: RememberOpts): RememberResult;
+/** Store one memory: the store's entryWrites group writes the row and its one remember audit row, under the caller's subject.
+ *  A write that carries a connector event or untrusted content goes through connectorWrites, which commits its companion rows with it. */
+export declare function remember<C extends Context>(ctx: C, opts: RememberOpts): StoreReply<C, RememberResult>;
 //# sourceMappingURL=remember.d.ts.map