hippo-memory 1.72.0 → 2.1.0

package/dist/api/recall-core.js

@@ -1,120 +0,0 @@
-// 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, storeFor } 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 under hippoRoot, yet writes through the caller's store, whose finishRecall skips any id it does not hold.
-    const store = storeFor(ctx);
-    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

@@ -1,53 +0,0 @@
-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

package/dist/api/recall-finish.js

@@ -1,30 +0,0 @@
-import { biasHintEnabled } from './recall-history.js';
-import { anchorSkippedRows, callerOf, noteRecall, peekSessionRing, sessionRing } from './recall-record.js';
-import { recordTokens } from './tokens.js';
-/** 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 const RECALL_RECORDING = {
-    http: { ring: 'http', ledger: 'http_recall', stats: 'every' },
-    cli: { ring: 'cli', ledger: 'recall', stats: 'shown' },
-};
-/** For a surface whose hint `retrieve` judges: the session's history, or the row saying the recall named no session. */
-export function recallLead(ctx, how, query, sessionId) {
-    return {
-        // Peeked, never created: a recall that then fails must not LRU-evict a live session.
-        recallHistory: sessionId && biasHintEnabled('anchoring') ? peekSessionRing(how.ring, ctx.tenantId, sessionId) : undefined,
-        // Written first in the recall's own write, so a recall that fails leaves no row.
-        leadingAudit: sessionId ? [] : anchorSkippedRows(callerOf(ctx), query),
-    };
-}
-/** Runs after the recall's own write, in this order: the ring, then the counter, then the ledger. */
-export async function recordShownRecall(ctx, store, how, shown) {
-    // A surface that only peeked has its ring created here, after the write, so a recall that fails cannot LRU-evict a live session.
-    const ring = sessionRing(how.ring, ctx.tenantId, shown.sessionId);
-    if (ring)
-        noteRecall(ring, shown.query, shown.topId, shown.anchoredOn);
-    // A recall with no audit row counts nothing, as it strengthens and traces nothing.
-    if (shown.written && (how.stats === 'every' || shown.items > 0))
-        await store.bumpRecallStats(shown.items);
-    // The ledger books text that was sent, so its row does not wait on the audit write.
-    await recordTokens(ctx, how.ledger, { items: shown.items, tokens: shown.tokens, sessionId: shown.ledgerSessionId });
-}
-//# sourceMappingURL=recall-finish.js.map

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

