hippo-memory 1.44.0 → 1.46.0

package/dist/search.js

@@ -2,8 +2,9 @@
  * BM25 search + optional embedding hybrid search for Hippo.
  * Zero external dependencies when embeddings are not available.
  */
-import { calculateStrength } from './memory.js';
-import { isOutcomeFastAblated, isRecallBoostAblated, evalNow } from './ablation.js';
+import { estimateTokens } from './token-ledger.js';
+import { calculateStrength, netWrong } from './memory.js';
+import { isOutcomeFastAblated, isRecallBoostAblated, isRecencyAblated, evalRecencyScaleDays, evalNow } from './ablation.js';
 import { extractPathTags, pathBoostMultiplier } from './path-context.js';
 import { detectScope, scopeMatch } from './scope.js';
 import { cosineSimilarity, embeddingModelRequiresReindex, loadEmbeddingIndex, } from './embeddings.js';
@@ -68,20 +69,28 @@ function bm25Score(corpus, docIdx, queryTerms) {
 // ---------------------------------------------------------------------------
 // Token budget estimation
 // ---------------------------------------------------------------------------
-/**
- * Rough token estimate: characters / 4 (works well for English text).
- */
-export function estimateTokens(text) {
-    return Math.ceil(text.length / 4);
-}
+// Rough token estimate (characters / 4). Defined once in token-ledger.ts and
+// re-exported here, where callers have always imported it from.
+export { estimateTokens };
 // ---------------------------------------------------------------------------
 // Recency boost
 // ---------------------------------------------------------------------------
 function recencyBoost(entry, now) {
+    if (isRecencyAblated())
+        return 1; // EVAL-ONLY ablation (see ablation.ts)
     const created = new Date(entry.created);
     const ageDays = (now.getTime() - created.getTime()) / (1000 * 60 * 60 * 24);
     // Exponential decay: memories < 1 day get boost ~1.0, older get less
-    return Math.exp(-ageDays / 30);
+    return Math.exp(-ageDays / (evalRecencyScaleDays() ?? 30));
+}
+/** Retrieval-time outcome nudge in [0.85, 1.15]; the E1 bm25-outcome baseline ranks with it too. */
+export function outcomeMultiplier(entry) {
+    const pos = entry.outcome_positive ?? 0;
+    const neg = entry.outcome_negative ?? 0;
+    // EVAL-ONLY ablation (see ablation.ts): the fast outcome channel.
+    if (isOutcomeFastAblated() || (pos === 0 && neg === 0))
+        return 1.0;
+    return Math.max(0.85, Math.min(1.15, 1 + 0.15 * Math.tanh((pos - neg) / 2)));
 }
 // ---------------------------------------------------------------------------
 // Temporal-aware scoring
@@ -237,8 +246,8 @@ export async function hybridSearch(query, entries, options = {}) {
     if (options.hippoRoot) {
         try {
             const provider = resolveEmbeddingProvider(options.hippoRoot);
-            if (provider.isAvailable() && !embeddingModelRequiresReindex(options.hippoRoot, provider.id)) {
-                const idx = loadEmbeddingIndex(options.hippoRoot);
+            const idx = provider.isAvailable() ? loadEmbeddingIndex(options.hippoRoot) : {};
+            if (provider.isAvailable() && !embeddingModelRequiresReindex(options.hippoRoot, provider.id, idx)) {
                 // Only spend a (possibly paid, off-box) query embedding when at least one
                 // of THIS search's entries has a cached vector to compare against. An
                 // index of only orphaned / out-of-scope vectors yields a meaningless
@@ -364,12 +373,7 @@ export async function hybridSearch(query, entries, options = {}) {
         compositeScore *= pathBoost;
         // Retrieval-time outcome personalization: nudge up/down from user feedback.
         // Distinct from reward-factor-via-strength (slow); this is immediate.
-        // EVAL-ONLY ablation (see ablation.ts): the fast outcome channel.
-        const pos = entries[i].outcome_positive ?? 0;
-        const neg = entries[i].outcome_negative ?? 0;
-        const outcomeBoost = isOutcomeFastAblated() || (pos === 0 && neg === 0)
-            ? 1.0
-            : Math.max(0.85, Math.min(1.15, 1 + 0.15 * Math.tanh((pos - neg) / 2)));
+        const outcomeBoost = outcomeMultiplier(entries[i]);
         compositeScore *= outcomeBoost;
         // Scope boost: memories tagged with the active scope get 1.5x; mismatching scopes get 0.5x
         const scopeSignal = scopeMatch(entries[i].tags, activeScope);
@@ -511,7 +515,7 @@ export async function hybridSearch(query, entries, options = {}) {
         const head = ordered.slice(0, topK);
         const tail = ordered.slice(topK);
         const rerankInputWithRank = head.map((r, i) => ({ ...r, preRerankRank: i + 1 }));
-        const reranked = await options.reranker(query, rerankInputWithRank, options.rerankerOptions);
+        const reranked = await options.reranker(query, rerankInputWithRank, { ...options.rerankerOptions, topK });
         const withPostRank = reranked.map((r, i) => ({ ...r, postRerankRank: i + 1 }));
         ordered = [...withPostRank, ...tail];
     }
@@ -929,12 +933,13 @@ export function markRetrieved(entries, now = evalNow()) {
     return entries.map((e) => {
         if (e.superseded_by)
             return e;
+        const wrong = netWrong(e) > 0;
         const updated = {
             ...e,
             retrieval_count: e.retrieval_count + 1,
-            last_retrieved: now.toISOString(),
-            // Extend half-life by +2 days per retrieval (PLAN.md)
-            half_life_days: e.half_life_days + 2,
+            last_retrieved: wrong ? e.last_retrieved : now.toISOString(),
+            // +2 days half-life per retrieval (PLAN.md); a wrong memory keeps both, since last_retrieved is the decay anchor
+            half_life_days: wrong ? e.half_life_days : e.half_life_days + 2,
         };
         updated.strength = calculateStrength(updated, now);
         return updated;

package/dist/server.d.ts

@@ -15,6 +15,8 @@ export interface ServeOpts {
     hippoRoot: string;
     port?: number;
     host?: string;
+    /** Stop and exit on SIGINT/SIGTERM. Only `hippo serve` owns the process, so only it sets this. */
+    handleSignals?: boolean;
 }
 /**
  * Recognise loopback remote addresses. Node reports IPv6-mapped IPv4 as
@@ -22,6 +24,9 @@ export interface ServeOpts {
  * the bare v4 and v6 loopbacks. Anything else is treated as remote.
  */
 export declare function isLoopback(remoteAddress: string | undefined): boolean;
+export declare const LOOPBACK_HOST_HEADER: RegExp;
+/** A browser request sent by another site. Non-browser clients send neither header and pass. */
+export declare function isCrossSite(req: IncomingMessage): boolean;
 /**
  * Rate-limit key for a request. Defaults to the socket's remote address.
  *

package/dist/server.js

@@ -22,7 +22,7 @@ export function __resetSessionRecallHistoryHttp() {
 import { PACKAGE_VERSION } from './version.js';
 import { validateApiKey } from './auth.js';
 import { createRateLimiter } from './rate-limit.js';
-import { remember, recall, RecallContractError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, } from './api.js';
+import { remember, retrieve, RecallContractError, ForbiddenError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, adminActor, recordTokens, } from './api.js';
 import { buildGraphModel } from './graph-view.js';
 import { MAX_ENTITY_NAME_LEN } from './graph.js';
 import { savePrediction, closePrediction, loadPredictionById, loadPredictionsByClass, loadOpenPredictions, computePredictionBaserate, VALID_CLOSURE_STATES, } from './predictions.js';
@@ -114,6 +114,8 @@ const VALID_AUDIT_OPS = new Set([
     'reject_refusal', // AT1 — emitted when the rejection guard refuses a write; lockstep
     'unreject_value', // AT1 — emitted by `hippo unreject`; lockstep
     'conflict_resolve', // AT1 — emitted by resolveConflict on every resolution path; lockstep
+    'half_life_migrate', // Decay default change — emitted by migrateDefaultHalfLife; lockstep with AuditOp union
+    'dormant_restore', // Dormant memories — emitted by api.restoreDormant; lockstep with AuditOp union + cli.ts VALID_AUDIT_OPS
 ]);
 // Cap on GET /v1/audit?limit=. Matches docs/api.md (when written) and is large
 // enough to dump a small deployment's full audit log without paginating, but
@@ -289,10 +291,13 @@ async function parseJsonBody(req) {
  *   - /unknown/i    → 404 (auth_revoke on unknown key_id)
  *   - /already superseded/i → 409 (chain conflict)
  *   - /not raw/i    → 400 (archive_raw on non-raw row)
- * Everything else maps to 400 (bad input).
+ * ForbiddenError maps to 403; everything else to 400 (bad input).
  */
 function mapApiError(err) {
     const message = err instanceof Error ? err.message : String(err);
+    if (err instanceof ForbiddenError) {
+        return { status: 403, message };
+    }
     const lower = message.toLowerCase();
     if (/not found/.test(lower) || /^unknown /.test(lower)) {
         return { status: 404, message };
@@ -300,6 +305,9 @@ function mapApiError(err) {
     if (/already superseded/.test(lower)) {
         return { status: 409, message };
     }
+    if (/requires admin role/.test(lower)) {
+        return { status: 403, message };
+    }
     return { status: 400, message };
 }
 function parseRequest(req) {
@@ -354,6 +362,25 @@ export function isLoopback(remoteAddress) {
         return true;
     return false;
 }
+// Any other Host on a loopback socket is DNS rebinding: a hostile page resolved to 127.0.0.1.
+export const LOOPBACK_HOST_HEADER = /^(localhost|127\.0\.0\.1|\[::1\])(:\d+)?$/i;
+/** A browser request sent by another site. Non-browser clients send neither header and pass. */
+export function isCrossSite(req) {
+    const site = req.headers['sec-fetch-site'];
+    if (site !== undefined && site !== 'same-origin' && site !== 'none')
+        return true;
+    const origin = req.headers.origin;
+    return origin !== undefined && origin !== `http://${req.headers.host}`;
+}
+// A browser on this machine is loopback too, so the no-key fallback also needs a local Host and a same-site caller.
+function assertLocalCaller(req) {
+    if (!isLoopback(req.socket.remoteAddress))
+        throw new HttpError(401, 'auth required');
+    const host = req.headers.host;
+    if ((host !== undefined && !LOOPBACK_HOST_HEADER.test(host)) || isCrossSite(req)) {
+        throw new HttpError(403, 'cross-site or non-local request refused; send an API key');
+    }
+}
 function readAuthHeader(req) {
     const raw = req.headers['authorization'];
     if (raw === undefined)
@@ -455,9 +482,7 @@ function buildContextWithAuth(req, hippoRoot) {
     if (process.env.HIPPO_REQUIRE_AUTH === '1') {
         throw new HttpError(401, 'auth required');
     }
-    if (!isLoopback(req.socket.remoteAddress)) {
-        throw new HttpError(401, 'auth required');
-    }
+    assertLocalCaller(req);
     // v1.12.0: loopback fallback is process-local, treat as admin.
     return {
         hippoRoot,
@@ -492,9 +517,7 @@ function requireAuth(req, hippoRoot) {
     if (process.env.HIPPO_REQUIRE_AUTH === '1') {
         throw new HttpError(401, 'auth required');
     }
-    if (!isLoopback(req.socket.remoteAddress)) {
-        throw new HttpError(401, 'auth required');
-    }
+    assertLocalCaller(req);
 }
 function getString(obj, key) {
     const v = obj[key];
@@ -632,10 +655,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             throw new HttpError(400, 'q is required');
         }
         const limitRaw = query.get('limit');
-        const limit = limitRaw === null ? undefined : Number(limitRaw);
-        if (limit !== undefined && (!Number.isFinite(limit) || limit <= 0)) {
-            throw new HttpError(400, 'limit must be a positive number');
-        }
+        const limit = limitRaw === null ? undefined : parseListLimit(limitRaw);
         const mode = query.get('mode');
         if (mode !== null && mode !== 'bm25' && mode !== 'hybrid' && mode !== 'physics') {
             throw new HttpError(400, "mode must be 'bm25', 'hybrid', or 'physics'");
@@ -671,11 +691,12 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         const summarizeOverflow = summarizeOverflowRaw === null
             ? undefined
             : (summarizeOverflowRaw === '1' || summarizeOverflowRaw === 'true');
-        // v1.7.2 T4: forward as Number(...) — NaN, 0, negative all reach
-        // recall() which throws RecallContractError with code='invalid_scorer_window'.
-        // No transport-side validation; recall() owns the contract.
+        // recall() owns the shape rule (NaN, 0 and negatives throw invalid_scorer_window); the transport caps remote cost.
         const scorerWindowRaw = query.get('scorer_window');
         const scorerWindow = scorerWindowRaw === null ? undefined : Number(scorerWindowRaw);
+        if (scorerWindow !== undefined && scorerWindow > 1000) {
+            throw new HttpError(400, 'scorer_window must be <= 1000');
+        }
         // v1.7.4: session_id for the dlPFC goal-stack boost. 256-char cap mirrors
         // fresh_tail_session_id (above). Trim then drop if empty so api.recall
         // sees undefined when the param is omitted or whitespace-only.
@@ -757,7 +778,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             recallExtra.recallHistory = httpRecallHistory;
         if (explain)
             recallExtra.explain = explain;
-        const result = recall(ctx, {
+        const result = await retrieve(ctx, {
             query: q,
             limit,
             mode: mode ?? undefined,
@@ -785,6 +806,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (includeContinuity) {
             res.setHeader('Cache-Control', 'no-store');
         }
+        recordTokens(ctx, 'http_recall', { items: result.results.length, tokens: result.tokens + (result.continuityTokens ?? 0), sessionId: sessionId ?? null });
         sendJson(res, 200, result);
         return;
     }
@@ -826,6 +848,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         if (scope !== undefined)
             assembleExtra.scope = scope;
         const result = assemble(ctx, assembleMatch.id, assembleExtra);
+        recordTokens(ctx, 'http_assemble', { items: result.items.length, tokens: result.tokens, sessionId: assembleMatch.id });
         sendJson(res, 200, result);
         return;
     }
@@ -1026,6 +1049,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
             crossProject,
             currentProject: resolveProjectIdentity(dirname(resolve(opts.hippoRoot))).name,
         });
+        recordTokens(ctx, 'http_context', { items: result.entries.length, tokens: result.tokens });
         sendJson(res, 200, result);
         return;
     }
@@ -1038,7 +1062,8 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
     // Tenant scope (Episode A follow-up tracked in TODOS.md): api.sleep operates
     // on the WHOLE hippoRoot (cross-tenant by design, matching CLI cmdSleep).
     // The loopback-only guard is the trust boundary today. Future non-loopback
-    // serving needs an admin-role gate before exposing this route.
+    // serving must also zero the cross-tenant counters for other tenants
+    // (D1 in docs/decisions/2026-05-24-blocked-items.md).
     if (method === 'POST' && path === '/v1/sleep') {
         // Defensive per-request loopback guard. Uses the canonical isLoopback()
         // helper above so any future extension (additional mapped/IPv6 forms,
@@ -1084,11 +1109,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         }
         // v1.12.3: optional body.role mirrors the --role CLI flag. Validated
         // strictly — anything other than 'admin'|'member' is a 400 (no silent
-        // fallback to admin). Required note: admin Bearer can mint a member
-        // key for the same tenant; member Bearer minting an admin key is NOT
-        // blocked here today (auth_create is currently unaudited per the A5 v2
-        // note in authCreate doc). The HTTP layer trusts the buildContextWithAuth
-        // role check at admin-gated routes; mint surface remains permissive.
+        // fallback to admin). authCreate refuses a member caller with a 403.
         const roleRaw = body['role'];
         let role;
         if (roleRaw !== undefined) {
@@ -1128,10 +1149,9 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
         sendJson(res, 200, result);
         return;
     }
-    // DELETE /v1/auth/keys/:keyId — revoke. authRevoke throws "Unknown key_id"
-    // for missing OR cross-tenant keys (no info leak), which mapApiError
-    // converts to 404. We return 200 with the result body rather than 204 to
-    // surface revokedAt to the caller.
+    // DELETE /v1/auth/keys/:keyId — revoke. Missing or cross-tenant keys are 404
+    // (no info leak); a member key targeting any key but its own is 403.
+    // 200 with the body rather than 204 so the caller sees revokedAt.
     const keyMatch = matchPath('/v1/auth/keys/:keyId', path);
     if (method === 'DELETE' && keyMatch) {
         validateIdSegment(keyMatch.keyId, 'key id');
@@ -2999,6 +3019,8 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
                 tenantId: ctx.tenantId,
                 // v1.12.0: McpContext.actor stays string; extract subject at the boundary.
                 actor: ctx.actor.subject,
+                // The caller's real role: MCP tools must not run a member key as admin.
+                role: ctx.actor.role,
                 clientKey: buildMcpClientKey(req),
             });
         }
@@ -3228,9 +3250,7 @@ export async function serve(opts) {
             server.close(() => resolve());
         });
     };
-    // Skip signal handlers under vitest so each test run does not register a
-    // stray SIGTERM/SIGINT listener that survives until the runner exits.
-    if (!process.env.VITEST) {
+    if (opts.handleSignals) {
         let shuttingDown = false;
         const gracefulShutdown = async (signal) => {
             if (shuttingDown)

package/dist/shared.js

@@ -153,7 +153,7 @@ export async function searchBothHybrid(query, localRoot, globalRoot, options = {
         if (!fs.existsSync(root))
             return [];
         return recallScope
-            ? loadRecallSearchEntries(root, query, searchWindow, tenantId, recallScope.requested, recallScope.additive ? 'additive' : 'exact')
+            ? loadRecallSearchEntries(root, query, searchWindow, tenantId, recallScope.requested, recallScope.additive ? 'additive' : 'exact', Boolean(includeSuperseded) || Boolean(asOf))
             : loadSearchEntries(root, query, searchWindow, tenantId);
     };
     let localEntries = loadEntries(localRoot);

package/dist/store.d.ts

@@ -10,6 +10,7 @@ import { SessionHandoff, HandoffEvidence, HandoffOutcome } from './handoff.js';
 import { Card, CardStatus, CardRun, CardComment } from './card.js';
 import { type ResolveProjectIdentityOpts } from './project-identity.js';
 import { RejectedValueError } from './rejection.js';
+import { type DormantMove } from './dormant.js';
 /** A value that round-trips through JSON.stringify/JSON.parse unchanged. */
 type JsonValue = string | number | boolean | null | JsonValue[] | {
     [key: string]: JsonValue;
@@ -108,6 +109,8 @@ export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void
 export declare function getHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
 export declare function isInitialized(hippoRoot: string): boolean;
 export declare function initStore(hippoRoot: string): void;
+/** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
+export declare const HALF_LIFE_BASE_META_KEY = "default_half_life_base";
 /**
  * Serialize a MemoryEntry to markdown with YAML frontmatter.
  */
@@ -203,9 +206,7 @@ export declare function buildIndexFromDb(db: ReturnType<typeof openHippoDb>): Hi
  * `buildIndexFromDb`'s query.
  */
 export declare function writeIndexMirror(hippoRoot: string, index: HippoIndex): void;
-/**
- * Load the current derived index from SQLite and refresh the mirror file.
- */
+/** Load the derived index from SQLite. Read-only: writers refresh index.json, so readers never race on it. */
 export declare function loadIndex(hippoRoot: string): HippoIndex;
 /**
  * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
@@ -298,6 +299,9 @@ export declare function readEntry(hippoRoot: string, id: string, tenantId?: stri
  * to fetch parent summaries for a set of overflowed leaves.
  */
 export declare function loadEntriesByIds(hippoRoot: string, ids: readonly string[], tenantId?: string): MemoryEntry[];
+/** Strengthen what a read returned: update only the four retrieval columns on the live row, never a stale copy.
+ *  Best effort: a failure logs and never fails the read. Returns the ids found in this store. */
+export declare function strengthenRetrieved(hippoRoot: string, ids: readonly string[], tenantId?: string): Set<string>;
 /**
  * All `kind='raw'` rows for a given session, tenant-scoped, returned
  * oldest-first. Used by `api.assemble` to walk a session's chronological
@@ -375,12 +379,14 @@ export declare function loadChildrenOf(hippoRoot: string, parentId: string, tena
  * removed) and `resolveConflict` (`conflict_resolve` row per resolution).
  * Default keeps `deleteEntry` byte-identical to its pre-split behavior.
  *
- * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row
- * with `id` existed.
+ * Returns `{tenantId, dagParentId}` for the removed row, or `null` if no row with `id`
+ * existed or `automatic` refused it (pinned or raw at DELETE time, so a late pin wins).
  */
 export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id: string, opts?: {
     actor?: string;
     suppressForgetAudit?: boolean;
+    reason?: string;
+    automatic?: boolean;
 }): {
     tenantId: string;
     dagParentId: string | null;
@@ -398,12 +404,20 @@ export declare function deleteEntryCore(db: ReturnType<typeof openHippoDb>, id:
  */
 export declare function deleteEntry(hippoRoot: string, id: string, opts?: {
     actor?: string;
+    reason?: string;
+    automatic?: boolean;
 }): boolean;
-/**
- * Batch-write and batch-delete entries in a single transaction.
- * Used by consolidation to avoid N open/close cycles.
- */
-export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEntry[], toDeleteIds: string[]): void;
+/** Consolidation's flush, one transaction. With `snapshot` (rows as the caller loaded them), a write keeps only
+ *  the fields the caller changed, takes the rest from the live row, and never resurrects a row that is gone.
+ *
+ *  `dormant` (src/dormant.ts): each move's snapshot is inserted into `dormant_memories` and its `memories` row
+ *  leaves exactly like a delete (FTS row, DAG parent dirty-mark, mirrors), in the same transaction, so a memory
+ *  is never in both places or in neither. Deletes and moves both skip rows that are no longer auto-deletable
+ *  (pinned or raw since the caller decided). Returns the ids that left `memories`, deleted or moved. */
+export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEntry[], toDeleteIds: string[], opts?: {
+    snapshot?: ReadonlyMap<string, MemoryEntry>;
+    dormant?: DormantMove[];
+}): string[];
 /**
  * Load all entries from SQLite.
  *
@@ -412,6 +426,8 @@ export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEn
  * paths that surface results to a user MUST pass a resolved tenant.
  */
 export declare function loadAllEntries(hippoRoot: string, tenantId?: string): MemoryEntry[];
+/** Every memory row on an open connection, so a caller can read inside its own transaction. */
+export declare function selectAllEntries(db: DatabaseSyncLike, tenantId?: string): MemoryEntry[];
 export declare function loadAmbientCandidates(hippoRoot: string, tenantId: string, recentNeeded: number, admit: (e: MemoryEntry) => boolean): MemoryEntry[];
 /**
  * Load likely search candidates directly from SQLite.
@@ -445,7 +461,7 @@ export declare function loadSearchEntries(hippoRoot: string, query: string, limi
  * mode (its `tenantId` option is optional); `loadSearchRows` already treats
  * undefined as "no tenant filter" for legacy callers.
  */
-export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive'): MemoryEntry[];
+export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean): MemoryEntry[];
 /**
  * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
  */
@@ -462,6 +478,8 @@ export declare function appendConsolidationRun(hippoRoot: string, run: {
     merged: number;
     removed: number;
 }): void;
+/** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
+export declare function countCreatedSinceLastSleep(hippoRoot: string, tenantId: string, now?: Date): number;
 /**
  * Session decay context: provides the data needed for session-based and adaptive decay.
  */