@@ -1,64 +0,0 @@
-/** Anchoring detector (recall-recurrence), pure module: `query_repeat` (a queryHash re-asked within the window returns the same topMemoryId) and
- * `memory_dominance` (the same topMemoryId across >= minDominance distinct queryHashes). Each pipeline keeps its OWN ring Map keyed by (tenant, session),
- * because its top-1 ranking differs. AnchoringHint and PlanningFallacyHint are independent signals. */
-export type AnchoringReason = 'query_repeat' | 'memory_dominance';
-export interface AnchoringHint {
-    reason: AnchoringReason;
-    /** The memory ID that is anchoring the agent's reasoning. */
-    memoryId: string;
-    /** For 'memory_dominance': how many distinct queries in the recent window
-     *  had this memory as their top-1 result. Always >= 3 when emitted. */
-    queryCount?: number;
-    /** Human-readable summary surfaced to the agent. */
-    summary: string;
-    /** Discriminator for hint origin; reserved for future variants. */
-    source: 'j1-recurrence';
-}
-export interface RecallHistoryEntry {
-    /** Hash of the queryText that produced this entry (see hashQueryText). */
-    queryHash: number;
-    /** Top-1 memory id this recall surfaced; null if zero results. */
-    topMemoryId: string | null;
-    /** ISO-8601 timestamp; advisory, not used by the detection rules. */
-    ts: string;
-    /** Memory id of the AnchoringHint that fired on this recall, if any; the caller writes it after detectAnchoring returns, and the cooldown reads it next
-     * time. */
-    anchoredOn?: string;
-}
-export type RecallHistorySnapshot = readonly RecallHistoryEntry[];
-export interface DetectAnchoringOpts {
-    /** memory_dominance threshold: number of distinct queryHashes that must have returned
-     *  the same topMemoryId. Default 3. */
-    minDominance?: number;
-    /** query_repeat window: how many recent history entries to scan for query repeat.
-     *  Default 5. */
-    recentRepeatWindow?: number;
-    /** Cooldown: suppress when the prior fire (per `anchoredOn`) was for the same topMemoryId within this many history entries. Default 3. */
-    cooldown?: number;
-}
-/** Normalizes a query (lowercase, strip non-alphanumerics, drop short tokens, sort, dedup, join) and hashes it with 32-bit FNV-1a.
- * Reordered words collide intentionally; deterministic across processes and V8 versions. */
-export declare function hashQueryText(query: string): number;
-/** Detects anchoring against the current (queryHash, topMemoryId); memory_dominance wins when both rules fire, since it spans DIFFERENT queries.
- * Cooldown is per memory: a hint on the SAME topMemoryId within `cooldown=3` history entries is suppressed. Returns an AnchoringHint or null. */
-export declare function detectAnchoring(history: RecallHistorySnapshot, currentQueryHash: number, currentTopMemoryId: string | null, opts?: DetectAnchoringOpts): AnchoringHint | null;
-/** Bounded FIFO ring of RecallHistoryEntry (oldest evicted when full); a thin array wrapper so snapshotRing returns a readonly view without copying. */
-export declare class RingBuffer {
-    private entries;
-    append(entry: RecallHistoryEntry): void;
-    snapshot(): RecallHistorySnapshot;
-    size(): number;
-}
-/** Builds the (tenant, session) key with a NUL delimiter: tenant and session ids are validated elsewhere to reject NUL,
- * so concatenation cannot collide even though API-key-derived subjects can contain `:`. */
-export declare function buildSessionKey(tenantId: string, sessionId: string): string;
-/** Get-or-create a RingBuffer per session key, capped at `maxSessions` (default 1000); at the cap the oldest-inserted key (first from Map.keys()) is
- * evicted. */
-export declare function getOrCreateRing(map: Map<string, RingBuffer>, key: string, maxSessions?: number): RingBuffer;
-/** Appends a recall to a ring; `anchoredOn` is the memoryId of the hint that fired on THIS recall (or undefined), read by detectAnchoring for cooldown. */
-export declare function appendRecall(ring: RingBuffer, queryHash: number, topMemoryId: string | null, anchoredOn?: string): void;
-/** Snapshot a ring as a readonly RecallHistorySnapshot. */
-export declare function snapshotRing(ring: RingBuffer): RecallHistorySnapshot;
-/** Whether a recall bias hint is enabled; reads env at call time, so `HIPPO_ANCHORING=off` or `HIPPO_AVAILABILITY=off` disables only that kind. */
-export declare function biasHintEnabled(kind: 'anchoring' | 'availability'): boolean;
-//# sourceMappingURL=recall-history.d.ts.map

package/dist/api/recall-history.js

@@ -1,159 +0,0 @@
-/** Anchoring detector (recall-recurrence), pure module: `query_repeat` (a queryHash re-asked within the window returns the same topMemoryId) and
- * `memory_dominance` (the same topMemoryId across >= minDominance distinct queryHashes). Each pipeline keeps its OWN ring Map keyed by (tenant, session),
- * because its top-1 ranking differs. AnchoringHint and PlanningFallacyHint are independent signals. */
-import { envAnchoringOff, envAvailabilityOff } from '../util/env.js';
-const DEFAULT_MIN_DOMINANCE = 3;
-const DEFAULT_RECENT_REPEAT_WINDOW = 5;
-const DEFAULT_COOLDOWN = 3;
-/** Normalizes a query (lowercase, strip non-alphanumerics, drop short tokens, sort, dedup, join) and hashes it with 32-bit FNV-1a.
- * Reordered words collide intentionally; deterministic across processes and V8 versions. */
-export function hashQueryText(query) {
-    if (!query)
-        return 0;
-    // Tokens are deduped before join so `foo foo bar` and `foo bar` count as one query for memory_dominance.
-    // Unicode classes (\p{L}, \p{N}, \p{M}; need /u) keep non-Latin queries from collapsing to an empty token set and colliding at hash 0.
-    const normalized = query
-        .toLowerCase()
-        .replace(/[^\p{L}\p{N}\p{M}\s]/gu, ' ')
-        .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/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('').
-    const tokens = filtered.length > 0 ? filtered : normalized;
-    const deduped = Array.from(new Set(tokens)).sort();
-    return fnv1a32(deduped.join(' '));
-}
-function fnv1a32(text) {
-    // FNV-1a 32-bit. Offset basis 2166136261, prime 16777619.
-    let hash = 2166136261;
-    for (let i = 0; i < text.length; i++) {
-        hash ^= text.charCodeAt(i);
-        // 32-bit multiply via Math.imul — handles overflow correctly.
-        hash = Math.imul(hash, 16777619);
-    }
-    // Coerce to unsigned 32-bit for stable comparison.
-    return hash >>> 0;
-}
-/** Detects anchoring against the current (queryHash, topMemoryId); memory_dominance wins when both rules fire, since it spans DIFFERENT queries.
- * Cooldown is per memory: a hint on the SAME topMemoryId within `cooldown=3` history entries is suppressed. Returns an AnchoringHint or null. */
-export function detectAnchoring(history, currentQueryHash, currentTopMemoryId, opts = {}) {
-    if (currentTopMemoryId === null)
-        return null;
-    const minDominance = opts.minDominance ?? DEFAULT_MIN_DOMINANCE;
-    const recentRepeatWindow = opts.recentRepeatWindow ?? DEFAULT_RECENT_REPEAT_WINDOW;
-    const cooldown = opts.cooldown ?? DEFAULT_COOLDOWN;
-    // Cooldown gate: was the most-recent hint (across the last `cooldown`
-    // entries) for THIS memory? If yes, suppress regardless of rule.
-    const cooldownSlice = history.slice(-cooldown);
-    for (const entry of cooldownSlice) {
-        if (entry.anchoredOn === currentTopMemoryId) {
-            return null;
-        }
-    }
-    // memory_dominance check FIRST (wins on tie).
-    const queryCount = countDistinctQueries(history, currentQueryHash, currentTopMemoryId);
-    if (queryCount >= minDominance) {
-        return {
-            reason: 'memory_dominance',
-            memoryId: currentTopMemoryId,
-            queryCount,
-            summary: `Memory ${currentTopMemoryId} has been the top result for ${queryCount} distinct queries in this session and may be anchoring your reasoning.`,
-            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);
-}
-const MAX_HISTORY = 10;
-const DEFAULT_MAX_SESSIONS = 1000;
-/** Bounded FIFO ring of RecallHistoryEntry (oldest evicted when full); a thin array wrapper so snapshotRing returns a readonly view without copying. */
-export class RingBuffer {
-    entries = [];
-    append(entry) {
-        this.entries.push(entry);
-        if (this.entries.length > MAX_HISTORY) {
-            this.entries.shift();
-        }
-    }
-    snapshot() {
-        return this.entries;
-    }
-    size() {
-        return this.entries.length;
-    }
-}
-/** Builds the (tenant, session) key with a NUL delimiter: tenant and session ids are validated elsewhere to reject NUL,
- * so concatenation cannot collide even though API-key-derived subjects can contain `:`. */
-export function buildSessionKey(tenantId, sessionId) {
-    return `${tenantId}\x00${sessionId}`;
-}
-/** Get-or-create a RingBuffer per session key, capped at `maxSessions` (default 1000); at the cap the oldest-inserted key (first from Map.keys()) is
- * evicted. */
-export function getOrCreateRing(map, key, maxSessions = DEFAULT_MAX_SESSIONS) {
-    const existing = map.get(key);
-    if (existing) {
-        // LRU touch: delete + re-insert to move to back of iteration order.
-        map.delete(key);
-        map.set(key, existing);
-        return existing;
-    }
-    if (map.size >= maxSessions) {
-        const oldest = map.keys().next().value;
-        if (oldest !== undefined)
-            map.delete(oldest);
-    }
-    const ring = new RingBuffer();
-    map.set(key, ring);
-    return ring;
-}
-/** Appends a recall to a ring; `anchoredOn` is the memoryId of the hint that fired on THIS recall (or undefined), read by detectAnchoring for cooldown. */
-export function appendRecall(ring, queryHash, topMemoryId, anchoredOn) {
-    const entry = {
-        queryHash,
-        topMemoryId,
-        ts: new Date().toISOString(),
-    };
-    if (anchoredOn !== undefined)
-        entry.anchoredOn = anchoredOn;
-    ring.append(entry);
-}
-/** Snapshot a ring as a readonly RecallHistorySnapshot. */
-export function snapshotRing(ring) {
-    return ring.snapshot();
-}
-/** Whether a recall bias hint is enabled; reads env at call time, so `HIPPO_ANCHORING=off` or `HIPPO_AVAILABILITY=off` disables only that kind. */
-export function biasHintEnabled(kind) {
-    return kind === 'anchoring'
-        ? !envAnchoringOff()
-        : !envAvailabilityOff();
-}
-//# sourceMappingURL=recall-history.js.map

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

@@ -1,43 +0,0 @@
-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;
-/** The session's history, read without creating or touching its ring, so a request that then fails evicts no live session. */
-export declare function peekSessionRing(surface: RecallSurface, tenantId: string, sessionId: string): RecallHistorySnapshot;
-/** 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;
-/** Whom a recall audit row names. */
-export interface RecallAuditCaller {
-    readonly tenantId: string;
-    readonly actor: string;
-}
-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;
-export declare function recallAuditMetadata(query: string, results: number): {
-    results: number;
-    query_hash: string;
-    query_length: number;
-};
-/** No session means no ring; the row hashes with SHA-256/16, since hashQueryText is FNV-1a and easy to reverse on short queries. */
-export declare function anchorSkippedRows(who: RecallAuditCaller, query: string): AppendAuditOpts[];
-export declare function anchoringRows(who: RecallAuditCaller, hint: AnchoringHint | null): AppendAuditOpts[];
-export declare function availabilityRows(who: RecallAuditCaller, hint: AvailabilityHint | null): AppendAuditOpts[];
-export interface ShownRecall {
-    readonly query: string;
-    readonly ring: RingBuffer | null;
-    readonly topId: string | null;
-    readonly anchoring: AnchoringHint | null;
-    readonly availability: AvailabilityHint | null;
-}
-/** 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[];
-export {};
-//# sourceMappingURL=recall-record.d.ts.map

package/dist/api/recall-record.js

@@ -1,78 +0,0 @@
-// The recall session rings and the recall audit rows, in one place for the CLI, MCP and HTTP surfaces.
-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(),
-    mcp: new Map(),
-    http: new Map(),
-};
-/** The session's ring, created on first use; null when anchoring is off or the call has no session. */
-export function sessionRing(surface, tenantId, sessionId) {
-    if (!biasHintEnabled('anchoring') || !sessionId)
-        return null;
-    return getOrCreateRing(rings[surface], buildSessionKey(tenantId, sessionId));
-}
-/** The session's history, read without creating or touching its ring, so a request that then fails evicts no live session. */
-export function peekSessionRing(surface, tenantId, sessionId) {
-    const ring = rings[surface].get(buildSessionKey(tenantId, sessionId));
-    return ring ? snapshotRing(ring) : [];
-}
-/** Records this recall's top row and hint, which the next recall's cooldown reads. */
-export function noteRecall(ring, query, topId, anchoredOn) {
-    appendRecall(ring, hashQueryText(query), topId, anchoredOn);
-}
-export function resetSessionRings(surface) {
-    rings[surface].clear();
-}
-export function callerOf(ctx) {
-    return { tenantId: ctx.tenantId, actor: ctx.actor.subject };
-}
-/** 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() } };
-}
-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) {
-    return { ...auditQueryFields(query), results };
-}
-/** No session means no ring; the row hashes with SHA-256/16, since hashQueryText is FNV-1a and easy to reverse on short queries. */
-export function anchorSkippedRows(who, query) {
-    if (!biasHintEnabled('anchoring'))
-        return [];
-    return [recallAuditRow(who, 'recall_anchor_skipped_no_session', undefined, auditQueryFields(query))];
-}
-export function anchoringRows(who, hint) {
-    if (hint?.reason === 'memory_dominance') {
-        return [recallAuditRow(who, 'recall_anchor_detected_memory_dominance', hint.memoryId, {
-                memory_id: hint.memoryId,
-                query_count: hint.queryCount ?? null,
-            })];
-    }
-    if (hint?.reason === 'query_repeat') {
-        return [recallAuditRow(who, 'recall_anchor_detected_query_repeat', hint.memoryId, { memory_id: hint.memoryId })];
-    }
-    return [];
-}
-export function availabilityRows(who, hint) {
-    if (!hint)
-        return [];
-    return [recallAuditRow(who, 'recall_availability_detected', undefined, {
-            recent_fraction: hint.recentFraction,
-            older_passed_over: hint.olderCandidatesPassedOver,
-            returned_count: hint.returnedCount,
-        })];
-}
-/** 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 function shownRecallRows(who, shown) {
-    return [
-        ...(shown.ring ? [] : anchorSkippedRows(who, shown.query)),
-        ...anchoringRows(who, shown.anchoring),
-        ...availabilityRows(who, shown.availability),
-    ];
-}
-//# sourceMappingURL=recall-record.js.map